1 /**************************************************************************/ 2 /* */ 3 /* Copyright (c) Microsoft Corporation. All rights reserved. */ 4 /* */ 5 /* This software is licensed under the Microsoft Software License */ 6 /* Terms for Microsoft Azure RTOS. Full text of the license can be */ 7 /* found in the LICENSE file at https://aka.ms/AzureRTOS_EULA */ 8 /* and in the root directory of this software. */ 9 /* */ 10 /**************************************************************************/ 11 12 /** 13 * @file nx_azure_iot_hub_client.h 14 * 15 * @brief Definition for the Azure IoT Hub client. 16 * @remark The IoT Hub MQTT protocol is described at 17 * https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-mqtt-support. 18 * 19 */ 20 21 #ifndef NX_AZURE_IOT_HUB_CLIENT_H 22 #define NX_AZURE_IOT_HUB_CLIENT_H 23 24 #ifdef __cplusplus 25 extern "C" { 26 #endif 27 28 #include "nx_azure_iot.h" 29 #include "azure/iot/az_iot_hub_client.h" 30 31 /**< Value denoting a message is of "None" type */ 32 #define NX_AZURE_IOT_HUB_NONE 0x00000000 33 34 /**< Value denoting a message is of "all" type */ 35 #define NX_AZURE_IOT_HUB_ALL_MESSAGE 0xFFFFFFFF 36 37 /**< Value denoting a message is a cloud-to-device message */ 38 #define NX_AZURE_IOT_HUB_CLOUD_TO_DEVICE_MESSAGE 0x00000001 39 40 /**< Value denoting a message is a command message */ 41 #define NX_AZURE_IOT_HUB_COMMAND 0x00000002 42 43 /**< Value denoting a message is a properties message */ 44 #define NX_AZURE_IOT_HUB_PROPERTIES 0x00000004 45 46 /**< Value denoting a message is a writable properties message */ 47 #define NX_AZURE_IOT_HUB_WRITABLE_PROPERTIES 0x00000008 48 49 /**< Value denoting a message is a reported properties response */ 50 #define NX_AZURE_IOT_HUB_REPORTED_PROPERTIES_RESPONSE 0x00000010 51 52 /* Map the message type. */ 53 #define NX_AZURE_IOT_HUB_DIRECT_METHOD NX_AZURE_IOT_HUB_COMMAND 54 #define NX_AZURE_IOT_HUB_DEVICE_TWIN_PROPERTIES NX_AZURE_IOT_HUB_PROPERTIES 55 #define NX_AZURE_IOT_HUB_DEVICE_TWIN_DESIRED_PROPERTIES NX_AZURE_IOT_HUB_WRITABLE_PROPERTIES 56 #define NX_AZURE_IOT_HUB_DEVICE_TWIN_REPORTED_PROPERTIES_RESPONSE NX_AZURE_IOT_HUB_REPORTED_PROPERTIES_RESPONSE 57 58 /* Set the default timeout for DNS query. */ 59 #ifndef NX_AZURE_IOT_HUB_CLIENT_DNS_TIMEOUT 60 #define NX_AZURE_IOT_HUB_CLIENT_DNS_TIMEOUT (5 * NX_IP_PERIODIC_RATE) 61 #endif /* NX_AZURE_IOT_HUB_CLIENT_DNS_TIMEOUT */ 62 63 /* Set the default timeout for connection with SAS token authentication in secs. */ 64 #ifndef NX_AZURE_IOT_HUB_CLIENT_TOKEN_CONNECTION_TIMEOUT 65 #ifdef NX_AZURE_IOT_HUB_CLIENT_TOKEN_EXPIRY 66 #define NX_AZURE_IOT_HUB_CLIENT_TOKEN_CONNECTION_TIMEOUT NX_AZURE_IOT_HUB_CLIENT_TOKEN_EXPIRY 67 #else 68 #define NX_AZURE_IOT_HUB_CLIENT_TOKEN_CONNECTION_TIMEOUT (3600) 69 #endif /* NX_AZURE_IOT_HUB_CLIENT_TOKEN_EXPIRY */ 70 #endif /* NX_AZURE_IOT_HUB_CLIENT_SAS_CONNECTION_TIMEOUT */ 71 72 #ifndef NX_AZURE_IOT_HUB_CLIENT_MAX_BACKOFF_IN_SEC 73 #define NX_AZURE_IOT_HUB_CLIENT_MAX_BACKOFF_IN_SEC (10 * 60) 74 #endif /* NX_AZURE_IOT_HUB_CLIENT_MAX_BACKOFF_IN_SEC */ 75 76 #ifndef NX_AZURE_IOT_HUB_CLIENT_INITIAL_BACKOFF_IN_SEC 77 #define NX_AZURE_IOT_HUB_CLIENT_INITIAL_BACKOFF_IN_SEC (3) 78 #endif /* NX_AZURE_IOT_HUB_CLIENT_INITIAL_BACKOFF_IN_SEC */ 79 80 #ifndef NX_AZURE_IOT_HUB_CLIENT_MAX_BACKOFF_JITTER_PERCENT 81 #define NX_AZURE_IOT_HUB_CLIENT_MAX_BACKOFF_JITTER_PERCENT (60) 82 #endif /* NX_AZURE_IOT_HUB_CLIENT_MAX_BACKOFF_JITTER_PERCENT */ 83 84 /* Define Azure IoT Hub Client state. */ 85 /**< The client is not connected */ 86 #define NX_AZURE_IOT_HUB_CLIENT_STATUS_NOT_CONNECTED 0 87 88 /**< The client is connecting */ 89 #define NX_AZURE_IOT_HUB_CLIENT_STATUS_CONNECTING 1 90 91 /**< The client is connected */ 92 #define NX_AZURE_IOT_HUB_CLIENT_STATUS_CONNECTED 2 93 94 /* Default TELEMETRY QoS is QoS1 */ 95 #ifndef NX_AZURE_IOT_HUB_CLIENT_TELEMETRY_QOS 96 #define NX_AZURE_IOT_HUB_CLIENT_TELEMETRY_QOS NX_AZURE_IOT_MQTT_QOS_1 97 #endif /* NX_AZURE_IOT_HUB_CLIENT_TELEMETRY_QOS */ 98 99 #ifndef NX_AZURE_IOT_HUB_CLIENT_MAX_COMPONENT_LIST 100 #define NX_AZURE_IOT_HUB_CLIENT_MAX_COMPONENT_LIST (4) 101 #endif /* NX_AZURE_IOT_HUB_CLIENT_MAX_COMPONENT_LIST */ 102 103 /* Forward declration*/ 104 struct NX_AZURE_IOT_HUB_CLIENT_STRUCT; 105 106 typedef struct NX_AZURE_IOT_HUB_CLIENT_RECEIVE_MESSAGE_STRUCT 107 { 108 NX_PACKET *message_head; 109 NX_PACKET *message_tail; 110 VOID (*message_callback)(struct NX_AZURE_IOT_HUB_CLIENT_STRUCT *hub_client_ptr, VOID *args); 111 VOID *message_callback_args; 112 UINT (*message_process)(struct NX_AZURE_IOT_HUB_CLIENT_STRUCT *hub_client_ptr, 113 NX_PACKET *packet_ptr, ULONG topic_offset, USHORT topic_length); 114 UINT (*message_enable)(struct NX_AZURE_IOT_HUB_CLIENT_STRUCT *hub_client_ptr); 115 } NX_AZURE_IOT_HUB_CLIENT_RECEIVE_MESSAGE; 116 117 /** 118 * @brief Azure IoT Hub Client struct 119 * 120 */ 121 typedef struct NX_AZURE_IOT_HUB_CLIENT_STRUCT 122 { 123 NX_AZURE_IOT *nx_azure_iot_ptr; 124 125 UINT nx_azure_iot_hub_client_state; 126 NX_AZURE_IOT_THREAD *nx_azure_iot_hub_client_thread_suspended; 127 NX_AZURE_IOT_HUB_CLIENT_RECEIVE_MESSAGE nx_azure_iot_hub_client_c2d_message; 128 NX_AZURE_IOT_HUB_CLIENT_RECEIVE_MESSAGE nx_azure_iot_hub_client_command_message; 129 NX_AZURE_IOT_HUB_CLIENT_RECEIVE_MESSAGE nx_azure_iot_hub_client_properties_message; 130 NX_AZURE_IOT_HUB_CLIENT_RECEIVE_MESSAGE nx_azure_iot_hub_client_writable_properties_message; 131 VOID (*nx_azure_iot_hub_client_report_properties_response_callback)( 132 struct NX_AZURE_IOT_HUB_CLIENT_STRUCT *hub_client_ptr, 133 UINT request_id, UINT response_status, ULONG version, VOID *args); 134 VOID *nx_azure_iot_hub_client_report_properties_response_callback_args; 135 136 VOID (*nx_azure_iot_hub_client_connection_status_callback)( 137 struct NX_AZURE_IOT_HUB_CLIENT_STRUCT *hub_client_ptr, 138 UINT status); 139 UINT (*nx_azure_iot_hub_client_token_refresh)( 140 struct NX_AZURE_IOT_HUB_CLIENT_STRUCT *hub_client_ptr, 141 ULONG expiry_time_secs, const UCHAR *key, UINT key_len, 142 UCHAR *sas_buffer, UINT sas_buffer_len, UINT *sas_length); 143 144 UINT nx_azure_iot_hub_client_request_id; 145 const UCHAR *nx_azure_iot_hub_client_symmetric_key; 146 UINT nx_azure_iot_hub_client_symmetric_key_length; 147 NX_AZURE_IOT_RESOURCE nx_azure_iot_hub_client_resource; 148 149 volatile UCHAR nx_azure_iot_hub_client_properties_subscribe_ack; 150 UCHAR reserved[3]; 151 152 az_iot_hub_client iot_hub_client_core; 153 UINT nx_azure_iot_hub_client_throttle_count; 154 ULONG nx_azure_iot_hub_client_throttle_end_time; 155 ULONG nx_azure_iot_hub_client_sas_token_expiry_time; 156 az_span nx_azure_iot_hub_client_component_list[NX_AZURE_IOT_HUB_CLIENT_MAX_COMPONENT_LIST]; 157 UINT (*nx_azure_iot_hub_client_component_callback[NX_AZURE_IOT_HUB_CLIENT_MAX_COMPONENT_LIST]) 158 (VOID *json_reader_ptr, 159 ULONG version, 160 VOID *args); 161 VOID *nx_azure_iot_hub_client_component_callback_args[NX_AZURE_IOT_HUB_CLIENT_MAX_COMPONENT_LIST]; 162 VOID (*nx_azure_iot_hub_client_component_properties_process)(struct NX_AZURE_IOT_HUB_CLIENT_STRUCT *hub_client_ptr, 163 NX_PACKET *packet_ptr, 164 UINT message_type); 165 } NX_AZURE_IOT_HUB_CLIENT; 166 167 168 /** 169 * @brief Initialize Azure IoT hub instance 170 * 171 * @param[in] hub_client_ptr A pointer to a #NX_AZURE_IOT_HUB_CLIENT. 172 * @param[in] nx_azure_iot_ptr A pointer to a #NX_AZURE_IOT. 173 * @param[in] host_name A `UCHAR` pointer to IoTHub hostname. Must be `NULL` terminated. 174 * @param[in] host_name_length Length of `host_name`. Does not include the `NULL` terminator. 175 * @param[in] device_id A `UCHAR` pointer to the device ID. 176 * @param[in] device_id_length Length of the `device_id`. Does not include the `NULL` terminator. 177 * @param[in] module_id A `UCHAR` pointer to the module ID. 178 * @param[in] module_id_length Length of the `module_id`. Does not include the `NULL` terminator. 179 * @param[in] crypto_array A pointer to an array of `NX_CRYPTO_METHOD`. 180 * @param[in] crypto_array_size Size of `crypto_array`. 181 * @param[in] cipher_map A pointer to an array of `NX_CRYPTO_CIPHERSUITE`. 182 * @param[in] cipher_map_size Size of `cipher_map`. 183 * @param[in] metadata_memory A `UCHAR` pointer to metadata memory buffer. 184 * @param[in] memory_size Size of `metadata_memory`. 185 * @param[in] trusted_certificate A pointer to `NX_SECURE_X509_CERT`, which are the server side certs. 186 * @return A `UINT` with the result of the API. 187 * @retval #NX_AZURE_IOT_SUCCESS Successfully initialized the Azure IoT hub client. 188 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to initialize the Azure IoT hub client due to invalid parameter. 189 * @retval #NX_AZURE_IOT_SDK_CORE_ERROR Fail to initialize the Azure IoT hub client due to SDK core error. 190 */ 191 UINT nx_azure_iot_hub_client_initialize(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 192 NX_AZURE_IOT *nx_azure_iot_ptr, 193 const UCHAR *host_name, UINT host_name_length, 194 const UCHAR *device_id, UINT device_id_length, 195 const UCHAR *module_id, UINT module_id_length, 196 const NX_CRYPTO_METHOD **crypto_array, UINT crypto_array_size, 197 const NX_CRYPTO_CIPHERSUITE **cipher_map, UINT cipher_map_size, 198 UCHAR *metadata_memory, UINT memory_size, 199 NX_SECURE_X509_CERT *trusted_certificate); 200 201 /** 202 * @brief Deinitialize the Azure IoT Hub instance. 203 * 204 * @param[in] hub_client_ptr A pointer to a #NX_AZURE_IOT_HUB_CLIENT. 205 * @return A `UINT` with the result of the API. 206 * @retval #NX_AZURE_IOT_SUCCESS Successfully de-initialized the Azure IoT hub client. 207 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to deinitialize the Azure IoT hub client due to invalid parameter. 208 */ 209 UINT nx_azure_iot_hub_client_deinitialize(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr); 210 211 /** 212 * @brief Add more trusted certificate in the IoT Hub client if needed. It can be called multiple times to set multiple trusted certificates. 213 * 214 * @param[in] hub_client_ptr A pointer to a #NX_AZURE_IOT_HUB_CLIENT. 215 * @param[in] trusted_certificate A pointer to a `NX_SECURE_X509_CERT`, which is the trusted certificate. 216 * @return A `UINT` with the result of the API. 217 * @retval #NX_AZURE_IOT_SUCCESS Successfully add trusted certificate to Azure IoT Hub Instance. 218 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to add trusted certificate to Azure IoT Hub Instance due to invalid parameter. 219 * @retval #NX_AZURE_IOT_INSUFFICIENT_BUFFER_SPACE Fail to add trusted certificate due to NX_AZURE_IOT_MAX_NUM_OF_TRUSTED_CERTS is too small. 220 */ 221 UINT nx_azure_iot_hub_client_trusted_cert_add(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 222 NX_SECURE_X509_CERT *trusted_certificate); 223 224 /** 225 * @brief Set the client certificate in the IoT Hub client. It can be called multiple times to set certificate chain. 226 * 227 * @param[in] hub_client_ptr A pointer to a #NX_AZURE_IOT_HUB_CLIENT. 228 * @param[in] device_certificate A pointer to a `NX_SECURE_X509_CERT`, which is the device certificate. 229 * @return A `UINT` with the result of the API. 230 * @retval #NX_AZURE_IOT_SUCCESS Successfully set device certificate to Azure IoT Hub Instance. 231 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to set device certificate to Azure IoT Hub Instance due to invalid parameter. 232 * @retval #NX_AZURE_IOT_INSUFFICIENT_BUFFER_SPACE Fail to set device certificate due to NX_AZURE_IOT_MAX_NUM_OF_DEVICE_CERTS is too small. 233 */ 234 UINT nx_azure_iot_hub_client_device_cert_set(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 235 NX_SECURE_X509_CERT *device_certificate); 236 237 /** 238 * @brief Set symmetric key in the IoT Hub client. 239 * 240 * @param[in] hub_client_ptr A pointer to a #NX_AZURE_IOT_HUB_CLIENT. 241 * @param[in] symmetric_key A pointer to a symmetric key. 242 * @param[in] symmetric_key_length Length of `symmetric_key`. 243 * @return A `UINT` with the result of the API. 244 * @retval #NX_AZURE_IOT_SUCCESS Successfully set symmetric key to IoTHub client. 245 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to set symmetric key to IoTHub client due to invalid parameter. 246 */ 247 UINT nx_azure_iot_hub_client_symmetric_key_set(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 248 const UCHAR *symmetric_key, UINT symmetric_key_length); 249 250 /** 251 * @brief Set model id in the IoT Hub client to enable PnP. 252 * @note To enable pnp, this routine should be called immediately after nx_azure_iot_hub_client_initialize(), 253 if model id is not set, only normal iothub APIs can be used, if it is set, only pnp APIs can be used. 254 * 255 * @param[in] hub_client_ptr A pointer to a #NX_AZURE_IOT_HUB_CLIENT. 256 * @param[in] model_id_ptr A pointer to a model id. 257 * @param[in] model_id_length Length of `model id`. 258 * @return A `UINT` with the result of the API. 259 * @retval #NX_AZURE_IOT_SUCCESS Successfully set model id to IoTHub client. 260 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to set model id to IoTHub client due to invalid parameter. 261 */ 262 UINT nx_azure_iot_hub_client_model_id_set(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 263 const UCHAR *model_id_ptr, UINT model_id_length); 264 265 /** 266 * @brief Add component name to IoT Hub client. 267 * @note This routine should be called for all the component in the PnP model. 268 * 269 * @param[in] hub_client_ptr A pointer to a #NX_AZURE_IOT_HUB_CLIENT. 270 * @param[in] component_name_ptr A pointer to component, that is part of PnP model. 271 * @param[in] component_name_length Length of the `component_name_ptr`. 272 * @return A `UINT` with the result of the API. 273 * @retval #NX_AZURE_IOT_SUCCESS Successfully add the component name to the PnP client. 274 * @retval #NX_AZURE_IOT_INSUFFICIENT_BUFFER_SPACE Fail to add the component name due to out of memory. 275 */ 276 UINT nx_azure_iot_hub_client_component_add(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 277 const UCHAR *component_name_ptr, 278 USHORT component_name_length); 279 280 #ifdef NXD_MQTT_OVER_WEBSOCKET 281 /** 282 * @brief Enable using MQTT over WebSocket to connect to IoTHub. 283 * 284 * @param[in] hub_client_ptr A pointer to a #NX_AZURE_IOT_HUB_CLIENT. 285 * @return A `UINT` with the result of the API. 286 * @retval #NX_AZURE_IOT_SUCCESS Successful if MQTT over WebSocket is enabled. 287 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to enable C2D message receiving due to invalid parameter. 288 * @retval NXD_MQTT_NOT_CONNECTED Fail to enable C2D message receiving due to MQTT not connected. 289 * @retval NXD_MQTT_PACKET_POOL_FAILURE Fail to enable C2D message receiving due to no available packet in pool. 290 * @retval NXD_MQTT_COMMUNICATION_FAILURE Fail to enable C2D message receiving due to TCP/TLS error. 291 */ 292 UINT nx_azure_iot_hub_client_websocket_enable(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr); 293 #endif /* NXD_MQTT_OVER_WEBSOCKET */ 294 295 /** 296 * @brief Connect to IoT Hub. 297 * 298 * @param[in] hub_client_ptr A pointer to a #NX_AZURE_IOT_HUB_CLIENT. 299 * @param[in] clean_session Can be set to `0` to re-use current session, or `1` to start new session 300 * @param[in] wait_option Number of ticks to wait for internal resources to be available. 301 * @return A `UINT` with the result of the API. 302 * @retval #NX_AZURE_IOT_SUCCESS Successful if connected to Azure IoT Hub. 303 * @retval #NX_AZURE_IOT_CONNECTING Successfully started connection but not yet completed. 304 * @retval #NX_AZURE_IOT_ALREADY_CONNECTED Already connected to Azure IoT Hub. 305 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to connect to Azure IoT Hub due to invalid parameter. 306 * @retval #NX_AZURE_IOT_SDK_CORE_ERROR Fail to connect to Azure IoT Hub due to SDK core error. 307 * @retval #NX_AZURE_IOT_INSUFFICIENT_BUFFER_SPACE Fail to connect to Azure IoT Hub due to buffer size is too small. 308 * @retval NX_DNS_QUERY_FAILED Fail to connect to Azure IoT Hub due to hostname can not be resolved. 309 * @retval NX_NO_PACKET Fail to connect to Azure IoT Hub due to no available packet in pool. 310 * @retval NX_INVALID_PARAMETERS Fail to connect to Azure IoT Hub due to invalid parameters. 311 * @retval NX_SECURE_TLS_INSUFFICIENT_METADATA_SPACE Fail to connect to Azure IoT Hub due to insufficient metadata space. 312 * @retval NX_SECURE_TLS_UNSUPPORTED_CIPHER Fail to connect to Azure IoT Hub due to unsupported cipher. 313 * @retval NXD_MQTT_ALREADY_CONNECTED Fail to connect to Azure IoT Hub due to MQTT session is not disconnected. 314 * @retval NXD_MQTT_CONNECT_FAILURE Fail to connect to Azure IoT Hub due to TCP/TLS connect error. 315 * @retval NXD_MQTT_COMMUNICATION_FAILURE Fail to connect to Azure IoT Hub due to MQTT connect error. 316 * @retval NXD_MQTT_ERROR_SERVER_UNAVAILABLE Fail to connect to Azure IoT Hub due to server unavailable. 317 * @retval NXD_MQTT_ERROR_NOT_AUTHORIZED Fail to connect to Azure IoT Hub due to authentication error. 318 */ 319 UINT nx_azure_iot_hub_client_connect(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 320 UINT clean_session, UINT wait_option); 321 322 /** 323 * @brief Disconnect from IoT Hub. 324 * 325 * @param[in] hub_client_ptr A pointer to a #NX_AZURE_IOT_HUB_CLIENT. 326 * @return A `UINT` with the result of the API. 327 * @retval #NX_AZURE_IOT_SUCCESS Successful if client disconnects. 328 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to disconnect due to invalid parameter. 329 */ 330 UINT nx_azure_iot_hub_client_disconnect(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr); 331 332 /** 333 * @brief Sets connection status callback function 334 * @details This routine sets the connection status callback. This callback function is 335 * invoked when IoT Hub status is changed, such as when the client is connected to IoT Hub. 336 * The different statuses include: 337 * 338 * - #NX_AZURE_IOT_SUCCESS 339 * - NX_SECURE_TLS_ALERT_RECEIVED 340 * - NX_SECURE_TLS_NO_SUPPORTED_CIPHERS 341 * - NX_SECURE_X509_CHAIN_VERIFY_FAILURE 342 * - NXD_MQTT_CONNECT_FAILURE 343 * - NXD_MQTT_ERROR_SERVER_UNAVAILABLE 344 * - NXD_MQTT_ERROR_NOT_AUTHORIZED 345 * - NX_AZURE_IOT_DISCONNECTED 346 * 347 * Setting the callback function to `NULL` disables the callback function. 348 * 349 * @param[in] hub_client_ptr A pointer to a #NX_AZURE_IOT_HUB_CLIENT. 350 * @param[in] connection_status_cb Pointer to a callback function invoked on connection status is changed. 351 * @return A `UINT` with the result of the API. 352 * @retval #NX_AZURE_IOT_SUCCESS Successful if connection status callback is set. 353 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to set connection status callback due to invalid parameter. 354 */ 355 UINT nx_azure_iot_hub_client_connection_status_callback_set(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 356 VOID (*connection_status_cb)( 357 struct NX_AZURE_IOT_HUB_CLIENT_STRUCT *client_ptr, 358 UINT status)); 359 360 /** 361 * @brief Sets receive callback function 362 * @details This routine sets the IoT Hub receive callback function. This callback 363 * function is invoked when a message is received from Azure IoT hub. Setting the 364 * callback function to `NULL` disables the callback function. Message types can be: 365 * 366 * - #NX_AZURE_IOT_HUB_CLOUD_TO_DEVICE_MESSAGE 367 * - #NX_AZURE_IOT_HUB_COMMAND / NX_AZURE_IOT_HUB_DIRECT_METHOD 368 * - #NX_AZURE_IOT_HUB_PROPERTIES / NX_AZURE_IOT_HUB_DEVICE_TWIN_PROPERTIES 369 * - #NX_AZURE_IOT_HUB_WRITABLE_PROPERTIES / NX_AZURE_IOT_HUB_DEVICE_TWIN_DESIRED_PROPERTIES 370 * 371 * @param[in] hub_client_ptr A pointer to a #NX_AZURE_IOT_HUB_CLIENT. 372 * @param[in] message_type Message type of callback function. 373 * @param[in] callback_ptr Pointer to a callback function invoked if the specified message type is received. 374 * @param[in] callback_args Pointer to an argument passed to callback function. 375 * @return A `UINT` with the result of the API. 376 * @retval #NX_AZURE_IOT_SUCCESS Successful if callback function is set. 377 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to set receive callback due to invalid parameter. 378 * @retval #NX_AZURE_IOT_NOT_SUPPORTED Fail to set receive callback due to message_type not supported. 379 */ 380 UINT nx_azure_iot_hub_client_receive_callback_set(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 381 UINT message_type, 382 VOID (*callback_ptr)( 383 NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 384 VOID *args), 385 VOID *callback_args); 386 387 /** 388 * @brief Creates telemetry message. 389 * @details This routine prepares a packet for sending telemetry data. After the packet is properly created, 390 * application owns the `NX_PACKET` and can add additional user-defined properties before sending out. 391 * 392 * @param[in] hub_client_ptr A pointer to a #NX_AZURE_IOT_HUB_CLIENT. 393 * @param[out] packet_pptr Returned allocated `NX_PACKET` on success. Caller owns the `NX_PACKET` memory. 394 * @param[in] wait_option Ticks to wait if no packet is available. 395 * @return A `UINT` with the result of the API. 396 * @retval #NX_AZURE_IOT_SUCCESS Successful if a packet is allocated. 397 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to allocate telemetry message due to invalid parameter. 398 * @retval #NX_AZURE_IOT_SDK_CORE_ERROR Fail to allocate telemetry message due to SDK core error. 399 * @retval NX_NO_PACKET Fail to allocate telemetry message due to no available packet in pool. 400 */ 401 UINT nx_azure_iot_hub_client_telemetry_message_create(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 402 NX_PACKET **packet_pptr, 403 UINT wait_option); 404 405 /** 406 * @brief Deletes telemetry message 407 * 408 * @param[in] packet_ptr The `NX_PACKET` to release. 409 * @return A `UINT` with the result of the API. 410 * @retval #NX_AZURE_IOT_SUCCESS Successful if a packet is deallocated. 411 */ 412 UINT nx_azure_iot_hub_client_telemetry_message_delete(NX_PACKET *packet_ptr); 413 414 /** 415 * @brief Set component to telemetry message. 416 * @details This routine allows an application to set a component name to a telemetry message 417 * before it is being sent. The component is stored in the sequence which the routine is being called. 418 * 419 * @param[in] packet_ptr A pointer to telemetry property packet. 420 * @param[in] component_name_ptr A pointer to a component name. 421 * @param[in] component_name_length Length of `component_name_ptr`. Does not include the `NULL` terminator. 422 * @param[in] wait_option Ticks to wait if no packet is available. 423 * @return A `UINT` with the result of the API. 424 * @retval #NX_AZURE_IOT_SUCCESS Successful if component is set. 425 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to set component due to invalid parameter. 426 * @retval NX_NO_PACKET Fail to set component due to no available packet in pool. 427 */ 428 UINT nx_azure_iot_hub_client_telemetry_component_set(NX_PACKET *packet_pptr, 429 const UCHAR *component_name_ptr, 430 USHORT component_name_length, 431 UINT wait_option); 432 433 /** 434 * @brief Add property to telemetry message 435 * @details This routine allows an application to add user-defined properties to a telemetry message 436 * before it is being sent. This routine can be called multiple times to add all the properties to 437 * the message. The properties are stored in the sequence which the routine is being called. 438 * The property must be added after a telemetry packet is created, and before the telemetry 439 * message is being sent. 440 * 441 * @param[in] packet_ptr A pointer to telemetry property packet. 442 * @param[in] property_name Pointer to property name. 443 * @param[in] property_name_length Length of property name. 444 * @param[in] property_value Pointer to property value. 445 * @param[in] property_value_length Length of property value. 446 * @param[in] wait_option Ticks to wait if packet needs to be expanded. 447 * @return A `UINT` with the result of the API. 448 * @retval #NX_AZURE_IOT_SUCCESS Successful if property is added. 449 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to add property due to invalid parameter. 450 * @retval NX_NO_PACKET Fail to add property due to no available packet in pool. 451 */ 452 UINT nx_azure_iot_hub_client_telemetry_property_add(NX_PACKET *packet_ptr, 453 const UCHAR *property_name, USHORT property_name_length, 454 const UCHAR *property_value, USHORT property_value_length, 455 UINT wait_option); 456 457 /** 458 * @brief Sends telemetry message to IoTHub. 459 * @details This routine sends telemetry to IoTHub, with `packet_ptr` containing all the properties. 460 * On successful return of this function, ownership of `NX_PACKET` is released. 461 * 462 * @param[in] hub_client_ptr A pointer to a #NX_AZURE_IOT_HUB_CLIENT. 463 * @param[in] packet_ptr A pointer to telemetry property packet. 464 * @param[in] telemetry_data Pointer to telemetry data. 465 * @param[in] data_size Size of telemetry data. 466 * @param[in] wait_option Ticks to wait for message to be sent. 467 * @return A `UINT` with the result of the API. 468 * @retval #NX_AZURE_IOT_SUCCESS Successful if telemetry message is sent out. 469 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to send telemetry message due to invalid parameter. 470 * @retval #NX_AZURE_IOT_INVALID_PACKET Fail to send telemetry message due to packet is invalid. 471 * @retval NXD_MQTT_PACKET_POOL_FAILURE Fail to send telemetry message due to no available packet in pool. 472 * @retval NXD_MQTT_COMMUNICATION_FAILURE Fail to send telemetry message due to TCP/TLS error. 473 * @retval NX_NO_PACKET Fail to send telemetry message due to no available packet in pool. 474 */ 475 UINT nx_azure_iot_hub_client_telemetry_send(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, NX_PACKET *packet_ptr, 476 const UCHAR *telemetry_data, UINT data_size, UINT wait_option); 477 478 /** 479 * @brief Enable receiving C2D message from IoTHub. 480 * 481 * @param[in] hub_client_ptr A pointer to a #NX_AZURE_IOT_HUB_CLIENT. 482 * @return A `UINT` with the result of the API. 483 * @retval #NX_AZURE_IOT_SUCCESS Successful if C2D message receiving is enabled. 484 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to enable C2D message receiving due to invalid parameter. 485 * @retval NXD_MQTT_NOT_CONNECTED Fail to enable C2D message receiving due to MQTT not connected. 486 * @retval NXD_MQTT_PACKET_POOL_FAILURE Fail to enable C2D message receiving due to no available packet in pool. 487 * @retval NXD_MQTT_COMMUNICATION_FAILURE Fail to enable C2D message receiving due to TCP/TLS error. 488 */ 489 UINT nx_azure_iot_hub_client_cloud_message_enable(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr); 490 491 /** 492 * @brief Disables receiving C2D message from IoTHub 493 * 494 * @param[in] hub_client_ptr A pointer to a #NX_AZURE_IOT_HUB_CLIENT. 495 * @return A `UINT` with the result of the API. 496 * @retval #NX_AZURE_IOT_SUCCESS Successful if C2D message receiving is disabled. 497 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to disable C2D message receiving due to invalid parameter. 498 * @retval NXD_MQTT_NOT_CONNECTED Fail to disable C2D message receiving due to MQTT not connected. 499 * @retval NXD_MQTT_PACKET_POOL_FAILURE Fail to disable C2D message receiving due to no available packet in pool. 500 * @retval NXD_MQTT_COMMUNICATION_FAILURE Fail to disable C2D message receiving due to TCP/TLS error. 501 */ 502 UINT nx_azure_iot_hub_client_cloud_message_disable(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr); 503 504 /** 505 * @brief Receives C2D message from IoTHub 506 * @details This routine receives C2D message from IoT Hub. If there are no messages in the receive 507 * queue, this routine can block.The amount of time it waits for a message is determined 508 * by the `wait_option` parameter. 509 * 510 * @param[in] hub_client_ptr A pointer to a #NX_AZURE_IOT_HUB_CLIENT. 511 * @param[out] packet_pptr Return a `NX_PACKET` pointer with C2D message on success. Caller owns the `NX_PACKET` memory. 512 * @param[in] wait_option Ticks to wait for message to arrive. 513 * @return A `UINT` with the result of the API. 514 * @retval #NX_AZURE_IOT_SUCCESS Successful if C2D message is received. 515 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to receive C2D message due to invalid parameter. 516 * @retval #NX_AZURE_IOT_NOT_ENABLED Fail to receive C2D message due to it is not enabled. 517 * @retval #NX_AZURE_IOT_NO_PACKET Fail to receive C2D message due to timeout. 518 * @retval #NX_AZURE_IOT_DISCONNECTED Fail to receive C2D message due to disconnection. 519 */ 520 UINT nx_azure_iot_hub_client_cloud_message_receive(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 521 NX_PACKET **packet_pptr, UINT wait_option); 522 523 /** 524 * @brief Retrieve the property with given property name in the C2D message. 525 * 526 * @param[in] hub_client_ptr A pointer to a NX_AZURE_IOT_HUB_CLIENT. 527 * @param[in] packet_ptr Pointer to NX_PACKET containing C2D message. 528 * @param[in] property_name A `UCHAR` pointer to property name. 529 * @param[in] property_name_length Length of `property_name`. 530 * @param[out] property_value Pointer to `UCHAR` array that contains property values. 531 * @param[out] property_value_length A `USHORT` pointer to size of `property_value`. 532 * @return A `UINT` with the result of the API. 533 * @retval #NX_AZURE_IOT_SUCCESS Successful if property is found and copied successfully into user buffer. 534 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to find the property due to invalid parameter. 535 * @retval #NX_AZURE_IOT_INVALID_PACKET Fail to find the property due to the packet is invalid. 536 * @retval #NX_AZURE_IOT_NOT_FOUND Property is not found. 537 * @retval #NX_AZURE_IOT_SDK_CORE_ERROR Fail to find the property due to parsing error. 538 */ 539 UINT nx_azure_iot_hub_client_cloud_message_property_get(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 540 NX_PACKET *packet_ptr, const UCHAR *property_name, 541 USHORT property_name_length, const UCHAR **property_value, 542 USHORT *property_value_length); 543 544 /** 545 * @brief Enables receiving direct method messages from IoTHub 546 * 547 * @param[in] hub_client_ptr A pointer to a #NX_AZURE_IOT_HUB_CLIENT. 548 * @return 549 * @retval #NX_AZURE_IOT_SUCCESS Successful if direct method message receiving is enabled. 550 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to enable direct method message receiving due to invalid parameter. 551 * @retval NXD_MQTT_NOT_CONNECTED Fail to enable direct method message receiving due to MQTT not connected. 552 * @retval NXD_MQTT_PACKET_POOL_FAILURE Fail to enable direct method message receiving due to no available packet in pool. 553 * @retval NXD_MQTT_COMMUNICATION_FAILURE Fail to enable direct method message receiving due to TCP/TLS error. 554 */ 555 UINT nx_azure_iot_hub_client_direct_method_enable(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr); 556 557 /** 558 * @brief Disables receiving direct method messages from IoTHub 559 * 560 * @param[in] hub_client_ptr A pointer to a #NX_AZURE_IOT_HUB_CLIENT. 561 * @return A `UINT` with the result of the API. 562 * @retval #NX_AZURE_IOT_SUCCESS Successful if direct method message receiving is disabled. 563 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to disable direct method message receiving due to invalid parameter. 564 * @retval NXD_MQTT_NOT_CONNECTED Fail to disable direct method message receiving due to MQTT not connected. 565 * @retval NXD_MQTT_PACKET_POOL_FAILURE Fail to disable direct method message receiving due to no available packet in pool. 566 * @retval NXD_MQTT_COMMUNICATION_FAILURE Fail to disable direct method message receiving due to TCP/TLS error. 567 */ 568 UINT nx_azure_iot_hub_client_direct_method_disable(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr); 569 570 /** 571 * @brief Receives direct method message from IoTHub 572 * @details This routine receives direct method message from IoT Hub. If there are no 573 * messages in the receive queue, this routine can block. The amount of time it waits for a 574 * message is determined by the `wait_option` parameter. 575 * 576 * @param[in] hub_client_ptr A pointer to a #NX_AZURE_IOT_HUB_CLIENT. 577 * @param[out] method_name_pptr Return a pointer to method name on success. 578 * @param[out] method_name_length_ptr Return length of `method_name_pptr` on success. 579 * @param[out] context_pptr Return a pointer to the context pointer on success. 580 * @param[out] context_length_ptr Return length of `context` on success. 581 * @param[out] packet_pptr Return `NX_PACKET` containing the method payload on success. Caller owns the `NX_PACKET` memory. 582 * @param[in] wait_option Ticks to wait for message to arrive. 583 * @return A `UINT` with the result of the API. 584 * @retval #NX_AZURE_IOT_SUCCESS Successful if direct method message is received. 585 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to receive direct method message due to invalid parameter. 586 * @retval #NX_AZURE_IOT_NOT_ENABLED Fail to receive direct method message due to it is not enabled. 587 * @retval #NX_AZURE_IOT_NO_PACKET Fail to receive direct method message due to timeout. 588 * @retval #NX_AZURE_IOT_INVALID_PACKET Fail to receive direct method message due to invalid packet. 589 * @retval #NX_AZURE_IOT_SDK_CORE_ERROR Fail to receive direct method message due to SDK core error. 590 * @retval #NX_AZURE_IOT_DISCONNECTED Fail to receive direct method message due to disconnect. 591 */ 592 UINT nx_azure_iot_hub_client_direct_method_message_receive(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 593 const UCHAR **method_name_pptr, USHORT *method_name_length_ptr, 594 VOID **context_pptr, USHORT *context_length_ptr, 595 NX_PACKET **packet_pptr, UINT wait_option); 596 597 /** 598 * @brief Return response to direct method message from IoTHub 599 * @details This routine returns response to the direct method message from IoT Hub. 600 * @note request_id ties the correlation between direct method receive and response. 601 * 602 * @param[in] hub_client_ptr A pointer to a #NX_AZURE_IOT_HUB_CLIENT. 603 * @param[in] status_code Status code for direct method. 604 * @param[in] context_ptr Pointer to context return from nx_azure_iot_hub_client_direct_method_message_receive(). 605 * @param[in] context_length Length of context. 606 * @param[in] payload Pointer to `UCHAR` containing the payload for the direct method response. Payload is in JSON format. 607 * @param[in] payload_length Length of `payload` 608 * @param[in] wait_option Ticks to wait for message to send. 609 * @return A `UINT` with the result of the API. 610 * @retval #NX_AZURE_IOT_SUCCESS Successful if direct method response is send. 611 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to send direct method response due to invalid parameter. 612 * @retval #NX_AZURE_IOT_SDK_CORE_ERROR Fail to send direct method response due to SDK core error. 613 * @retval NX_NO_PACKET Fail send direct method response due to no available packet in pool. 614 */ 615 UINT nx_azure_iot_hub_client_direct_method_message_response(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 616 UINT status_code, VOID *context_ptr, 617 USHORT context_length, const UCHAR *payload, 618 UINT payload_length, UINT wait_option); 619 620 /** 621 * @brief Enables receiving command messages from IoTHub 622 * 623 * @param[in] hub_client_ptr A pointer to a #NX_AZURE_IOT_HUB_CLIENT. 624 * @return 625 * @retval #NX_AZURE_IOT_SUCCESS Successful if command message receiving is enabled. 626 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to enable command message receiving due to invalid parameter. 627 * @retval NXD_MQTT_NOT_CONNECTED Fail to enable command message receiving due to MQTT not connected. 628 * @retval NXD_MQTT_PACKET_POOL_FAILURE Fail to enable command message receiving due to no available packet in pool. 629 * @retval NXD_MQTT_COMMUNICATION_FAILURE Fail to enable command message receiving due to TCP/TLS error. 630 */ 631 UINT nx_azure_iot_hub_client_command_enable(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr); 632 633 /** 634 * @brief Disables receiving command messages from IoTHub 635 * 636 * @param[in] hub_client_ptr A pointer to a #NX_AZURE_IOT_HUB_CLIENT. 637 * @return A `UINT` with the result of the API. 638 * @retval #NX_AZURE_IOT_SUCCESS Successful if command message receiving is disabled. 639 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to disable command message receiving due to invalid parameter. 640 * @retval NXD_MQTT_NOT_CONNECTED Fail to disable command message receiving due to MQTT not connected. 641 * @retval NXD_MQTT_PACKET_POOL_FAILURE Fail to disable command message receiving due to no available packet in pool. 642 * @retval NXD_MQTT_COMMUNICATION_FAILURE Fail to disable command message receiving due to TCP/TLS error. 643 */ 644 UINT nx_azure_iot_hub_client_command_disable(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr); 645 646 /** 647 * @brief Receives PnP command message from IoTHub 648 * @details This routine receives command message from IoT Hub. If there are no 649 * messages in the receive queue, this routine can block. The amount of time it waits for a 650 * message is determined by the `wait_option` parameter. 651 * 652 * @param[in] hub_client_ptr A pointer to a #NX_AZURE_IOT_HUB_CLIENT. 653 * @param[out] component_name_pptr Return a pointer to PnP component name on success. 654 * @param[out] component_name_length_ptr Return length of `*component_name_pptr` on success. 655 * @param[out] command_name_pptr Return a pointer to command name on success. 656 * @param[out] command_name_length_ptr Return length of `command_name_pptr` on success. 657 * @param[out] context_pptr Return a pointer to the context pointer on success. 658 * @param[out] context_length_ptr Return length of `context` on success. 659 * @param[out] packet_pptr Return `NX_PACKET` containing the command payload on success. Caller owns the `NX_PACKET` memory. 660 * @param[in] wait_option Ticks to wait for message to arrive. 661 * @return A `UINT` with the result of the API. 662 * @retval #NX_AZURE_IOT_SUCCESS Successful if command message is received. 663 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to receive command message due to invalid parameter. 664 * @retval #NX_AZURE_IOT_NOT_ENABLED Fail to receive command message due to it is not enabled. 665 * @retval #NX_AZURE_IOT_NO_PACKET Fail to receive command message due to timeout. 666 * @retval #NX_AZURE_IOT_INVALID_PACKET Fail to receive command message due to invalid packet. 667 * @retval #NX_AZURE_IOT_SDK_CORE_ERROR Fail to receive command message due to SDK core error. 668 * @retval #NX_AZURE_IOT_DISCONNECTED Fail to receive command message due to disconnect. 669 */ 670 UINT nx_azure_iot_hub_client_command_message_receive(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 671 const UCHAR **component_name_pptr, USHORT *component_name_length_ptr, 672 const UCHAR **command_name_pptr, USHORT *command_name_length_ptr, 673 VOID **context_pptr, USHORT *context_length_ptr, 674 NX_PACKET **packet_pptr, UINT wait_option); 675 676 /** 677 * @brief Return response to PnP command message from IoTHub 678 * @details This routine returns response to the command message from IoT Hub. 679 * @note request_id ties the correlation between command receive and response. 680 * 681 * @param[in] hub_client_ptr A pointer to a #NX_AZURE_IOT_HUB_CLIENT. 682 * @param[in] status_code Status code for command. 683 * @param[in] context_ptr Pointer to context return from nx_azure_iot_hub_client_command_message_receive(). 684 * @param[in] context_length Length of context. 685 * @param[in] payload Pointer to `UCHAR` containing the payload for the command response. Payload is in JSON format. 686 * @param[in] payload_length Length of `payload` 687 * @param[in] wait_option Ticks to wait for message to send. 688 * @return A `UINT` with the result of the API. 689 * @retval #NX_AZURE_IOT_SUCCESS Successful if command response is send. 690 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to send command response due to invalid parameter. 691 * @retval #NX_AZURE_IOT_SDK_CORE_ERROR Fail to send command response due to SDK core error. 692 * @retval NX_NO_PACKET Fail send command response due to no available packet in pool. 693 */ 694 UINT nx_azure_iot_hub_client_command_message_response(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 695 UINT status_code, VOID *context_ptr, 696 USHORT context_length, const UCHAR *payload, 697 UINT payload_length, UINT wait_option); 698 699 /** 700 * @brief Enables device twin feature 701 * @details This routine enables device twin feature. 702 * 703 * @param[in] hub_client_ptr A pointer to a #NX_AZURE_IOT_HUB_CLIENT 704 * @return A `UINT` with the result of the API. 705 * @retval #NX_AZURE_IOT_SUCCESS Successful if device twin feature is enabled. 706 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to enable device twin feature due to invalid parameter. 707 * @retval NXD_MQTT_NOT_CONNECTED Fail to enable device twin feature due to MQTT not connected. 708 * @retval NXD_MQTT_PACKET_POOL_FAILURE Fail to enable device twin feature due to no available packet in pool. 709 * @retval NXD_MQTT_COMMUNICATION_FAILURE Fail to enable device twin feature due to TCP/TLS error. 710 */ 711 UINT nx_azure_iot_hub_client_device_twin_enable(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr); 712 713 /** 714 * @brief Disables device twin feature 715 * @details This routine disables device twin feature. 716 * 717 * @param[in] hub_client_ptr A pointer to a #NX_AZURE_IOT_HUB_CLIENT 718 * @return A `UINT` with the result of the API. 719 * @retval #NX_AZURE_IOT_SUCCESS Successful if device twin feature is disabled. 720 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to disable device twin feature due to invalid parameter. 721 * @retval NXD_MQTT_NOT_CONNECTED Fail to disable device twin feature due to MQTT not connected. 722 * @retval NXD_MQTT_PACKET_POOL_FAILURE Fail to disable device twin feature due to no available packet in pool. 723 * @retval NXD_MQTT_COMMUNICATION_FAILURE Fail to disable device twin feature due to TCP/TLS error. 724 */ 725 UINT nx_azure_iot_hub_client_device_twin_disable(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr); 726 727 /** 728 * @brief Sets reported properties response callback function 729 * @details This routine sets the reponse receive callback function for reported properties. This callback 730 * function is invoked when a response is received from Azure IoT hub for reported properties and no 731 * thread is waiting for response. Setting the callback function to `NULL` disables the callback 732 * function. 733 * 734 * @param[in] hub_client_ptr A pointer to a #NX_AZURE_IOT_HUB_CLIENT. 735 * @param[in] callback_ptr Pointer to a callback function invoked. 736 * @param[in] callback_args Pointer to an argument passed to callback function. 737 * @return A `UINT` with the result of the API. 738 * @retval #NX_AZURE_IOT_SUCCESS Successful if callback function is set. 739 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to set callback due to invalid parameter. 740 */ 741 UINT nx_azure_iot_hub_client_reported_properties_response_callback_set(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 742 VOID (*callback_ptr)( 743 NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 744 UINT request_id, 745 UINT response_status, 746 ULONG version, 747 VOID *args), 748 VOID *callback_args); 749 750 /* Map old API to new API. */ 751 #define nx_azure_iot_hub_client_report_properties_response_callback_set nx_azure_iot_hub_client_reported_properties_response_callback_set 752 753 /** 754 * @brief Send device twin reported properties to IoT Hub 755 * @details This routine sends device twin reported properties to IoT Hub. 756 * 757 * @param[in] hub_client_ptr A pointer to a #NX_AZURE_IOT_HUB_CLIENT. 758 * @param[in] message_buffer JSON document containing the reported properties. 759 * @param[in] message_length Length of JSON document. 760 * @param[out] request_id_ptr Request Id assigned to the request. 761 * @param[out] response_status_ptr Status return for successful send of reported properties. 762 * @param[out] version_ptr Version return for successful send of reported properties. 763 * @param[in] wait_option Ticks to wait for message to send. 764 * @return A `UINT` with the result of the API. 765 * @retval #NX_AZURE_IOT_SUCCESS Successful if device twin reported properties is sent. 766 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to send reported properties due to invalid parameter. 767 * @retval #NX_AZURE_IOT_NOT_ENABLED Fail to send reported properties due to device twin is not enabled. 768 * @retval #NX_AZURE_IOT_SDK_CORE_ERROR Fail to send reported properties due to SDK core error. 769 * @retval #NX_AZURE_IOT_INSUFFICIENT_BUFFER_SPACE Fail to send reported properties due to buffer size is too small. 770 * @retval #NX_AZURE_IOT_NO_PACKET Fail to send reported properties due to no packet available. 771 * @retval NX_NO_PACKET Fail to send reported properties due to no packet available. 772 * @retval #NX_AZURE_IOT_DISCONNECTED Fail to send reported properties due to disconnect. 773 */ 774 UINT nx_azure_iot_hub_client_device_twin_reported_properties_send(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 775 const UCHAR *message_buffer, UINT message_length, 776 UINT *request_id_ptr, UINT *response_status_ptr, 777 ULONG *version_ptr, UINT wait_option); 778 779 /** 780 * @brief Request complete device twin properties 781 * @details This routine requests complete device twin properties. 782 * 783 * @param[in] hub_client_ptr A pointer to a #NX_AZURE_IOT_HUB_CLIENT 784 * @param[in] wait_option Ticks to wait for sending request. 785 * @return A `UINT` with the result of the API. 786 * @retval #NX_AZURE_IOT_SUCCESS Successful if device twin properties is requested. 787 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to send device twin request due to invalid parameter. 788 * @retval #NX_AZURE_IOT_NO_SUBSCRIBE_ACK Fail to send device twin request due to no subscribe ack. 789 * @retval #NX_AZURE_IOT_SDK_CORE_ERROR Fail to send device twin request due to SDK core error. 790 * @retval #NX_AZURE_IOT_INSUFFICIENT_BUFFER_SPACE Fail to send device twin request due to buffer size is too small. 791 * @retval #NX_AZURE_IOT_NO_PACKET Fail to send device twin request due to no packet available. 792 * @retval NX_NO_PACKET Fail to send device twin request due to no packet available. 793 */ 794 UINT nx_azure_iot_hub_client_device_twin_properties_request(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 795 UINT wait_option); 796 797 /** 798 * @brief Receive complete device twin properties 799 * @details This routine receives complete device twin properties. 800 * 801 * @param[in] hub_client_ptr A pointer to a #NX_AZURE_IOT_HUB_CLIENT 802 * @param[out] packet_pptr Pointer to #NX_PACKET* that contains complete twin document. Caller owns the `NX_PACKET` memory. 803 * @param[in] wait_option Ticks to wait for message to receive. 804 * @return A `UINT` with the result of the API. 805 * @retval #NX_AZURE_IOT_SUCCESS Successful if device twin properties is received. 806 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to receive device twin properties due to invalid parameter. 807 * @retval #NX_AZURE_IOT_NOT_ENABLED Fail to receive device twin properties due to it is not enabled. 808 * @retval #NX_AZURE_IOT_NO_PACKET Fail to receive device twin properties due to timeout. 809 * @retval #NX_AZURE_IOT_INVALID_PACKET Fail to receive device twin properties due to invalid packet. 810 * @retval #NX_AZURE_IOT_SDK_CORE_ERROR Fail to receive device twin properties due to SDK core error. 811 * @retval #NX_AZURE_IOT_SERVER_RESPONSE_ERROR Response code from server is not 2xx. 812 * @retval #NX_AZURE_IOT_DISCONNECTED Fail to receive device twin properties due to disconnect. 813 */ 814 UINT nx_azure_iot_hub_client_device_twin_properties_receive(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 815 NX_PACKET **packet_pptr, UINT wait_option); 816 817 /** 818 * @brief Receive desired properties form IoTHub 819 * @details This routine receives desired properties from IoTHub. 820 * 821 * @param[in] hub_client_ptr A pointer to a #NX_AZURE_IOT_HUB_CLIENT. 822 * @param[out] packet_pptr Pointer to #NX_PACKET* that contains complete twin document. Caller owns the `NX_PACKET` memory. 823 * @param[in] wait_option Ticks to wait for message to receive. 824 * @return A `UINT` with the result of the API. 825 * @retval #NX_AZURE_IOT_SUCCESS Successful if desired properties is received. 826 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to receive desired properties due to invalid parameter. 827 * @retval #NX_AZURE_IOT_NOT_ENABLED Fail to receive desired properties due to it is not enabled. 828 * @retval #NX_AZURE_IOT_NO_PACKET Fail to receive desired properties due to timeout. 829 * @retval #NX_AZURE_IOT_INVALID_PACKET Fail to receive desired properties due to invalid packet. 830 * @retval #NX_AZURE_IOT_DISCONNECTED Fail to receive desired properties due to disconnect. 831 */ 832 UINT nx_azure_iot_hub_client_device_twin_desired_properties_receive(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 833 NX_PACKET **packet_pptr, UINT wait_option); 834 835 /** 836 * @brief Enables properties feature 837 * @details This routine enables property feature. 838 * 839 * @param[in] hub_client_ptr A pointer to a #NX_AZURE_IOT_HUB_CLIENT 840 * @return A `UINT` with the result of the API. 841 * @retval #NX_AZURE_IOT_SUCCESS Successful if property feature is enabled. 842 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to enable property feature due to invalid parameter. 843 * @retval NXD_MQTT_NOT_CONNECTED Fail to enable property feature due to MQTT not connected. 844 * @retval NXD_MQTT_PACKET_POOL_FAILURE Fail to enable property feature due to no available packet in pool. 845 * @retval NXD_MQTT_COMMUNICATION_FAILURE Fail to enable property feature due to TCP/TLS error. 846 */ 847 UINT nx_azure_iot_hub_client_properties_enable(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr); 848 849 /** 850 * @brief Disables properties feature 851 * @details This routine disables property feature. 852 * 853 * @param[in] hub_client_ptr A pointer to a #NX_AZURE_IOT_HUB_CLIENT 854 * @return A `UINT` with the result of the API. 855 * @retval #NX_AZURE_IOT_SUCCESS Successful if property feature is disabled. 856 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to disable property feature due to invalid parameter. 857 * @retval NXD_MQTT_NOT_CONNECTED Fail to disable property feature due to MQTT not connected. 858 * @retval NXD_MQTT_PACKET_POOL_FAILURE Fail to disable property feature due to no available packet in pool. 859 * @retval NXD_MQTT_COMMUNICATION_FAILURE Fail to disable property feature due to TCP/TLS error. 860 */ 861 UINT nx_azure_iot_hub_client_properties_disable(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr); 862 863 /** 864 * @brief Creates reported properties message. 865 * 866 * @param[in] hub_client_ptr A pointer to a #NX_AZURE_IOT_HUB_CLIENT. 867 * @param[out] packet_pptr Return `NX_PACKET` containing the reported properties payload on success. 868 * @param[in] wait_option Ticks to wait for writer creation 869 * @return A `UINT` with the result of the API. 870 * @retval #NX_AZURE_IOT_SUCCESS Successful if a message writer is created. 871 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to create message writer due to invalid parameter. 872 * @retval #NX_AZURE_IOT_SDK_CORE_ERROR Fail to create message writer due to SDK core error. 873 * @retval NX_NO_PACKET Fail to create message writer due to no available packet in pool. 874 */ 875 UINT nx_azure_iot_hub_client_reported_properties_create(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 876 NX_PACKET **packet_pptr, 877 UINT wait_option); 878 879 /** 880 * @brief Sends reported properties message to IoTHub. 881 * @note The return status of the API indicates if the reported properties is sent out successfully or not, 882 * the response status is used to track if the reported properties is accepted or not by IoT Hub, and the 883 * reponse status is available only when the return status is NX_AZURE_IOT_SUCCESS. 884 * 885 * @param[in] hub_client_ptr A pointer to a #NX_AZURE_IOT_HUB_CLIENT. 886 * @param[in] packet_ptr A pointer to a #NX_PACKET 887 * @param[out] request_id_ptr Request Id assigned to the request. 888 * @param[out] response_status_ptr Status return for successful send of reported properties. 889 * @param[out] version_ptr Version return for successful send of reported properties. 890 * @param[in] wait_option Ticks to wait for message to send. 891 * @return A `UINT` with the result of the API. 892 * @retval #NX_AZURE_IOT_SUCCESS Successful if reported properties is sent. 893 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to send reported properties due to invalid parameter. 894 * @retval #NX_AZURE_IOT_NOT_ENABLED Fail to send reported properties due to property is not enabled. 895 * @retval #NX_AZURE_IOT_SDK_CORE_ERROR Fail to send reported properties due to SDK core error. 896 * @retval #NX_AZURE_IOT_INSUFFICIENT_BUFFER_SPACE Fail to send reported properties due to buffer size is too small. 897 * @retval NX_NO_PACKET Fail to send reported properties due to no packet available. 898 * @retval #NX_AZURE_IOT_DISCONNECTED Fail to send reported properties due to disconnect. 899 */ 900 UINT nx_azure_iot_hub_client_reported_properties_send(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 901 NX_PACKET *packet_ptr, 902 UINT *request_id_ptr, UINT *response_status_ptr, 903 ULONG *version_ptr, UINT wait_option); 904 905 /** 906 * @brief Request complete properties 907 * @details This routine requests complete properties. 908 * 909 * @param[in] hub_client_ptr A pointer to a #NX_AZURE_IOT_HUB_CLIENT. 910 * @param[in] wait_option Ticks to wait for request to send. 911 * @return A `UINT` with the result of the API. 912 * @retval #NX_AZURE_IOT_SUCCESS Successful if request get all properties is sent. 913 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to request get all properties due to invalid parameter. 914 * @retval #NX_AZURE_IOT_NO_SUBSCRIBE_ACK Fail to request get all properties due to no subscribe ack. 915 * @retval #NX_AZURE_IOT_SDK_CORE_ERROR Fail to request get all properties due to SDK core error. 916 * @retval #NX_AZURE_IOT_INSUFFICIENT_BUFFER_SPACE Fail to request get all properties due to buffer size is too small. 917 * @retval #NX_AZURE_IOT_NO_PACKET Fail to request get all properties due to no packet available. 918 * @retval NX_NO_PACKET Fail to request get all properties due to no packet available. 919 */ 920 UINT nx_azure_iot_hub_client_properties_request(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 921 UINT wait_option); 922 923 /** 924 * @brief Receive all the properties 925 * @details This routine receives all the properties. 926 * 927 * @param[in] hub_client_ptr A pointer to a #NX_AZURE_IOT_HUB_CLIENT. 928 * @param[out] packet_pptr Return `NX_PACKET` containing properties payload on success. 929 * @param[in] wait_option Ticks to wait for message to receive. 930 * @return A `UINT` with the result of the API. 931 * @retval #NX_AZURE_IOT_SUCCESS Successful if all properties is received. 932 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to receive all properties due to invalid parameter. 933 * @retval #NX_AZURE_IOT_NOT_ENABLED Fail to receive all properties due to it is not enabled. 934 * @retval #NX_AZURE_IOT_NO_PACKET Fail to receive all properties due to timeout. 935 * @retval #NX_AZURE_IOT_INVALID_PACKET Fail to receive all properties due to invalid packet. 936 * @retval #NX_AZURE_IOT_SDK_CORE_ERROR Fail to receive all properties due to SDK core error. 937 * @retval #NX_AZURE_IOT_SERVER_RESPONSE_ERROR Response code from server is not 2xx. 938 * @retval #NX_AZURE_IOT_DISCONNECTED Fail to receive all properties due to disconnect. 939 */ 940 UINT nx_azure_iot_hub_client_properties_receive(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 941 NX_PACKET **packet_pptr, 942 UINT wait_option); 943 944 /** 945 * @brief Receive writable properties form IoTHub 946 * @details This routine receives writable properties from IoTHub. 947 * 948 * @param[in] hub_client_ptr A pointer to a #NX_AZURE_IOT_HUB_CLIENT. 949 * @param[out] packet_pptr A pointer to a #NX_PACKET containing writable properties on success. 950 * @param[in] wait_option Ticks to wait for message to receive. 951 * @return A `UINT` with the result of the API. 952 * @retval #NX_AZURE_IOT_SUCCESS Successful if writable properties is received. 953 * @retval #NX_AZURE_IOT_INVALID_PARAMETER Fail to receive writable properties due to invalid parameter. 954 * @retval #NX_AZURE_IOT_NOT_ENABLED Fail to receive writable properties due to it is not enabled. 955 * @retval #NX_AZURE_IOT_NO_PACKET Fail to receive writable properties due to timeout. 956 * @retval #NX_AZURE_IOT_INVALID_PACKET Fail to receive writable properties due to invalid packet. 957 * @retval #NX_AZURE_IOT_DISCONNECTED Fail to receive writable properties due to disconnect. 958 */ 959 UINT nx_azure_iot_hub_client_writable_properties_receive(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 960 NX_PACKET **packet_pptr, 961 UINT wait_option); 962 963 #ifdef __cplusplus 964 } 965 #endif 966 #endif /* NX_AZURE_IOT_HUB_CLIENT_H */ 967
