source: azure_iot_hub/trunk/azure_iothub/iothub_client/inc/iothub_device_client_ll.h@ 389

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

ビルドが通るよう更新
  • Property svn:eol-style set to native
  • Property svn:mime-type set to text/x-chdr;charset=UTF-8
File size: 23.8 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_c_shared_utility/macro_utils.h"
30#include "azure_c_shared_utility/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 *
128 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
129 */
130 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);
131
132 /**
133 * @brief This function returns the current sending status for IoTHubClient.
134 *
135 * @param iotHubClientHandle The handle created by a call to the create function.
136 * @param iotHubClientStatus The sending state is populated at the address pointed
137 * at by this parameter. The value will be set to
138 * @c IOTHUBCLIENT_SENDSTATUS_IDLE if there is currently
139 * no item to be sent and @c IOTHUBCLIENT_SENDSTATUS_BUSY
140 * if there are.
141 *
142 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
143 */
144 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubDeviceClient_LL_GetSendStatus, IOTHUB_DEVICE_CLIENT_LL_HANDLE, iotHubClientHandle, IOTHUB_CLIENT_STATUS*, iotHubClientStatus);
145
146 /**
147 * @brief Sets up the message callback to be invoked when IoT Hub issues a
148 * message to the device. This is a blocking call.
149 *
150 * @param iotHubClientHandle The handle created by a call to the create function.
151 * @param messageCallback The callback specified by the device for receiving
152 * messages from IoT Hub.
153 * @param userContextCallback User specified context that will be provided to the
154 * callback. This can be @c NULL.
155 *
156 * @b NOTE: The application behavior is undefined if the user calls
157 * the ::IoTHubDeviceClient_LL_Destroy function from within any callback.
158 *
159 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
160 */
161 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubDeviceClient_LL_SetMessageCallback, IOTHUB_DEVICE_CLIENT_LL_HANDLE, iotHubClientHandle, IOTHUB_CLIENT_MESSAGE_CALLBACK_ASYNC, messageCallback, void*, userContextCallback);
162
163 /**
164 * @brief Sets up the connection status callback to be invoked representing the status of
165 * the connection to IOT Hub. This is a blocking call.
166 *
167 * @param iotHubClientHandle The handle created by a call to the create function.
168 * @param connectionStatusCallback The callback specified by the device for receiving
169 * updates about the status of the connection to IoT Hub.
170 * @param userContextCallback User specified context that will be provided to the
171 * callback. This can be @c NULL.
172 *
173 * @b NOTE: The application behavior is undefined if the user calls
174 * the ::IoTHubDeviceClient_LL_Destroy function from within any callback.
175 *
176 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
177 */
178 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubDeviceClient_LL_SetConnectionStatusCallback, IOTHUB_DEVICE_CLIENT_LL_HANDLE, iotHubClientHandle, IOTHUB_CLIENT_CONNECTION_STATUS_CALLBACK, connectionStatusCallback, void*, userContextCallback);
179
180 /**
181 * @brief Sets up the connection status callback to be invoked representing the status of
182 * the connection to IOT Hub. This is a blocking call.
183 *
184 * @param iotHubClientHandle The handle created by a call to the create function.
185 * @param retryPolicy The policy to use to reconnect to IoT Hub when a
186 * connection drops.
187 * @param retryTimeoutLimitInSeconds Maximum amount of time(seconds) to attempt reconnection when a
188 * connection drops to IOT Hub.
189 *
190 * @b NOTE: The application behavior is undefined if the user calls
191 * the ::IoTHubDeviceClient_LL_Destroy function from within any callback.
192 *
193 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
194 */
195 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubDeviceClient_LL_SetRetryPolicy, IOTHUB_DEVICE_CLIENT_LL_HANDLE, iotHubClientHandle, IOTHUB_CLIENT_RETRY_POLICY, retryPolicy, size_t, retryTimeoutLimitInSeconds);
196
197
198 /**
199 * @brief Sets up the connection status callback to be invoked representing the status of
200 * the connection to IOT Hub. This is a blocking call.
201 *
202 * @param iotHubClientHandle The handle created by a call to the create function.
203 * @param retryPolicy Out parameter containing the policy to use to reconnect to IoT Hub.
204 * @param retryTimeoutLimitInSeconds Out parameter containing maximum amount of time in seconds to attempt reconnection
205 to IOT Hub.
206 *
207 * @b NOTE: The application behavior is undefined if the user calls
208 * the ::IoTHubDeviceClient_LL_Destroy function from within any callback.
209 *
210 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
211 */
212 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubDeviceClient_LL_GetRetryPolicy, IOTHUB_DEVICE_CLIENT_LL_HANDLE, iotHubClientHandle, IOTHUB_CLIENT_RETRY_POLICY*, retryPolicy, size_t*, retryTimeoutLimitInSeconds);
213
214 /**
215 * @brief This function returns in the out parameter @p lastMessageReceiveTime
216 * what was the value of the @c time function when the last message was
217 * received at the client.
218 *
219 * @param iotHubClientHandle The handle created by a call to the create function.
220 * @param lastMessageReceiveTime Out parameter containing the value of @c time function
221 * when the last message was received.
222 *
223 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
224 */
225 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubDeviceClient_LL_GetLastMessageReceiveTime, IOTHUB_DEVICE_CLIENT_LL_HANDLE, iotHubClientHandle, time_t*, lastMessageReceiveTime);
226
227 /**
228 * @brief This function MUST be called by the user so work (sending/receiving data on the wire,
229 * computing and enforcing timeout controls, managing the connection to the IoT Hub) can
230 * be done by the IoTHubClient.
231 * The recommended call frequency is at least once every 100 milliseconds.
232 *
233 * @param iotHubClientHandle The handle created by a call to the create function.
234 *
235 * All IoTHubClient interactions (in regards to network traffic
236 * and/or user level callbacks) are the effect of calling this
237 * function and they take place synchronously inside _DoWork.
238 */
239 MOCKABLE_FUNCTION(, void, IoTHubDeviceClient_LL_DoWork, IOTHUB_DEVICE_CLIENT_LL_HANDLE, iotHubClientHandle);
240
241 /**
242 * @brief This API sets a runtime option identified by parameter @p optionName
243 * to a value pointed to by @p value. @p optionName and the data type
244 * @p value is pointing to are specific for every option.
245 *
246 * @param iotHubClientHandle The handle created by a call to the create function.
247 * @param optionName Name of the option.
248 * @param value The value.
249 *
250 * The options that can be set via this API are:
251 * - @b timeout - the maximum time in milliseconds a communication is
252 * allowed to use. @p value is a pointer to an @c unsigned @c int with
253 * the timeout value in milliseconds. This is only supported for the HTTP
254 * protocol as of now. When the HTTP protocol uses CURL, the meaning of
255 * the parameter is <em>total request time</em>. When the HTTP protocol uses
256 * winhttp, the meaning is the same as the @c dwSendTimeout and
257 * @c dwReceiveTimeout parameters of the
258 * <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/aa384116(v=vs.85).aspx">
259 * WinHttpSetTimeouts</a> API.
260 * - @b CURLOPT_LOW_SPEED_LIMIT - only available for HTTP protocol and only
261 * when CURL is used. It has the same meaning as CURL's option with the same
262 * name. @p value is pointer to a long.
263 * - @b CURLOPT_LOW_SPEED_TIME - 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_FORBID_REUSE - 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_FRESH_CONNECT - 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_VERBOSE - 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 keepalive - available for MQTT protocol. Integer value that sets the
276 * interval in seconds when pings are sent to the server.
277 * - @b logtrace - available for MQTT protocol. Boolean value that turns on and
278 * off the diagnostic logging.
279 * - @b sas_token_lifetime - available for MQTT & AMQP protocol. size_t value that that determines the
280 * sas token timeout length.
281 *
282 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
283 */
284 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubDeviceClient_LL_SetOption, IOTHUB_DEVICE_CLIENT_LL_HANDLE, iotHubClientHandle, const char*, optionName, const void*, value);
285
286 /**
287 * @brief This API specifies a callback to be used when the device receives a desired state update.
288 *
289 * @param iotHubClientHandle The handle created by a call to the create function.
290 * @param deviceTwinCallback The callback specified by the device client to be used for updating
291 * the desired state. The callback will be called in response to patch
292 * request send by the IoTHub services. The payload will be passed to the
293 * callback, along with two version numbers:
294 * - Desired:
295 * - LastSeenReported:
296 * @param userContextCallback User specified context that will be provided to the
297 * callback. This can be @c NULL.
298 *
299 * @b NOTE: The application behavior is undefined if the user calls
300 * the ::IoTHubDeviceClient_LL_Destroy function from within any callback.
301 *
302 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
303 */
304 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubDeviceClient_LL_SetDeviceTwinCallback, IOTHUB_DEVICE_CLIENT_LL_HANDLE, iotHubClientHandle, IOTHUB_CLIENT_DEVICE_TWIN_CALLBACK, deviceTwinCallback, void*, userContextCallback);
305
306 /**
307 * @brief This API sends a report of the device's properties and their current values.
308 *
309 * @param iotHubClientHandle The handle created by a call to the create function.
310 * @param reportedState The current device property values to be 'reported' to the IoTHub.
311 * @param reportedStateCallback The callback specified by the device client to be called with the
312 * result of the transaction.
313 * @param userContextCallback User specified context that will be provided to the
314 * callback. This can be @c NULL.
315 *
316 * @b NOTE: The application behavior is undefined if the user calls
317 * the ::IoTHubDeviceClient_LL_Destroy function from within any callback.
318 *
319 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
320 */
321 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);
322
323 /**
324 * @brief This API enabled the device to request the full device twin (with all the desired and reported properties) on demand.
325 *
326 * @param iotHubClientHandle The handle created by a call to the create function.
327 * @param deviceTwinCallback The callback specified by the device client to receive the Twin document.
328 * @param userContextCallback User specified context that will be provided to the
329 * callback. This can be @c NULL.
330 *
331 * @b NOTE: The application behavior is undefined if the user calls
332 * the ::IoTHubClient_LL_Destroy function from within any callback.
333 *
334 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
335 */
336 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubDeviceClient_LL_GetTwinAsync, IOTHUB_DEVICE_CLIENT_LL_HANDLE, iotHubClientHandle, IOTHUB_CLIENT_DEVICE_TWIN_CALLBACK, deviceTwinCallback, void*, userContextCallback);
337
338 /**
339 * @brief This API sets the callback for async cloud to device method calls.
340 *
341 * @param iotHubClientHandle The handle created by a call to the create function.
342 * @param inboundDeviceMethodCallback The callback which will be called by IoTHub.
343 * @param userContextCallback User specified context that will be provided to the
344 * callback. This can be @c NULL.
345 *
346 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
347 */
348 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubDeviceClient_LL_SetDeviceMethodCallback, IOTHUB_DEVICE_CLIENT_LL_HANDLE, iotHubClientHandle, IOTHUB_CLIENT_DEVICE_METHOD_CALLBACK_ASYNC, deviceMethodCallback, void*, userContextCallback);
349
350 /**
351 * @brief This API responds to an asnyc method callback identified the methodId.
352 *
353 * @param iotHubClientHandle The handle created by a call to the create function.
354 * @param methodId The methodId of the Device Method callback.
355 * @param response The response data for the method callback.
356 * @param response_size The size of the response data buffer.
357 * @param status_response The status response of the method callback.
358 *
359 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
360 */
361 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);
362
363#ifndef DONT_USE_UPLOADTOBLOB
364 /**
365 * @brief This API uploads to Azure Storage the content pointed to by @p source having the size @p size
366 * under the blob name devicename/@pdestinationFileName
367 *
368 * @param iotHubClientHandle The handle created by a call to the create function.
369 * @param destinationFileName name of the file.
370 * @param source pointer to the source for file content (can be NULL)
371 * @param size the size of the source in memory (if @p source is NULL then size needs to be 0).
372 *
373 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
374 */
375 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubDeviceClient_LL_UploadToBlob, IOTHUB_DEVICE_CLIENT_LL_HANDLE, iotHubClientHandle, const char*, destinationFileName, const unsigned char*, source, size_t, size);
376
377 /**
378 * @brief This API uploads to Azure Storage the content provided block by block by @p getDataCallback
379 * under the blob name devicename/@pdestinationFileName
380 *
381 * @param iotHubClientHandle The handle created by a call to the create function.
382 * @param destinationFileName name of the file.
383 * @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.
384 * @param context Any data provided by the user to serve as context on getDataCallback.
385 *
386 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
387 */
388 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);
389
390#endif /*DONT_USE_UPLOADTOBLOB*/
391
392#ifdef __cplusplus
393}
394#endif
395
396#endif /* IOTHUB_DEVICE_CLIENT_LL_H */
Note: See TracBrowser for help on using the repository browser.