com.microsoft.azure.sdk.iot.device

Class DeviceClient

java.lang.Object

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

All Implemented Interfaces:

Closeable, AutoCloseable

public final class DeviceClient
extends Object
implements Closeable

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.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	DeviceClient.IotHubClientState The state of the IoT Hub client's connection with the IoT Hub.

Field Summary

Fields

Modifier and Type	Field and Description
protected DeviceClientConfig	config
static Charset	CONNECTION_STRING_CHARSET The charset used for URL-encoding the device ID in the connection string.
static String	DEVICE_ID_ATTRIBUTE The device ID attribute name in a connection string.
static String	HOSTNAME_ATTRIBUTE The hostname attribute name in a connection string.
protected long	RECEIVE_PERIOD_MILLIS
static long	RECEIVE_PERIOD_MILLIS_AMQPS The number of milliseconds the transport will wait between polling for messages.
static long	RECEIVE_PERIOD_MILLIS_HTTPS
static long	RECEIVE_PERIOD_MILLIS_MQTT
static long	SEND_PERIOD_MILLIS The number of milliseconds the transport will wait between sending out messages.
protected static String	SET_CERTIFICATE_PATH
protected static String	SET_MINIMUM_POLLING_INTERVAL
protected static String	SET_SAS_TOKEN_EXPIRY_TIME
static String	SHARED_ACCESS_KEY_ATTRIBUTE The shared access key attribute name in a connection string.
static String	SHARED_ACCESS_TOKEN_ATTRIBUTE The shared access signature attribute name in a connection string.
protected DeviceClient.IotHubClientState	state
protected ScheduledExecutorService	taskScheduler
protected IotHubTransport	transport

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	DeviceClient()
	DeviceClient(String connString, IotHubClientProtocol protocol) Constructor that takes a connection string as an argument.

Method Summary

Modifier and Type	Method and Description
void	close() Completes all current outstanding requests and closes the IoT Hub client.
protected void	initIotHubClient(String iotHubHostname, String deviceId, String deviceKey, String sharedAccessToken, IotHubClientProtocol protocol) Initializes an IoT Hub device client with the given parameters.
void	open() Starts asynchronously sending and receiving messages from an IoT Hub.
void	sendEventAsync(Message message, IotHubEventCallback callback, Object callbackContext) Asynchronously sends an event message to the IoT Hub.
DeviceClient	setMessageCallback(MessageCallback callback, Object context) Sets the message callback.
void	setOption(String optionName, Object value) Sets a runtime option identified by parameter optionName to value.

Methods inherited from class java.lang.Object

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

Field Detail

SET_MINIMUM_POLLING_INTERVAL

protected static final String SET_MINIMUM_POLLING_INTERVAL

See Also:

Constant Field Values

SET_CERTIFICATE_PATH

protected static final String SET_CERTIFICATE_PATH

See Also:

Constant Field Values

SET_SAS_TOKEN_EXPIRY_TIME

protected static final String SET_SAS_TOKEN_EXPIRY_TIME

See Also:

Constant Field Values

SEND_PERIOD_MILLIS

public static long SEND_PERIOD_MILLIS

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

RECEIVE_PERIOD_MILLIS_AMQPS

public static long RECEIVE_PERIOD_MILLIS_AMQPS

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

RECEIVE_PERIOD_MILLIS_MQTT

public static long RECEIVE_PERIOD_MILLIS_MQTT

RECEIVE_PERIOD_MILLIS_HTTPS

public static long RECEIVE_PERIOD_MILLIS_HTTPS

HOSTNAME_ATTRIBUTE

public static final String HOSTNAME_ATTRIBUTE

The hostname attribute name in a connection string.

See Also:

Constant Field Values

DEVICE_ID_ATTRIBUTE

public static final String DEVICE_ID_ATTRIBUTE

The device ID attribute name in a connection string.

See Also:

Constant Field Values

SHARED_ACCESS_KEY_ATTRIBUTE

public static final String SHARED_ACCESS_KEY_ATTRIBUTE

The shared access key attribute name in a connection string.

See Also:

Constant Field Values

SHARED_ACCESS_TOKEN_ATTRIBUTE

public static final String SHARED_ACCESS_TOKEN_ATTRIBUTE

The shared access signature attribute name in a connection string.

See Also:

Constant Field Values

CONNECTION_STRING_CHARSET

public static final Charset CONNECTION_STRING_CHARSET

The charset used for URL-encoding the device ID in the connection string.

config

protected DeviceClientConfig config

transport

protected IotHubTransport transport

taskScheduler

protected ScheduledExecutorService taskScheduler

state

protected DeviceClient.IotHubClientState state

RECEIVE_PERIOD_MILLIS

protected long RECEIVE_PERIOD_MILLIS

Constructor Detail

DeviceClient

public DeviceClient(String connString,
                    IotHubClientProtocol protocol)
             throws URISyntaxException

Constructor that takes a connection string as an argument.

Parameters:

connString - 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:

IllegalArgumentException - if any of connString or protocol are null; or if connString is missing one of the following attributes:HostName, DeviceId, or SharedAccessKey.

URISyntaxException - if the IoT hub hostname does not conform to RFC 3986.

DeviceClient

protected DeviceClient()

Method Detail

open

public void open()
          throws IOException

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

Throws:

IOException - if a connection to an IoT Hub is cannot be established.

close

public void close()
           throws IOException

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. After close() is called, the IoT Hub client is no longer usable. If the client is already closed, the function shall do nothing.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Throws:

IOException - if the connection to an IoT Hub cannot be closed.

sendEventAsync

public void sendEventAsync(Message message,
                           IotHubEventCallback callback,
                           Object callbackContext)

Asynchronously sends an event message to the IoT Hub.

Parameters:

message - the message to be sent.

callback - the callback to be invoked when a response is received. Can be null.

callbackContext - a context to be passed to the callback. Can be null if no callback is provided.

Throws:

IllegalArgumentException - if the message provided is null.

IllegalStateException - if the client has not been opened yet or is already closed.

setMessageCallback

public DeviceClient setMessageCallback(MessageCallback callback,
                                       Object context)

Sets the message callback.

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:

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

IllegalStateException - if the callback is set after the client is closed.

initIotHubClient

protected void initIotHubClient(String iotHubHostname,
                                String deviceId,
                                String deviceKey,
                                String sharedAccessToken,
                                IotHubClientProtocol protocol)
                         throws URISyntaxException

Initializes an IoT Hub device client with the given parameters.

Parameters:

iotHubHostname - the IoT Hub hostname.

deviceId - the device ID.

deviceKey - the device key.

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

Throws:

IllegalArgumentException - if any of iotHubHostname, deviceId, deviceKey, or protocol are null; or if iotHubHostname does not contain a valid IoT Hub name as its prefix.

URISyntaxException - if the IoT Hub hostname does not conform to RFC 3986.

setOption

public void setOption(String optionName,
                      Object value)

Sets a runtime option identified by parameter optionName to value. 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 type long. - 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 type String. - 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 type long.

Parameters:

optionName - the option name to modify

value - an object of the appropriate type for the option's value