Azure IoT C SDK
Data Structures | Macros | Typedefs | Enumerations
iothub_client_core_common.h File Reference

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 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.
 
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.
 
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.
 

Detailed Description

Shared enums, structures, and callback functions for IoT Hub client.

Typedef Documentation

◆ IOTHUB_CLIENT_COMMAND_CALLBACK_ASYNC

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.

Parameters
[in]commandRequestParameters specified by the service application initiating command request.
[out]commandResponseResponse filled in by application callback to the command request.
[in]userContextCallbackUser context pointer set in initial call to IoTHubDeviceClient_LL_SubscribeToCommands().

◆ IOTHUB_CLIENT_CONNECTION_STATUS_CALLBACK

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.

Parameters
resultWhether device is successfully connected (IOTHUB_CLIENT_CONNECTION_AUTHENTICATED) or not (IOTHUB_CLIENT_CONNECTION_UNAUTHENTICATED).
reasonMore information about result, especially if connection was unsuccessful.
userContextCallbackContext that application specified during initial API call to receive status change notifications.

◆ IOTHUB_CLIENT_DEVICE_METHOD_CALLBACK_ASYNC

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.

Parameters
method_nameName of method being invoked.
payloadRequest payload received from IoT Hub.
sizeNumber of bytes in payload.
responseResponse of the request, as specified by the application. This should NOT include the null-terminator.
response_sizeNumber of bytes application specifies in response.
userContextCallbackContext that application specified during initial API call to receive device or module method calls.
Remarks
The application should allocate response with malloc. The IoT Hub client SDK will free the data automatically.
Warning
The data in payload is not guaranteed to be a null-terminated string.
Returns
HTTP style return code to indicate success or failure of the method call.

◆ IOTHUB_CLIENT_DEVICE_TWIN_CALLBACK

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.

Parameters
update_stateWhether application has received a full twin or just a patch update.
payLoadPayload of twin received.
sizeNumber of bytes in payload.
userContextCallbackContext that application specified during initial API call to receive twin data.
Warning
The data in payLoad is not guaranteed to be a null-terminated string.

◆ IOTHUB_CLIENT_EVENT_CONFIRMATION_CALLBACK

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.

Parameters
resultResult of the telemetry send operation.
userContextCallbackContext that application specified during initial API send call.

◆ IOTHUB_CLIENT_FILE_UPLOAD_CALLBACK

typedef void(* IOTHUB_CLIENT_FILE_UPLOAD_CALLBACK) (IOTHUB_CLIENT_FILE_UPLOAD_RESULT result, void *userContextCallback)

Deprecated callback mechanism for uploading data to a blob.

Deprecated:
This callback type is deprecated. Use the callback IOTHUB_CLIENT_FILE_UPLOAD_GET_DATA_CALLBACK_EX() instead.

◆ IOTHUB_CLIENT_FILE_UPLOAD_GET_DATA_CALLBACK

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.

Deprecated:
This callback type is deprecated. Use the callback IOTHUB_CLIENT_FILE_UPLOAD_GET_DATA_CALLBACK_EX() instead.

◆ IOTHUB_CLIENT_FILE_UPLOAD_GET_DATA_CALLBACK_EX

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.

Parameters
resultThe result of the upload of the previous block of data provided by the user.
dataNext block of data to be uploaded, to be provided by the user when this callback is invoked.
sizeSize of the data parameter.
contextUser context provided on the call to IoTHubClient_UploadMultipleBlocksToBlobAsync.
Returns
IOTHUB_CLIENT_FILE_UPLOAD_GET_DATA_RESULT indicating whether the application is returning data to be sent or not.
Remarks
If the user wants to abort the upload, the callback should return IOTHUB_CLIENT_FILE_UPLOAD_GET_DATA_ABORT It should return IOTHUB_CLIENT_FILE_UPLOAD_GET_DATA_OK otherwise. If a NULL is provided for parameter "data" and/or zero is provided for "size", the user indicates to the client that the complete file has been uploaded. In such case this callback will be invoked only once more to indicate the status of the final block upload. If result is not FILE_UPLOAD_OK, the upload is cancelled and this callback stops being invoked. When this callback is called for the last time, no data or size is expected, so data and size are NULL

◆ IOTHUB_CLIENT_MESSAGE_CALLBACK_ASYNC

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.

Parameters
messageThe incoming message received from IoT Hub.
userContextCallbackContext that application specified during initial API call to receive incoming cloud-to-device messages.
Returns
IOTHUBMESSAGE_DISPOSITION_RESULT indicating how client has acknowledged the incoming cloud-to-device message.

◆ IOTHUB_CLIENT_PROPERTIES_RECEIVED_CALLBACK

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.

Parameters
[in]payloadTypeWhether the payload contains all properties from IoT Hub or only the ones that have just been updated.
[in]payloadRaw payload of the request. This is NOT guaranteed to be a \0 terminated string.
[in]payloadLengthNumber of bytes of payload.
[in]userContextCallbackUser context pointer set in initial call to retrieving the properties (for example, IoTHubDeviceClient_LL_GetPropertiesAsync() or IoTHubDeviceClient_LL_GetPropertiesAndSubscribeToUpdatesAsync()).

◆ IOTHUB_CLIENT_PROPERTY_ACKNOWLEDGED_CALLBACK

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.

Parameters
[in]statusCodeStatus code IoT Hub returns when receiving a property or writable property response from the device.
This corresponds to HTTP status codes.
[in]userContextCallbackOptional user specified context set in the call that sent the properties (for example, IoTHubDeviceClient_LL_SendPropertiesAsync()).

◆ IOTHUB_CLIENT_REPORTED_STATE_CALLBACK

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.

Parameters
status_codeHTTP style status code indicating success or failure of operation.
userContextCallbackContext that application specified during initial API call to update twin data.

◆ IOTHUB_CLIENT_TELEMETRY_CALLBACK

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.

Parameters
[in]resultResult of operation sending to IoT Hub.
[in]userContextCallbackOptional user specified context set in call that initiated the message send (for example, IoTHubDeviceClient_LL_SendTelemetryAsync()).

◆ IOTHUB_METHOD_INVOKE_CALLBACK

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.

Parameters
resultResult of the operation
responseStatusHTTP status code returned from the module or device. This is only valid if result is IOTHUB_CLIENT_OK.
responsePayloadHTTP response payload returned from the module or device. This is only valid if result is IOTHUB_CLIENT_OK.
responsePayloadSizeNumber of bytes in responsePayload. This is only valid if result is IOTHUB_CLIENT_OK.
contextContext value passed is initial call to IoTHubModuleClient_ModuleMethodInvokeAsync() (e.g.).
Remarks
Module clients when hosted in IoT Edge may themselves invoke methods on either modules on the same IoT Edge device or on downstream devices using APIs such as IoTHubModuleClient_LL_DeviceMethodInvoke() or IoTHubModuleClient_LL_ModuleMethodInvoke(). These APIs operate asynchronously. When the invoked module or device returns (or times out), the IoT Hub SDK will invoke the application's IOTHUB_METHOD_INVOKE_CALLBACK() callback.
Warning
This API is only applicable to applications running inside a module container hosted by IoT Edge. Calling outside a IoT Edge hosted edge container will result in undefined results.