DeviceClient Class

Definition

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.

public class DeviceClient
Inheritance
java.lang.Object
Closeable
DeviceClient

Constructors

DeviceClient()
DeviceClient(String connString, IotHubClientProtocol protocol)

Constructor that takes a connection string as an argument.

DeviceClient(String connString, IotHubClientProtocol protocol, String publicKeyCertificate, boolean isCertificatePath, String privateKey, boolean isPrivateKeyPath)

Constructor that uses x509 authentication for communicating with IotHub

DeviceClient(String connString, TransportClient transportClient)

Constructor that takes a connection string and a transport client as an argument.

Fields

CONNECTION_STRING_CHARSET

Deprecated

as of release 1.2.27 this value is deprecated and will not be replaced. The charset used for URL-encoding the device ID in the connection string.

</xrefdescription>

DEVICE_ID_ATTRIBUTE

Deprecated

as of release 1.2.27 this value is deprecated and will not be replaced. The device ID attribute name in a connection string.

</xrefdescription>

HOSTNAME_ATTRIBUTE

Deprecated

as of release 1.2.27 this value is deprecated and will not be replaced. The hostname attribute name in a connection string.

</xrefdescription>

RECEIVE_PERIOD_MILLIS
RECEIVE_PERIOD_MILLIS_AMQPS

Deprecated

as of release 1.2.27 these value is deprecated and replaced by setOption(String, Object)SetMinimumPollingInterval to change it.

</xrefdescription>

The number of milliseconds the transport will wait between polling for messages.

RECEIVE_PERIOD_MILLIS_HTTPS
RECEIVE_PERIOD_MILLIS_MQTT
SEND_PERIOD_MILLIS

Deprecated

as of release 1.2.27 this value is deprecated and replaced by setOption(String, Object)SetSendInterval to change it.

</xrefdescription>

The number of milliseconds the transport will wait between sending out messages.

SHARED_ACCESS_KEY_ATTRIBUTE

Deprecated

as of release 1.2.27 this value is deprecated and will not be replaced. The shared access key attribute name in a connection string.

</xrefdescription>

SHARED_ACCESS_TOKEN_ATTRIBUTE

Deprecated

as of release 1.2.27 this value is deprecated and will not be replaced. The shared access signature attribute name in a connection string.

</xrefdescription>

Methods

close()

Completes all current outstanding requests and closes the IoT Hub client. Must be called to terminate the background thread that is sending data to IoT Hub. AftercloseNow() is called, the IoT Hub client is no longer usable. If the client is already closed, the function shall do nothing. Deprecated

: As of release 1.1.25 this call is replaced by closeNow()

closeNow()

Closes the IoT Hub client by releasing any resources held by client. When closeNow 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. AftercloseNow() is called, the IoT Hub client is no longer usable. If the client is already closed, the function shall do nothing.

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

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

getConfig()

Getter for the device client config.

getDeviceTwin()
getProductInfo()
open()

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

registerConnectionStateCallback(IotHubConnectionStateCallback callback, Object callbackContext)

Registers a callback to be executed whenever the connection to the device is lost or established. Deprecated

as of release 1.10.0 by registerConnectionStatusChangeCallback(IotHubConnectionStatusChangeCallback callback, Object callbackContext)

registerConnectionStatusChangeCallback(IotHubConnectionStatusChangeCallback callback, Object callbackContext)

Registers a callback to be executed when the connection status of the device changes. The callback will be fired with a status and a reason why the device's status changed. When the callback is fired, the provided context will be provided alongside the status and reason.

sendEventAsync(Message message, IotHubEventCallback callback, Object callbackContext)

Asynchronously sends an event message to the IoT Hub.

sendReportedProperties(Set<Property> reportedProperties)

Sends reported properties

sendReportedProperties(Set<Property> reportedProperties, int version)

Sends reported properties

setMessageCallback(MessageCallback callback, Object context)

Sets the message callback.

setOperationTimeout(long timeout)

Set the length of time, in milliseconds, that any given operation will expire in. These operations include reconnecting upon a connection drop and sending a message.

setOption(String optionName, Object value)

Sets a runtime option identified by parameteroptionName tovalue .

The options that can be set via this API are:

  • SetMinimumPollingInterval - this option is applicable only when the transport configured with this client is HTTP. This option specifies the interval in milliseconds between calls to the service checking for availability of new messages. The value is expected to be of typelong .

  • SetCertificatePath - this option is applicable only when the transport configured with this client is AMQP. This option specifies the path to the certificate used to verify peer. The value is expected to be of typeString .

  • SetSASTokenExpiryTime - this option is applicable for HTTP/ AMQP/MQTT. This option specifies the interval in seconds after which SASToken expires. If the transport is already open then setting this option will restart the transport with the updated expiry time. The value is expected to be of typelong .

setRetryPolicy(RetryPolicy retryPolicy)

Sets the given retry policy on the underlying transport See more details about the default retry policy and about using custom retry policies here

startDeviceTwin(IotHubEventCallback deviceTwinStatusCallback, Object deviceTwinStatusCallbackContext, PropertyCallBack genericPropertyCallBack, Object genericPropertyCallBackContext)

Starts the device twin.

startDeviceTwin(IotHubEventCallback deviceTwinStatusCallback, Object deviceTwinStatusCallbackContext, TwinPropertyCallBack genericPropertyCallBack, Object genericPropertyCallBackContext)

Starts the device twin.

subscribeToDesiredProperties(Map<Property, Pair<PropertyCallBack<String, Object>, Object>> onDesiredPropertyChange)

Subscribes to desired properties

subscribeToDeviceMethod(DeviceMethodCallback deviceMethodCallback, Object deviceMethodCallbackContext, IotHubEventCallback deviceMethodStatusCallback, Object deviceMethodStatusCallbackContext)

Subscribes to device methods

subscribeToTwinDesiredProperties(Map<Property, Pair<TwinPropertyCallBack, Object>> onDesiredPropertyChange)

Subscribes to desired properties

uploadToBlobAsync(String destinationBlobName, InputStream inputStream, long streamLength, IotHubEventCallback callback, Object callbackContext)

Asynchronously upload a stream to the IoT Hub.