DeviceClient Class

  • Reference
Package:
com.microsoft.azure.sdk.iot.device
  • java.lang.Object

public class DeviceClient extends InternalClient

The public-facing API. Allows a single logical or physical device to connect to an IoT Hub. The IoT Hub client supports sending events to and receiving messages from an IoT Hub.

To support these workflows, the client library will provide the following abstractions: a message, with its payload and associated properties; and a client, which sends and receives messages.

The client buffers messages while the network is down, and re-sends them when the network comes back online. It also batches messages to improve communication efficiency (HTTPS only).

The client supports HTTPS 1.1 and AMQPS 1.0 transports.

Constructor Summary

Constructor Description
DeviceClient(String connectionString, IotHubClientProtocol protocol)

Constructor that takes a connection string as an argument.
DeviceClient(String connectionString, IotHubClientProtocol protocol, ClientOptions clientOptions)

Constructor that takes a connection string as an argument.
DeviceClient(String hostName, String deviceId, SasTokenProvider sasTokenProvider, IotHubClientProtocol protocol)

Constructor that allows for the client's SAS token generation to be controlled by the user. Note that options in this client such as setting the SAS token expiry time will throw UnsupportedOperationException since the SDK no longer controls that when this constructor is used.

DeviceClient(String hostName, String deviceId, SasTokenProvider sasTokenProvider, IotHubClientProtocol protocol, ClientOptions clientOptions)

Constructor that allows for the client's SAS token generation to be controlled by the user. Note that options in this client such as setting the SAS token expiry time will throw UnsupportedOperationException since the SDK no longer controls that when this constructor is used.

DeviceClient(String uri, String deviceId, SecurityProvider securityProvider, IotHubClientProtocol protocol)

Creates a device client that uses the provided security provider for authentication.
DeviceClient(String uri, String deviceId, SecurityProvider securityProvider, IotHubClientProtocol protocol, ClientOptions clientOptions)

Creates a device client that uses the provided security provider for authentication.

Method Summary

Modifier and Type Method and Description
void close()

Closes the IoT hub client by releasing any resources held by client. When close is called all the messages that were in transit or pending to be sent will be informed to the user in the callbacks and any existing connection to IotHub will be closed. Must be called to terminate the background thread that is sending data to IoT hub. After close is called, the IoT hub client must be opened again before it can be used again. If the client is already closed, the function shall do nothing.
void completeFileUpload(FileUploadCompletionNotification notification)

Notify IoT hub that a file upload has been completed, successfully or otherwise. See this documentation for more details.

FileUploadSasUriResponse getFileUploadSasUri(FileUploadSasUriRequest request)

Get a file upload SAS URI which the Azure Storage SDK can use to upload a file to blob for this device. See this documentation for more details.

boolean isMultiplexed()

Returns if this client is or ever was registered to a MultiplexingClient instance. Device clients that were cannot be used in non-multiplexed connections. Device clients that aren't registered to any multiplexing client will still return true.

void open(boolean withRetry)

Starts asynchronously sending and receiving messages from an IoT hub. If the client is already open, the function shall do nothing.
DeviceClient setMessageCallback(MessageCallback callback, Object context)

Sets the message callback.

Inherited Members

InternalClient.DEFAULT_TIMEOUT_MILLISECONDS InternalClient.getConfig() InternalClient.getProductInfo() InternalClient.getTwin() InternalClient.getTwin(int timeoutMilliseconds) InternalClient.getTwinAsync(GetTwinCallback twinCallback, Object callbackContext) InternalClient.getTwinAsync(GetTwinCorrelatingMessageCallback twinCallback, Object callbackContext) InternalClient.sendEvent(Message message) InternalClient.sendEvent(Message message, int timeoutMilliseconds) InternalClient.sendEventAsync(Message message, MessageSentCallback callback, Object callbackContext) InternalClient.sendEvents(List<Message> messages) InternalClient.sendEvents(List<Message> messages, int timeoutMilliseconds) InternalClient.sendEventsAsync(List<Message> messages, MessagesSentCallback callback, Object callbackContext) InternalClient.setConnectionStatusChangeCallback(IotHubConnectionStatusChangeCallback callback, Object callbackContext) InternalClient.setOperationTimeout(long timeout) InternalClient.setRetryPolicy(RetryPolicy retryPolicy) InternalClient.subscribeToDesiredProperties(DesiredPropertiesCallback desiredPropertiesCallback, Object desiredPropertiesCallbackContext) InternalClient.subscribeToDesiredProperties(DesiredPropertiesCallback desiredPropertiesCallback, Object desiredPropertiesCallbackContext, int timeoutMilliseconds) InternalClient.subscribeToDesiredPropertiesAsync(DesiredPropertiesCallback desiredPropertiesCallback, Object desiredPropertiesCallbackContext, SubscriptionAcknowledgedCallback subscriptionAcknowledgedCallback, Object desiredPropertiesSubscriptionCallbackContext) InternalClient.subscribeToMethods(MethodCallback methodCallback, Object methodCallbackContext) InternalClient.subscribeToMethods(MethodCallback methodCallback, Object methodCallbackContext, int timeoutMilliseconds) InternalClient.subscribeToMethodsAsync(MethodCallback methodCallback, Object methodCallbackContext, SubscriptionAcknowledgedCallback methodStatusCallback, Object methodStatusCallbackContext) InternalClient.updateReportedProperties(TwinCollection reportedProperties) InternalClient.updateReportedProperties(TwinCollection reportedProperties, int timeoutMilliseconds) InternalClient.updateReportedPropertiesAsync(TwinCollection reportedProperties, ReportedPropertiesCallback reportedPropertiesCallback, Object callbackContext) InternalClient.updateReportedPropertiesAsync(TwinCollection reportedProperties, ReportedPropertiesUpdateCorrelatingMessageCallback reportedPropertiesUpdateCorrelatingMessageCallback, Object callbackContext)

Constructor Details

DeviceClient

public DeviceClient(String connectionString, IotHubClientProtocol protocol)

Constructor that takes a connection string as an argument.

Parameters:

connectionString -

the connection string. The connection string is a set of key-value pairs that are separated by ';', with the keys and values separated by '='. It should contain values for the following keys: HostName  

</code> ,<code>DeviceId 

</code> , and<code>SharedAccessKey 

</code> . </p>

protocol - the communication protocol used (i.e. HTTPS).

Throws:

IllegalArgumentException -

if any ofconnectionString  

</code> or <code>protocol 

</code> are<code>null 

</code> ; or if<code>connectionString 

</code> is missing one of the following attributes:<code>HostName 

</code> ,<code>DeviceId 

</code> , or <code>SharedAccessKey 

</code> or if the IoT hub hostname does not conform to RFC 3986 or if the provided<code>connectionString 

</code> is for an x509 authenticated device </p>

DeviceClient

public DeviceClient(String connectionString, IotHubClientProtocol protocol, ClientOptions clientOptions)

Constructor that takes a connection string as an argument.

Parameters:

connectionString -

the connection string. The connection string is a set of key-value pairs that are separated by ';', with the keys and values separated by '='. It should contain values for the following keys: HostName  

</code> ,<code>DeviceId 

</code> , and<code>SharedAccessKey 

</code> . </p>

protocol - the communication protocol used (i.e. HTTPS)
clientOptions - The options that allow configuration of the device client instance during initialization

Throws:

IllegalArgumentException -

if any ofconnectionString  

</code> or <code>protocol 

</code> are<code>null 

</code> ; or if<code>connectionString 

</code> is missing one of the following attributes:<code>HostName 

</code> ,<code>DeviceId 

</code> , or <code>SharedAccessKey 

</code> or if the IoT hub hostname does not conform to RFC 3986 or if the provided<code>connectionString 

</code> is for an x509 authenticated device </p>

DeviceClient

public DeviceClient(String hostName, String deviceId, SasTokenProvider sasTokenProvider, IotHubClientProtocol protocol)

Constructor that allows for the client's SAS token generation to be controlled by the user. Note that options in this client such as setting the SAS token expiry time will throw UnsupportedOperationException since the SDK no longer controls that when this constructor is used.

Parameters:

hostName - The host name of the IoT Hub that this client will connect to.
deviceId - The Id of the device that the connection will identify as.
sasTokenProvider - The provider of all SAS tokens that are used during authentication.
protocol - The protocol that the client will connect over.

DeviceClient

public DeviceClient(String hostName, String deviceId, SasTokenProvider sasTokenProvider, IotHubClientProtocol protocol, ClientOptions clientOptions)

Constructor that allows for the client's SAS token generation to be controlled by the user. Note that options in this client such as setting the SAS token expiry time will throw UnsupportedOperationException since the SDK no longer controls that when this constructor is used.

Parameters:

hostName - The host name of the IoT Hub that this client will connect to.
deviceId - The Id of the device that the connection will identify as.
sasTokenProvider - The provider of all SAS tokens that are used during authentication.
protocol - The protocol that the client will connect over.
clientOptions - The options that allow configuration of the device client instance during initialization.

DeviceClient

public DeviceClient(String uri, String deviceId, SecurityProvider securityProvider, IotHubClientProtocol protocol)

Creates a device client that uses the provided security provider for authentication.

Parameters:

uri - The hostname of the iot hub to connect to (format: "yourHubName.azure-devices.net")
deviceId - The id for the device to use
securityProvider - The security provider for the device
protocol - The protocol the device shall use for communication to the IoT Hub

Throws:

IOException - If the SecurityProvider throws any exception while authenticating

DeviceClient

public DeviceClient(String uri, String deviceId, SecurityProvider securityProvider, IotHubClientProtocol protocol, ClientOptions clientOptions)

Creates a device client that uses the provided security provider for authentication.

Parameters:

uri - The hostname of the iot hub to connect to (format: "yourHubName.azure-devices.net")
deviceId - The id for the device to use
securityProvider - The security provider for the device
protocol - The protocol the device shall use for communication to the IoT Hub
clientOptions - The options that allow configuration of the device client instance during initialization

Throws:

IOException - If the SecurityProvider throws any exception while authenticating

Method Details

close

public void close()

Closes the IoT hub client by releasing any resources held by client. When close is called all the messages that were in transit or pending to be sent will be informed to the user in the callbacks and any existing connection to IotHub will be closed. Must be called to terminate the background thread that is sending data to IoT hub. After close is called, the IoT hub client must be opened again before it can be used again. If the client is already closed, the function shall do nothing.

Throws:

UnsupportedOperationException - if called on a device that is multiplexed.

completeFileUpload

public void completeFileUpload(FileUploadCompletionNotification notification)

Notify IoT hub that a file upload has been completed, successfully or otherwise. See this documentation for more details.

Parameters:

notification - The notification details, including if the file upload succeeded.

Throws:

IotHubClientException - If this HTTPS request fails to send or if the service rejects the request for any reason.

getFileUploadSasUri

public FileUploadSasUriResponse getFileUploadSasUri(FileUploadSasUriRequest request)

Get a file upload SAS URI which the Azure Storage SDK can use to upload a file to blob for this device. See this documentation for more details.

Parameters:

request - The request details for getting the SAS URI, including the destination blob name.

Returns:

The file upload details to be used with the Azure Storage SDK in order to upload a file from this device.

Throws:

IotHubClientException - If this HTTPS request fails to send or if the service rejects the request for any reason.

isMultiplexed

public boolean isMultiplexed()

Returns if this client is or ever was registered to a MultiplexingClient instance. Device clients that were cannot be used in non-multiplexed connections. Device clients that aren't registered to any multiplexing client will still return true.

Returns:

true if this client is or ever was registered to a MultiplexingClient instance, false otherwise.

open

public void open(boolean withRetry)

Starts asynchronously sending and receiving messages from an IoT hub. If the client is already open, the function shall do nothing.

Parameters:

withRetry - if true, this open call will apply the retry policy to allow for the open call to be retried if it fails. Both the operation timeout set in setOperationTimeout(long timeout) and the retry policy set in {setRetryPolicy(RetryPolicy retryPolicy)} will be respected while retrying to open the connection.

Throws:

IotHubClientException - if a connection to an IoT hub cannot be established or if the connection can be established but the service rejects it for any reason.

setMessageCallback

public DeviceClient setMessageCallback(MessageCallback callback, Object context)

Sets the message callback.

Parameters:

callback -

the message callback. Can benull  

</code> . </p>

context -

the context to be passed to the callback. Can benull  

</code> .</p>

Returns:

itself, for fluent setting.

Throws:

IllegalArgumentException -

if the callback isnull  

</code> but a context is passed in. </p>

Applies to