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()
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.

sendEventAsync(Message message, IotHubEventCallback callback, Object callbackContext)

Asynchronously sends an event message to the IoT Hub.

sendReportedProperties(Set<Property> reportedProperties)

Sends reported properties

setMessageCallback(MessageCallback callback, Object context)

Sets the message callback.

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 .

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.