source: azure_iot_hub_f767zi/trunk/azure_iot_sdk/iothub_client/inc/iothub_device_client_ll.h@ 457

Last change on this file since 457 was 457, checked in by coas-nagasima, 4 years ago

ファイルを追加
  • Property svn:eol-style set to native
  • Property svn:mime-type set to text/x-chdr;charset=UTF-8
File size: 24.3 KB
Line 
1// Copyright (c) Microsoft. All rights reserved.
2// Licensed under the MIT license. See LICENSE file in the project root for full license information.
3
4/** @file iothub_device_client_ll.h
5* @brief APIs that allow a user (usually a device) to communicate
6* with an Azure IoTHub.
7*
8* @details IoTHubDeviceClient_LL is a module that allows a user (usually a
9* device) to communicate with an Azure IoTHub. It can send events
10* and receive messages. At any given moment in time there can only
11* be at most 1 message callback function.
12*
13* This API surface contains a set of APIs that allows the user to
14* interact with the lower layer portion of the IoTHubClient. These APIs
15* contain @c _LL_ in their name, but retain the same functionality like the
16* @c IoTHubDeviceClient_... APIs, with one difference. If the @c _LL_ APIs are
17* used then the user is responsible for scheduling when the actual work done
18* by the IoTHubClient happens (when the data is sent/received on/from the wire).
19* This is useful for constrained devices where spinning a separate thread is
20* often not desired.
21*/
22
23#ifndef IOTHUB_DEVICE_CLIENT_LL_H
24#define IOTHUB_DEVICE_CLIENT_LL_H
25
26#include <stddef.h>
27#include <stdint.h>
28
29#include "azure_macro_utils/macro_utils.h"
30#include "umock_c/umock_c_prod.h"
31
32#include "iothub_transport_ll.h"
33#include "iothub_client_core_ll.h"
34
35#ifdef __cplusplus
36extern "C"
37{
38#endif
39
40typedef struct IOTHUB_CLIENT_CORE_LL_HANDLE_DATA_TAG* IOTHUB_DEVICE_CLIENT_LL_HANDLE;
41
42
43 /**
44 * @brief Creates a IoT Hub client for communication with an existing
45 * IoT Hub using the specified connection string parameter.
46 *
47 * @param connectionString Pointer to a character string
48 * @param protocol Function pointer for protocol implementation
49 *
50 * Sample connection string:
51 * <blockquote>
52 * <pre>HostName=[IoT Hub name goes here].[IoT Hub suffix goes here, e.g., private.azure-devices-int.net];DeviceId=[Device ID goes here];SharedAccessKey=[Device key goes here];</pre>
53 * </blockquote>
54 *
55 * @return A non-NULL @c IOTHUB_DEVICE_CLIENT_LL_HANDLE value that is used when
56 * invoking other functions for IoT Hub client and @c NULL on failure.
57 */
58 MOCKABLE_FUNCTION(, IOTHUB_DEVICE_CLIENT_LL_HANDLE, IoTHubDeviceClient_LL_CreateFromConnectionString, const char*, connectionString, IOTHUB_CLIENT_TRANSPORT_PROVIDER, protocol);
59
60 /**
61 * @brief Creates a IoT Hub client for communication with an existing IoT
62 * Hub using the specified parameters.
63 *
64 * @param config Pointer to an @c IOTHUB_CLIENT_CONFIG structure
65 *
66 * The API does not allow sharing of a connection across multiple
67 * devices. This is a blocking call.
68 *
69 * @return A non-NULL @c IOTHUB_DEVICE_CLIENT_LL_HANDLE value that is used when
70 * invoking other functions for IoT Hub client and @c NULL on failure.
71 */
72 MOCKABLE_FUNCTION(, IOTHUB_DEVICE_CLIENT_LL_HANDLE, IoTHubDeviceClient_LL_Create, const IOTHUB_CLIENT_CONFIG*, config);
73
74 /**
75 * @brief Creates a IoT Hub client for communication with an existing IoT
76 * Hub using an existing transport.
77 *
78 * @param config Pointer to an @c IOTHUB_CLIENT_DEVICE_CONFIG structure
79 *
80 * The API *allows* sharing of a connection across multiple
81 * devices. This is a blocking call.
82 *
83 * @return A non-NULL @c IOTHUB_DEVICE_CLIENT_LL_HANDLE value that is used when
84 * invoking other functions for IoT Hub client and @c NULL on failure.
85 */
86 MOCKABLE_FUNCTION(, IOTHUB_DEVICE_CLIENT_LL_HANDLE, IoTHubDeviceClient_LL_CreateWithTransport, const IOTHUB_CLIENT_DEVICE_CONFIG*, config);
87
88 /**
89 * @brief Creates a IoT Hub client for communication with an existing IoT
90 * Hub using the device auth module.
91 *
92 * @param iothub_uri Pointer to an ioThub hostname received in the registration process
93 * @param device_id Pointer to the device Id of the device
94 * @param device_auth_handle A device auth handle used to generate the connection string
95 * @param protocol Function pointer for protocol implementation
96 *
97 * @return A non-NULL @c IOTHUB_DEVICE_CLIENT_LL_HANDLE value that is used when
98 * invoking other functions for IoT Hub client and @c NULL on failure.
99 */
100 MOCKABLE_FUNCTION(, IOTHUB_DEVICE_CLIENT_LL_HANDLE, IoTHubDeviceClient_LL_CreateFromDeviceAuth, const char*, iothub_uri, const char*, device_id, IOTHUB_CLIENT_TRANSPORT_PROVIDER, protocol);
101
102 /**
103 * @brief Disposes of resources allocated by the IoT Hub client. This is a
104 * blocking call.
105 *
106 * @param iotHubClientHandle The handle created by a call to the create function.
107 */
108 MOCKABLE_FUNCTION(, void, IoTHubDeviceClient_LL_Destroy, IOTHUB_DEVICE_CLIENT_LL_HANDLE, iotHubClientHandle);
109
110 /**
111 * @brief Asynchronous call to send the message specified by @p eventMessageHandle.
112 *
113 * @param iotHubClientHandle The handle created by a call to the create function.
114 * @param eventMessageHandle The handle to an IoT Hub message.
115 * @param eventConfirmationCallback The callback specified by the device for receiving
116 * confirmation of the delivery of the IoT Hub message.
117 * This callback can be expected to invoke the
118 * ::IoTHubDeviceClient_LL_SendEventAsync function for the
119 * same message in an attempt to retry sending a failing
120 * message. The user can specify a @c NULL value here to
121 * indicate that no callback is required.
122 * @param userContextCallback User specified context that will be provided to the
123 * callback. This can be @c NULL.
124 *
125 * @b NOTE: The application behavior is undefined if the user calls
126 * the ::IoTHubDeviceClient_LL_Destroy function from within any callback.
127 * @remarks
128 * The IOTHUB_MESSAGE_HANDLE instance provided as argument is copied by the function,
129 * so this argument can be destroyed by the calling application right after IoTHubDeviceClient_LL_SendEventAsync returns.
130 * The copy of @c eventMessageHandle is later destroyed by the iothub client when the message is effectively sent, if a failure sending it occurs, or if the client is destroyed.
131 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
132 */
133 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubDeviceClient_LL_SendEventAsync, IOTHUB_DEVICE_CLIENT_LL_HANDLE, iotHubClientHandle, IOTHUB_MESSAGE_HANDLE, eventMessageHandle, IOTHUB_CLIENT_EVENT_CONFIRMATION_CALLBACK, eventConfirmationCallback, void*, userContextCallback);
134
135 /**
136 * @brief This function returns the current sending status for IoTHubClient.
137 *
138 * @param iotHubClientHandle The handle created by a call to the create function.
139 * @param iotHubClientStatus The sending state is populated at the address pointed
140 * at by this parameter. The value will be set to
141 * @c IOTHUBCLIENT_SENDSTATUS_IDLE if there is currently
142 * no item to be sent and @c IOTHUBCLIENT_SENDSTATUS_BUSY
143 * if there are.
144 *
145 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
146 */
147 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubDeviceClient_LL_GetSendStatus, IOTHUB_DEVICE_CLIENT_LL_HANDLE, iotHubClientHandle, IOTHUB_CLIENT_STATUS*, iotHubClientStatus);
148
149 /**
150 * @brief Sets up the message callback to be invoked when IoT Hub issues a
151 * message to the device. This is a blocking call.
152 *
153 * @param iotHubClientHandle The handle created by a call to the create function.
154 * @param messageCallback The callback specified by the device for receiving
155 * messages from IoT Hub.
156 * @param userContextCallback User specified context that will be provided to the
157 * callback. This can be @c NULL.
158 *
159 * @b NOTE: The application behavior is undefined if the user calls
160 * the ::IoTHubDeviceClient_LL_Destroy function from within any callback.
161 *
162 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
163 */
164 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubDeviceClient_LL_SetMessageCallback, IOTHUB_DEVICE_CLIENT_LL_HANDLE, iotHubClientHandle, IOTHUB_CLIENT_MESSAGE_CALLBACK_ASYNC, messageCallback, void*, userContextCallback);
165
166 /**
167 * @brief Sets up the connection status callback to be invoked representing the status of
168 * the connection to IOT Hub. This is a blocking call.
169 *
170 * @param iotHubClientHandle The handle created by a call to the create function.
171 * @param connectionStatusCallback The callback specified by the device for receiving
172 * updates about the status of the connection to IoT Hub.
173 * @param userContextCallback User specified context that will be provided to the
174 * callback. This can be @c NULL.
175 *
176 * @b NOTE: The application behavior is undefined if the user calls
177 * the ::IoTHubDeviceClient_LL_Destroy function from within any callback.
178 *
179 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
180 */
181 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubDeviceClient_LL_SetConnectionStatusCallback, IOTHUB_DEVICE_CLIENT_LL_HANDLE, iotHubClientHandle, IOTHUB_CLIENT_CONNECTION_STATUS_CALLBACK, connectionStatusCallback, void*, userContextCallback);
182
183 /**
184 * @brief Sets up the connection status callback to be invoked representing the status of
185 * the connection to IOT Hub. This is a blocking call.
186 *
187 * @param iotHubClientHandle The handle created by a call to the create function.
188 * @param retryPolicy The policy to use to reconnect to IoT Hub when a
189 * connection drops.
190 * @param retryTimeoutLimitInSeconds Maximum amount of time(seconds) to attempt reconnection when a
191 * connection drops to IOT Hub.
192 *
193 * @b NOTE: The application behavior is undefined if the user calls
194 * the ::IoTHubDeviceClient_LL_Destroy function from within any callback.
195 *
196 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
197 */
198 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubDeviceClient_LL_SetRetryPolicy, IOTHUB_DEVICE_CLIENT_LL_HANDLE, iotHubClientHandle, IOTHUB_CLIENT_RETRY_POLICY, retryPolicy, size_t, retryTimeoutLimitInSeconds);
199
200
201 /**
202 * @brief Sets up the connection status callback to be invoked representing the status of
203 * the connection to IOT Hub. This is a blocking call.
204 *
205 * @param iotHubClientHandle The handle created by a call to the create function.
206 * @param retryPolicy Out parameter containing the policy to use to reconnect to IoT Hub.
207 * @param retryTimeoutLimitInSeconds Out parameter containing maximum amount of time in seconds to attempt reconnection
208 to IOT Hub.
209 *
210 * @b NOTE: The application behavior is undefined if the user calls
211 * the ::IoTHubDeviceClient_LL_Destroy function from within any callback.
212 *
213 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
214 */
215 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubDeviceClient_LL_GetRetryPolicy, IOTHUB_DEVICE_CLIENT_LL_HANDLE, iotHubClientHandle, IOTHUB_CLIENT_RETRY_POLICY*, retryPolicy, size_t*, retryTimeoutLimitInSeconds);
216
217 /**
218 * @brief This function returns in the out parameter @p lastMessageReceiveTime
219 * what was the value of the @c time function when the last message was
220 * received at the client.
221 *
222 * @param iotHubClientHandle The handle created by a call to the create function.
223 * @param lastMessageReceiveTime Out parameter containing the value of @c time function
224 * when the last message was received.
225 *
226 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
227 */
228 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubDeviceClient_LL_GetLastMessageReceiveTime, IOTHUB_DEVICE_CLIENT_LL_HANDLE, iotHubClientHandle, time_t*, lastMessageReceiveTime);
229
230 /**
231 * @brief This function MUST be called by the user so work (sending/receiving data on the wire,
232 * computing and enforcing timeout controls, managing the connection to the IoT Hub) can
233 * be done by the IoTHubClient.
234 * The recommended call frequency is at least once every 100 milliseconds.
235 *
236 * @param iotHubClientHandle The handle created by a call to the create function.
237 *
238 * All IoTHubClient interactions (in regards to network traffic
239 * and/or user level callbacks) are the effect of calling this
240 * function and they take place synchronously inside _DoWork.
241 */
242 MOCKABLE_FUNCTION(, void, IoTHubDeviceClient_LL_DoWork, IOTHUB_DEVICE_CLIENT_LL_HANDLE, iotHubClientHandle);
243
244 /**
245 * @brief This API sets a runtime option identified by parameter @p optionName
246 * to a value pointed to by @p value. @p optionName and the data type
247 * @p value is pointing to are specific for every option.
248 *
249 * @param iotHubClientHandle The handle created by a call to the create function.
250 * @param optionName Name of the option.
251 * @param value The value.
252 *
253 * The options that can be set via this API are:
254 * - @b timeout - the maximum time in milliseconds a communication is
255 * allowed to use. @p value is a pointer to an @c unsigned @c int with
256 * the timeout value in milliseconds. This is only supported for the HTTP
257 * protocol as of now. When the HTTP protocol uses CURL, the meaning of
258 * the parameter is <em>total request time</em>. When the HTTP protocol uses
259 * winhttp, the meaning is the same as the @c dwSendTimeout and
260 * @c dwReceiveTimeout parameters of the
261 * <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/aa384116(v=vs.85).aspx">
262 * WinHttpSetTimeouts</a> API.
263 * - @b CURLOPT_LOW_SPEED_LIMIT - only available for HTTP protocol and only
264 * when CURL is used. It has the same meaning as CURL's option with the same
265 * name. @p value is pointer to a long.
266 * - @b CURLOPT_LOW_SPEED_TIME - only available for HTTP protocol and only
267 * when CURL is used. It has the same meaning as CURL's option with the same
268 * name. @p value is pointer to a long.
269 * - @b CURLOPT_FORBID_REUSE - only available for HTTP protocol and only
270 * when CURL is used. It has the same meaning as CURL's option with the same
271 * name. @p value is pointer to a long.
272 * - @b CURLOPT_FRESH_CONNECT - only available for HTTP protocol and only
273 * when CURL is used. It has the same meaning as CURL's option with the same
274 * name. @p value is pointer to a long.
275 * - @b CURLOPT_VERBOSE - only available for HTTP protocol and only
276 * when CURL is used. It has the same meaning as CURL's option with the same
277 * name. @p value is pointer to a long.
278 * - @b keepalive - available for MQTT protocol. Integer value that sets the
279 * interval in seconds when pings are sent to the server.
280 * - @b logtrace - available for MQTT protocol. Boolean value that turns on and
281 * off the diagnostic logging.
282 * - @b sas_token_lifetime - available for MQTT & AMQP protocol. size_t value that that determines the
283 * sas token timeout length.
284 * - @b OPTION_TRUSTED_CERT - Azure Server certificate used to validate TLS connection to iothub.
285 *
286 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
287 */
288 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubDeviceClient_LL_SetOption, IOTHUB_DEVICE_CLIENT_LL_HANDLE, iotHubClientHandle, const char*, optionName, const void*, value);
289
290 /**
291 * @brief This API specifies a callback to be used when the device receives a desired state update.
292 *
293 * @param iotHubClientHandle The handle created by a call to the create function.
294 * @param deviceTwinCallback The callback specified by the device client to be used for updating
295 * the desired state. The callback will be called in response to patch
296 * request send by the IoTHub services. The payload will be passed to the
297 * callback, along with two version numbers:
298 * - Desired:
299 * - LastSeenReported:
300 * @param userContextCallback User specified context that will be provided to the
301 * callback. This can be @c NULL.
302 *
303 * @b NOTE: The application behavior is undefined if the user calls
304 * the ::IoTHubDeviceClient_LL_Destroy function from within any callback.
305 *
306 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
307 */
308 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubDeviceClient_LL_SetDeviceTwinCallback, IOTHUB_DEVICE_CLIENT_LL_HANDLE, iotHubClientHandle, IOTHUB_CLIENT_DEVICE_TWIN_CALLBACK, deviceTwinCallback, void*, userContextCallback);
309
310 /**
311 * @brief This API sends a report of the device's properties and their current values.
312 *
313 * @param iotHubClientHandle The handle created by a call to the create function.
314 * @param reportedState The current device property values to be 'reported' to the IoTHub.
315 * @param reportedStateCallback The callback specified by the device client to be called with the
316 * result of the transaction.
317 * @param userContextCallback User specified context that will be provided to the
318 * callback. This can be @c NULL.
319 *
320 * @b NOTE: The application behavior is undefined if the user calls
321 * the ::IoTHubDeviceClient_LL_Destroy function from within any callback.
322 *
323 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
324 */
325 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubDeviceClient_LL_SendReportedState, IOTHUB_DEVICE_CLIENT_LL_HANDLE, iotHubClientHandle, const unsigned char*, reportedState, size_t, size, IOTHUB_CLIENT_REPORTED_STATE_CALLBACK, reportedStateCallback, void*, userContextCallback);
326
327 /**
328 * @brief This API enabled the device to request the full device twin (with all the desired and reported properties) on demand.
329 *
330 * @param iotHubClientHandle The handle created by a call to the create function.
331 * @param deviceTwinCallback The callback specified by the device client to receive the Twin document.
332 * @param userContextCallback User specified context that will be provided to the
333 * callback. This can be @c NULL.
334 *
335 * @b NOTE: The application behavior is undefined if the user calls
336 * the ::IoTHubClient_LL_Destroy function from within any callback.
337 *
338 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
339 */
340 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubDeviceClient_LL_GetTwinAsync, IOTHUB_DEVICE_CLIENT_LL_HANDLE, iotHubClientHandle, IOTHUB_CLIENT_DEVICE_TWIN_CALLBACK, deviceTwinCallback, void*, userContextCallback);
341
342 /**
343 * @brief This API sets the callback for async cloud to device method calls.
344 *
345 * @param iotHubClientHandle The handle created by a call to the create function.
346 * @param inboundDeviceMethodCallback The callback which will be called by IoTHub.
347 * @param userContextCallback User specified context that will be provided to the
348 * callback. This can be @c NULL.
349 *
350 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
351 */
352 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubDeviceClient_LL_SetDeviceMethodCallback, IOTHUB_DEVICE_CLIENT_LL_HANDLE, iotHubClientHandle, IOTHUB_CLIENT_DEVICE_METHOD_CALLBACK_ASYNC, deviceMethodCallback, void*, userContextCallback);
353
354 /**
355 * @brief This API responds to an asnyc method callback identified the methodId.
356 *
357 * @param iotHubClientHandle The handle created by a call to the create function.
358 * @param methodId The methodId of the Device Method callback.
359 * @param response The response data for the method callback.
360 * @param response_size The size of the response data buffer.
361 * @param status_response The status response of the method callback.
362 *
363 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
364 */
365 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubDeviceClient_LL_DeviceMethodResponse, IOTHUB_DEVICE_CLIENT_LL_HANDLE, iotHubClientHandle, METHOD_HANDLE, methodId, const unsigned char*, response, size_t, respSize, int, statusCode);
366
367#ifndef DONT_USE_UPLOADTOBLOB
368 /**
369 * @brief This API uploads to Azure Storage the content pointed to by @p source having the size @p size
370 * under the blob name devicename/@pdestinationFileName
371 *
372 * @param iotHubClientHandle The handle created by a call to the create function.
373 * @param destinationFileName name of the file.
374 * @param source pointer to the source for file content (can be NULL)
375 * @param size the size of the source in memory (if @p source is NULL then size needs to be 0).
376 *
377 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
378 */
379 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubDeviceClient_LL_UploadToBlob, IOTHUB_DEVICE_CLIENT_LL_HANDLE, iotHubClientHandle, const char*, destinationFileName, const unsigned char*, source, size_t, size);
380
381 /**
382 * @brief This API uploads to Azure Storage the content provided block by block by @p getDataCallback
383 * under the blob name devicename/@pdestinationFileName
384 *
385 * @param iotHubClientHandle The handle created by a call to the create function.
386 * @param destinationFileName name of the file.
387 * @param getDataCallbackEx A callback to be invoked to acquire the file chunks to be uploaded, as well as to indicate the status of the upload of the previous block.
388 * @param context Any data provided by the user to serve as context on getDataCallback.
389 *
390 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
391 */
392 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubDeviceClient_LL_UploadMultipleBlocksToBlob, IOTHUB_DEVICE_CLIENT_LL_HANDLE, iotHubClientHandle, const char*, destinationFileName, IOTHUB_CLIENT_FILE_UPLOAD_GET_DATA_CALLBACK_EX, getDataCallbackEx, void*, context);
393
394#endif /*DONT_USE_UPLOADTOBLOB*/
395
396#ifdef __cplusplus
397}
398#endif
399
400#endif /* IOTHUB_DEVICE_CLIENT_LL_H */
Note: See TracBrowser for help on using the repository browser.