iothub_client.h File Reference

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

Parameters:

config

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

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

Parameters:

connectionString	Pointer to a character string
protocol	Function 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.

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

Parameters:

transportHandle	TRANSPORT_HANDLE which represents a connection.
config	Pointer 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.

Disposes of resources allocated by the IoT Hub client.

This is a blocking call.

Parameters:

iotHubClientHandle

The handle created by a call to the create function.

Definition at line 417 of file iothub_client.c.

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:

iotHubClientHandle	The handle created by a call to the create function.
lastMessageReceiveTime	Out 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.

This function returns the current sending status for IoTHubClient.

Parameters:

iotHubClientHandle	The handle created by a call to the create function.
iotHubClientStatus	The 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.

Asynchronous call to send the message specified by eventMessageHandle.

Parameters:

iotHubClientHandle	The handle created by a call to the create function.
eventMessageHandle	The handle to an IoT Hub message.
eventConfirmationCallback	The 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.
userContextCallback	User 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.

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

This is a blocking call.

Parameters:

iotHubClientHandle	The handle created by a call to the create function.
messageCallback	The callback specified by the device for receiving messages from IoT Hub.
userContextCallback	User 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.

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:

iotHubClientHandle	The handle created by a call to the create function.
optionName	Name of the option.
value	The 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.

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

Parameters:

iotHubClientHandle	The handle created by a call to the IoTHubClient_Create function.
destinationFileName	The name of the file to be created in Azure Blob Storage.
source	The source of data.
size	The size of data.
iotHubClientFileUploadCallback	A callback to be invoked when the file upload operation has finished.
context	A 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.