Xin Zhang / azure-iot-c-sdk-f767zi

Dependents:   samplemqtt

Committer:
XinZhangMS
Date:
Thu Aug 23 06:52:14 2018 +0000
Revision:
0:f7f1f0d76dd6
azure-c-sdk for mbed os supporting NUCLEO_F767ZI

Who changed what in which revision?

UserRevisionLine numberNew contents of line
XinZhangMS 0:f7f1f0d76dd6 1 // Copyright (c) Microsoft. All rights reserved.
XinZhangMS 0:f7f1f0d76dd6 2 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
XinZhangMS 0:f7f1f0d76dd6 3
XinZhangMS 0:f7f1f0d76dd6 4 /** @file iothub_client.h
XinZhangMS 0:f7f1f0d76dd6 5 * @brief Extends the IoTHubCLient_LL module with additional features.
XinZhangMS 0:f7f1f0d76dd6 6 *
XinZhangMS 0:f7f1f0d76dd6 7 * @details IoTHubClient is a module that extends the IoTHubCLient_LL
XinZhangMS 0:f7f1f0d76dd6 8 * module with 2 features:
XinZhangMS 0:f7f1f0d76dd6 9 * - scheduling the work for the IoTHubCLient from a
XinZhangMS 0:f7f1f0d76dd6 10 * thread, so that the user does not need to create their
XinZhangMS 0:f7f1f0d76dd6 11 * own thread
XinZhangMS 0:f7f1f0d76dd6 12 * - thread-safe APIs
XinZhangMS 0:f7f1f0d76dd6 13 */
XinZhangMS 0:f7f1f0d76dd6 14
XinZhangMS 0:f7f1f0d76dd6 15 #ifndef IOTHUB_CLIENT_H
XinZhangMS 0:f7f1f0d76dd6 16 #define IOTHUB_CLIENT_H
XinZhangMS 0:f7f1f0d76dd6 17
XinZhangMS 0:f7f1f0d76dd6 18 #include <stddef.h>
XinZhangMS 0:f7f1f0d76dd6 19 #include <stdint.h>
XinZhangMS 0:f7f1f0d76dd6 20
XinZhangMS 0:f7f1f0d76dd6 21 #include "azure_c_shared_utility/umock_c_prod.h"
XinZhangMS 0:f7f1f0d76dd6 22 #include "iothub_transport_ll.h"
XinZhangMS 0:f7f1f0d76dd6 23 #include "iothub_client_core_ll.h"
XinZhangMS 0:f7f1f0d76dd6 24 #include "iothub_client_core.h"
XinZhangMS 0:f7f1f0d76dd6 25 #include "iothub_client_ll.h"
XinZhangMS 0:f7f1f0d76dd6 26
XinZhangMS 0:f7f1f0d76dd6 27 #ifndef IOTHUB_CLIENT_INSTANCE_TYPE
XinZhangMS 0:f7f1f0d76dd6 28 typedef IOTHUB_CLIENT_CORE_HANDLE IOTHUB_CLIENT_HANDLE;
XinZhangMS 0:f7f1f0d76dd6 29 #define IOTHUB_CLIENT_INSTANCE_TYPE
XinZhangMS 0:f7f1f0d76dd6 30 #endif // IOTHUB_CLIENT_INSTANCE
XinZhangMS 0:f7f1f0d76dd6 31
XinZhangMS 0:f7f1f0d76dd6 32
XinZhangMS 0:f7f1f0d76dd6 33 #ifdef __cplusplus
XinZhangMS 0:f7f1f0d76dd6 34 extern "C"
XinZhangMS 0:f7f1f0d76dd6 35 {
XinZhangMS 0:f7f1f0d76dd6 36 #endif
XinZhangMS 0:f7f1f0d76dd6 37
XinZhangMS 0:f7f1f0d76dd6 38 /**
XinZhangMS 0:f7f1f0d76dd6 39 * @brief Creates a IoT Hub client for communication with an existing
XinZhangMS 0:f7f1f0d76dd6 40 * IoT Hub using the specified connection string parameter.
XinZhangMS 0:f7f1f0d76dd6 41 *
XinZhangMS 0:f7f1f0d76dd6 42 * @param connectionString Pointer to a character string
XinZhangMS 0:f7f1f0d76dd6 43 * @param protocol Function pointer for protocol implementation
XinZhangMS 0:f7f1f0d76dd6 44 *
XinZhangMS 0:f7f1f0d76dd6 45 * Sample connection string:
XinZhangMS 0:f7f1f0d76dd6 46 * <blockquote>
XinZhangMS 0:f7f1f0d76dd6 47 * <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>
XinZhangMS 0:f7f1f0d76dd6 48 * <pre>HostName=[IoT Hub name goes here].[IoT Hub suffix goes here, e.g., private.azure-devices-int.net];DeviceId=[Device ID goes here];SharedAccessSignature=SharedAccessSignature sr=[IoT Hub name goes here].[IoT Hub suffix goes here, e.g., private.azure-devices-int.net]/devices/[Device ID goes here]&sig=[SAS Token goes here]&se=[Expiry Time goes here];</pre>
XinZhangMS 0:f7f1f0d76dd6 49 * </blockquote>
XinZhangMS 0:f7f1f0d76dd6 50 *
XinZhangMS 0:f7f1f0d76dd6 51 * @return A non-NULL @c IOTHUB_CLIENT_HANDLE value that is used when
XinZhangMS 0:f7f1f0d76dd6 52 * invoking other functions for IoT Hub client and @c NULL on failure.
XinZhangMS 0:f7f1f0d76dd6 53 */
XinZhangMS 0:f7f1f0d76dd6 54 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_HANDLE, IoTHubClient_CreateFromConnectionString, const char*, connectionString, IOTHUB_CLIENT_TRANSPORT_PROVIDER, protocol);
XinZhangMS 0:f7f1f0d76dd6 55
XinZhangMS 0:f7f1f0d76dd6 56 /**
XinZhangMS 0:f7f1f0d76dd6 57 * @brief Creates a IoT Hub client for communication with an existing IoT
XinZhangMS 0:f7f1f0d76dd6 58 * Hub using the specified parameters.
XinZhangMS 0:f7f1f0d76dd6 59 *
XinZhangMS 0:f7f1f0d76dd6 60 * @param config Pointer to an @c IOTHUB_CLIENT_CONFIG structure
XinZhangMS 0:f7f1f0d76dd6 61 *
XinZhangMS 0:f7f1f0d76dd6 62 * The API does not allow sharing of a connection across multiple
XinZhangMS 0:f7f1f0d76dd6 63 * devices. This is a blocking call.
XinZhangMS 0:f7f1f0d76dd6 64 *
XinZhangMS 0:f7f1f0d76dd6 65 * @return A non-NULL @c IOTHUB_CLIENT_HANDLE value that is used when
XinZhangMS 0:f7f1f0d76dd6 66 * invoking other functions for IoT Hub client and @c NULL on failure.
XinZhangMS 0:f7f1f0d76dd6 67 */
XinZhangMS 0:f7f1f0d76dd6 68 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_HANDLE, IoTHubClient_Create, const IOTHUB_CLIENT_CONFIG*, config);
XinZhangMS 0:f7f1f0d76dd6 69
XinZhangMS 0:f7f1f0d76dd6 70 /**
XinZhangMS 0:f7f1f0d76dd6 71 * @brief Creates a IoT Hub client for communication with an existing IoT
XinZhangMS 0:f7f1f0d76dd6 72 * Hub using the specified parameters.
XinZhangMS 0:f7f1f0d76dd6 73 *
XinZhangMS 0:f7f1f0d76dd6 74 * @param transportHandle TRANSPORT_HANDLE which represents a connection.
XinZhangMS 0:f7f1f0d76dd6 75 * @param config Pointer to an @c IOTHUB_CLIENT_CONFIG structure
XinZhangMS 0:f7f1f0d76dd6 76 *
XinZhangMS 0:f7f1f0d76dd6 77 * The API allows sharing of a connection across multiple
XinZhangMS 0:f7f1f0d76dd6 78 * devices. This is a blocking call.
XinZhangMS 0:f7f1f0d76dd6 79 *
XinZhangMS 0:f7f1f0d76dd6 80 * @return A non-NULL @c IOTHUB_CLIENT_HANDLE value that is used when
XinZhangMS 0:f7f1f0d76dd6 81 * invoking other functions for IoT Hub client and @c NULL on failure.
XinZhangMS 0:f7f1f0d76dd6 82 */
XinZhangMS 0:f7f1f0d76dd6 83 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_HANDLE, IoTHubClient_CreateWithTransport, TRANSPORT_HANDLE, transportHandle, const IOTHUB_CLIENT_CONFIG*, config);
XinZhangMS 0:f7f1f0d76dd6 84
XinZhangMS 0:f7f1f0d76dd6 85 /**
XinZhangMS 0:f7f1f0d76dd6 86 * @brief Creates a IoT Hub client for communication with an existing IoT
XinZhangMS 0:f7f1f0d76dd6 87 * Hub using the device auth module.
XinZhangMS 0:f7f1f0d76dd6 88 *
XinZhangMS 0:f7f1f0d76dd6 89 * @param iothub_uri Pointer to an ioThub hostname received in the registration process
XinZhangMS 0:f7f1f0d76dd6 90 * @param device_id Pointer to the device Id of the device
XinZhangMS 0:f7f1f0d76dd6 91 * @param protocol Function pointer for protocol implementation
XinZhangMS 0:f7f1f0d76dd6 92 *
XinZhangMS 0:f7f1f0d76dd6 93 * @return A non-NULL @c IOTHUB_CLIENT_LL_HANDLE value that is used when
XinZhangMS 0:f7f1f0d76dd6 94 * invoking other functions for IoT Hub client and @c NULL on failure.
XinZhangMS 0:f7f1f0d76dd6 95 */
XinZhangMS 0:f7f1f0d76dd6 96 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_HANDLE, IoTHubClient_CreateFromDeviceAuth, const char*, iothub_uri, const char*, device_id, IOTHUB_CLIENT_TRANSPORT_PROVIDER, protocol);
XinZhangMS 0:f7f1f0d76dd6 97
XinZhangMS 0:f7f1f0d76dd6 98 /**
XinZhangMS 0:f7f1f0d76dd6 99 * @brief Disposes of resources allocated by the IoT Hub client. This is a
XinZhangMS 0:f7f1f0d76dd6 100 * blocking call.
XinZhangMS 0:f7f1f0d76dd6 101 *
XinZhangMS 0:f7f1f0d76dd6 102 * @param iotHubClientHandle The handle created by a call to the create function.
XinZhangMS 0:f7f1f0d76dd6 103 */
XinZhangMS 0:f7f1f0d76dd6 104 MOCKABLE_FUNCTION(, void, IoTHubClient_Destroy, IOTHUB_CLIENT_HANDLE, iotHubClientHandle);
XinZhangMS 0:f7f1f0d76dd6 105
XinZhangMS 0:f7f1f0d76dd6 106 /**
XinZhangMS 0:f7f1f0d76dd6 107 * @brief Asynchronous call to send the message specified by @p eventMessageHandle.
XinZhangMS 0:f7f1f0d76dd6 108 *
XinZhangMS 0:f7f1f0d76dd6 109 * @param iotHubClientHandle The handle created by a call to the create function.
XinZhangMS 0:f7f1f0d76dd6 110 * @param eventMessageHandle The handle to an IoT Hub message.
XinZhangMS 0:f7f1f0d76dd6 111 * @param eventConfirmationCallback The callback specified by the device for receiving
XinZhangMS 0:f7f1f0d76dd6 112 * confirmation of the delivery of the IoT Hub message.
XinZhangMS 0:f7f1f0d76dd6 113 * This callback can be expected to invoke the
XinZhangMS 0:f7f1f0d76dd6 114 * ::IoTHubClient_SendEventAsync function for the
XinZhangMS 0:f7f1f0d76dd6 115 * same message in an attempt to retry sending a failing
XinZhangMS 0:f7f1f0d76dd6 116 * message. The user can specify a @c NULL value here to
XinZhangMS 0:f7f1f0d76dd6 117 * indicate that no callback is required.
XinZhangMS 0:f7f1f0d76dd6 118 * @param userContextCallback User specified context that will be provided to the
XinZhangMS 0:f7f1f0d76dd6 119 * callback. This can be @c NULL.
XinZhangMS 0:f7f1f0d76dd6 120 *
XinZhangMS 0:f7f1f0d76dd6 121 * @b NOTE: The application behavior is undefined if the user calls
XinZhangMS 0:f7f1f0d76dd6 122 * the ::IoTHubClient_Destroy function from within any callback.
XinZhangMS 0:f7f1f0d76dd6 123 *
XinZhangMS 0:f7f1f0d76dd6 124 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
XinZhangMS 0:f7f1f0d76dd6 125 */
XinZhangMS 0:f7f1f0d76dd6 126 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubClient_SendEventAsync, IOTHUB_CLIENT_HANDLE, iotHubClientHandle, IOTHUB_MESSAGE_HANDLE, eventMessageHandle, IOTHUB_CLIENT_EVENT_CONFIRMATION_CALLBACK, eventConfirmationCallback, void*, userContextCallback);
XinZhangMS 0:f7f1f0d76dd6 127
XinZhangMS 0:f7f1f0d76dd6 128 /**
XinZhangMS 0:f7f1f0d76dd6 129 * @brief This function returns the current sending status for IoTHubClient.
XinZhangMS 0:f7f1f0d76dd6 130 *
XinZhangMS 0:f7f1f0d76dd6 131 * @param iotHubClientHandle The handle created by a call to the create function.
XinZhangMS 0:f7f1f0d76dd6 132 * @param iotHubClientStatus The sending state is populated at the address pointed
XinZhangMS 0:f7f1f0d76dd6 133 * at by this parameter. The value will be set to
XinZhangMS 0:f7f1f0d76dd6 134 * @c IOTHUBCLIENT_SENDSTATUS_IDLE if there is currently
XinZhangMS 0:f7f1f0d76dd6 135 * no item to be sent and @c IOTHUBCLIENT_SENDSTATUS_BUSY
XinZhangMS 0:f7f1f0d76dd6 136 * if there are.
XinZhangMS 0:f7f1f0d76dd6 137 *
XinZhangMS 0:f7f1f0d76dd6 138 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
XinZhangMS 0:f7f1f0d76dd6 139 */
XinZhangMS 0:f7f1f0d76dd6 140 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubClient_GetSendStatus, IOTHUB_CLIENT_HANDLE, iotHubClientHandle, IOTHUB_CLIENT_STATUS*, iotHubClientStatus);
XinZhangMS 0:f7f1f0d76dd6 141
XinZhangMS 0:f7f1f0d76dd6 142 /**
XinZhangMS 0:f7f1f0d76dd6 143 * @brief Sets up the message callback to be invoked when IoT Hub issues a
XinZhangMS 0:f7f1f0d76dd6 144 * message to the device. This is a blocking call.
XinZhangMS 0:f7f1f0d76dd6 145 *
XinZhangMS 0:f7f1f0d76dd6 146 * @param iotHubClientHandle The handle created by a call to the create function.
XinZhangMS 0:f7f1f0d76dd6 147 * @param messageCallback The callback specified by the device for receiving
XinZhangMS 0:f7f1f0d76dd6 148 * messages from IoT Hub.
XinZhangMS 0:f7f1f0d76dd6 149 * @param userContextCallback User specified context that will be provided to the
XinZhangMS 0:f7f1f0d76dd6 150 * callback. This can be @c NULL.
XinZhangMS 0:f7f1f0d76dd6 151 *
XinZhangMS 0:f7f1f0d76dd6 152 * @b NOTE: The application behavior is undefined if the user calls
XinZhangMS 0:f7f1f0d76dd6 153 * the ::IoTHubClient_Destroy function from within any callback.
XinZhangMS 0:f7f1f0d76dd6 154 *
XinZhangMS 0:f7f1f0d76dd6 155 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
XinZhangMS 0:f7f1f0d76dd6 156 */
XinZhangMS 0:f7f1f0d76dd6 157 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubClient_SetMessageCallback, IOTHUB_CLIENT_HANDLE, iotHubClientHandle, IOTHUB_CLIENT_MESSAGE_CALLBACK_ASYNC, messageCallback, void*, userContextCallback);
XinZhangMS 0:f7f1f0d76dd6 158
XinZhangMS 0:f7f1f0d76dd6 159 /**
XinZhangMS 0:f7f1f0d76dd6 160 * @brief Sets up the connection status callback to be invoked representing the status of
XinZhangMS 0:f7f1f0d76dd6 161 * the connection to IOT Hub. This is a blocking call.
XinZhangMS 0:f7f1f0d76dd6 162 *
XinZhangMS 0:f7f1f0d76dd6 163 * @param iotHubClientHandle The handle created by a call to the create function.
XinZhangMS 0:f7f1f0d76dd6 164 * @param connectionStatusCallback The callback specified by the device for receiving
XinZhangMS 0:f7f1f0d76dd6 165 * updates about the status of the connection to IoT Hub.
XinZhangMS 0:f7f1f0d76dd6 166 * @param userContextCallback User specified context that will be provided to the
XinZhangMS 0:f7f1f0d76dd6 167 * callback. This can be @c NULL.
XinZhangMS 0:f7f1f0d76dd6 168 *
XinZhangMS 0:f7f1f0d76dd6 169 * @b NOTE: The application behavior is undefined if the user calls
XinZhangMS 0:f7f1f0d76dd6 170 * the ::IoTHubClient_LL_Destroy function from within any callback.
XinZhangMS 0:f7f1f0d76dd6 171 *
XinZhangMS 0:f7f1f0d76dd6 172 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
XinZhangMS 0:f7f1f0d76dd6 173 */
XinZhangMS 0:f7f1f0d76dd6 174 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubClient_SetConnectionStatusCallback, IOTHUB_CLIENT_HANDLE, iotHubClientHandle, IOTHUB_CLIENT_CONNECTION_STATUS_CALLBACK, connectionStatusCallback, void*, userContextCallback);
XinZhangMS 0:f7f1f0d76dd6 175
XinZhangMS 0:f7f1f0d76dd6 176 /**
XinZhangMS 0:f7f1f0d76dd6 177 * @brief Sets up the connection status callback to be invoked representing the status of
XinZhangMS 0:f7f1f0d76dd6 178 * the connection to IOT Hub. This is a blocking call.
XinZhangMS 0:f7f1f0d76dd6 179 *
XinZhangMS 0:f7f1f0d76dd6 180 * @param iotHubClientHandle The handle created by a call to the create function.
XinZhangMS 0:f7f1f0d76dd6 181 * @param retryPolicy The policy to use to reconnect to IoT Hub when a
XinZhangMS 0:f7f1f0d76dd6 182 * connection drops.
XinZhangMS 0:f7f1f0d76dd6 183 * @param retryTimeoutLimitInSeconds Maximum amount of time(seconds) to attempt reconnection when a
XinZhangMS 0:f7f1f0d76dd6 184 * connection drops to IOT Hub.
XinZhangMS 0:f7f1f0d76dd6 185 *
XinZhangMS 0:f7f1f0d76dd6 186 * @b NOTE: The application behavior is undefined if the user calls
XinZhangMS 0:f7f1f0d76dd6 187 * the ::IoTHubClient_LL_Destroy function from within any callback.
XinZhangMS 0:f7f1f0d76dd6 188 *
XinZhangMS 0:f7f1f0d76dd6 189 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
XinZhangMS 0:f7f1f0d76dd6 190 */
XinZhangMS 0:f7f1f0d76dd6 191 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubClient_SetRetryPolicy, IOTHUB_CLIENT_HANDLE, iotHubClientHandle, IOTHUB_CLIENT_RETRY_POLICY, retryPolicy, size_t, retryTimeoutLimitInSeconds);
XinZhangMS 0:f7f1f0d76dd6 192
XinZhangMS 0:f7f1f0d76dd6 193 /**
XinZhangMS 0:f7f1f0d76dd6 194 * @brief Sets up the connection status callback to be invoked representing the status of
XinZhangMS 0:f7f1f0d76dd6 195 * the connection to IOT Hub. This is a blocking call.
XinZhangMS 0:f7f1f0d76dd6 196 *
XinZhangMS 0:f7f1f0d76dd6 197 * @param iotHubClientHandle The handle created by a call to the create function.
XinZhangMS 0:f7f1f0d76dd6 198 * @param retryPolicy Out parameter containing the policy to use to reconnect to IoT Hub.
XinZhangMS 0:f7f1f0d76dd6 199 * @param retryTimeoutLimitInSeconds Out parameter containing maximum amount of time in seconds to attempt reconnection
XinZhangMS 0:f7f1f0d76dd6 200 to IOT Hub.
XinZhangMS 0:f7f1f0d76dd6 201 *
XinZhangMS 0:f7f1f0d76dd6 202 * @b NOTE: The application behavior is undefined if the user calls
XinZhangMS 0:f7f1f0d76dd6 203 * the ::IoTHubClient_LL_Destroy function from within any callback.
XinZhangMS 0:f7f1f0d76dd6 204 *
XinZhangMS 0:f7f1f0d76dd6 205 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
XinZhangMS 0:f7f1f0d76dd6 206 */
XinZhangMS 0:f7f1f0d76dd6 207 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubClient_GetRetryPolicy, IOTHUB_CLIENT_HANDLE, iotHubClientHandle, IOTHUB_CLIENT_RETRY_POLICY*, retryPolicy, size_t*, retryTimeoutLimitInSeconds);
XinZhangMS 0:f7f1f0d76dd6 208
XinZhangMS 0:f7f1f0d76dd6 209 /**
XinZhangMS 0:f7f1f0d76dd6 210 * @brief This function returns in the out parameter @p lastMessageReceiveTime
XinZhangMS 0:f7f1f0d76dd6 211 * what was the value of the @c time function when the last message was
XinZhangMS 0:f7f1f0d76dd6 212 * received at the client.
XinZhangMS 0:f7f1f0d76dd6 213 *
XinZhangMS 0:f7f1f0d76dd6 214 * @param iotHubClientHandle The handle created by a call to the create function.
XinZhangMS 0:f7f1f0d76dd6 215 * @param lastMessageReceiveTime Out parameter containing the value of @c time function
XinZhangMS 0:f7f1f0d76dd6 216 * when the last message was received.
XinZhangMS 0:f7f1f0d76dd6 217 *
XinZhangMS 0:f7f1f0d76dd6 218 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
XinZhangMS 0:f7f1f0d76dd6 219 */
XinZhangMS 0:f7f1f0d76dd6 220 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubClient_GetLastMessageReceiveTime, IOTHUB_CLIENT_HANDLE, iotHubClientHandle, time_t*, lastMessageReceiveTime);
XinZhangMS 0:f7f1f0d76dd6 221
XinZhangMS 0:f7f1f0d76dd6 222 /**
XinZhangMS 0:f7f1f0d76dd6 223 * @brief This API sets a runtime option identified by parameter @p optionName
XinZhangMS 0:f7f1f0d76dd6 224 * to a value pointed to by @p value. @p optionName and the data type
XinZhangMS 0:f7f1f0d76dd6 225 * @p value is pointing to are specific for every option.
XinZhangMS 0:f7f1f0d76dd6 226 *
XinZhangMS 0:f7f1f0d76dd6 227 * @param iotHubClientHandle The handle created by a call to the create function.
XinZhangMS 0:f7f1f0d76dd6 228 * @param optionName Name of the option.
XinZhangMS 0:f7f1f0d76dd6 229 * @param value The value.
XinZhangMS 0:f7f1f0d76dd6 230 *
XinZhangMS 0:f7f1f0d76dd6 231 * The options that can be set via this API are:
XinZhangMS 0:f7f1f0d76dd6 232 * - @b timeout - the maximum time in milliseconds a communication is
XinZhangMS 0:f7f1f0d76dd6 233 * allowed to use. @p value is a pointer to an @c unsigned @c int with
XinZhangMS 0:f7f1f0d76dd6 234 * the timeout value in milliseconds. This is only supported for the HTTP
XinZhangMS 0:f7f1f0d76dd6 235 * protocol as of now. When the HTTP protocol uses CURL, the meaning of
XinZhangMS 0:f7f1f0d76dd6 236 * the parameter is <em>total request time</em>. When the HTTP protocol uses
XinZhangMS 0:f7f1f0d76dd6 237 * winhttp, the meaning is the same as the @c dwSendTimeout and
XinZhangMS 0:f7f1f0d76dd6 238 * @c dwReceiveTimeout parameters of the
XinZhangMS 0:f7f1f0d76dd6 239 * <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/aa384116(v=vs.85).aspx">
XinZhangMS 0:f7f1f0d76dd6 240 * WinHttpSetTimeouts</a> API.
XinZhangMS 0:f7f1f0d76dd6 241 * - @b CURLOPT_LOW_SPEED_LIMIT - only available for HTTP protocol and only
XinZhangMS 0:f7f1f0d76dd6 242 * when CURL is used. It has the same meaning as CURL's option with the same
XinZhangMS 0:f7f1f0d76dd6 243 * name. @p value is pointer to a long.
XinZhangMS 0:f7f1f0d76dd6 244 * - @b CURLOPT_LOW_SPEED_TIME - only available for HTTP protocol and only
XinZhangMS 0:f7f1f0d76dd6 245 * when CURL is used. It has the same meaning as CURL's option with the same
XinZhangMS 0:f7f1f0d76dd6 246 * name. @p value is pointer to a long.
XinZhangMS 0:f7f1f0d76dd6 247 * - @b CURLOPT_FORBID_REUSE - only available for HTTP protocol and only
XinZhangMS 0:f7f1f0d76dd6 248 * when CURL is used. It has the same meaning as CURL's option with the same
XinZhangMS 0:f7f1f0d76dd6 249 * name. @p value is pointer to a long.
XinZhangMS 0:f7f1f0d76dd6 250 * - @b CURLOPT_FRESH_CONNECT - only available for HTTP protocol and only
XinZhangMS 0:f7f1f0d76dd6 251 * when CURL is used. It has the same meaning as CURL's option with the same
XinZhangMS 0:f7f1f0d76dd6 252 * name. @p value is pointer to a long.
XinZhangMS 0:f7f1f0d76dd6 253 * - @b CURLOPT_VERBOSE - only available for HTTP protocol and only
XinZhangMS 0:f7f1f0d76dd6 254 * when CURL is used. It has the same meaning as CURL's option with the same
XinZhangMS 0:f7f1f0d76dd6 255 * name. @p value is pointer to a long.
XinZhangMS 0:f7f1f0d76dd6 256 * - @b messageTimeout - the maximum time in milliseconds until a message
XinZhangMS 0:f7f1f0d76dd6 257 * is timeouted. The time starts at IoTHubClient_SendEventAsync. By default,
XinZhangMS 0:f7f1f0d76dd6 258 * messages do not expire. @p is a pointer to a uint64_t
XinZhangMS 0:f7f1f0d76dd6 259 * - @b svc2cl_keep_alive_timeout_secs - the AMQP service side keep alive interval in seconds.
XinZhangMS 0:f7f1f0d76dd6 260 * After the connection established the client requests the server to set the
XinZhangMS 0:f7f1f0d76dd6 261 * keep alive interval for given time.
XinZhangMS 0:f7f1f0d76dd6 262 * If it is not set then the default 240 sec applies.
XinZhangMS 0:f7f1f0d76dd6 263 * If it is set to zero the server will not send keep alive messages to the client.
XinZhangMS 0:f7f1f0d76dd6 264 * - @b cl2svc_keep_alive_send_ratio - the AMQP client side keep alive interval in seconds.
XinZhangMS 0:f7f1f0d76dd6 265 * After the connection established the server requests the client to set the
XinZhangMS 0:f7f1f0d76dd6 266 * keep alive interval for given time.
XinZhangMS 0:f7f1f0d76dd6 267 * If it is not set then the default ratio of 1/2 is applied.
XinZhangMS 0:f7f1f0d76dd6 268 * The ratio has to be greater than 0.0 and equal to or less than 0.9
XinZhangMS 0:f7f1f0d76dd6 269
XinZhangMS 0:f7f1f0d76dd6 270 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
XinZhangMS 0:f7f1f0d76dd6 271 */
XinZhangMS 0:f7f1f0d76dd6 272 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubClient_SetOption, IOTHUB_CLIENT_HANDLE, iotHubClientHandle, const char*, optionName, const void*, value);
XinZhangMS 0:f7f1f0d76dd6 273
XinZhangMS 0:f7f1f0d76dd6 274 /**
XinZhangMS 0:f7f1f0d76dd6 275 * @brief This API specifies a call back to be used when the device receives a state update.
XinZhangMS 0:f7f1f0d76dd6 276 *
XinZhangMS 0:f7f1f0d76dd6 277 * @param iotHubClientHandle The handle created by a call to the create function.
XinZhangMS 0:f7f1f0d76dd6 278 * @param deviceTwinCallback The callback specified by the device client to be used for updating
XinZhangMS 0:f7f1f0d76dd6 279 * the desired state. The callback will be called in response to a
XinZhangMS 0:f7f1f0d76dd6 280 * request send by the IoTHub services. The payload will be passed to the
XinZhangMS 0:f7f1f0d76dd6 281 * callback, along with two version numbers:
XinZhangMS 0:f7f1f0d76dd6 282 * - Desired:
XinZhangMS 0:f7f1f0d76dd6 283 * - LastSeenReported:
XinZhangMS 0:f7f1f0d76dd6 284 * @param userContextCallback User specified context that will be provided to the
XinZhangMS 0:f7f1f0d76dd6 285 * callback. This can be @c NULL.
XinZhangMS 0:f7f1f0d76dd6 286 *
XinZhangMS 0:f7f1f0d76dd6 287 * @b NOTE: The application behavior is undefined if the user calls
XinZhangMS 0:f7f1f0d76dd6 288 * the ::IoTHubClient_Destroy function from within any callback.
XinZhangMS 0:f7f1f0d76dd6 289 *
XinZhangMS 0:f7f1f0d76dd6 290 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
XinZhangMS 0:f7f1f0d76dd6 291 */
XinZhangMS 0:f7f1f0d76dd6 292 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubClient_SetDeviceTwinCallback, IOTHUB_CLIENT_HANDLE, iotHubClientHandle, IOTHUB_CLIENT_DEVICE_TWIN_CALLBACK, deviceTwinCallback, void*, userContextCallback);
XinZhangMS 0:f7f1f0d76dd6 293
XinZhangMS 0:f7f1f0d76dd6 294 /**
XinZhangMS 0:f7f1f0d76dd6 295 * @brief This API sends a report of the device's properties and their current values.
XinZhangMS 0:f7f1f0d76dd6 296 *
XinZhangMS 0:f7f1f0d76dd6 297 * @param iotHubClientHandle The handle created by a call to the create function.
XinZhangMS 0:f7f1f0d76dd6 298 * @param reportedState The current device property values to be 'reported' to the IoTHub.
XinZhangMS 0:f7f1f0d76dd6 299 * @param reportedStateCallback The callback specified by the device client to be called with the
XinZhangMS 0:f7f1f0d76dd6 300 * result of the transaction.
XinZhangMS 0:f7f1f0d76dd6 301 * @param userContextCallback User specified context that will be provided to the
XinZhangMS 0:f7f1f0d76dd6 302 * callback. This can be @c NULL.
XinZhangMS 0:f7f1f0d76dd6 303 *
XinZhangMS 0:f7f1f0d76dd6 304 * @b NOTE: The application behavior is undefined if the user calls
XinZhangMS 0:f7f1f0d76dd6 305 * the ::IoTHubClient_Destroy function from within any callback.
XinZhangMS 0:f7f1f0d76dd6 306 *
XinZhangMS 0:f7f1f0d76dd6 307 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
XinZhangMS 0:f7f1f0d76dd6 308 */
XinZhangMS 0:f7f1f0d76dd6 309 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubClient_SendReportedState, IOTHUB_CLIENT_HANDLE, iotHubClientHandle, const unsigned char*, reportedState, size_t, size, IOTHUB_CLIENT_REPORTED_STATE_CALLBACK, reportedStateCallback, void*, userContextCallback);
XinZhangMS 0:f7f1f0d76dd6 310
XinZhangMS 0:f7f1f0d76dd6 311 /**
XinZhangMS 0:f7f1f0d76dd6 312 * @brief This API sets callback for cloud to device method call.
XinZhangMS 0:f7f1f0d76dd6 313 *
XinZhangMS 0:f7f1f0d76dd6 314 * @param iotHubClientHandle The handle created by a call to the create function.
XinZhangMS 0:f7f1f0d76dd6 315 * @param deviceMethodCallback The callback which will be called by IoTHub.
XinZhangMS 0:f7f1f0d76dd6 316 * @param userContextCallback User specified context that will be provided to the
XinZhangMS 0:f7f1f0d76dd6 317 * callback. This can be @c NULL.
XinZhangMS 0:f7f1f0d76dd6 318 *
XinZhangMS 0:f7f1f0d76dd6 319 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
XinZhangMS 0:f7f1f0d76dd6 320 */
XinZhangMS 0:f7f1f0d76dd6 321 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubClient_SetDeviceMethodCallback, IOTHUB_CLIENT_HANDLE, iotHubClientHandle, IOTHUB_CLIENT_DEVICE_METHOD_CALLBACK_ASYNC, deviceMethodCallback, void*, userContextCallback);
XinZhangMS 0:f7f1f0d76dd6 322
XinZhangMS 0:f7f1f0d76dd6 323 /**
XinZhangMS 0:f7f1f0d76dd6 324 * @brief This API sets callback for async cloud to device method call.
XinZhangMS 0:f7f1f0d76dd6 325 *
XinZhangMS 0:f7f1f0d76dd6 326 * @param iotHubClientHandle The handle created by a call to the create function.
XinZhangMS 0:f7f1f0d76dd6 327 * @param inboundDeviceMethodCallback The callback which will be called by IoTHub.
XinZhangMS 0:f7f1f0d76dd6 328 * @param userContextCallback User specified context that will be provided to the
XinZhangMS 0:f7f1f0d76dd6 329 * callback. This can be @c NULL.
XinZhangMS 0:f7f1f0d76dd6 330 *
XinZhangMS 0:f7f1f0d76dd6 331 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
XinZhangMS 0:f7f1f0d76dd6 332 */
XinZhangMS 0:f7f1f0d76dd6 333 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubClient_SetDeviceMethodCallback_Ex, IOTHUB_CLIENT_HANDLE, iotHubClientHandle, IOTHUB_CLIENT_INBOUND_DEVICE_METHOD_CALLBACK, inboundDeviceMethodCallback, void*, userContextCallback);
XinZhangMS 0:f7f1f0d76dd6 334
XinZhangMS 0:f7f1f0d76dd6 335 /**
XinZhangMS 0:f7f1f0d76dd6 336 * @brief This API responses to a asnyc method callback identified the methodId.
XinZhangMS 0:f7f1f0d76dd6 337 *
XinZhangMS 0:f7f1f0d76dd6 338 * @param iotHubClientHandle The handle created by a call to the create function.
XinZhangMS 0:f7f1f0d76dd6 339 * @param methodId The methodId of the Device Method callback.
XinZhangMS 0:f7f1f0d76dd6 340 * @param response The response data for the method callback.
XinZhangMS 0:f7f1f0d76dd6 341 * @param response_size The size of the response data buffer.
XinZhangMS 0:f7f1f0d76dd6 342 * @param status_response The status response of the method callback.
XinZhangMS 0:f7f1f0d76dd6 343 *
XinZhangMS 0:f7f1f0d76dd6 344 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
XinZhangMS 0:f7f1f0d76dd6 345 */
XinZhangMS 0:f7f1f0d76dd6 346 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubClient_DeviceMethodResponse, IOTHUB_CLIENT_HANDLE, iotHubClientHandle, METHOD_HANDLE, methodId, const unsigned char*, response, size_t, response_size, int, statusCode);
XinZhangMS 0:f7f1f0d76dd6 347
XinZhangMS 0:f7f1f0d76dd6 348 #ifndef DONT_USE_UPLOADTOBLOB
XinZhangMS 0:f7f1f0d76dd6 349 /**
XinZhangMS 0:f7f1f0d76dd6 350 * @brief IoTHubClient_UploadToBlobAsync uploads data from memory to a file in Azure Blob Storage.
XinZhangMS 0:f7f1f0d76dd6 351 *
XinZhangMS 0:f7f1f0d76dd6 352 * @param iotHubClientHandle The handle created by a call to the IoTHubClient_Create function.
XinZhangMS 0:f7f1f0d76dd6 353 * @param destinationFileName The name of the file to be created in Azure Blob Storage.
XinZhangMS 0:f7f1f0d76dd6 354 * @param source The source of data.
XinZhangMS 0:f7f1f0d76dd6 355 * @param size The size of data.
XinZhangMS 0:f7f1f0d76dd6 356 * @param iotHubClientFileUploadCallback A callback to be invoked when the file upload operation has finished.
XinZhangMS 0:f7f1f0d76dd6 357 * @param context A user-provided context to be passed to the file upload callback.
XinZhangMS 0:f7f1f0d76dd6 358 *
XinZhangMS 0:f7f1f0d76dd6 359 * @return IOTHUB_CLIENT_OK upon success or an error code upon failure.
XinZhangMS 0:f7f1f0d76dd6 360 */
XinZhangMS 0:f7f1f0d76dd6 361 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubClient_UploadToBlobAsync, IOTHUB_CLIENT_HANDLE, iotHubClientHandle, const char*, destinationFileName, const unsigned char*, source, size_t, size, IOTHUB_CLIENT_FILE_UPLOAD_CALLBACK, iotHubClientFileUploadCallback, void*, context);
XinZhangMS 0:f7f1f0d76dd6 362
XinZhangMS 0:f7f1f0d76dd6 363 /**
XinZhangMS 0:f7f1f0d76dd6 364 ** DEPRECATED: Use IoTHubClient_UploadMultipleBlocksToBlobAsyncEx instead **
XinZhangMS 0:f7f1f0d76dd6 365 * @brief Uploads a file to a Blob storage in chunks, fed through the callback function provided by the user.
XinZhangMS 0:f7f1f0d76dd6 366 * @remarks This function allows users to upload large files in chunks, not requiring the whole file content to be passed in memory.
XinZhangMS 0:f7f1f0d76dd6 367 * @param iotHubClientHandle The handle created by a call to the IoTHubClient_Create function.
XinZhangMS 0:f7f1f0d76dd6 368 * @param destinationFileName The name of the file to be created in Azure Blob Storage.
XinZhangMS 0:f7f1f0d76dd6 369 * @param getDataCallback 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.
XinZhangMS 0:f7f1f0d76dd6 370 * @param context Any data provided by the user to serve as context on getDataCallback.
XinZhangMS 0:f7f1f0d76dd6 371 * @returns An IOTHUB_CLIENT_RESULT value indicating the success or failure of the API call.
XinZhangMS 0:f7f1f0d76dd6 372 ** DEPRECATED: Use IoTHubClient_UploadMultipleBlocksToBlobAsyncEx instead **
XinZhangMS 0:f7f1f0d76dd6 373 */
XinZhangMS 0:f7f1f0d76dd6 374 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubClient_UploadMultipleBlocksToBlobAsync, IOTHUB_CLIENT_HANDLE, iotHubClientHandle, const char*, destinationFileName, IOTHUB_CLIENT_FILE_UPLOAD_GET_DATA_CALLBACK, getDataCallback, void*, context);
XinZhangMS 0:f7f1f0d76dd6 375
XinZhangMS 0:f7f1f0d76dd6 376 /**
XinZhangMS 0:f7f1f0d76dd6 377 * @brief Uploads a file to a Blob storage in chunks, fed through the callback function provided by the user.
XinZhangMS 0:f7f1f0d76dd6 378 * @remarks This function allows users to upload large files in chunks, not requiring the whole file content to be passed in memory.
XinZhangMS 0:f7f1f0d76dd6 379 * @param iotHubClientHandle The handle created by a call to the IoTHubClient_Create function.
XinZhangMS 0:f7f1f0d76dd6 380 * @param destinationFileName The name of the file to be created in Azure Blob Storage.
XinZhangMS 0:f7f1f0d76dd6 381 * @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.
XinZhangMS 0:f7f1f0d76dd6 382 * @param context Any data provided by the user to serve as context on getDataCallback.
XinZhangMS 0:f7f1f0d76dd6 383 * @returns An IOTHUB_CLIENT_RESULT value indicating the success or failure of the API call.*/
XinZhangMS 0:f7f1f0d76dd6 384 MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubClient_UploadMultipleBlocksToBlobAsyncEx, IOTHUB_CLIENT_HANDLE, iotHubClientHandle, const char*, destinationFileName, IOTHUB_CLIENT_FILE_UPLOAD_GET_DATA_CALLBACK_EX, getDataCallbackEx, void*, context);
XinZhangMS 0:f7f1f0d76dd6 385
XinZhangMS 0:f7f1f0d76dd6 386 #endif /* DONT_USE_UPLOADTOBLOB */
XinZhangMS 0:f7f1f0d76dd6 387
XinZhangMS 0:f7f1f0d76dd6 388 #ifdef __cplusplus
XinZhangMS 0:f7f1f0d76dd6 389 }
XinZhangMS 0:f7f1f0d76dd6 390 #endif
XinZhangMS 0:f7f1f0d76dd6 391
XinZhangMS 0:f7f1f0d76dd6 392 #endif /* IOTHUB_CLIENT_H */