Azure IoT C SDK
|
Shared enums, structures, and callback functions for IoT Hub client. More...
#include "azure_macro_utils/macro_utils.h"
#include "umock_c/umock_c_prod.h"
#include "iothub_transport_ll.h"
#include "iothub_message.h"
Go to the source code of this file.
Data Structures | |
struct | IOTHUB_CLIENT_CONFIG |
This struct specifies IoT Hub client configuration. More... | |
struct | IOTHUB_CLIENT_DEVICE_CONFIG |
This struct specifies IoT Hub client device configuration. More... | |
struct | IOTHUB_CLIENT_COMMAND_REQUEST |
This struct specifies parameters of an incoming command request. More... | |
struct | IOTHUB_CLIENT_COMMAND_RESPONSE |
This struct specifies parameters of an outgoing command response. More... | |
Macros | |
#define | IOTHUB_CLIENT_COMMAND_REQUEST_STRUCT_VERSION_1 1 |
Current version of IOTHUB_CLIENT_COMMAND_REQUEST structure. | |
#define | IOTHUB_CLIENT_COMMAND_RESPONSE_STRUCT_VERSION_1 1 |
Current version of IOTHUB_CLIENT_COMMAND_RESPONSE structure. | |
Typedefs | |
typedef void(* | IOTHUB_CLIENT_FILE_UPLOAD_CALLBACK) (IOTHUB_CLIENT_FILE_UPLOAD_RESULT result, void *userContextCallback) |
Deprecated callback mechanism for uploading data to a blob. More... | |
typedef struct IOTHUB_CLIENT_LL_UPLOADTOBLOB_CONTEXT_STRUCT * | IOTHUB_CLIENT_LL_UPLOADTOBLOB_CONTEXT_HANDLE |
typedef void(* | IOTHUB_METHOD_INVOKE_CALLBACK) (IOTHUB_CLIENT_RESULT result, int responseStatus, unsigned char *responsePayload, size_t responsePayloadSize, void *context) |
Signature of the callback that the application implements to receive notifications of module initiated device method calls. More... | |
typedef void(* | IOTHUB_CLIENT_EVENT_CONFIRMATION_CALLBACK) (IOTHUB_CLIENT_CONFIRMATION_RESULT result, void *userContextCallback) |
Signature of the callback that the application implements to process acknowledgement or failures when sending telemetry to IoT Hub. More... | |
typedef void(* | IOTHUB_CLIENT_CONNECTION_STATUS_CALLBACK) (IOTHUB_CLIENT_CONNECTION_STATUS result, IOTHUB_CLIENT_CONNECTION_STATUS_REASON reason, void *userContextCallback) |
Signature of the callback that the application implements to process connection status changes between device and IoT Hub. More... | |
typedef IOTHUBMESSAGE_DISPOSITION_RESULT(* | IOTHUB_CLIENT_MESSAGE_CALLBACK_ASYNC) (IOTHUB_MESSAGE_HANDLE message, void *userContextCallback) |
Signature of the callback that the application implements to process incoming cloud-to-device messages. More... | |
typedef void(* | IOTHUB_CLIENT_DEVICE_TWIN_CALLBACK) (DEVICE_TWIN_UPDATE_STATE update_state, const unsigned char *payLoad, size_t size, void *userContextCallback) |
Signature of the callback that the application implements to process data received from an IoT Hub device or module twin. More... | |
typedef void(* | IOTHUB_CLIENT_REPORTED_STATE_CALLBACK) (int status_code, void *userContextCallback) |
Signature of the callback that the application implements to receive notifications of device or module initiated twin updates. More... | |
typedef int(* | IOTHUB_CLIENT_DEVICE_METHOD_CALLBACK_ASYNC) (const char *method_name, const unsigned char *payload, size_t size, unsigned char **response, size_t *response_size, void *userContextCallback) |
Signature of the callback that the application implements to receive incoming device or module method invocations from IoT Hub. More... | |
typedef void(* | IOTHUB_CLIENT_FILE_UPLOAD_GET_DATA_CALLBACK) (IOTHUB_CLIENT_FILE_UPLOAD_RESULT result, unsigned char const **data, size_t *size, void *context) |
Deprecated callback mechanism for uploading data to a blob. More... | |
typedef IOTHUB_CLIENT_FILE_UPLOAD_GET_DATA_RESULT(* | IOTHUB_CLIENT_FILE_UPLOAD_GET_DATA_CALLBACK_EX) (IOTHUB_CLIENT_FILE_UPLOAD_RESULT result, unsigned char const **data, size_t *size, void *context) |
Signature of the callback that the application implements to process IoT Hub client SDK requesting additional chunks to upload to blob. More... | |
typedef void(* | IOTHUB_CLIENT_COMMAND_CALLBACK_ASYNC) (const IOTHUB_CLIENT_COMMAND_REQUEST *commandRequest, IOTHUB_CLIENT_COMMAND_RESPONSE *commandResponse, void *userContextCallback) |
Function callback application implements to process an incoming command from IoT Hub. More... | |
typedef void(* | IOTHUB_CLIENT_TELEMETRY_CALLBACK) (IOTHUB_CLIENT_CONFIRMATION_RESULT result, void *userContextCallback) |
Function callback application implements to receive notifications when IoT Hub acknowledges telemetry. More... | |
typedef void(* | IOTHUB_CLIENT_PROPERTY_ACKNOWLEDGED_CALLBACK) (int statusCode, void *userContextCallback) |
Function callback application implements to receive acknowledgements of properties sent from the client to IoT Hub. More... | |
typedef void(* | IOTHUB_CLIENT_PROPERTIES_RECEIVED_CALLBACK) (IOTHUB_CLIENT_PROPERTY_PAYLOAD_TYPE payloadType, const unsigned char *payload, size_t payloadLength, void *userContextCallback) |
Function callback application implements to process properties received from IoT Hub. More... | |
Enumerations | |
enum | IOTHUB_CLIENT_FILE_UPLOAD_RESULT { FILE_UPLOAD_OK , FILE_UPLOAD_ERROR } |
Enumeration specifying the status of a file upload operation. | |
enum | IOTHUB_CLIENT_RESULT { IOTHUB_CLIENT_OK , IOTHUB_CLIENT_INVALID_ARG , IOTHUB_CLIENT_ERROR , IOTHUB_CLIENT_INVALID_SIZE , IOTHUB_CLIENT_INDEFINITE_TIME } |
Enumeration specifying the status of calls to IoT Hub client. | |
enum | IOTHUB_CLIENT_RETRY_POLICY { IOTHUB_CLIENT_RETRY_NONE , IOTHUB_CLIENT_RETRY_IMMEDIATE , IOTHUB_CLIENT_RETRY_INTERVAL , IOTHUB_CLIENT_RETRY_LINEAR_BACKOFF , IOTHUB_CLIENT_RETRY_EXPONENTIAL_BACKOFF , IOTHUB_CLIENT_RETRY_EXPONENTIAL_BACKOFF_WITH_JITTER , IOTHUB_CLIENT_RETRY_RANDOM } |
Enumeration specifying the retry strategy the IoT Hub client should use. | |
enum | IOTHUB_CLIENT_STATUS { IOTHUB_CLIENT_SEND_STATUS_IDLE , IOTHUB_CLIENT_SEND_STATUS_BUSY } |
Enumeration returned by the GetSendStatus family of APIs (e.g. IoTHubDeviceClient_LL_GetSendStatus()) to indicate the current sending status of the IoT Hub client. | |
enum | IOTHUBMESSAGE_DISPOSITION_RESULT { IOTHUBMESSAGE_ACCEPTED , IOTHUBMESSAGE_REJECTED , IOTHUBMESSAGE_ABANDONED , IOTHUBMESSAGE_ASYNC_ACK } |
Enumeration returned by application callbacks that receive cloud-to-device messages. | |
enum | IOTHUB_CLIENT_CONFIRMATION_RESULT { IOTHUB_CLIENT_CONFIRMATION_OK , IOTHUB_CLIENT_CONFIRMATION_BECAUSE_DESTROY , IOTHUB_CLIENT_CONFIRMATION_MESSAGE_TIMEOUT , IOTHUB_CLIENT_CONFIRMATION_ERROR } |
Enumeration passed to the application's callback to process the success or failure of telemetry initiated by APIs in the SendEventAsync family (e.g. IoTHubDeviceClient_LL_SendEventAsync()). | |
enum | IOTHUB_CLIENT_CONNECTION_STATUS { IOTHUB_CLIENT_CONNECTION_AUTHENTICATED , IOTHUB_CLIENT_CONNECTION_UNAUTHENTICATED } |
Enumeration passed to the application callback indicating connection status changes to IoT Hub. More... | |
enum | IOTHUB_CLIENT_CONNECTION_STATUS_REASON { IOTHUB_CLIENT_CONNECTION_EXPIRED_SAS_TOKEN , IOTHUB_CLIENT_CONNECTION_DEVICE_DISABLED , IOTHUB_CLIENT_CONNECTION_BAD_CREDENTIAL , IOTHUB_CLIENT_CONNECTION_RETRY_EXPIRED , IOTHUB_CLIENT_CONNECTION_NO_NETWORK , IOTHUB_CLIENT_CONNECTION_COMMUNICATION_ERROR , IOTHUB_CLIENT_CONNECTION_OK , IOTHUB_CLIENT_CONNECTION_NO_PING_RESPONSE , IOTHUB_CLIENT_CONNECTION_QUOTA_EXCEEDED } |
Enumeration passed to the application callback indicating reason that connection was unsuccessful. More... | |
enum | IOTHUB_CLIENT_PROPERTY_PAYLOAD_TYPE { IOTHUB_CLIENT_PROPERTY_PAYLOAD_ALL , IOTHUB_CLIENT_PROPERTY_PAYLOAD_WRITABLE_UPDATES } |
Enumeration passed to IoT Hub device and module client property update callbacks to indicate whether or not the complete set of properties has arrived or just a partial set. | |
enum | DEVICE_TWIN_UPDATE_STATE { DEVICE_TWIN_UPDATE_COMPLETE , DEVICE_TWIN_UPDATE_PARTIAL } |
Enumeration passed to application callback to receive IoT Hub device or module twin data indicating whether the full twin or just partial update was received. | |
enum | IOTHUB_CLIENT_FILE_UPLOAD_GET_DATA_RESULT { IOTHUB_CLIENT_FILE_UPLOAD_GET_DATA_OK , IOTHUB_CLIENT_FILE_UPLOAD_GET_DATA_ABORT } |
Return value applications use in their implementation of IOTHUB_CLIENT_FILE_UPLOAD_GET_DATA_CALLBACK_EX() to indicate status. | |
Shared enums, structures, and callback functions for IoT Hub client.
typedef void(* IOTHUB_CLIENT_COMMAND_CALLBACK_ASYNC) (const IOTHUB_CLIENT_COMMAND_REQUEST *commandRequest, IOTHUB_CLIENT_COMMAND_RESPONSE *commandResponse, void *userContextCallback) |
Function callback application implements to process an incoming command from IoT Hub.
[in] | commandRequest | Parameters specified by the service application initiating command request. |
[out] | commandResponse | Response filled in by application callback to the command request. |
[in] | userContextCallback | User context pointer set in initial call to IoTHubDeviceClient_LL_SubscribeToCommands() . |
typedef void(* IOTHUB_CLIENT_CONNECTION_STATUS_CALLBACK) (IOTHUB_CLIENT_CONNECTION_STATUS result, IOTHUB_CLIENT_CONNECTION_STATUS_REASON reason, void *userContextCallback) |
Signature of the callback that the application implements to process connection status changes between device and IoT Hub.
result | Whether device is successfully connected (IOTHUB_CLIENT_CONNECTION_AUTHENTICATED ) or not (IOTHUB_CLIENT_CONNECTION_UNAUTHENTICATED ). |
reason | More information about result , especially if connection was unsuccessful. |
userContextCallback | Context that application specified during initial API call to receive status change notifications. |
typedef int(* IOTHUB_CLIENT_DEVICE_METHOD_CALLBACK_ASYNC) (const char *method_name, const unsigned char *payload, size_t size, unsigned char **response, size_t *response_size, void *userContextCallback) |
Signature of the callback that the application implements to receive incoming device or module method invocations from IoT Hub.
method_name | Name of method being invoked. |
payload | Request payload received from IoT Hub. |
size | Number of bytes in payload . |
response | Response of the request, as specified by the application. This should NOT include the null-terminator. |
response_size | Number of bytes application specifies in response . |
userContextCallback | Context that application specified during initial API call to receive device or module method calls. |
response
with malloc
. The IoT Hub client SDK will free
the data automatically.payload
is not guaranteed to be a null-terminated string.typedef void(* IOTHUB_CLIENT_DEVICE_TWIN_CALLBACK) (DEVICE_TWIN_UPDATE_STATE update_state, const unsigned char *payLoad, size_t size, void *userContextCallback) |
Signature of the callback that the application implements to process data received from an IoT Hub device or module twin.
update_state | Whether application has received a full twin or just a patch update. |
payLoad | Payload of twin received. |
size | Number of bytes in payload . |
userContextCallback | Context that application specified during initial API call to receive twin data. |
payLoad
is not guaranteed to be a null-terminated string. typedef void(* IOTHUB_CLIENT_EVENT_CONFIRMATION_CALLBACK) (IOTHUB_CLIENT_CONFIRMATION_RESULT result, void *userContextCallback) |
Signature of the callback that the application implements to process acknowledgement or failures when sending telemetry to IoT Hub.
result | Result of the telemetry send operation. |
userContextCallback | Context that application specified during initial API send call. |
typedef void(* IOTHUB_CLIENT_FILE_UPLOAD_CALLBACK) (IOTHUB_CLIENT_FILE_UPLOAD_RESULT result, void *userContextCallback) |
Deprecated callback mechanism for uploading data to a blob.
typedef void(* IOTHUB_CLIENT_FILE_UPLOAD_GET_DATA_CALLBACK) (IOTHUB_CLIENT_FILE_UPLOAD_RESULT result, unsigned char const **data, size_t *size, void *context) |
Deprecated callback mechanism for uploading data to a blob.
typedef IOTHUB_CLIENT_FILE_UPLOAD_GET_DATA_RESULT(* IOTHUB_CLIENT_FILE_UPLOAD_GET_DATA_CALLBACK_EX) (IOTHUB_CLIENT_FILE_UPLOAD_RESULT result, unsigned char const **data, size_t *size, void *context) |
Signature of the callback that the application implements to process IoT Hub client SDK requesting additional chunks to upload to blob.
result | The result of the upload of the previous block of data provided by the user. |
data | Next block of data to be uploaded, to be provided by the user when this callback is invoked. |
size | Size of the data parameter. |
context | User context provided on the call to IoTHubClient_UploadMultipleBlocksToBlobAsync. |
typedef struct IOTHUB_CLIENT_LL_UPLOADTOBLOB_CONTEXT_STRUCT* IOTHUB_CLIENT_LL_UPLOADTOBLOB_CONTEXT_HANDLE |
struct IOTHUB_CLIENT_LL_UPLOADTOBLOB_CONTEXT_STRUCT
contains information specifically related to an individual upload request currently active in Azure IoT Hub, mainly the correlation-id and Azure Blob SAS URI provided by the Azure IoT Hub when a new upload is started. The struct IOTHUB_CLIENT_LL_UPLOADTOBLOB_HANDLE_DATA
on the other hand holds common information (independent from individual upload requests) that is used for upload-to-blob Rest API calls to Azure IoT Hub. typedef IOTHUBMESSAGE_DISPOSITION_RESULT(* IOTHUB_CLIENT_MESSAGE_CALLBACK_ASYNC) (IOTHUB_MESSAGE_HANDLE message, void *userContextCallback) |
Signature of the callback that the application implements to process incoming cloud-to-device messages.
message | The incoming message received from IoT Hub. |
userContextCallback | Context that application specified during initial API call to receive incoming cloud-to-device messages. |
typedef void(* IOTHUB_CLIENT_PROPERTIES_RECEIVED_CALLBACK) (IOTHUB_CLIENT_PROPERTY_PAYLOAD_TYPE payloadType, const unsigned char *payload, size_t payloadLength, void *userContextCallback) |
Function callback application implements to process properties received from IoT Hub.
[in] | payloadType | Whether the payload contains all properties from IoT Hub or only the ones that have just been updated. |
[in] | payload | Raw payload of the request. This is NOT guaranteed to be a \0 terminated string. |
[in] | payloadLength | Number of bytes of payload . |
[in] | userContextCallback | User context pointer set in initial call to retrieving the properties (for example, IoTHubDeviceClient_LL_GetPropertiesAsync() or IoTHubDeviceClient_LL_GetPropertiesAndSubscribeToUpdatesAsync() ). |
typedef void(* IOTHUB_CLIENT_PROPERTY_ACKNOWLEDGED_CALLBACK) (int statusCode, void *userContextCallback) |
Function callback application implements to receive acknowledgements of properties sent from the client to IoT Hub.
[in] | statusCode | Status code IoT Hub returns when receiving a property or writable property response from the device. This corresponds to HTTP status codes. |
[in] | userContextCallback | Optional user specified context set in the call that sent the properties (for example, IoTHubDeviceClient_LL_SendPropertiesAsync() ). |
typedef void(* IOTHUB_CLIENT_REPORTED_STATE_CALLBACK) (int status_code, void *userContextCallback) |
Signature of the callback that the application implements to receive notifications of device or module initiated twin updates.
status_code | HTTP style status code indicating success or failure of operation. |
userContextCallback | Context that application specified during initial API call to update twin data. |
typedef void(* IOTHUB_CLIENT_TELEMETRY_CALLBACK) (IOTHUB_CLIENT_CONFIRMATION_RESULT result, void *userContextCallback) |
Function callback application implements to receive notifications when IoT Hub acknowledges telemetry.
[in] | result | Result of operation sending to IoT Hub. |
[in] | userContextCallback | Optional user specified context set in call that initiated the message send (for example, IoTHubDeviceClient_LL_SendTelemetryAsync() ). |
typedef void(* IOTHUB_METHOD_INVOKE_CALLBACK) (IOTHUB_CLIENT_RESULT result, int responseStatus, unsigned char *responsePayload, size_t responsePayloadSize, void *context) |
Signature of the callback that the application implements to receive notifications of module initiated device method calls.
result | Result of the operation |
responseStatus | HTTP status code returned from the module or device. This is only valid if result is IOTHUB_CLIENT_OK . |
responsePayload | HTTP response payload returned from the module or device. This is only valid if result is IOTHUB_CLIENT_OK . |
responsePayloadSize | Number of bytes in responsePayload . This is only valid if result is IOTHUB_CLIENT_OK . |
context | Context value passed is initial call to IoTHubModuleClient_ModuleMethodInvokeAsync() (e.g.). |
Enumeration passed to the application callback indicating connection status changes to IoT Hub.
IOTHUB_CLIENT_CONNECTION_AUTHENTICATED
means the device or module client is ready to communicate with the Azure IoT Hub, being both connected and authenticated. IOTHUB_CLIENT_CONNECTION_UNAUTHENTICATED
means the device or module client is not ready to communicate with the Azure IoT Hub. See the corresponding value of IOTHUB_CLIENT_CONNECTION_STATUS_REASON
for more details. Enumeration passed to the application callback indicating reason that connection was unsuccessful.
IOTHUB_CLIENT_CONNECTION_STATUS_REASON
has a specific semantics depending on the transport protocol used. Here is a brief description of the reasons for each transport protocol: IOTHUB_CLIENT_CONNECTION_EXPIRED_SAS_TOKEN
MQTT: The SAS token used in the current MQTT connection is expired and the client must reconnect with a new SAS token. AMQP: Not applicable. HTTP: Not applicable. IOTHUB_CLIENT_CONNECTION_DEVICE_DISABLED
MQTT: An MQTT CONNECT to the Azure IoT Hub was rejected. AMQP: Not applicable. HTTP: Not applicable. IOTHUB_CLIENT_CONNECTION_BAD_CREDENTIAL
MQTT: Not applicable. AMQP: A SAS-based authentication request failed. HTTP: Not applicable. IOTHUB_CLIENT_CONNECTION_RETRY_EXPIRED
MQTT: The MQTT transport has made its maximum number of attempts to reconnect to the Azure IoT Hub and it will no longer try. AMQP: The AMQP transport has made its maximum number of attempts to reconnect to the Azure IoT Hub and it will no longer try. HTTP: Not applicable. IOTHUB_CLIENT_CONNECTION_NO_NETWORK
MQTT: An MQTT CONNECT packet failed to be sent to the Azure IoT Hub for any reason. AMQP: A network connection issue was detected, which includes socket errors, failures on AMQP ATTACH to CBS link (for authentication). HTTP: Not applicable. IOTHUB_CLIENT_CONNECTION_COMMUNICATION_ERROR
MQTT: A telemetry message timed out receiving a PUBACK from the Azure IoT Hub, there was an error sending a PUBACK or PUBREC to Azure IoT Hub, or an I/O error occurred when using WebSockets. AMQP: Authentication request timed out, received an unexpected link DETACH from Azure IoT Hub, or a link ATTACH timed out. HTTP: Not applicable. IOTHUB_CLIENT_CONNECTION_OK
Applicable to all transport protocols. The Azure IoT C SDK client is connected and ready to communicate with the Azure IoT Hub. This reason is applicable only to IOTHUB_CLIENT_CONNECTION_AUTHENTICATED
. IOTHUB_CLIENT_CONNECTION_NO_PING_RESPONSE
MQTT: The MQTT transport timed out waiting for a ping response from the Azure IoT Hub. AMQP: Not applicable. HTTP: Not applicable. IOTHUB_CLIENT_CONNECTION_QUOTA_EXCEEDED
MQTT: Not applicable. AMQP: The Azure IoT Hub rejected a telemetry message because the maximum daily quota of telemetry messages has been reached. HTTP: Not applicable.