com.microsoft.azure.sdk.iot.device

Class DeviceClient

java.lang.Object

com.microsoft.azure.sdk.iot.device.InternalClient

com.microsoft.azure.sdk.iot.device.DeviceClient

public final 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 MQTT 3.1.1, HTTPS 1.1 and AMQPS 1.0 transports.

Field Summary

Fields inherited from class com.microsoft.azure.sdk.iot.device.InternalClient

DEFAULT_TIMEOUT_MILLISECONDS

Constructor Summary

Constructors

Constructor and Description
DeviceClient(java.lang.String connectionString, IotHubClientProtocol protocol) Constructor that takes a connection string as an argument.
DeviceClient(java.lang.String connectionString, IotHubClientProtocol protocol, ClientOptions clientOptions) Constructor that takes a connection string as an argument.
DeviceClient(java.lang.String hostName, java.lang.String deviceId, SasTokenProvider sasTokenProvider, IotHubClientProtocol protocol) Constructor that allows for the client's SAS token generation to be controlled by the user.
DeviceClient(java.lang.String hostName, java.lang.String deviceId, SasTokenProvider sasTokenProvider, IotHubClientProtocol protocol, ClientOptions clientOptions) Constructor that allows for the client's SAS token generation to be controlled by the user.
DeviceClient(java.lang.String uri, java.lang.String deviceId, com.microsoft.azure.sdk.iot.provisioning.security.SecurityProvider securityProvider, IotHubClientProtocol protocol) Creates a device client that uses the provided security provider for authentication.
DeviceClient(java.lang.String uri, java.lang.String deviceId, com.microsoft.azure.sdk.iot.provisioning.security.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.
void	completeFileUpload(FileUploadCompletionNotification notification) Notify IoT hub that a file upload has been completed, successfully or otherwise.
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.
boolean	isMultiplexed() Returns if this client is or ever was registered to a MultiplexingClient instance.
void	open(boolean withRetry) Starts asynchronously sending and receiving messages from an IoT hub.
DeviceClient	setMessageCallback(MessageCallback callback, java.lang.Object context) Sets the message callback.

Methods inherited from class com.microsoft.azure.sdk.iot.device.InternalClient

getConfig, getProductInfo, getTwin, getTwin, getTwinAsync, getTwinAsync, sendEvent, sendEvent, sendEventAsync, sendEvents, sendEvents, sendEventsAsync, setConnectionStatusChangeCallback, setOperationTimeout, setRetryPolicy, subscribeToDesiredProperties, subscribeToDesiredProperties, subscribeToDesiredPropertiesAsync, subscribeToMethods, subscribeToMethods, subscribeToMethodsAsync, updateReportedProperties, updateReportedProperties, updateReportedPropertiesAsync, updateReportedPropertiesAsync

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DeviceClient

public DeviceClient(java.lang.String connectionString,
                    IotHubClientProtocol protocol)
             throws java.lang.IllegalArgumentException

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, DeviceId, and SharedAccessKey.

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

Throws:

java.lang.IllegalArgumentException - if any of connectionString or protocol are null; or if connectionString is missing one of the following attributes:HostName, DeviceId, or SharedAccessKey or if the IoT hub hostname does not conform to RFC 3986 or if the provided connectionString is for an x509 authenticated device

DeviceClient

public DeviceClient(java.lang.String connectionString,
                    IotHubClientProtocol protocol,
                    ClientOptions clientOptions)
             throws java.lang.IllegalArgumentException

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, DeviceId, and SharedAccessKey.

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

clientOptions - The options that allow configuration of the device client instance during initialization

Throws:

java.lang.IllegalArgumentException - if any of connectionString or protocol are null; or if connectionString is missing one of the following attributes:HostName, DeviceId, or SharedAccessKey or if the IoT hub hostname does not conform to RFC 3986 or if the provided connectionString is for an x509 authenticated device

DeviceClient

public DeviceClient(java.lang.String hostName,
                    java.lang.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(java.lang.String hostName,
                    java.lang.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(java.lang.String uri,
                    java.lang.String deviceId,
                    com.microsoft.azure.sdk.iot.provisioning.security.SecurityProvider securityProvider,
                    IotHubClientProtocol protocol)
             throws java.io.IOException

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:

java.io.IOException - If the SecurityProvider throws any exception while authenticating

DeviceClient

public DeviceClient(java.lang.String uri,
                    java.lang.String deviceId,
                    com.microsoft.azure.sdk.iot.provisioning.security.SecurityProvider securityProvider,
                    IotHubClientProtocol protocol,
                    ClientOptions clientOptions)
             throws java.io.IOException

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:

java.io.IOException - If the SecurityProvider throws any exception while authenticating

Method Detail

setMessageCallback

public DeviceClient setMessageCallback(MessageCallback callback,
                                       java.lang.Object context)
                                throws java.lang.IllegalArgumentException

Sets the message callback.

This should be set before opening the client. If it is set after opening the client, any messages sent by the service may be missed.

This callback is preserved between reconnection attempts and preserved after re-opening a previously closed client.

Parameters:

callback - the message callback. Can be null.

context - the context to be passed to the callback. Can be null.

Returns:

itself, for fluent setting.

Throws:

java.lang.IllegalArgumentException - if the callback is null but a context is passed in.

open

public void open(boolean withRetry)
          throws IotHubClientException

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

Overrides:

open in class InternalClient

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 InternalClient.setOperationTimeout(long) and the retry policy set in {InternalClient.setRetryPolicy(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.

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.

Overrides:

close in class InternalClient

Throws:

java.lang.UnsupportedOperationException - if called on a device that is multiplexed.

getFileUploadSasUri

public FileUploadSasUriResponse getFileUploadSasUri(FileUploadSasUriRequest request)
                                             throws IotHubClientException

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.

completeFileUpload

public void completeFileUpload(FileUploadCompletionNotification notification)
                        throws IotHubClientException

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.

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.