1 /*************************************************************************** 2 * Copyright (c) 2024 Microsoft Corporation 3 * 4 * This program and the accompanying materials are made available under the 5 * terms of the MIT License which is available at 6 * https://opensource.org/licenses/MIT. 7 * 8 * SPDX-License-Identifier: MIT 9 **************************************************************************/ 10 11 12 /**************************************************************************/ 13 /**************************************************************************/ 14 /** */ 15 /** NetX Component */ 16 /** */ 17 /** Cloud Helper */ 18 /** */ 19 /**************************************************************************/ 20 /**************************************************************************/ 21 22 23 /**************************************************************************/ 24 /* */ 25 /* APPLICATION INTERFACE DEFINITION RELEASE */ 26 /* */ 27 /* nx_cloud.h PORTABLE C */ 28 /* 6.1 */ 29 /* AUTHOR */ 30 /* */ 31 /* Yuxin Zhou, Microsoft Corporation */ 32 /* */ 33 /* DESCRIPTION */ 34 /* */ 35 /* This file defines the NetX Cloud component, including all data */ 36 /* types and external references. */ 37 /* */ 38 /* RELEASE HISTORY */ 39 /* */ 40 /* DATE NAME DESCRIPTION */ 41 /* */ 42 /* 09-30-2020 Yuxin Zhou Initial Version 6.1 */ 43 /* */ 44 /**************************************************************************/ 45 46 #ifndef NX_CLOUD_H 47 #define NX_CLOUD_H 48 49 /* Determine if a C++ compiler is being used. If so, ensure that standard 50 C is used to process the API information. */ 51 52 #ifdef __cplusplus 53 54 /* Yes, C++ compiler is present. Use standard C. */ 55 extern "C" { 56 57 #endif 58 59 /* Include the ThreadX and port-specific data type file. */ 60 61 #include "tx_api.h" 62 #include "nx_api.h" 63 64 65 /* Define CLOUD constants. */ 66 #define NX_CLOUD_ID ((ULONG)0x434C4F44) 67 68 69 /* API return values. */ 70 #define NX_CLOUD_MODULE_ALREADY_REGISTERED 0xF0 71 #define NX_CLOUD_MODULE_NOT_REGISTERED 0xF1 72 #define NX_CLOUD_MODULE_BOUND 0xF2 73 #define NX_CLOUD_MODULE_EVENT_INVALID 0xF3 74 75 76 /* Define events processed by cloud helper. */ 77 #define NX_CLOUD_ALL_EVENTS 0xFFFFFFFF /* All event flags. */ 78 79 /* Define the common events for all modules. */ 80 #define NX_CLOUD_COMMON_PERIODIC_EVENT 0x00000001u /* Periodic event, 1s */ 81 82 /* Define the module events. */ 83 #define NX_CLOUD_MODULE_MQTT_EVENT 0x00010000u /* MQTT event */ 84 #define NX_CLOUD_MODULE_AZURE_SDK_EVENT 0x00020000u /* Azure SDK event */ 85 #define NX_CLOUD_MODULE_AZURE_ADU_EVENT 0x00040000u /* Azure Device Update event */ 86 #define NX_CLOUD_MODULE_AZURE_ISM_EVENT 0x00080000u /* Azure IoT Security Module event */ 87 88 89 /* Define the all common events. */ 90 #define NX_CLOUD_COMMON_ALL_EVENT (NX_CLOUD_COMMON_PERIODIC_EVENT) 91 92 93 typedef struct NX_CLOUD_MODULE_STRUCT 94 { 95 96 /* Define the module name. */ 97 const CHAR *nx_cloud_module_name; 98 99 /* Define the module registered events including common events and module event 100 that are processed in cloud helper thread. */ 101 ULONG nx_cloud_module_registered_events; 102 103 /* Define the actual current event flags in this module that are processed 104 in module processing routine. */ 105 ULONG nx_cloud_module_own_events; 106 107 /* Define the module processing routine. */ 108 VOID (*nx_cloud_module_process)(VOID *module_context, ULONG common_events, ULONG module_own_events); 109 110 /* Define the context that is passed to module processing routine. */ 111 VOID *nx_cloud_module_context; 112 113 /* Define the next pointer of created module. */ 114 struct NX_CLOUD_MODULE_STRUCT *nx_cloud_module_next; 115 116 /* Define the cloud pointer associated with the module. */ 117 struct NX_CLOUD_STRUCT *nx_cloud_ptr; 118 119 } NX_CLOUD_MODULE; 120 121 typedef struct NX_CLOUD_STRUCT 122 { 123 124 /* Define the cloud ID. */ 125 ULONG nx_cloud_id; 126 127 /* Define the cloud name. */ 128 const CHAR *nx_cloud_name; 129 130 /* Define the cloud helper thread that process cloud modules. */ 131 TX_THREAD nx_cloud_thread; 132 133 /* Define the event flags that are used to stimulate the cloud helper 134 thread. */ 135 TX_EVENT_FLAGS_GROUP nx_cloud_events; 136 137 /* Define the internal mutex used for protection . */ 138 TX_MUTEX nx_cloud_mutex; 139 140 /* Define the periodic timer for cloud modules. */ 141 TX_TIMER nx_cloud_periodic_timer; 142 143 /* Define the head pointer of the created module list. */ 144 NX_CLOUD_MODULE *nx_cloud_modules_list_header; 145 146 /* Define the number of created module instances. */ 147 ULONG nx_cloud_modules_count; 148 149 } NX_CLOUD; 150 151 152 #ifndef NX_CLOUD_SOURCE_CODE 153 154 /* Application caller is present, perform API mapping. */ 155 156 /* Determine if error checking is desired. If so, map CLOUD API functions 157 to the appropriate error checking front-ends. Otherwise, map API 158 functions to the core functions that actually perform the work. 159 Note: error checking is enabled by default. */ 160 161 #ifdef NX_DISABLE_ERROR_CHECKING 162 163 /* Services without error checking. */ 164 165 #define nx_cloud_create _nx_cloud_create 166 #define nx_cloud_delete _nx_cloud_delete 167 #define nx_cloud_module_register _nx_cloud_module_register 168 #define nx_cloud_module_deregister _nx_cloud_module_deregister 169 #define nx_cloud_module_event_set _nx_cloud_module_event_set 170 #define nx_cloud_module_event_clear _nx_cloud_module_event_clear 171 172 #else 173 174 /* Services with error checking. */ 175 176 #define nx_cloud_create _nxe_cloud_create 177 #define nx_cloud_delete _nxe_cloud_delete 178 #define nx_cloud_module_register _nxe_cloud_module_register 179 #define nx_cloud_module_deregister _nxe_cloud_module_deregister 180 #define nx_cloud_module_event_set _nxe_cloud_module_event_set 181 #define nx_cloud_module_event_clear _nxe_cloud_module_event_clear 182 183 #endif 184 185 /* Define the prototypes accessible to the application software. */ 186 187 /* Create/delete cloud helper thread. */ 188 UINT nx_cloud_create(NX_CLOUD* cloud_ptr, const CHAR* cloud_name, VOID* memory_ptr, ULONG memory_size, UINT priority); 189 UINT nx_cloud_delete(NX_CLOUD* cloud_ptr); 190 191 /* Register/deregister module in cloud thread. */ 192 UINT nx_cloud_module_register(NX_CLOUD* cloud_ptr, NX_CLOUD_MODULE* module_ptr, const CHAR* module_name, ULONG module_event, 193 VOID (*module_process)(VOID* module_context, ULONG common_events, ULONG module_own_events), VOID* module_context); 194 UINT nx_cloud_module_deregister(NX_CLOUD* cloud_ptr, NX_CLOUD_MODULE* module_ptr); 195 UINT nx_cloud_module_event_set(NX_CLOUD_MODULE *cloud_module, ULONG module_own_event); 196 UINT nx_cloud_module_event_clear(NX_CLOUD_MODULE *cloud_module, ULONG module_own_event); 197 198 #else 199 200 /* Cloud source code is being compiled, do not perform any API mapping. */ 201 202 UINT _nxe_cloud_create(NX_CLOUD* cloud_ptr, const CHAR* cloud_name, VOID* memory_ptr, ULONG memory_size, UINT priority); 203 UINT _nx_cloud_create(NX_CLOUD* cloud_ptr, const CHAR* cloud_name, VOID* memory_ptr, ULONG memory_size, UINT priority); 204 UINT _nxe_cloud_delete(NX_CLOUD* cloud_ptr); 205 UINT _nx_cloud_delete(NX_CLOUD* cloud_ptr); 206 UINT _nxe_cloud_module_register(NX_CLOUD* cloud_ptr, NX_CLOUD_MODULE* module_ptr, const CHAR* module_name, ULONG module_event, 207 VOID(*module_process)(VOID* module_context, ULONG common_events, ULONG module_own_events), VOID* module_context); 208 UINT _nx_cloud_module_register(NX_CLOUD* cloud_ptr, NX_CLOUD_MODULE* module_ptr, const CHAR* module_name, ULONG module_event, 209 VOID(*module_process)(VOID* module_context, ULONG common_events, ULONG module_own_events), VOID* module_context); 210 UINT _nxe_cloud_module_deregister(NX_CLOUD* cloud_ptr, NX_CLOUD_MODULE* module_ptr); 211 UINT _nx_cloud_module_deregister(NX_CLOUD* cloud_ptr, NX_CLOUD_MODULE* module_ptr); 212 UINT _nxe_cloud_module_event_set(NX_CLOUD_MODULE *cloud_module, ULONG module_own_event); 213 UINT _nx_cloud_module_event_set(NX_CLOUD_MODULE *cloud_module, ULONG module_own_event); 214 UINT _nxe_cloud_module_event_clear(NX_CLOUD_MODULE *cloud_module, ULONG module_own_event); 215 UINT _nx_cloud_module_event_clear(NX_CLOUD_MODULE *cloud_module, ULONG module_own_event); 216 217 #endif 218 219 220 /* Determine if a C++ compiler is being used. If so, complete the standard 221 C conditional started above. */ 222 #ifdef __cplusplus 223 } 224 #endif 225 226 #endif /* NX_CLOUD_H */ 227
