1# Azure IoT Hub Client Properties
2
3**nx_azure_iot_hub_client_reported_properties_component_begin**
4***
5<div style="text-align: right">Append the necessary characters to a reported property JSON payload belonging to a subcomponent.</div>
6
7**Prototype**
8```c
9UINT nx_azure_iot_hub_client_reported_properties_component_begin(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr,
10                                                                 NX_AZURE_IOT_JSON_WRITER *writer_ptr,
11                                                                 const UCHAR *component_name_ptr,
12                                                                 USHORT component_name_length);
13```
14**Description**
15
16<p>This routine appends the necessary characters to a reported properties JSON payload belonging to a subcomponent. The payload will be of the form: </p>
17
18```c
19"reported": {
20    "<component_name>": {
21        "__t": "c",
22        "temperature": 23
23    }
24}
25```
26
27**Note** This API should be used in conjunction with
28```c
29nx_azure_iot_hub_client_reported_properties_component_end()
30```
31
32**Parameters**
33
34| Name | Description |
35| - |:-|
36| hub_client_ptr [in]    | A pointer to a `NX_AZURE_IOT_HUB_CLIENT`. |
37| writer_ptr [in]    | A pointer to a #NX_AZURE_IOT_JSON_WRITER. |
38| component_name_ptr [in]    | A pointer to a component name. |
39| component_name_length [in]    | Length of `component_name_ptr`. |
40
41
42**Return Values**
43* NX_AZURE_IOT_SUCCESS Successful if JSON payload was prefixed successfully.
44
45**Allowed From**
46
47Threads
48
49**Example**
50
51**See Also**
52
53
54<div style="page-break-after: always;"></div>
55
56**nx_azure_iot_hub_client_reported_properties_component_end**
57***
58<div style="text-align: right">Append the necessary characters to end a reported property JSON payload belonging to a subcomponent.</div>
59
60**Prototype**
61```c
62UINT nx_azure_iot_hub_client_reported_properties_component_end(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr,
63                                                               NX_AZURE_IOT_JSON_WRITER *writer_ptr);
64```
65**Description**
66
67<p>This routine appends the necessary characters to end a reported properties JSON payload</p>
68
69**Note** This API should be used in conjunction with
70
71```c
72nx_azure_iot_hub_client_reported_properties_component_begin()
73```
74
75
76**Parameters**
77
78| Name | Description |
79| - |:-|
80| hub_client_ptr [in]    | A pointer to a `NX_AZURE_IOT_HUB_CLIENT`. |
81| writer_ptr [in]    | A pointer to a #NX_AZURE_IOT_JSON_WRITER. |
82
83
84**Return Values**
85* NX_AZURE_IOT_SUCCESS The JSON payload was suffixed successfully.
86
87**Allowed From**
88
89Threads
90
91**Example**
92
93**See Also**
94
95
96<div style="page-break-after: always;"></div>
97
98**nx_azure_iot_hub_client_reported_properties_status_begin**
99***
100<div style="text-align: right"> Begin a property response payload with confirmation status.</div>
101
102**Prototype**
103```c
104UINT nx_azure_iot_hub_client_reported_properties_status_begin(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr,
105                                                              NX_AZURE_IOT_JSON_WRITER *writer_ptr,
106                                                              const UCHAR *property_name_ptr,
107                                                              UINT property_name_length,
108                                                              UINT status_code,
109                                                              ULONG version,
110                                                              const UCHAR *description_ptr,
111                                                              UINT description_length);
112```
113**Description**
114
115<p>This API should be used in response to an incoming writable property. More details can be found
116here:
117
118https://docs.microsoft.com/en-us/azure/iot-pnp/concepts-convention#writable-properties
119
120The payload will be of the form:
121<p>
122**Without component**
123
124```c
125//{
126//  "<property_name>":{
127//    "ac": <status_code>,
128//    "av": <version>,
129//    "ad": "<description>",
130//    "value": <user_value>
131//  }
132//}
133```
134
135<p>To send a status for a property belonging to a component, first call the
136nx_azure_iot_hub_client_reported_property_status_begin() API to prefix the payload with the
137necessary identification. The API call flow would look like the following with the listed JSON
138payload being generated.<p>
139
140**With component**
141
142```c
143nx_azure_iot_hub_client_reported_properties_component_begin()
144nx_azure_iot_hub_client_reported_properties_status_begin()
145// Append user value here (<user_value>)
146nx_azure_iot_hub_client_reported_properties_status_end()
147nx_azure_iot_hub_client_reported_properties_component_end()
148
149//{
150//  "<component_name>": {
151//    "__t": "c",
152//    "<property_name>": {
153//      "ac": <status_code>,
154//      "av": <version>,
155//      "ad": "<description>",
156//      "value": <user_value>
157//    }
158//  }
159//}
160```
161
162**Note** This API should be used in conjunction with
163```c
164nx_azure_iot_hub_client_reported_properties_status_end()
165```
166
167**Parameters**
168
169| Name | Description |
170| - |:-|
171| hub_client_ptr [in]    | A pointer to a `NX_AZURE_IOT_HUB_CLIENT`. |
172| writer_ptr [in]    | A pointer to a #NX_AZURE_IOT_JSON_WRITER. |
173| property_name_ptr [in]    | A pointer to property name. |
174| property_name_length [in]    |  Length of `property_name_ptr`. |
175| status_code [in]    | The HTTP-like status code to respond with. |
176| version [in]    | The version of the property the application is acknowledging. |
177| description_ptr [in]    | An optional pointer to description detailing the context or any details about the acknowledgement. This can be empty string. |
178| description_length [in]    | Length of description_ptr. |
179
180
181**Return Values**
182* NX_AZURE_IOT_SUCCESS Successful appended JSON prefix.
183
184**Allowed From**
185
186Threads
187
188**Example**
189
190**See Also**
191
192
193<div style="page-break-after: always;"></div>
194
195**nx_azure_iot_hub_client_reported_properties_status_end**
196***
197<div style="text-align: right">End a property response payload with confirmation status.</div>
198
199**Prototype**
200```c
201UINT nx_azure_iot_hub_client_reported_properties_status_end(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr,
202                                                          NX_AZURE_IOT_JSON_WRITER *writer_ptr);
203```
204**Description**
205
206<p>This routine ends the property response payload.</p>
207
208**Note** This API should be used in conjunction with
209```c
210nx_azure_iot_hub_client_reported_properties_status_begin()
211```
212
213**Parameters**
214
215| Name | Description |
216| - |:-|
217| hub_client_ptr [in]    | A pointer to a `NX_AZURE_IOT_HUB_CLIENT`. |
218| writer_ptr [in]    | A pointer to a #NX_AZURE_IOT_JSON_WRITER. |
219
220
221**Return Values**
222* NX_AZURE_IOT_SUCCESS Successful appended JSON suffix.
223
224**Allowed From**
225
226Threads
227
228**Example**
229
230**See Also**
231
232
233<div style="page-break-after: always;"></div>
234
235**nx_azure_iot_hub_client_properties_version_get**
236***
237<div style="text-align: right">Get the property version</div>
238
239**Prototype**
240```c
241UINT nx_azure_iot_hub_client_properties_version_get(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr,
242                                                    NX_AZURE_IOT_JSON_READER *reader_ptr,
243                                                    UINT message_type, ULONG *version_ptr);
244```
245**Description**
246
247<p>This routine gets the property version.</p>
248
249**Parameters**
250
251| Name | Description |
252| - |:-|
253| hub_client_ptr [in]    | A pointer to a `NX_AZURE_IOT_HUB_CLIENT`. |
254| reader_ptr [in]    | A pointer to a #NX_AZURE_IOT_JSON_READER containing properties document. |
255| message_type [in]    | Type of message repsonse, only valid value are NX_AZURE_IOT_HUB_PROPERTIES or NX_AZURE_IOT_HUB_WRITABLE_PROPERTIES. |
256| version_ptr [out]    | The numeric version of the properties in JSON payload. |
257
258
259**Return Values**
260* NX_AZURE_IOT_SUCCESS Successful if got the property version.
261
262**Allowed From**
263
264Threads
265
266**Example**
267
268**See Also**
269
270<div style="page-break-after: always;"></div>
271
272**nx_azure_iot_hub_client_properties_component_property_next_get**
273***
274<div style="text-align: right">Return the next desired or reported property in the property document passed.</div>
275
276**Prototype**
277```c
278UINT nx_azure_iot_hub_client_properties_component_property_next_get(NX_AZURE_IOT_HUB_CLIENT *hub_client_ptr,
279                                                                    NX_AZURE_IOT_JSON_READER *reader_ptr,
280                                                                    UINT message_type, UINT property_type,
281                                                                    const UCHAR **component_name_pptr,
282                                                                    USHORT *component_name_length_ptr);
283```
284**Description**
285
286<p>This routine gets the next writable or reported property in the properties document passed.</p>
287
288**Note**  that between calls, the UCHAR* pointed to by \p component_name_pptr shall not be modified, only checked and compared. Internally, the pointer is only changed if the component name changes in the JSON document and is not necessarily set every invocation of the function.
289
290On success, the `reader_ptr` will be set on a valid property name. After checking the property name, the reader can be advanced to the property value by calling nx_azure_iot_json_reader_next_token(). Note that on the subsequent call to this API, it is expected that the json reader will be placed AFTER the read property name and value. That means that after reading the property value (including single values or complex objects), the user must call nx_azure_iot_json_reader_next_token().
291
292Below is a code snippet which you can use as a starting point:
293```c
294 while ((status = nx_azure_iot_hub_client_properties_component_property_next_get(&iothub_client,
295                                                                                 &json_reader,
296                                                                                 message_type,
297                                                                                 NX_AZURE_IOT_HUB_CLIENT_PROPERTY_WRITABLE,
298                                                                                 &component_name_ptr, &component_length)) == NX_AZURE_IOT_SUCCESS)
299 {
300
301     /* Check if property is of interest (substitute user_property for your own property name)  */
302     if (nx_azure_iot_json_reader_token_is_text_equal(&json_reader, user_property, user_property_length))
303     {
304         nx_azure_iot_json_reader_next_token(&json_reader);
305
306         /* Get the property value here
307            Example: nx_azure_iot_json_reader_token_int32_get(&json_reader, &user_int);  */
308
309         /* Skip to next property value  */
310         nx_azure_iot_json_reader_next_token(&json_reader);
311    }
312    else
313    {
314
315        /* The JSON reader must be advanced regardless of whether the property
316           is of interest or not.  */
317        nx_azure_iot_json_reader_next_token(&json_reader);
318
319        /* Skip children in case the property value is an object.  */
320        nx_azure_iot_json_reader_skip_children(&json_reader);
321        nx_azure_iot_json_reader_next_token(&json_reader);
322    }
323}
324```
325
326**Parameters**
327
328| Name | Description |
329| - |:-|
330| hub_client_ptr [in]    | A pointer to a `NX_AZURE_IOT_HUB_CLIENT`. |
331| reader_ptr [in]    | A pointer to a #NX_AZURE_IOT_JSON_READER containing properties document. |
332| message_type [in]    | Type of message repsonse, only valid value are NX_AZURE_IOT_HUB_PROPERTIES or NX_AZURE_IOT_HUB_WRITABLE_PROPERTIES. |
333| property_type [in]    | Type of property, only valid value are NX_AZURE_IOT_HUB_CLIENT_PROPERTY_REPORTED_FROM_DEVICE or NX_AZURE_IOT_HUB_CLIENT_PROPERTY_WRITABLE. |
334| component_name_pptr [out]    | A pointer to component name for the property returned using reader_ptr. |
335| component_name_length_ptr [out]    | Length of the component name. |
336
337
338**Return Values**
339* NX_AZURE_IOT_SUCCESS Successful if next property is found.
340
341**Allowed From**
342
343Threads
344
345**Example**
346
347**See Also**
348
349<div style="page-break-after: always;"></div>
350
351