corrected version (with typedef struct IOTHUB_CLIENT_LL_UPLOADTOBLOB_HANDLE_DATA* IOTHUB_CLIENT_LL_UPLOADTOBLOB_HANDLE;) included in the sources

Dependents:   STM32F746_iothub_client_sample_mqtt

Fork of iothub_client by Azure IoT

Embed: (wiki syntax)

« Back to documentation index

iothub_client.h File Reference

iothub_client.h File Reference

Extends the IoTHubCLient_LL module with additional features. More...

Go to the source code of this file.

Functions

IOTHUB_CLIENT_HANDLE IoTHubClient_CreateFromConnectionString (const char *connectionString, IOTHUB_CLIENT_TRANSPORT_PROVIDER protocol)
 Creates a IoT Hub client for communication with an existing IoT Hub using the specified connection string parameter.
IOTHUB_CLIENT_HANDLE IoTHubClient_Create (const IOTHUB_CLIENT_CONFIG *config)
 Creates a IoT Hub client for communication with an existing IoT Hub using the specified parameters.
IOTHUB_CLIENT_HANDLE IoTHubClient_CreateWithTransport (TRANSPORT_HANDLE transportHandle, const IOTHUB_CLIENT_CONFIG *config)
 Creates a IoT Hub client for communication with an existing IoT Hub using the specified parameters.
void IoTHubClient_Destroy (IOTHUB_CLIENT_HANDLE iotHubClientHandle)
 Disposes of resources allocated by the IoT Hub client.
IOTHUB_CLIENT_RESULT IoTHubClient_SendEventAsync (IOTHUB_CLIENT_HANDLE iotHubClientHandle, IOTHUB_MESSAGE_HANDLE eventMessageHandle, IOTHUB_CLIENT_EVENT_CONFIRMATION_CALLBACK eventConfirmationCallback, void *userContextCallback)
 Asynchronous call to send the message specified by eventMessageHandle.
IOTHUB_CLIENT_RESULT IoTHubClient_GetSendStatus (IOTHUB_CLIENT_HANDLE iotHubClientHandle, IOTHUB_CLIENT_STATUS *iotHubClientStatus)
 This function returns the current sending status for IoTHubClient.
IOTHUB_CLIENT_RESULT IoTHubClient_SetMessageCallback (IOTHUB_CLIENT_HANDLE iotHubClientHandle, IOTHUB_CLIENT_MESSAGE_CALLBACK_ASYNC messageCallback, void *userContextCallback)
 Sets up the message callback to be invoked when IoT Hub issues a message to the device.
IOTHUB_CLIENT_RESULT IoTHubClient_GetLastMessageReceiveTime (IOTHUB_CLIENT_HANDLE iotHubClientHandle, time_t *lastMessageReceiveTime)
 This function returns in the out parameter lastMessageReceiveTime what was the value of the time function when the last message was received at the client.
IOTHUB_CLIENT_RESULT IoTHubClient_SetOption (IOTHUB_CLIENT_HANDLE iotHubClientHandle, const char *optionName, const void *value)
 This API sets a runtime option identified by parameter optionName to a value pointed to by value.
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)
 IoTHubClient_UploadToBlobAsync uploads data from memory to a file in Azure Blob Storage.

Detailed Description

Extends the IoTHubCLient_LL module with additional features.

IoTHubClient is a module that extends the IoTHubCLient_LL module with 2 features:

  • scheduling the work for the IoTHubCLient from a thread, so that the user does not need to create their own thread
  • thread-safe APIs

Definition in file iothub_client.h.


Function Documentation

IOTHUB_CLIENT_HANDLE IoTHubClient_Create ( const IOTHUB_CLIENT_CONFIG config )

Creates a IoT Hub client for communication with an existing IoT Hub using the specified parameters.

Parameters:
configPointer to an IOTHUB_CLIENT_CONFIG structure

The API does not allow sharing of a connection across multiple devices. This is a blocking call.

Returns:
A non-NULL IOTHUB_CLIENT_HANDLE value that is used when invoking other functions for IoT Hub client and NULL on failure.

Definition at line 246 of file iothub_client.c.

IOTHUB_CLIENT_HANDLE IoTHubClient_CreateFromConnectionString ( const char *  connectionString,
IOTHUB_CLIENT_TRANSPORT_PROVIDER  protocol 
)

Creates a IoT Hub client for communication with an existing IoT Hub using the specified connection string parameter.

Parameters:
connectionStringPointer to a character string
protocolFunction pointer for protocol implementation

Sample connection string: <blockquote>

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];
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];

</blockquote>

Returns:
A non-NULL IOTHUB_CLIENT_HANDLE value that is used when invoking other functions for IoT Hub client and NULL on failure.

Definition at line 171 of file iothub_client.c.

IOTHUB_CLIENT_HANDLE IoTHubClient_CreateWithTransport ( TRANSPORT_HANDLE  transportHandle,
const IOTHUB_CLIENT_CONFIG config 
)

Creates a IoT Hub client for communication with an existing IoT Hub using the specified parameters.

Parameters:
transportHandleTRANSPORT_HANDLE which represents a connection.
configPointer to an IOTHUB_CLIENT_CONFIG structure

The API allows sharing of a connection across multiple devices. This is a blocking call.

Returns:
A non-NULL IOTHUB_CLIENT_HANDLE value that is used when invoking other functions for IoT Hub client and NULL on failure.

Definition at line 303 of file iothub_client.c.

void IoTHubClient_Destroy ( IOTHUB_CLIENT_HANDLE  iotHubClientHandle )

Disposes of resources allocated by the IoT Hub client.

This is a blocking call.

Parameters:
iotHubClientHandleThe handle created by a call to the create function.

Definition at line 417 of file iothub_client.c.

IOTHUB_CLIENT_RESULT IoTHubClient_GetLastMessageReceiveTime ( IOTHUB_CLIENT_HANDLE  iotHubClientHandle,
time_t *  lastMessageReceiveTime 
)

This function returns in the out parameter lastMessageReceiveTime what was the value of the time function when the last message was received at the client.

Parameters:
iotHubClientHandleThe handle created by a call to the create function.
lastMessageReceiveTimeOut parameter containing the value of time function when the last message was received.
Returns:
IOTHUB_CLIENT_OK upon success or an error code upon failure.

Definition at line 624 of file iothub_client.c.

IOTHUB_CLIENT_RESULT IoTHubClient_GetSendStatus ( IOTHUB_CLIENT_HANDLE  iotHubClientHandle,
IOTHUB_CLIENT_STATUS *  iotHubClientStatus 
)

This function returns the current sending status for IoTHubClient.

Parameters:
iotHubClientHandleThe handle created by a call to the create function.
iotHubClientStatusThe sending state is populated at the address pointed at by this parameter. The value will be set to IOTHUBCLIENT_SENDSTATUS_IDLE if there is currently no item to be sent and IOTHUBCLIENT_SENDSTATUS_BUSY if there are.
Returns:
IOTHUB_CLIENT_OK upon success or an error code upon failure.

Definition at line 545 of file iothub_client.c.

IOTHUB_CLIENT_RESULT IoTHubClient_SendEventAsync ( IOTHUB_CLIENT_HANDLE  iotHubClientHandle,
IOTHUB_MESSAGE_HANDLE  eventMessageHandle,
IOTHUB_CLIENT_EVENT_CONFIRMATION_CALLBACK  eventConfirmationCallback,
void *  userContextCallback 
)

Asynchronous call to send the message specified by eventMessageHandle.

Parameters:
iotHubClientHandleThe handle created by a call to the create function.
eventMessageHandleThe handle to an IoT Hub message.
eventConfirmationCallbackThe callback specified by the device for receiving confirmation of the delivery of the IoT Hub message. This callback can be expected to invoke the IoTHubClient_SendEventAsync function for the same message in an attempt to retry sending a failing message. The user can specify a NULL value here to indicate that no callback is required.
userContextCallbackUser specified context that will be provided to the callback. This can be NULL.

NOTE: The application behavior is undefined if the user calls the IoTHubClient_Destroy function from within any callback.

Returns:
IOTHUB_CLIENT_OK upon success or an error code upon failure.

Definition at line 500 of file iothub_client.c.

IOTHUB_CLIENT_RESULT IoTHubClient_SetMessageCallback ( IOTHUB_CLIENT_HANDLE  iotHubClientHandle,
IOTHUB_CLIENT_MESSAGE_CALLBACK_ASYNC  messageCallback,
void *  userContextCallback 
)

Sets up the message callback to be invoked when IoT Hub issues a message to the device.

This is a blocking call.

Parameters:
iotHubClientHandleThe handle created by a call to the create function.
messageCallbackThe callback specified by the device for receiving messages from IoT Hub.
userContextCallbackUser specified context that will be provided to the callback. This can be NULL.

NOTE: The application behavior is undefined if the user calls the IoTHubClient_Destroy function from within any callback.

Returns:
IOTHUB_CLIENT_OK upon success or an error code upon failure.

Definition at line 580 of file iothub_client.c.

IOTHUB_CLIENT_RESULT IoTHubClient_SetOption ( IOTHUB_CLIENT_HANDLE  iotHubClientHandle,
const char *  optionName,
const void *  value 
)

This API sets a runtime option identified by parameter optionName to a value pointed to by value.

optionName and the data type value is pointing to are specific for every option.

Parameters:
iotHubClientHandleThe handle created by a call to the create function.
optionNameName of the option.
valueThe value.

The options that can be set via this API are:

  • timeout - the maximum time in milliseconds a communication is allowed to use. value is a pointer to an unsigned int with the timeout value in milliseconds. This is only supported for the HTTP protocol as of now. When the HTTP protocol uses CURL, the meaning of the parameter is total request time. When the HTTP protocol uses winhttp, the meaning is the same as the dwSendTimeout and dwReceiveTimeout parameters of the WinHttpSetTimeouts API.
  • CURLOPT_LOW_SPEED_LIMIT - only available for HTTP protocol and only when CURL is used. It has the same meaning as CURL's option with the same name. value is pointer to a long.
  • CURLOPT_LOW_SPEED_TIME - only available for HTTP protocol and only when CURL is used. It has the same meaning as CURL's option with the same name. value is pointer to a long.
  • CURLOPT_FORBID_REUSE - only available for HTTP protocol and only when CURL is used. It has the same meaning as CURL's option with the same name. value is pointer to a long.
  • CURLOPT_FRESH_CONNECT - only available for HTTP protocol and only when CURL is used. It has the same meaning as CURL's option with the same name. value is pointer to a long.
  • CURLOPT_VERBOSE - only available for HTTP protocol and only when CURL is used. It has the same meaning as CURL's option with the same name. value is pointer to a long.
  • messageTimeout - the maximum time in milliseconds until a message is timeouted. The time starts at IoTHubClient_SendEventAsync. By default, messages do not expire. is a pointer to a uint64_t
    Returns:
    IOTHUB_CLIENT_OK upon success or an error code upon failure.

Definition at line 659 of file iothub_client.c.

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 
)

IoTHubClient_UploadToBlobAsync uploads data from memory to a file in Azure Blob Storage.

Parameters:
iotHubClientHandleThe handle created by a call to the IoTHubClient_Create function.
destinationFileNameThe name of the file to be created in Azure Blob Storage.
sourceThe source of data.
sizeThe size of data.
iotHubClientFileUploadCallbackA callback to be invoked when the file upload operation has finished.
contextA user-provided context to be passed to the file upload callback.
Returns:
IOTHUB_CLIENT_OK upon success or an error code upon failure.

Definition at line 747 of file iothub_client.c.