1# Azure IoT Hub Client 2 3## APIs: 4 5### Connect 6 7* [nx_azure_iot_hub_client_initialize](#nx_azure_iot_hub_client_initialize) 8* [nx_azure_iot_hub_client_deinitialize](#nx_azure_iot_hub_client_deinitialize) 9* [nx_azure_iot_hub_client_model_id_set](#nx_azure_iot_hub_client_model_id_set) 10* [nx_azure_iot_hub_client_component_add](#nx_azure_iot_hub_client_component_add) 11* [nx_azure_iot_hub_client_trusted_cert_add](#nx_azure_iot_hub_client_trusted_cert_add) 12* [nx_azure_iot_hub_client_device_cert_set](#nx_azure_iot_hub_client_device_cert_set) 13* [nx_azure_iot_hub_client_symmetric_key_set](#nx_azure_iot_hub_client_symmetric_key_set) 14* [nx_azure_iot_hub_client_websocket_enable](#nx_azure_iot_hub_client_websocket_enable) 15* [nx_azure_iot_hub_client_connect](#nx_azure_iot_hub_client_connect) 16* [nx_azure_iot_hub_client_disconnect](#nx_azure_iot_hub_client_disconnect) 17* [nx_azure_iot_hub_client_connection_status_callback_set](#nx_azure_iot_hub_client_connection_status_callback_set) 18* [nx_azure_iot_hub_client_receive_callback_set](#nx_azure_iot_hub_client_receive_callback_set) 19 20### C2D 21 22* [nx_azure_iot_hub_client_cloud_message_enable](#nx_azure_iot_hub_client_cloud_message_enable) 23* [nx_azure_iot_hub_client_cloud_message_disable](#nx_azure_iot_hub_client_cloud_message_disable) 24* [nx_azure_iot_hub_client_cloud_message_receive](#nx_azure_iot_hub_client_cloud_message_receive) 25* [nx_azure_iot_hub_client_cloud_message_property_get](#nx_azure_iot_hub_client_cloud_message_property_get) 26 27### Telemetry 28 29* [nx_azure_iot_hub_client_telemetry_message_create](#nx_azure_iot_hub_client_telemetry_message_create) 30* [nx_azure_iot_hub_client_telemetry_message_delete](#nx_azure_iot_hub_client_telemetry_message_delete) 31* [nx_azure_iot_hub_client_telemetry_component_set](#nx_azure_iot_hub_client_telemetry_component_set) 32* [nx_azure_iot_hub_client_telemetry_property_add](#nx_azure_iot_hub_client_telemetry_property_add) 33* [nx_azure_iot_hub_client_telemetry_send](#nx_azure_iot_hub_client_telemetry_send) 34 35### Command 36 37* [nx_azure_iot_hub_client_command_enable](#nx_azure_iot_hub_client_command_enable) 38* [nx_azure_iot_hub_client_command_disable](#nx_azure_iot_hub_client_command_disable) 39* [nx_azure_iot_hub_client_command_message_receive](#nx_azure_iot_hub_client_command_message_receive) 40* [nx_azure_iot_hub_client_command_message_response](#nx_azure_iot_hub_client_command_message_response) 41 42### Direct Method 43 44* [nx_azure_iot_hub_client_direct_method_enable](#nx_azure_iot_hub_client_direct_method_enable) 45* [nx_azure_iot_hub_client_direct_method_disable](#nx_azure_iot_hub_client_direct_method_disable) 46* [nx_azure_iot_hub_client_direct_method_message_receive](#nx_azure_iot_hub_client_direct_method_message_receive) 47* [nx_azure_iot_hub_client_direct_method_message_response](#nx_azure_iot_hub_client_direct_method_message_response) 48 49### Properties 50 51* [nx_azure_iot_hub_client_properties_enable](#nx_azure_iot_hub_client_properties_enable) 52* [nx_azure_iot_hub_client_properties_disable](#nx_azure_iot_hub_client_properties_disable) 53* [nx_azure_iot_hub_client_reported_properties_response_callback_set](#nx_azure_iot_hub_client_reported_properties_response_callback_set) 54* [nx_azure_iot_hub_client_reported_properties_create](#nx_azure_iot_hub_client_reported_properties_create) 55* [nx_azure_iot_hub_client_reported_properties_send](#nx_azure_iot_hub_client_reported_properties_send) 56* [nx_azure_iot_hub_client_properties_request](#nx_azure_iot_hub_client_properties_request) 57* [nx_azure_iot_hub_client_properties_receive](#nx_azure_iot_hub_client_properties_receive) 58* [nx_azure_iot_hub_client_writable_properties_receive](#nx_azure_iot_hub_client_writable_properties_receive) 59 60### Device Twin 61 62* [nx_azure_iot_hub_client_device_twin_enable](#nx_azure_iot_hub_client_device_twin_enable) 63* [nx_azure_iot_hub_client_device_twin_disable](#nx_azure_iot_hub_client_device_twin_disable) 64* [nx_azure_iot_hub_client_device_twin_reported_properties_send](#nx_azure_iot_hub_client_device_twin_reported_properties_send) 65* [nx_azure_iot_hub_client_device_twin_properties_request](#nx_azure_iot_hub_client_device_twin_properties_request) 66* [nx_azure_iot_hub_client_device_twin_properties_receive](#nx_azure_iot_hub_client_device_twin_properties_receive) 67* [nx_azure_iot_hub_client_device_twin_desired_properties_receive](#nx_azure_iot_hub_client_device_twin_desired_properties_receive) 68 69#### **nx_azure_iot_hub_client_initialize** 70*** 71<div style="text-align: right"> Initialize Azure IoT hub instance</div> 72 73**Prototype** 74```c 75UINT nx_azure_iot_hub_client_initialize(NX_AZURE_IOT_HUB_CLIENT* hub_client_ptr, 76 NX_AZURE_IOT *nx_azure_iot_ptr, 77 const UCHAR *host_name, UINT host_name_length, 78 const UCHAR *device_id, UINT device_id_length, 79 const UCHAR *module_id, UINT module_id_length, 80 const NX_CRYPTO_METHOD **crypto_array, UINT crypto_array_size, 81 const NX_CRYPTO_CIPHERSUITE **cipher_map, UINT cipher_map_size, 82 UCHAR * metadata_memory, UINT memory_size, 83 NX_SECURE_X509_CERT *trusted_certificate); 84``` 85**Description** 86 87<p>This routine initializes the IoT Hub client.</p> 88 89**Parameters** 90 91| Name | Description | 92| - |:-| 93| hub_client_ptr [in] | A pointer to a `NX_AZURE_IOT_HUB_CLIENT`. | 94| nx_azure_iot_ptr [in] | A pointer to a `NX_AZURE_IOT`.| 95| host_name [in] | A pointer to IoTHub hostname. Must be NULL terminated string. | 96| host_name_length [in] | Length of the IoTHub hostname. | 97| device_id [in] | A pointer to device ID. | 98| device_id_length [in] | Length of the device ID. | 99| module_id [in] | A pointer to module ID. | 100| module_id_length [in] | Length of the module ID. | 101| crypto_array [in] | A pointer to `NX_CRYPTO_METHOD` | 102| crypto_array_size [in] | Size of crypto method array | 103| cipher_map [in] | A pointer to `NX_CRYPTO_CIPHERSUITE` | 104| cipher_map_size [in] | Size of cipher map | 105| metadata_memory [in] | A pointer to metadata memory buffer. | 106| memory_size [in] | Size of metadata buffer | 107| trusted_certificate [in] | A pointer to `NX_SECURE_X509_CERT`, which is server side certs | 108 109**Return Values** 110* NX_AZURE_IOT_SUCCESS Successfully initialized the Azure IoT hub. 111* NX_AZURE_IOT_INVALID_PARAMETER Fail to initialize the Azure IoT hub client due to invalid parameter. 112* NX_AZURE_IOT_SDK_CORE_ERROR Fail to initialize the Azure IoT hub client due to SDK core error. 113 114**Allowed From** 115 116Threads 117 118**Example** 119 120**See Also** 121 122<div style="page-break-after: always;"></div> 123 124#### **nx_azure_iot_hub_client_deinitialize** 125*** 126<div style="text-align: right"> Cleanup the Azure IoT Hub</div> 127 128**Prototype** 129```c 130UINT nx_azure_iot_hub_client_deinitialize(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr); 131``` 132**Description** 133 134<p>The routine deinitializes the IoT Hub client</p> 135 136**Parameters** 137| | | 138| ------------- |:-------------| 139| hub_client_ptr [in] | A pointer to a `NX_AZURE_IOT_HUB_CLIENT` | 140 141 142**Return Values** 143* NX_AZURE_IOT_SUCCESS Successfully de-initialized the Azure IoT hub client. 144* NX_AZURE_IOT_INVALID_PARAMETER Fail to deinitialize the Azure IoT hub client due to invalid parameter. 145 146**Allowed From** 147 148Threads 149 150**Example** 151 152**See Also** 153 154<div style="page-break-after: always;"></div> 155 156#### **nx_azure_iot_hub_client_trusted_cert_add** 157*** 158<div style="text-align: right"> Add trusted certificate </div> 159 160**Prototype** 161```c 162UINT nx_azure_iot_hub_client_trusted_cert_add(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 163 NX_SECURE_X509_CERT *trusted_certificate); 164``` 165**Description** 166 167<p>This routine adds the trusted certificate. It can be called multiple times to set multiple trusted certificates.</p> 168 169**Parameters** 170 171| Name | Description | 172| - |:-| 173| hub_client_ptr [in] | A pointer to a `NX_AZURE_IOT_HUB_CLIENT` | 174| trusted_certificate [in] | A pointer to a `NX_SECURE_X509_CERT` | 175 176**Return Values** 177* NX_AZURE_IOT_SUCCESS Successfully add trusted certificate to Azure IoT Hub Instance. 178* NX_AZURE_IOT_INVALID_PARAMETER Fail to add trusted certificate to Azure IoT Hub Instance due to invalid parameter. 179* NX_AZURE_IOT_INSUFFICIENT_BUFFER_SPACE Fail to add trusted certificate due to `NX_AZURE_IOT_MAX_NUM_OF_TRUSTED_CERTS` is too small. 180 181**Allowed From** 182 183Threads 184 185**Example** 186 187**See Also** 188 189<div style="page-break-after: always;"></div> 190 191#### **nx_azure_iot_hub_client_device_cert_set** 192*** 193<div style="text-align: right"> Set client certificate </div> 194 195**Prototype** 196```c 197UINT nx_azure_iot_hub_client_device_cert_set(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 198 NX_SECURE_X509_CERT *device_certificate); 199``` 200**Description** 201 202<p>This routine sets the device certificate. It can be called multiple times to set certificate chain.</p> 203 204**Parameters** 205 206| Name | Description | 207| - |:-| 208| hub_client_ptr [in] | A pointer to a `NX_AZURE_IOT_HUB_CLIENT` | 209| device_certificate [in] | A pointer to a `NX_SECURE_X509_CERT` | 210 211**Return Values** 212* NX_AZURE_IOT_SUCCESS Successfully set device certificate to Azure IoT Hub Instance. 213* NX_AZURE_IOT_INVALID_PARAMETER Fail to set device certificate to Azure IoT Hub Instance due to invalid parameter. 214* NX_AZURE_IOT_INSUFFICIENT_BUFFER_SPACE Fail to set device certificate due to `NX_AZURE_IOT_MAX_NUM_OF_DEVICE_CERTS` is too small. 215 216**Allowed From** 217 218Threads 219 220**Example** 221 222**See Also** 223 224<div style="page-break-after: always;"></div> 225 226#### **nx_azure_iot_hub_client_symmetric_key_set** 227*** 228<div style="text-align: right"> Set symmetric key </div> 229 230**Prototype** 231```c 232UINT nx_azure_iot_hub_client_symmetric_key_set(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 233 const UCHAR *symmetric_key, UINT symmetric_key_length); 234``` 235**Description** 236 237<p>This routine sets the symmetric key.</p> 238 239**Parameters** 240 241| Name | Description | 242| - |:-| 243| hub_client_ptr [in] | A pointer to a `NX_AZURE_IOT_HUB_CLIENT` | 244| symmetric_key [in] | A pointer to a symmetric key. | 245| symmetric_key_length [in] | Length of symmetric key | 246 247**Return Values** 248* NX_AZURE_IOT_SUCCESS Successfully set symmetric key to IoTHub client. 249* NX_AZURE_IOT_INVALID_PARAMETER Fail to set symmetric key to IoTHub client due to invalid parameter. 250 251**Allowed From** 252 253Threads 254 255**Example** 256 257**See Also** 258 259<div style="page-break-after: always;"></div> 260 261#### **nx_azure_iot_hub_client_model_id_set** 262*** 263<div style="text-align: right"> Set Device Twin model id in the IoT Hub client. </div> 264 265**Prototype** 266```c 267UINT nx_azure_iot_hub_client_model_id_set(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 268 const UCHAR *model_id_ptr, UINT model_id_length); 269``` 270**Description** 271 272<p>This routine sets the model id in the IoT Hub client to enable PnP.</p> 273 274**Parameters** 275 276| Name | Description | 277| - |:-| 278| hub_client_ptr [in] | A pointer to a `NX_AZURE_IOT_HUB_CLIENT` | 279| model_id_ptr [in] | A pointer to a model id. | 280| model_id_length [in] | Length of model id | 281 282**Return Values** 283* NX_AZURE_IOT_SUCCESS Successfully set model id to IoTHub client. 284* NX_AZURE_IOT_INVALID_PARAMETER Fail to set model id to IoTHub client due to invalid parameter. 285 286**Allowed From** 287 288Threads 289 290**Example** 291 292**See Also** 293 294<div style="page-break-after: always;"></div> 295 296#### **nx_azure_iot_hub_client_component_add** 297*** 298<div style="text-align: right"> Add component to IoT Hub client </div> 299 300**Prototype** 301```c 302UINT nx_azure_iot_hub_client_component_add(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 303 const UCHAR *component_name_ptr, 304 USHORT component_name_length); 305``` 306**Description** 307 308<p>This routine should be called for all the components in the IoT hub model.</p> 309 310**Parameters** 311 312| Name | Description | 313| - |:-| 314| hub_client_ptr [in] | A pointer to a `NX_AZURE_IOT_HUB_CLIENT` | 315| component_name_ptr [in] | A pointer to component, that is part of IoT hub model. | 316| component_name_length [in] | Length of the `component_name_ptr`. | 317 318**Return Values** 319* NX_AZURE_IOT_SUCCESS Successfully set device certificate to AZ IoT Hub Instance. 320* NX_AZURE_IOT_INSUFFICIENT_BUFFER_SPACE Fail to add the component name due to out of memory. 321 322**Allowed From** 323 324Threads 325 326**Example** 327 328**See Also** 329 330<div style="page-break-after: always;"></div> 331 332#### **nx_azure_iot_hub_client_websocket_enable** 333*** 334<div style="text-align: right"> Enables MQTT over WebSocket to connect to IoT Hub</div> 335 336**Prototype** 337```c 338UINT nx_azure_iot_hub_client_websocket_enable(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr); 339``` 340**Description** 341 342<p>This routine enables MQTT over WebSocket to connect to the Azure IoT Hub.</p> 343 344**Parameters** 345 346| Name | Description | 347| - |:-| 348| hub_client_ptr [in] | A pointer to a `NX_AZURE_IOT_HUB_CLIENT` | 349 350 351**Return Values** 352* NX_AZURE_IOT_SUCCESS Successful if MQTT over Websocket is enabled. 353* NX_AZURE_IOT_INVALID_PARAMETER Fail to enable MQTT over WebSocket due to invalid parameter. 354 355**Allowed From** 356 357Threads 358 359**Example** 360 361**See Also** 362 363<div style="page-break-after: always;"></div> 364 365#### **nx_azure_iot_hub_client_connect** 366*** 367<div style="text-align: right"> Connects to IoT Hub</div> 368 369**Prototype** 370```c 371UINT nx_azure_iot_hub_client_connect(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 372 UINT clean_session, UINT wait_option); 373``` 374**Description** 375 376<p>This routine connects to the Azure IoT Hub.</p> 377 378**Parameters** 379 380| Name | Description | 381| - |:-| 382| hub_client_ptr [in] | A pointer to a `NX_AZURE_IOT_HUB_CLIENT` | 383| clean_session [in] | 0 re-use current session, or 1 to start new session | 384| wait_option [in] | Number of ticks to wait for internal resources to be available. | 385 386 387**Return Values** 388* NX_AZURE_IOT_SUCCESS Successful if connected to Azure IoT Hub. 389* NX_AZURE_IOT_CONNECTING Successfully started connection but not yet completed. 390* NX_AZURE_IOT_ALREADY_CONNECTED Already connected to Azure IoT Hub. 391* NX_AZURE_IOT_INVALID_PARAMETER Fail to connect to Azure IoT Hub due to invalid parameter. 392* NX_AZURE_IOT_SDK_CORE_ERROR Fail to connect to Azure IoT Hub due to SDK core error. 393* NX_AZURE_IOT_INSUFFICIENT_BUFFER_SPACE Fail to connect to Azure IoT Hub due to buffer size is too small. 394* NX_DNS_QUERY_FAILED Fail to connect to Azure IoT Hub due to hostname can not be resolved. 395* NX_NO_PACKET Fail to connect to Azure IoT Hub due to no available packet in pool. 396* NX_INVALID_PARAMETERS Fail to connect to Azure IoT Hub due to invalid parameters. 397* NX_SECURE_TLS_INSUFFICIENT_METADATA_SPACE Fail to connect to Azure IoT Hub due to insufficient metadata space. 398* NX_SECURE_TLS_UNSUPPORTED_CIPHER Fail to connect to Azure IoT Hub due to unsupported cipher. 399* NXD_MQTT_ALREADY_CONNECTED Fail to connect to Azure IoT Hub due to MQTT session is not disconnected. 400* NXD_MQTT_CONNECT_FAILURE Fail to connect to Azure IoT Hub due to TCP/TLS connect error. 401* NXD_MQTT_COMMUNICATION_FAILURE Fail to connect to Azure IoT Hub due to MQTT connect error. 402* NXD_MQTT_ERROR_SERVER_UNAVAILABLE Fail to connect to Azure IoT Hub due to server unavailable. 403* NXD_MQTT_ERROR_NOT_AUTHORIZED Fail to connect to Azure IoT Hub due to authentication error. 404 405**Allowed From** 406 407Threads 408 409**Example** 410 411**See Also** 412 413<div style="page-break-after: always;"></div> 414 415#### **nx_azure_iot_hub_client_disconnect** 416*** 417<div style="text-align: right"> Disconnects the client</div> 418 419**Prototype** 420```c 421UINT nx_azure_iot_hub_client_disconnect(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr); 422``` 423**Description** 424 425<p>This routine disconnects the client.</p> 426 427**Parameters** 428 429| Name | Description | 430| - |:-| 431| hub_client_ptr [in] | A pointer to a `NX_AZURE_IOT_HUB_CLIENT` | 432 433 434**Return Values** 435* NX_AZURE_IOT_SUCCESS Successful if client disconnects. 436* NX_AZURE_IOT_INVALID_PARAMETER Fail to disconnect due to invalid parameter. 437 438**Allowed From** 439 440Threads 441 442**Example** 443 444**See Also** 445 446<div style="page-break-after: always;"></div> 447 448#### **nx_azure_iot_hub_client_connection_status_callback_set** 449*** 450<div style="text-align: right"> Sets connection status callback function</div> 451 452**Prototype** 453```c 454UINT nx_azure_iot_hub_client_connection_status_callback_set(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 455 VOID (*connection_status_cb)( 456 struct NX_AZURE_IOT_HUB_CLIENT_STRUCT 457 *hub_client_ptr, UINT status)); 458``` 459**Description** 460 461<p>This routine sets the connection status callback. This callback function is invoked when the IoT Hub status is changed, such as: return NX_AZURE_IOT_SUCCESS status once client is connected to IoT Hub. Setting the callback function to NULL disables the callback function. Following status will be returned on disconnection.</p> 462 463* NX_SECURE_TLS_ALERT_RECEIVED 464* NX_SECURE_TLS_NO_SUPPORTED_CIPHERS 465* NX_SECURE_X509_CHAIN_VERIFY_FAILURE 466* NXD_MQTT_CONNECT_FAILURE 467* NXD_MQTT_ERROR_SERVER_UNAVAILABLE 468* NXD_MQTT_ERROR_NOT_AUTHORIZED 469* NX_AZURE_IOT_DISCONNECTED 470* NX_AZURE_IOT_SAS_TOKEN_EXPIRED 471 472**Parameters** 473 474| Name | Description | 475| - |:-| 476| hub_client_ptr [in] | A pointer to a `NX_AZURE_IOT_HUB_CLIENT` | 477| connection_status_cb [in] | Pointer to a callback function invoked once connection status is changed. | 478 479 480**Return Values** 481* NX_AZURE_IOT_SUCCESS Successful if connection status callback is set. 482* NX_AZURE_IOT_INVALID_PARAMETER Fail to set connection status callback due to invalid parameter. 483 484**Allowed From** 485 486Threads 487 488**Example** 489 490**See Also** 491 492<div style="page-break-after: always;"></div> 493 494#### **nx_azure_iot_hub_client_receive_callback_set** 495*** 496<div style="text-align: right"> Sets receive callback function</div> 497 498**Prototype** 499```c 500UINT nx_azure_iot_hub_client_receive_callback_set(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 501 UINT message_type, 502 VOID (*callback_ptr)( 503 NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, VOID *args), 504 VOID *callback_args); 505``` 506**Description** 507 508<p>This routine sets the IoT Hub receive callback function. This callback function is invoked when a message is received from Azure IoT hub. Setting the callback function to NULL disables the callback function. Message types can be NX_AZURE_IOT_HUB_CLOUD_TO_DEVICE_MESSAGE, NX_AZURE_IOT_HUB_COMMAND, NX_AZURE_IOT_HUB_PROPERTIES, NX_AZURE_IOT_HUB_WRITABLE_PROPERTIES, NX_AZURE_IOT_HUB_DIRECT_METHOD, NX_AZURE_IOT_HUB_DEVICE_TWIN_PROPERTIES and NX_AZURE_IOT_HUB_DEVICE_TWIN_DESIRED_PROPERTIES. </p> 509 510**Parameters** 511 512| Name | Description | 513| - |:-| 514| hub_client_ptr [in] | A pointer to a `NX_AZURE_IOT_HUB_CLIENT`. | 515| message_type [in] | Message type of callback function. | 516| callback_ptr [in] | Pointer to a callback function invoked on specified message type is received. | 517| callback_args [in] | Pointer to an argument passed to callback function. | 518 519 520**Return Values** 521* NX_AZURE_IOT_SUCCESS Successful if callback function is set. 522* NX_AZURE_IOT_INVALID_PARAMETER Fail to set receive callback due to invalid parameter. 523* NX_AZURE_IOT_NOT_SUPPORTED Fail to set receive callback due to message_type not supported. 524 525**Allowed From** 526 527Threads 528 529**Example** 530 531**See Also** 532 533<div style="page-break-after: always;"></div> 534 535#### **nx_azure_iot_hub_client_telemetry_message_create** 536*** 537<div style="text-align: right"> Creates telemetry message</div> 538 539**Prototype** 540```c 541UINT nx_azure_iot_hub_client_telemetry_message_create(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 542 NX_PACKET **packet_pptr, 543 UINT wait_option); 544``` 545**Description** 546 547<p>This routine prepares a packet for sending telemetry data. After the packet is properly created, application owns the `NX_PACKET` and can add additional user-defined properties before sending out.</p> 548 549**Parameters** 550 551| Name | Description | 552| - |:-| 553| hub_client_ptr [in] | A pointer to a `NX_AZURE_IOT_HUB_CLIENT`. | 554| packet_pptr [out] | Return allocated packet on success. Caller owns the `NX_PACKET` memory. | 555| wait_option [in] | Ticks to wait if no packet is available. | 556 557 558**Return Values** 559* NX_AZURE_IOT_SUCCESS Successful if a packet is allocated. 560* NX_AZURE_IOT_INVALID_PARAMETER Fail to allocate telemetry message due to invalid parameter. 561* NX_AZURE_IOT_SDK_CORE_ERROR Fail to allocate telemetry message due to SDK core error. 562* NX_NO_PACKET Fail to allocate telemetry message due to no available packet in pool. 563 564**Allowed From** 565 566Threads 567 568**Example** 569 570**See Also** 571 572<div style="page-break-after: always;"></div> 573 574#### **nx_azure_iot_hub_client_telemetry_message_delete** 575*** 576<div style="text-align: right"> Deletes telemetry message</div> 577 578**Prototype** 579```c 580UINT nx_azure_iot_hub_client_telemetry_message_delete(NX_PACKET *packet_ptr); 581``` 582**Description** 583 584<p>This routine deletes the telemetry message.</p> 585 586**Parameters** 587 588| Name | Description | 589| - |:-| 590| packet_ptr [in] | Release the `NX_PACKET` on success. | 591 592 593**Return Values** 594* NX_AZURE_IOT_SUCCESS (0x0) Successful if a packet is deallocated. 595 596**Allowed From** 597 598Threads 599 600**Example** 601 602**See Also** 603 604<div style="page-break-after: always;"></div> 605 606#### **nx_azure_iot_hub_client_telemetry_component_set** 607*** 608<div style="text-align: right"> Sets component to telemetry message</div> 609 610**Prototype** 611```c 612UINT nx_azure_iot_hub_client_telemetry_component_set(NX_PACKET *packet_ptr, 613 const UCHAR *component_name_ptr, 614 USHORT component_name_length, 615 UINT wait_option)); 616``` 617**Description** 618 619<p>This routine allows an application to set a component name to a telemetry message before it is being sent. The component is stored in the sequence which the routine is called. The component must be set after a telemetry packet is created, and before the telemetry message is being sent.</p> 620 621**Parameters** 622 623| Name | Description | 624| - |:-| 625| packet_ptr [in] | A pointer to telemetry component packet. | 626| component_name_ptr [in] | A pointer to a component name. | 627| component_name_length [in] | Length of component name. | 628| wait_option [in] | Ticks to wait if packet needs to be expanded. | 629 630 631**Return Values** 632* NX_AZURE_IOT_SUCCESS Successful if component is set. 633* NX_AZURE_IOT_INVALID_PARAMETER Fail to set component due to invalid parameter. 634* NX_NO_PACKET Fail to set component due to no available packet in pool. 635 636**Allowed From** 637 638Threads 639 640**Example** 641 642**See Also** 643 644<div style="page-break-after: always;"></div> 645 646#### **nx_azure_iot_hub_client_telemetry_property_add** 647*** 648<div style="text-align: right"> Adds property to telemetry message</div> 649 650**Prototype** 651```c 652UINT nx_azure_iot_hub_client_telemetry_property_add(NX_PACKET *packet_ptr, 653 const UCHAR *property_name, USHORT property_name_length, 654 const UCHAR *property_value, USHORT property_value_length, 655 UINT wait_option); 656``` 657**Description** 658 659<p>This routine allows an application to add user-defined properties to a telemetry message before it is being sent. This routine can be called multiple times to add all the properties to the message. The properties are stored in the sequence which the routine is called. The property must be added after a telemetry packet is created, and before the telemetry message is being sent.</p> 660 661**Parameters** 662 663| Name | Description | 664| - |:-| 665| packet_ptr [in] | A pointer to telemetry property packet. | 666| property_name [in] | Pointer to property name. | 667| property_name_length [in] | Length of property name. | 668| property_value [in] | Pointer to property value. | 669| property_value_length [in] | Length of property value. | 670| wait_option [in] | Ticks to wait if packet needs to be expanded. | 671 672 673**Return Values** 674* NX_AZURE_IOT_SUCCESS Successful if property is added. 675* NX_AZURE_IOT_INVALID_PARAMETER Fail to add property due to invalid parameter. 676* NX_NO_PACKET Fail to add property due to no available packet in pool. 677 678**Allowed From** 679 680Threads 681 682**Example** 683 684**See Also** 685 686<div style="page-break-after: always;"></div> 687 688#### **nx_azure_iot_hub_client_telemetry_send** 689*** 690<div style="text-align: right"> Sends telemetry message to IoTHub</div> 691 692**Prototype** 693```c 694UINT nx_azure_iot_hub_client_telemetry_send(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, NX_PACKET *packet_ptr, 695 const UCHAR *telemetry_data, UINT data_size, UINT wait_option); 696``` 697**Description** 698 699<p>This routine sends telemetry to IoTHub, with packet_ptr containing all the properties. On successful return of this function, ownership of `NX_PACKET` is released.</p> 700 701**Parameters** 702 703| Name | Description | 704| - |:-| 705| hub_client_ptr [in] | A pointer to a `NX_AZURE_IOT_HUB_CLIENT`. | 706| packet_ptr [in] | A pointer to telemetry property packet. | 707| telemetry_data [in] | Pointer to telemetry data. | 708| data_size [in] | Size of telemetry data. | 709| wait_option [in] | Ticks to wait for message to be sent. | 710 711 712**Return Values** 713* NX_AZURE_IOT_SUCCESS Successful if telemetry message is sent out. 714* NX_AZURE_IOT_INVALID_PARAMETER Fail to send telemetry message due to invalid parameter. 715* NX_AZURE_IOT_INVALID_PACKET Fail to send telemetry message due to packet is invalid. 716* NXD_MQTT_PACKET_POOL_FAILURE Fail to send telemetry message due to no available packet in pool. 717* NXD_MQTT_COMMUNICATION_FAILURE Fail to send telemetry message due to TCP/TLS error. 718* NX_NO_PACKET Fail to send telemetry message due to no available packet in pool. 719 720**Allowed From** 721 722Threads 723 724**Example** 725 726**See Also** 727 728<div style="page-break-after: always;"></div> 729 730#### **nx_azure_iot_hub_client_cloud_message_enable** 731*** 732<div style="text-align: right"> Enables receiving C2D message from IoTHub</div> 733 734**Prototype** 735```c 736UINT nx_azure_iot_hub_client_cloud_message_enable(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr); 737``` 738**Description** 739 740<p>This routine enables receiving C2D message from IoT Hub.</p> 741 742**Parameters** 743 744| Name | Description | 745| - |:-| 746| hub_client_ptr [in] | A pointer to a `NX_AZURE_IOT_HUB_CLIENT`. | 747 748 749**Return Values** 750* NX_AZURE_IOT_SUCCESS Successful if C2D message receiving is enabled. 751* NX_AZURE_IOT_INVALID_PARAMETER Fail to enable C2D message receiving due to invalid parameter. 752* NXD_MQTT_NOT_CONNECTED Fail to enable C2D message receiving due to MQTT not connected. 753* NXD_MQTT_PACKET_POOL_FAILURE Fail to enable C2D message receiving due to no available packet in pool. 754* NXD_MQTT_COMMUNICATION_FAILURE Fail to enable C2D message receiving due to TCP/TLS error. 755 756**Allowed From** 757 758Threads 759 760**Example** 761 762**See Also** 763 764<div style="page-break-after: always;"></div> 765 766#### **nx_azure_iot_hub_client_cloud_message_disable** 767*** 768<div style="text-align: right"> Disables receiving C2D message from IoTHub</div> 769 770**Prototype** 771```c 772UINT nx_azure_iot_hub_client_cloud_message_disable(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr); 773``` 774**Description** 775 776<p>This routine disables receiving C2D message from IoT Hub.</p> 777 778**Parameters** 779 780| Name | Description | 781| - |:-| 782| hub_client_ptr [in] | A pointer to a `NX_AZURE_IOT_HUB_CLIENT`. | 783 784 785**Return Values** 786* NX_AZURE_IOT_SUCCESS Successful if C2D message receiving is disabled. 787* NX_AZURE_IOT_INVALID_PARAMETER Fail to disable C2D message receiving due to invalid parameter. 788* NXD_MQTT_NOT_CONNECTED Fail to disable C2D message receiving due to MQTT not connected. 789* NXD_MQTT_PACKET_POOL_FAILURE Fail to disable C2D message receiving due to no available packet in pool. 790* NXD_MQTT_COMMUNICATION_FAILURE Fail to disable C2D message receiving due to TCP/TLS error. 791 792**Allowed From** 793 794Threads 795 796**Example** 797 798**See Also** 799 800<div style="page-break-after: always;"></div> 801 802#### **nx_azure_iot_hub_client_cloud_message_receive** 803*** 804<div style="text-align: right"> Receives C2D message from IoTHub</div> 805 806**Prototype** 807```c 808UINT nx_azure_iot_hub_client_cloud_message_receive(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 809 NX_PACKET **packet_pptr, 810 UINT wait_option); 811``` 812**Description** 813 814<p>This routine receives C2D message from IoT Hub. If there are no messages in the receive queue, this routine can block. The amount of time it waits for a message is determined by the wait_option parameter.</p> 815 816**Parameters** 817 818| Name | Description | 819| - |:-| 820| hub_client_ptr [in] | A pointer to a `NX_AZURE_IOT_HUB_CLIENT`. | 821| packet_pptr [out] | Return a packet pointer with C2D message on success. Caller owns the `NX_PACKET` memory. | 822| wait_option [in] | Ticks to wait for message to arrive. | 823 824 825**Return Values** 826* NX_AZURE_IOT_SUCCESS Successful if C2D message is received. 827* NX_AZURE_IOT_INVALID_PARAMETER Fail to receive C2D message due to invalid parameter. 828* NX_AZURE_IOT_NOT_ENABLED Fail to receive C2D message due to it is not enabled. 829* NX_AZURE_IOT_NO_PACKET Fail to receive C2D message due to timeout. 830* NX_AZURE_IOT_DISCONNECTED Fail to receive C2D message due to disconnection. 831 832**Allowed From** 833 834Threads 835 836**Example** 837 838**See Also** 839 840<div style="page-break-after: always;"></div> 841 842#### **nx_azure_iot_hub_client_cloud_message_property_get** 843*** 844<div style="text-align: right"> Retrieve the property with given property name in the C2D message</div> 845 846**Prototype** 847```c 848UINT nx_azure_iot_hub_client_cloud_message_property_get(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, NX_PACKET *packet_ptr, 849 const UCHAR *property_name, USHORT property_name_length, 850 const UCHAR **property_value, USHORT *property_value_length); 851``` 852**Description** 853 854<p>This routine retrieves the property with given property name in the NX_PACKET.</p> 855 856**Parameters** 857 858| Name | Description | 859| - |:-| 860| hub_client_ptr [in] | A pointer to a `NX_AZURE_IOT_HUB_CLIENT`. | 861| packet_ptr [in] | Pointer to `NX_PACKET` containing C2D message. | 862| property_name [in] | Pointer to property name. | 863| property_name_length [in] | Property name length. | 864| property_value [out] | Pointer to memory that contains property value | 865| property_value_length [out] | Pointer to size of property value. | 866 867 868**Return Values** 869* NX_AZURE_IOT_SUCCESS Successful if property is found and copied successfully into user buffer. 870* NX_AZURE_IOT_INVALID_PARAMETER Fail to find the property due to invalid parameter. 871* NX_AZURE_IOT_INVALID_PACKET Fail to find the property due to the packet is invalid. 872* NX_AZURE_IOT_NOT_FOUND Property is not found. 873* NX_AZURE_IOT_SDK_CORE_ERROR Fail to find the property due to parsing error. 874 875**Allowed From** 876 877Threads 878 879**Example** 880 881**See Also** 882 883<div style="page-break-after: always;"></div> 884 885#### **nx_azure_iot_hub_client_direct_method_enable** 886*** 887<div style="text-align: right"> Enables receiving direct method messages from IoTHub </div> 888 889**Prototype** 890```c 891UINT nx_azure_iot_hub_client_direct_method_enable(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr); 892 893``` 894**Description** 895 896<p>This routine enables receiving direct method messages from IoT Hub. </p> 897 898**Parameters** 899| Name | Description | 900| - |:-| 901| hub_client_ptr [in] | A pointer to a `NX_AZURE_IOT_HUB_CLIENT` | 902 903**Return Values** 904* NX_AZURE_IOT_SUCCESS Successful if direct method message receiving is enabled. 905* NX_AZURE_IOT_INVALID_PARAMETER Fail to enable direct method message receiving due to invalid parameter. 906* NXD_MQTT_NOT_CONNECTED Fail to enable direct method message receiving due to MQTT not connected. 907* NXD_MQTT_PACKET_POOL_FAILURE Fail to enable direct method message receiving due to no available packet in pool. 908* NXD_MQTT_COMMUNICATION_FAILURE Fail to enable direct method message receiving due to TCP/TLS error. 909 910**Allowed From** 911 912Threads 913 914**Example** 915 916**See Also** 917 918<div style="page-break-after: always;"></div> 919 920#### **nx_azure_iot_hub_client_direct_method_disable** 921*** 922<div style="text-align: right"> Disables receiving direct method messages from IoTHub</div> 923 924**Prototype** 925```c 926UINT nx_azure_iot_hub_client_direct_method_disable(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr); 927``` 928**Description** 929 930<p>This routine disables receiving direct method messages from IoT Hub.</p> 931 932**Parameters** 933 934| Name | Description | 935| - |:-| 936| hub_client_ptr [in] | A pointer to a `NX_AZURE_IOT_HUB_CLIENT`. | 937 938 939**Return Values** 940* NX_AZURE_IOT_SUCCESS Successful if direct method message receiving is disabled. 941* NX_AZURE_IOT_INVALID_PARAMETER Fail to disable direct method message receiving due to invalid parameter. 942* NXD_MQTT_NOT_CONNECTED Fail to disable direct method message receiving due to MQTT not connected. 943* NXD_MQTT_PACKET_POOL_FAILURE Fail to disable direct method message receiving due to no available packet in pool. 944* NXD_MQTT_COMMUNICATION_FAILURE Fail to disable direct method message receiving due to TCP/TLS error. 945 946**Allowed From** 947 948Threads 949 950**Example** 951 952**See Also** 953 954<div style="page-break-after: always;"></div> 955 956#### **nx_azure_iot_hub_client_direct_method_message_receive** 957*** 958<div style="text-align: right"> Receives direct method message from IoTHub</div> 959 960**Prototype** 961```c 962UINT nx_azure_iot_hub_client_direct_method_message_receive(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 963 const UCHAR **method_name_pptr, USHORT *method_name_length_ptr, 964 VOID **context_pptr, USHORT *context_length_ptr, 965 NX_PACKET **packet_pptr, UINT wait_option); 966``` 967**Description** 968 969<p>This routine receives direct method message from IoT Hub. If there are no messages in the receive queue, this routine can block. The amount of time it waits for a message is determined by the wait_option parameter.</p> 970 971**Parameters** 972 973| Name | Description | 974| - |:-| 975| hub_client_ptr [in] | A pointer to a `NX_AZURE_IOT_HUB_CLIENT`. | 976| method_name_pptr [out] | Return a pointer to method name on success. | 977| method_name_length_ptr [out] | Return length of method name on success. | 978| context_pptr [out] | Return a pointer to context pointer on success. | 979| context_length_ptr [out] | Return length of context on success. | 980| packet_pptr [out] | Return `NX_PACKET` containing the method payload on success. Caller owns the `NX_PACKET` memory. | 981| wait_option [in] | Ticks to wait for message to arrive. | 982 983 984**Return Values** 985* NX_AZURE_IOT_SUCCESS Successful if direct method message is received. 986* NX_AZURE_IOT_INVALID_PARAMETER Fail to receive direct method message due to invalid parameter. 987* NX_AZURE_IOT_NOT_ENABLED Fail to receive direct method message due to it is not enabled. 988* NX_AZURE_IOT_NO_PACKET Fail to receive direct method message due to timeout. 989* NX_AZURE_IOT_INVALID_PACKET Fail to receive direct method message due to invalid packet. 990* NX_AZURE_IOT_SDK_CORE_ERROR Fail to receive direct method message due to SDK core error. 991* NX_AZURE_IOT_DISCONNECTED Fail to receive direct method message due to disconnect. 992 993**Allowed From** 994 995Threads 996 997**Example** 998 999**See Also** 1000 1001<div style="page-break-after: always;"></div> 1002 1003#### **nx_azure_iot_hub_client_direct_method_message_response** 1004*** 1005<div style="text-align: right"> Return response to direct method message from IoTHub</div> 1006 1007**Prototype** 1008```c 1009UINT nx_azure_iot_hub_client_direct_method_message_response(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 1010 UINT status_code, VOID *context_ptr, USHORT context_length,, 1011 const UCHAR *payload, UINT payload_length, UINT wait_option); 1012``` 1013**Description** 1014 1015<p>This routine returns response to the direct method message from IoT Hub. Note: request_id ties the correlation between direct method receive and response.</p> 1016 1017**Parameters** 1018 1019| Name | Description | 1020| - |:-| 1021| hub_client_ptr [in] | A pointer to a `NX_AZURE_IOT_HUB_CLIENT`. | 1022| status_code [in] | Status code for direct method. | 1023| context_ptr [in] | Pointer to context return from nx_azure_iot_hub_client_direct_method_message_receive. | 1024| context_length [in] | Length of context. | 1025| payload [in] | Pointer to `UCHAR` containing the payload for the direct method response. Payload is in JSON format. | 1026| payload_length [in] | Length of the payload | 1027| wait_option [in] | Ticks to wait for message to send. | 1028 1029 1030**Return Values** 1031* NX_AZURE_IOT_SUCCESS Successful if direct method response is send. 1032* NX_AZURE_IOT_INVALID_PARAMETER Fail to send direct method response due to invalid parameter. 1033* NX_AZURE_IOT_SDK_CORE_ERROR Fail to send direct method response due to SDK core error. 1034* NX_NO_PACKET Fail send direct method response due to no available packet in pool. 1035 1036**Allowed From** 1037 1038Threads 1039 1040**Example** 1041 1042**See Also** 1043 1044<div style="page-break-after: always;"></div> 1045 1046#### **nx_azure_iot_hub_client_command_enable** 1047*** 1048<div style="text-align: right"> Enables receiving command messages from IoTHub </div> 1049 1050**Prototype** 1051```c 1052UINT nx_azure_iot_hub_client_command_enable(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr); 1053 1054``` 1055**Description** 1056 1057<p>This routine enables receiving command messages from IoT Hub. </p> 1058 1059**Parameters** 1060| Name | Description | 1061| - |:-| 1062| hub_client_ptr [in] | A pointer to a `NX_AZURE_IOT_HUB_CLIENT` | 1063 1064**Return Values** 1065* NX_AZURE_IOT_SUCCESS Successful if command message receiving is enabled. 1066* NX_AZURE_IOT_INVALID_PARAMETER Fail to enable command message receiving due to invalid parameter. 1067* NXD_MQTT_NOT_CONNECTED Fail to enable command message receiving due to MQTT not connected. 1068* NXD_MQTT_PACKET_POOL_FAILURE Fail to enable command message receiving due to no available packet in pool. 1069* NXD_MQTT_COMMUNICATION_FAILURE Fail to enable command message receiving due to TCP/TLS error. 1070 1071**Allowed From** 1072 1073Threads 1074 1075**Example** 1076 1077**See Also** 1078 1079<div style="page-break-after: always;"></div> 1080 1081#### **nx_azure_iot_hub_client_command_disable** 1082*** 1083<div style="text-align: right"> Disables receiving command messages from IoTHub</div> 1084 1085**Prototype** 1086```c 1087UINT nx_azure_iot_hub_client_command_disable(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr); 1088``` 1089**Description** 1090 1091<p>This routine disables receiving command messages from IoT Hub.</p> 1092 1093**Parameters** 1094 1095| Name | Description | 1096| - |:-| 1097| hub_client_ptr [in] | A pointer to a `NX_AZURE_IOT_HUB_CLIENT`. | 1098 1099 1100**Return Values** 1101* NX_AZURE_IOT_SUCCESS Successful if command message receiving is disabled. 1102* NX_AZURE_IOT_INVALID_PARAMETER Fail to disable command message receiving due to invalid parameter. 1103* NXD_MQTT_NOT_CONNECTED Fail to disable command message receiving due to MQTT not connected. 1104* NXD_MQTT_PACKET_POOL_FAILURE Fail to disable command message receiving due to no available packet in pool. 1105* NXD_MQTT_COMMUNICATION_FAILURE Fail to disable command message receiving due to TCP/TLS error. 1106 1107**Allowed From** 1108 1109Threads 1110 1111**Example** 1112 1113**See Also** 1114 1115<div style="page-break-after: always;"></div> 1116 1117#### **nx_azure_iot_hub_client_command_message_receive** 1118*** 1119<div style="text-align: right"> Receives IoT Hub command message from IoTHub</div> 1120 1121**Prototype** 1122```c 1123UINT nx_azure_iot_hub_client_command_message_receive(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 1124 const UCHAR **component_name_pptr, 1125 USHORT *component_name_length_ptr, 1126 const UCHAR **pnp_command_name_pptr, 1127 USHORT *pnp_command_name_length_ptr, 1128 VOID **context_pptr, 1129 USHORT *context_length_ptr, 1130 NX_PACKET **packet_pptr, 1131 UINT wait_option); 1132``` 1133**Description** 1134 1135<p>This routine receives IoT Hub command message from IoT Hub. If there are no messages in the receive queue, this routine can block.</p> 1136 1137**Parameters** 1138 1139| Name | Description | 1140| - |:-| 1141| hub_client_ptr [in] | A pointer to a `NX_AZURE_IOT_HUB_CLIENT`. | 1142| component_name_pptr [out] | Return a pointer to IoT Hub component name on success. | 1143| component_name_length_ptr [out] | Return length of `*component_name_pptr` on success. | 1144| pnp_command_name_pptr [out] | Return a pointer to IoT Hub command name on success. | 1145| pnp_command_name_length_ptr [out] | Return length of `*pnp_command_name_pptr` on success. | 1146| context_pptr [out] | Return a pointer to context pointer on success. | 1147| context_length_ptr [out] | Return length of context on success. | 1148| packet_pptr [out] | Return `NX_PACKET` containing the command payload on success. Caller owns the `NX_PACKET` memory. | 1149| wait_option [in] | Ticks to wait for message to arrive. | 1150 1151 1152**Return Values** 1153* NX_AZURE_IOT_SUCCESS Successful if IoT Hub command message is received. 1154* NX_AZURE_IOT_INVALID_PARAMETER Fail to receive IoT Hub command message due to invalid parameter. 1155* NX_AZURE_IOT_NOT_ENABLED Fail to receive IoT Hub command message due to it is not enabled. 1156* NX_AZURE_IOT_NO_PACKET Fail to receive IoT Hub command message due to timeout. 1157* NX_AZURE_IOT_INVALID_PACKET Fail to receive IoT Hub command message due to invalid packet. 1158* NX_AZURE_IOT_SDK_CORE_ERROR Fail to receive IoT Hub command message due to SDK core error. 1159* NX_AZURE_IOT_DISCONNECTED Fail to receive IoT Hub command message due to disconnect. 1160 1161**Allowed From** 1162 1163Threads 1164 1165**Example** 1166 1167**See Also** 1168 1169<div style="page-break-after: always;"></div> 1170 1171#### **nx_azure_iot_hub_client_command_message_response** 1172*** 1173<div style="text-align: right"> Return response to IoT hub command message from IoTHub</div> 1174 1175**Prototype** 1176```c 1177UINT nx_azure_iot_hub_client_command_message_response(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 1178 UINT status_code, VOID *context_ptr, 1179 USHORT context_length, const UCHAR *payload_ptr, 1180 UINT payload_length, UINT wait_option); 1181``` 1182**Description** 1183 1184<p>This routine returns response to the IoT hub command message from IoT Hub. Note: request_id ties the correlation between command receive and response.</p> 1185 1186**Parameters** 1187 1188| Name | Description | 1189| - |:-| 1190| hub_client_ptr [in] | A pointer to a `NX_AZURE_IOT_HUB_CLIENT`. | 1191| status_code [in] | Status code for pnp command message. | 1192| context_ptr [in] | Pointer to context return from nx_azure_iot_hub_client_command_receive. | 1193| context_length [in] | Length of context. | 1194| payload [in] | Pointer to `UCHAR` containing the payload for the IoT Hub command response. Payload is in JSON format. | 1195| payload_length [in] | Length of the payload | 1196| wait_option [in] | Ticks to wait for message to send. | 1197 1198 1199**Return Values** 1200* NX_AZURE_IOT_SUCCESS Successful if IoT Hub command response is send. 1201* NX_AZURE_IOT_INVALID_PARAMETER Fail to send IoT Hub command response due to invalid parameter. 1202* NX_AZURE_IOT_SDK_CORE_ERROR Fail to send IoT Hub command response due to SDK core error. 1203* NX_NO_PACKET Fail send IoT Hub command response due to no available packet in pool. 1204 1205**Allowed From** 1206 1207Threads 1208 1209**Example** 1210 1211**See Also** 1212 1213<div style="page-break-after: always;"></div> 1214 1215#### **nx_azure_iot_hub_client_device_twin_enable** 1216*** 1217<div style="text-align: right">Enables device twin feature</div> 1218 1219**Prototype** 1220```c 1221UINT nx_azure_iot_hub_client_device_twin_enable(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr); 1222``` 1223**Description** 1224 1225<p>This routine enables device twin feature.</p> 1226 1227**Parameters** 1228 1229| Name | Description | 1230| - |:-| 1231| hub_client_ptr [in] | A pointer to a `NX_AZURE_IOT_HUB_CLIENT`. | 1232 1233 1234**Return Values** 1235* NX_AZURE_IOT_SUCCESS Successful if device twin feature is enabled. 1236* NX_AZURE_IOT_INVALID_PARAMETER Fail to enable device twin feature due to invalid parameter. 1237* NXD_MQTT_NOT_CONNECTED Fail to enable device twin feature due to MQTT not connected. 1238* NXD_MQTT_PACKET_POOL_FAILURE Fail to enable device twin feature due to no available packet in pool. 1239* NXD_MQTT_COMMUNICATION_FAILURE Fail to enable device twin feature due to TCP/TLS error. 1240 1241**Allowed From** 1242 1243Threads 1244 1245**Example** 1246 1247**See Also** 1248 1249 1250<div style="page-break-after: always;"></div> 1251 1252#### **nx_azure_iot_hub_client_device_twin_disable** 1253*** 1254<div style="text-align: right">Disables device twin feature</div> 1255 1256**Prototype** 1257```c 1258UINT nx_azure_iot_hub_client_device_twin_disable(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr); 1259``` 1260**Description** 1261 1262<p>This routine disables device twin feature.</p> 1263 1264**Parameters** 1265 1266| Name | Description | 1267| - |:-| 1268| hub_client_ptr [in] | A pointer to a `NX_AZURE_IOT_HUB_CLIENT`. | 1269 1270 1271**Return Values** 1272* NX_AZURE_IOT_SUCCESS Successful if device twin feature is disabled. 1273* NX_AZURE_IOT_INVALID_PARAMETER Fail to disable device twin feature due to invalid parameter. 1274* NXD_MQTT_NOT_CONNECTED Fail to disable device twin feature due to MQTT not connected. 1275* NXD_MQTT_PACKET_POOL_FAILURE Fail to disable device twin feature due to no available packet in pool. 1276* NXD_MQTT_COMMUNICATION_FAILURE Fail to disable device twin feature due to TCP/TLS error. 1277 1278**Allowed From** 1279 1280Threads 1281 1282**Example** 1283 1284**See Also** 1285 1286 1287<div style="page-break-after: always;"></div> 1288 1289#### **nx_azure_iot_hub_client_reported_properties_response_callback_set** 1290*** 1291<div style="text-align: right">Sets reported properties response callback function</div> 1292 1293**Prototype** 1294```c 1295UINT nx_azure_iot_hub_client_reported_properties_response_callback_set(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 1296 VOID (*callback_ptr)( 1297 NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 1298 UINT request_id, 1299 UINT response_status, 1300 ULONG version, 1301 VOID *args), 1302 VOID *callback_args); 1303``` 1304**Description** 1305 1306<p>This routine sets the response receive callback function for reported properties. This callback function is invoked when a response is received from Azure IoT hub for reported properties and no thread is waiting for response. Setting the callback function to NULL disables the callback function.</p> 1307 1308**Parameters** 1309 1310| Name | Description | 1311| - |:-| 1312| hub_client_ptr [in] | A pointer to a `NX_AZURE_IOT_HUB_CLIENT`. | 1313| callback_ptr [in] | Pointer to a callback function invoked. | 1314| callback_args [in] | Pointer to an argument passed to callback function. | 1315 1316 1317**Return Values** 1318* NX_AZURE_IOT_SUCCESS Successful if callback function is set. 1319* NX_AZURE_IOT_INVALID_PARAMETER Fail to set callback due to invalid parameter. 1320 1321**Allowed From** 1322 1323Threads 1324 1325**Example** 1326 1327**See Also** 1328 1329 1330<div style="page-break-after: always;"></div> 1331 1332#### **nx_azure_iot_hub_client_device_twin_reported_properties_send** 1333*** 1334<div style="text-align: right">Send device twin reported properties to IoT Hub</div> 1335 1336**Prototype** 1337```c 1338UINT nx_azure_iot_hub_client_device_twin_reported_properties_send(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 1339 const UCHAR *message_buffer, UINT message_length, 1340 UINT *request_id_ptr, UINT *response_status_ptr, 1341 ULONG *version_ptr, UINT wait_option); 1342``` 1343**Description** 1344 1345<p>This routine sends device twin reported properties to IoT Hub.</p> 1346 1347**Parameters** 1348 1349| Name | Description | 1350| - |:-| 1351| hub_client_ptr [in] | A pointer to a `NX_AZURE_IOT_HUB_CLIENT`. | 1352| message_buffer [in] | JSON document containing the reported properties. | 1353| message_length [in] | Length of JSON document. | 1354| request_id_ptr [out] | Request Id assigned to the request. | 1355| response_status_ptr [out] | Status return for successful send of reported properties.| 1356| version_ptr [out] | Version return for successful send of reported properties.| 1357| wait_option [in] | Ticks to wait for message to send. | 1358 1359 1360**Return Values** 1361* NX_AZURE_IOT_SUCCESS Successful if device twin reported properties is sent. 1362* NX_AZURE_IOT_INVALID_PARAMETER Fail to send reported properties due to invalid parameter. 1363* NX_AZURE_IOT_NOT_ENABLED Fail to send reported properties due to device twin is not enabled. 1364* NX_AZURE_IOT_SDK_CORE_ERROR Fail to send reported properties due to SDK core error. 1365* NX_AZURE_IOT_INSUFFICIENT_BUFFER_SPACE Fail to send reported properties due to buffer size is too small. 1366* NX_AZURE_IOT_NO_PACKET Fail to send reported properties due to no packet available. 1367* NX_NO_PACKET Fail to send reported properties due to no packet available. 1368* NX_AZURE_IOT_DISCONNECTED Fail to send reported properties due to disconnect. 1369 1370**Allowed From** 1371 1372Threads 1373 1374**Example** 1375 1376**See Also** 1377 1378 1379<div style="page-break-after: always;"></div> 1380 1381#### **nx_azure_iot_hub_client_device_twin_properties_request** 1382*** 1383<div style="text-align: right">Request complete device twin properties</div> 1384 1385**Prototype** 1386```c 1387UINT nx_azure_iot_hub_client_device_twin_properties_request(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 1388 UINT wait_option); 1389``` 1390**Description** 1391 1392<p>This routine requests complete device twin properties.</p> 1393 1394**Parameters** 1395 1396| Name | Description | 1397| - |:-| 1398| hub_client_ptr [in] | A pointer to a `NX_AZURE_IOT_HUB_CLIENT`. | 1399| wait_option [in] | Ticks to wait for to wait for sending request. | 1400 1401 1402**Return Values** 1403* NX_AZURE_IOT_SUCCESS Successful if device twin properties is requested. 1404* NX_AZURE_IOT_INVALID_PARAMETER Fail to send device twin request due to invalid parameter. 1405* NX_AZURE_IOT_NO_SUBSCRIBE_ACK Fail to send device twin request due to no subscribe ack. 1406* NX_AZURE_IOT_SDK_CORE_ERROR Fail to send device twin request due to SDK core error. 1407* NX_AZURE_IOT_INSUFFICIENT_BUFFER_SPACE Fail to send device twin request due to buffer size is too small. 1408* NX_AZURE_IOT_NO_PACKET Fail to send reported properties due to no packet available. 1409* NX_NO_PACKET Fail to send reported properties due to no packet available. 1410 1411**Allowed From** 1412 1413Threads 1414 1415**Example** 1416 1417**See Also** 1418 1419<div style="page-break-after: always;"></div> 1420 1421#### **nx_azure_iot_hub_client_device_twin_properties_receive** 1422*** 1423<div style="text-align: right">Receive complete device twin properties</div> 1424 1425**Prototype** 1426```c 1427UINT nx_azure_iot_hub_client_device_twin_properties_receive(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 1428 NX_PACKET **packet_pptr, UINT wait_option); 1429``` 1430**Description** 1431 1432<p>This routine receives complete device twin properties.</p> 1433 1434**Parameters** 1435 1436| Name | Description | 1437| - |:-| 1438| hub_client_ptr [in] | A pointer to a `NX_AZURE_IOT_HUB_CLIENT`. | 1439| packet_pptr [out] | Pointer to `NX_PACKET*` that contains complete device twin properties. Caller owns the `NX_PACKET` memory. | 1440| wait_option [in] | Ticks to wait for message to receive. | 1441 1442 1443**Return Values** 1444* NX_AZURE_IOT_SUCCESS Successful if device twin properties is received. 1445* NX_AZURE_IOT_INVALID_PARAMETER Fail to receive device twin properties due to invalid parameter. 1446* NX_AZURE_IOT_NOT_ENABLED Fail to receive device twin properties due to it is not enabled. 1447* NX_AZURE_IOT_NO_PACKET Fail to receive device twin properties due to timeout. 1448* NX_AZURE_IOT_INVALID_PACKET Fail to receive device twin properties due to invalid packet. 1449* NX_AZURE_IOT_SDK_CORE_ERROR Fail to receive device twin properties due to SDK core error. 1450* NX_AZURE_IOT_SERVER_RESPONSE_ERROR Response code from server is not 2xx. 1451* NX_AZURE_IOT_DISCONNECTED Fail to receive device twin properties due to disconnect. 1452 1453**Allowed From** 1454 1455Threads 1456 1457**Example** 1458 1459**See Also** 1460 1461<div style="page-break-after: always;"></div> 1462 1463#### **nx_azure_iot_hub_client_device_twin_desired_properties_receive** 1464*** 1465<div style="text-align: right">Receive desired properties form IoTHub</div> 1466 1467**Prototype** 1468```c 1469UINT nx_azure_iot_hub_client_device_twin_desired_properties_receive(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 1470 NX_PACKET **packet_pptr, UINT wait_option); 1471``` 1472**Description** 1473 1474<p>This routine receives desired properties from IoTHub.</p> 1475 1476**Parameters** 1477 1478| Name | Description | 1479| - |:-| 1480| hub_client_ptr [in] | A pointer to a `NX_AZURE_IOT_HUB_CLIENT`. | 1481| packet_pptr [out] | Pointer to `NX_PACKET*` that contains complete twin document. Caller owns the `NX_PACKET` memory. | 1482| wait_option [in] | Ticks to wait for message to receive. | 1483 1484 1485**Return Values** 1486* NX_AZURE_IOT_SUCCESS Successful if desired properties is received. 1487* NX_AZURE_IOT_INVALID_PARAMETER Fail to receive desired properties due to invalid parameter. 1488* NX_AZURE_IOT_NOT_ENABLED Fail to receive desired properties due to it is not enabled. 1489* NX_AZURE_IOT_NO_PACKET Fail to receive desired properties due to timeout. 1490* NX_AZURE_IOT_INVALID_PACKET Fail to receive desired properties due to invalid packet. 1491* NX_AZURE_IOT_DISCONNECTED Fail to receive desired properties due to disconnect. 1492 1493**Allowed From** 1494 1495Threads 1496 1497**Example** 1498 1499**See Also** 1500 1501<div style="page-break-after: always;"></div> 1502 1503#### **nx_azure_iot_hub_client_properties_enable** 1504*** 1505<div style="text-align: right">Enables properties feature</div> 1506 1507**Prototype** 1508```c 1509UINT nx_azure_iot_hub_client_properties_enable(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr); 1510``` 1511**Description** 1512 1513<p>This routine enables properties feature.</p> 1514 1515**Parameters** 1516 1517| Name | Description | 1518| - |:-| 1519| hub_client_ptr [in] | A pointer to a `NX_AZURE_IOT_HUB_CLIENT`. | 1520 1521 1522**Return Values** 1523* NX_AZURE_IOT_SUCCESS Successful if properties feature is enabled. 1524* NX_AZURE_IOT_INVALID_PARAMETER Fail to enable properties feature due to invalid parameter. 1525* NXD_MQTT_NOT_CONNECTED Fail to enable properties feature due to MQTT not connected. 1526* NXD_MQTT_PACKET_POOL_FAILURE Fail to enable properties feature due to no available packet in pool. 1527* NXD_MQTT_COMMUNICATION_FAILURE Fail to enable properties feature due to TCP/TLS error. 1528 1529**Allowed From** 1530 1531Threads 1532 1533**Example** 1534 1535**See Also** 1536 1537 1538<div style="page-break-after: always;"></div> 1539 1540#### **nx_azure_iot_hub_client_properties_disable** 1541*** 1542<div style="text-align: right">Disables properties feature</div> 1543 1544**Prototype** 1545```c 1546UINT nx_azure_iot_hub_client_properties_disable(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr); 1547``` 1548**Description** 1549 1550<p>This routine disables properties feature.</p> 1551 1552**Parameters** 1553 1554| Name | Description | 1555| - |:-| 1556| hub_client_ptr [in] | A pointer to a `NX_AZURE_IOT_HUB_CLIENT`. | 1557 1558 1559**Return Values** 1560* NX_AZURE_IOT_SUCCESS Successful if properties feature is disabled. 1561* NX_AZURE_IOT_INVALID_PARAMETER Fail to disable properties feature due to invalid parameter. 1562* NXD_MQTT_NOT_CONNECTED Fail to disable properties feature due to MQTT not connected. 1563* NXD_MQTT_PACKET_POOL_FAILURE Fail to disable properties feature due to no available packet in pool. 1564* NXD_MQTT_COMMUNICATION_FAILURE Fail to disable properties feature due to TCP/TLS error. 1565 1566**Allowed From** 1567 1568Threads 1569 1570**Example** 1571 1572**See Also** 1573 1574 1575<div style="page-break-after: always;"></div> 1576 1577#### **nx_azure_iot_hub_client_reported_properties_create** 1578*** 1579<div style="text-align: right">Creates IoT Hub reported property message.</div> 1580 1581**Prototype** 1582```c 1583UINT nx_azure_iot_hub_client_reported_properties_create(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 1584 NX_PACKET **packet_pptr, 1585 UINT wait_option) 1586``` 1587**Description** 1588 1589<p>This routine creates a reported properties message.</p> 1590 1591**Parameters** 1592 1593| Name | Description | 1594| - |:-| 1595| hub_client_ptr [in] | A pointer to a `NX_AZURE_IOT_HUB_CLIENT`. | 1596| packet_pptr [out] | Return allocated packet on success. | 1597| wait_option [in] | Ticks to wait for writer creation. | 1598 1599 1600**Return Values** 1601* NX_AZURE_IOT_SUCCESS Successful if a message writer is created. 1602* NX_AZURE_IOT_INVALID_PARAMETER Fail to create message writer due to invalid parameter. 1603* NX_AZURE_IOT_SDK_CORE_ERROR Fail to create message writer due to SDK core error. 1604* NX_NO_PACKET Fail to create message writer due to no available packet in pool. 1605 1606**Allowed From** 1607 1608Threads 1609 1610**Example** 1611 1612**See Also** 1613 1614 1615<div style="page-break-after: always;"></div> 1616 1617#### **nx_azure_iot_hub_client_reported_properties_send** 1618*** 1619<div style="text-align: right">Sends IoT Hub reported properties message to IoTHub.</div> 1620 1621**Prototype** 1622```c 1623UINT nx_azure_iot_hub_client_reported_properties_send(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 1624 NX_PACKET *packet_ptr, 1625 UINT *request_id_ptr, UINT *response_status_ptr, 1626 ULONG *version_ptr, UINT wait_option); 1627``` 1628**Description** 1629 1630<p>This routine sends the reported properties contain in the packet.</p> 1631<p>Note: The return status of the API indicates if the reported properties is sent out successfully or not, 1632the response status is used to track if the reported properties is accepted or not by IoT Hub, and the 1633reponse status is available only when the return status is NX_AZURE_IOT_SUCCESS.</p> 1634 1635**Parameters** 1636 1637| Name | Description | 1638| - |:-| 1639| hub_client_ptr [in] | A pointer to a `NX_AZURE_IOT_HUB_CLIENT`. | 1640| packet_ptr [in] | A pointer to a #NX_PACKET. | 1641| request_id_ptr [out] | Request Id assigned to the request. | 1642| response_status_ptr [out] | Status return for successful send of reported properties. | 1643| version_ptr [out] | Version return for successful send of reported properties. | 1644| wait_option [in] | Ticks to wait for message to send. | 1645 1646 1647**Return Values** 1648 * NX_AZURE_IOT_SUCCESS Successful if reported properties is sent. 1649 * NX_AZURE_IOT_INVALID_PARAMETER Fail to send reported properties due to invalid parameter. 1650 * NX_AZURE_IOT_NOT_ENABLED Fail to send reported properties due to property is not enabled. 1651 * NX_AZURE_IOT_SDK_CORE_ERROR Fail to send reported properties due to SDK core error. 1652 * NX_AZURE_IOT_INSUFFICIENT_BUFFER_SPACE Fail to send reported properties due to buffer size is too small. 1653 * NX_NO_PACKET Fail to send reported properties due to no packet available. 1654 * NX_AZURE_IOT_DISCONNECTED Fail to send reported properties due to disconnect. 1655 1656**Allowed From** 1657 1658Threads 1659 1660**Example** 1661 1662**See Also** 1663 1664<div style="page-break-after: always;"></div> 1665 1666#### **nx_azure_iot_hub_client_properties_request** 1667*** 1668<div style="text-align: right">Request complete properties</div> 1669 1670**Prototype** 1671```c 1672UINT nx_azure_iot_hub_client_properties_request(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 1673 UINT wait_option); 1674``` 1675**Description** 1676 1677<p>This routine requests complete properties.</p> 1678 1679**Parameters** 1680 1681| Name | Description | 1682| - |:-| 1683| hub_client_ptr [in] | A pointer to a `NX_AZURE_IOT_HUB_CLIENT`. | 1684| wait_option [in] | Ticks to wait for to wait for sending request. | 1685 1686 1687**Return Values** 1688* NX_AZURE_IOT_SUCCESS Successful if request get all properties is sent.. 1689* NX_AZURE_IOT_INVALID_PARAMETER Fail to request get all properties due to invalid parameter. 1690* NX_AZURE_IOT_NO_SUBSCRIBE_ACK Fail to request get all properties due to no subscribe ack. 1691* NX_AZURE_IOT_SDK_CORE_ERROR Fail to request get all properties due to SDK core error. 1692* NX_AZURE_IOT_INSUFFICIENT_BUFFER_SPACE Fail to request get all properties due to buffer size is too small. 1693* NX_AZURE_IOT_NO_PACKET Fail to request get all properties due to no packet available. 1694* NX_NO_PACKET Fail to request get all properties due to no packet available. 1695 1696**Allowed From** 1697 1698Threads 1699 1700**Example** 1701 1702**See Also** 1703 1704<div style="page-break-after: always;"></div> 1705 1706#### **nx_azure_iot_hub_client_properties_receive** 1707*** 1708<div style="text-align: right">Receive all the properties</div> 1709 1710**Prototype** 1711```c 1712UINT nx_azure_iot_hub_client_properties_receive(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 1713 NX_PACKET **packet_pptr, 1714 UINT wait_option); 1715``` 1716**Description** 1717 1718<p>This routine receives all the properties.</p> 1719 1720**Parameters** 1721 1722| Name | Description | 1723| - |:-| 1724| hub_client_ptr [in] | A pointer to a `NX_AZURE_IOT_HUB_CLIENT`. | 1725| packet_pptr [out] | A pointer to a #NX_PACKET containing all the properties. | 1726| wait_option [in] | Ticks to wait for message to receive. | 1727 1728 1729**Return Values** 1730* NX_AZURE_IOT_SUCCESS Successful if all properties is received. 1731* NX_AZURE_IOT_INVALID_PARAMETER Fail to receive all properties due to invalid parameter. 1732* NX_AZURE_IOT_NOT_ENABLED Fail to receive all properties due to it is not enabled. 1733* NX_AZURE_IOT_NO_PACKET Fail to receive all properties due to timeout. 1734* NX_AZURE_IOT_INVALID_PACKET Fail to receive all properties due to invalid packet. 1735* NX_AZURE_IOT_SDK_CORE_ERROR Fail to receive all properties due to SDK core error. 1736* NX_AZURE_IOT_SERVER_RESPONSE_ERROR Response code from server is not 2xx. 1737* NX_AZURE_IOT_DISCONNECTED Fail to receive all properties due to disconnect. 1738 1739**Allowed From** 1740 1741Threads 1742 1743**Example** 1744 1745**See Also** 1746 1747<div style="page-break-after: always;"></div> 1748 1749#### **nx_azure_iot_hub_client_writable_properties_receive** 1750*** 1751<div style="text-align: right">Receive writable properties form IoTHub</div> 1752 1753**Prototype** 1754```c 1755UINT nx_azure_iot_hub_client_writable_properties_receive(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr, 1756 NX_PACKET **packet_pptr, 1757 UINT wait_option); 1758``` 1759**Description** 1760 1761<p>This routine receives writable properties from IoTHub.</p> 1762 1763**Parameters** 1764 1765| Name | Description | 1766| - |:-| 1767| hub_client_ptr [in] | A pointer to a `NX_AZURE_IOT_HUB_CLIENT`. | 1768| packet_pptr [out] | A pointer to a #NX_PACKET containing writable properties. | 1769| wait_option [in] | Ticks to wait for message to receive. | 1770 1771 1772**Return Values** 1773* NX_AZURE_IOT_SUCCESS Successful if writable properties is received. 1774* NX_AZURE_IOT_INVALID_PARAMETER Fail to receive writable properties due to invalid parameter. 1775* NX_AZURE_IOT_NOT_ENABLED Fail to receive writable properties due to it is not enabled. 1776* NX_AZURE_IOT_NO_PACKET Fail to receive writable properties due to timeout. 1777* NX_AZURE_IOT_INVALID_PACKET Fail to receive writable properties due to invalid packet. 1778* NX_AZURE_IOT_DISCONNECTED Fail to receive writable properties due to disconnect. 1779 1780**Allowed From** 1781 1782Threads 1783 1784**Example** 1785 1786**See Also** 1787 1788<div style="page-break-after: always;"></div> 1789 1790
