DeviceClient Class

Package:

com.microsoft.azure.sdk.iot.device

Maven Artifact:

com.microsoft.azure.sdk.iot:iot-device-client:1.30.1

• java.lang.Object
• • com.microsoft.azure.sdk.iot.device.InternalClient
  • • com.microsoft.azure.sdk.iot.device.DeviceClient

Implements

java.io.Closeable

public final class DeviceClient
extends InternalClient
implements java.io.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.

Field Summary

Modifier and Type	Field and Description
static final java.nio.charset.Charset	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.
static final java.lang.String	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.
static final java.lang.String	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.
protected long	RECEIVE_PERIOD_MILLIS
static long	RECEIVE_PERIOD_MILLIS_AMQPS Deprecated as of release 1.2.27 these value is deprecated and replaced by setOption(String optionName, Object value) SetMinimumPollingInterval to change it. 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 Deprecated as of release 1.2.27 this value is deprecated and replaced by setOption(String optionName, Object value) SetSendInterval to change it. The number of milliseconds the transport will wait between sending out messages.
static final java.lang.String	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.
static final java.lang.String	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.

Constructor Summary

Modifier	Constructor	Description
protected	DeviceClient()
	DeviceClient(String connString, IotHubClientProtocol protocol)	Constructor that takes a connection string as an argument.
	DeviceClient(String connString, IotHubClientProtocol protocol, ClientOptions clientOptions)	Constructor that takes a connection string as an argument.
	DeviceClient(String connString, IotHubClientProtocol protocol, String publicKeyCertificate, boolean isCertificatePath, String privateKey, boolean isPrivateKeyPath)	Deprecated For x509 authentication, use DeviceClient(String connString, IotHubClientProtocol protocol, ClientOptions clientOptions) and provide an SSLContext instance in the ClientOptions instance. For a sample on how to build this SSLContext, see this code which references a helper class for building SSLContext objects for x509 authentication as well as for SAS based authentication. When not using this deprecated constructor, you can safely exclude the Bouncycastle dependencies that this library declares. See this pom.xml for an example of how to do this. Constructor that uses x509 authentication for communicating with IotHub
	DeviceClient(String connString, IotHubClientProtocol protocol, SSLContext sslContext)	Deprecated For x509 authentication, use DeviceClient(String connString, IotHubClientProtocol protocol, ClientOptions clientOptions) and provide an SSLContext instance in the ClientOptions instance. For a sample on how to build this SSLContext, see this code which references a helper class for building SSLContext objects for x509 authentication as well as for SAS based authentication. When not using this deprecated constructor, you can safely exclude the Bouncycastle dependencies that this library declares. See this pom.xml for an example of how to do this. Creates a device client that uses the provided SSLContext for SSL negotiation
	DeviceClient(String connString, TransportClient transportClient)	Deprecated MultiplexingClient should be used instead of TransportClient for creating all multiplexed connections. Constructor that takes a connection string and a transport client 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.
	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.

Method Summary

Modifier and Type	Method and Description
void	<Type1,Type2>startDeviceTwin(IotHubEventCallback deviceTwinStatusCallback, Object deviceTwinStatusCallbackContext, DeviceTwin.PropertyCallBack<Type1,Type2> genericPropertyCallBack, Object genericPropertyCallBackContext) Starts the device twin.
void	close() Deprecated : As of release 1.1.25 this call is replaced by closeNow() Completes all current outstanding requests and closes the IoT Hub client.
void	closeNow() 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.
void	completeFileUploadAsync(FileUploadCompletionNotification notification) Deprecated This function is not actually async, so use completeFileUpload(FileUploadCompletionNotification notification) to avoid confusion Notify IoT Hub that a file upload has been completed, successfully or otherwise.
static DeviceClient	createFromSecurityProvider(String uri, String deviceId, SecurityProvider securityProvider, IotHubClientProtocol protocol) Creates a device client that uses the provided security provider for authentication.
static DeviceClient	createFromSecurityProvider(String uri, String deviceId, SecurityProvider securityProvider, IotHubClientProtocol protocol, ClientOptions clientOptions) Creates a device client that uses the provided security provider for authentication.
void	getDeviceTwin() Retrieves the twin's latest desired properties
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.
void	open() Starts asynchronously sending and receiving messages from an IoT Hub.
void	registerConnectionStateCallback(IotHubConnectionStateCallback callback, Object callbackContext) Deprecated as of release 1.10.0 by #registerConnectionStatusChangeCallback(IotHubConnectionStatusChangeCallback callback, Object callbackContext) Registers a callback to be executed whenever the connection to the device is lost or established.
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.
void	startDeviceTwin(IotHubEventCallback deviceTwinStatusCallback, Object deviceTwinStatusCallbackContext, DeviceTwin.TwinPropertiesCallback genericPropertiesCallBack, Object genericPropertyCallBackContext) Starts the device twin.
void	startDeviceTwin(IotHubEventCallback deviceTwinStatusCallback, Object deviceTwinStatusCallbackContext, DeviceTwin.TwinPropertyCallBack genericPropertyCallBack, Object genericPropertyCallBackContext) Starts the device twin.
void	subscribeToDeviceMethod(DeviceTwin.DeviceMethodCallback deviceMethodCallback, Object deviceMethodCallbackContext, IotHubEventCallback deviceMethodStatusCallback, Object deviceMethodStatusCallbackContext) Subscribes to device methods
void	uploadToBlobAsync(String destinationBlobName, InputStream inputStream, long streamLength, IotHubEventCallback callback, Object callbackContext) Deprecated Use getFileUploadSasUri(FileUploadSasUriRequest request) to get the SAS URI, use the azure storage SDK to upload a file to that SAS URI, and then use completeFileUpload(FileUploadCompletionNotification notification) to notify Iot Hub that your file upload has completed, successfully or otherwise. This method does all three of these tasks for you, but has limited configuration options. Asynchronously upload a stream to the IoT Hub.

Methods inherited from InternalClient

close closeNow getConfig getProductInfo isMultiplexed open registerConnectionStatusChangeCallback sendEventAsync sendEventBatchAsync sendReportedProperties sendReportedProperties sendReportedProperties sendReportedProperties setAsMultiplexed setOperationTimeout setOption setProxySettings setRetryPolicy subscribeToDesiredProperties subscribeToTwinDesiredProperties

Methods inherited from java.lang.Object

java.lang.Object.clone java.lang.Object.equals java.lang.Object.finalize java.lang.Object.getClass java.lang.Object.hashCode java.lang.Object.notify java.lang.Object.notifyAll java.lang.Object.toString java.lang.Object.wait java.lang.Object.wait java.lang.Object.wait

Field Details

CONNECTION_STRING_CHARSET

public static final Charset 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.

DEVICE_ID_ATTRIBUTE

public static final String 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.

HOSTNAME_ATTRIBUTE

public static final String 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.

RECEIVE_PERIOD_MILLIS

protected long RECEIVE_PERIOD_MILLIS

RECEIVE_PERIOD_MILLIS_AMQPS

public static long RECEIVE_PERIOD_MILLIS_AMQPS

Deprecated

as of release 1.2.27 these value is deprecated and replaced by setOption(String optionName, Object value) SetMinimumPollingInterval to change it. The number of milliseconds the transport will wait between polling for messages.

RECEIVE_PERIOD_MILLIS_HTTPS

public static long RECEIVE_PERIOD_MILLIS_HTTPS

RECEIVE_PERIOD_MILLIS_MQTT

public static long RECEIVE_PERIOD_MILLIS_MQTT

SEND_PERIOD_MILLIS

public static long SEND_PERIOD_MILLIS

Deprecated

as of release 1.2.27 this value is deprecated and replaced by setOption(String optionName, Object value) SetSendInterval to change it. The number of milliseconds the transport will wait between sending out messages.

SHARED_ACCESS_KEY_ATTRIBUTE

public static final String 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.

SHARED_ACCESS_TOKEN_ATTRIBUTE

public static final String 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.

Constructor Details

DeviceClient

protected DeviceClient()

DeviceClient

public DeviceClient(String connString, IotHubClientProtocol protocol)

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:

java.net.URISyntaxException - if any of connString or protocol are null; or if connString 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 connString is for an x509 authenticated device

java.lang.IllegalArgumentException - if any of connString or protocol are null; or if connString 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 connString is for an x509 authenticated device

DeviceClient

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

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)

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

Throws:

java.net.URISyntaxException - if any of connString or protocol are null; or if connString 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 connString is for an x509 authenticated device

java.lang.IllegalArgumentException - if any of connString or protocol are null; or if connString 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 connString is for an x509 authenticated device

DeviceClient

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

Deprecated

For x509 authentication, use DeviceClient(String connString, IotHubClientProtocol protocol, ClientOptions clientOptions) and provide an SSLContext instance in the ClientOptions instance. For a sample on how to build this SSLContext, see this code which references a helper class for building SSLContext objects for x509 authentication as well as for SAS based authentication. When not using this deprecated constructor, you can safely exclude the Bouncycastle dependencies that this library declares. See this pom.xml for an example of how to do this.

Constructor that uses x509 authentication for communicating with IotHub

Parameters:

connString - the connection string for the x509 device to connect as (format: "HostName=...;DeviceId=...;x509=true")

protocol - the protocol to use when communicating with IotHub

publicKeyCertificate - the PEM formatted public key certificate or the path to a PEM formatted public key certificate file. Append if there is any intermediate or chained certificates to the end of the public certificate file in the following format: -----BEGIN CERTIFICATE----- (Primary SSL certificate) -----END CERTIFICATE----- ----BEGIN CERTIFICATE----- (Intermediate certificate) -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- (Root certificate) -----END CERTIFICATE-----

isCertificatePath - if the provided publicKeyCertificate is a path to a file containing the PEM formatted public key certificate

privateKey - the PEM formatted private key or the path to a PEM formatted private key file

isPrivateKeyPath - if the provided privateKey is a path to a file containing the PEM formatted private key

Throws:

java.net.URISyntaxException - if the hostname in the connection string is not a valid URI

DeviceClient

public DeviceClient(String connString, IotHubClientProtocol protocol, SSLContext sslContext)

Deprecated

For x509 authentication, use DeviceClient(String connString, IotHubClientProtocol protocol, ClientOptions clientOptions) and provide an SSLContext instance in the ClientOptions instance. For a sample on how to build this SSLContext, see this code which references a helper class for building SSLContext objects for x509 authentication as well as for SAS based authentication. When not using this deprecated constructor, you can safely exclude the Bouncycastle dependencies that this library declares. See this pom.xml for an example of how to do this.

Creates a device client that uses the provided SSLContext for SSL negotiation

Parameters:

connString - the connection string for the device. May be an x509 connection string (format: "HostName=...;DeviceId=...;x509=true") and it may be a SAS connection string (format: "HostName=...;DeviceId=...;SharedAccessKey=..."). If this connection string is an x509 connection string, the client will use the provided SSLContext for authentication.

protocol - the protocol to use when communicating with IotHub

sslContext - the ssl context that will be used during authentication. If the provided connection string does not contain SAS based credentials, then the sslContext will be used for x509 authentication. If the provided connection string does contain SAS based credentials, the sslContext will still be used during SSL negotiation.

Throws:

java.net.URISyntaxException - if the hostname in the connection string is not a valid URI

DeviceClient

public DeviceClient(String connString, TransportClient transportClient)

Deprecated

MultiplexingClient should be used instead of TransportClient for creating all multiplexed connections.

Constructor that takes a connection string and a transport client 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.

transportClient - the transport client to use by the device client.

Throws:

java.net.URISyntaxException - if connString or if connString 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 connString is for an x509 authenticated device

java.lang.IllegalArgumentException - if connString or if connString 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 connString is for an x509 authenticated device

java.lang.UnsupportedOperationException - if connString or if connString 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 connString is for an x509 authenticated device

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.

Method Details

<Type1,Type2>startDeviceTwin

public void startDeviceTwin(IotHubEventCallback deviceTwinStatusCallback, Object deviceTwinStatusCallbackContext, DeviceTwin.PropertyCallBack genericPropertyCallBack, Object genericPropertyCallBackContext)

Starts the device twin. This device client will receive a callback with the current state of the full twin, including reported properties and desired properties. After that callback is received, this device client will receive a callback each time a desired property is updated. That callback will either contain the full desired properties set, or only the updated desired property depending on how the desired property was changed. IoT Hub supports a PUT and a PATCH on the twin. The PUT will cause this device client to receive the full desired properties set, and the PATCH will cause this device client to only receive the updated desired properties. Similarly, the version of each desired property will be incremented from a PUT call, and only the actually updated desired property will have its version incremented from a PATCH call. The java service client library uses the PATCH call when updated desired properties, but it builds the patch such that all properties are included in the patch. As a result, the device side will receive full twin updates, not partial updates. See PUT and PATCH

Parameters:

deviceTwinStatusCallback - the IotHubEventCallback callback for providing the status of Device Twin operations. Cannot be null.

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

genericPropertyCallBack - the PropertyCallBack callback for providing any changes in desired properties. Cannot be null.

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

Throws:

java.io.IOException - if the callback is null

java.lang.IllegalArgumentException - if the callback is null

java.lang.UnsupportedOperationException - if the callback is null

close

public void close()

Deprecated

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

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

Overrides:

DeviceClient.close()

Throws:

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

closeNow

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

Overrides:

DeviceClient.closeNow()

Throws:

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

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:

java.io.IOException - If this HTTPS request fails to send.

completeFileUploadAsync

public void completeFileUploadAsync(FileUploadCompletionNotification notification)

Deprecated

This function is not actually async, so use completeFileUpload(FileUploadCompletionNotification notification) to avoid confusion

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:

java.io.IOException - If this HTTPS request fails to send.

createFromSecurityProvider

public static DeviceClient createFromSecurityProvider(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

Returns:

The created device client instance

Throws:

java.net.URISyntaxException - If the provided connString could not be parsed.

java.io.IOException - If the provided connString could not be parsed.

createFromSecurityProvider

public static DeviceClient createFromSecurityProvider(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

Returns:

The created device client instance

Throws:

java.net.URISyntaxException - If the provided connString could not be parsed.

java.io.IOException - If the provided connString could not be parsed.

getDeviceTwin

public void getDeviceTwin()

Retrieves the twin's latest desired properties

Throws:

java.io.IOException - if the iothub cannot be reached

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:

java.io.IOException - If this HTTPS request fails to send.

java.net.URISyntaxException - If this HTTPS request fails to send.

open

public void open()

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

Overrides:

DeviceClient.open()

Throws:

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

registerConnectionStateCallback

public void registerConnectionStateCallback(IotHubConnectionStateCallback callback, Object callbackContext)

Deprecated

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

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

Parameters:

callback - the callback to be called.

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

Throws:

java.lang.IllegalArgumentException - if the provided callback is null

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:

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

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. - SetSendInterval - this option is applicable to all protocols. This value sets the period (in milliseconds) that this SDK spawns threads to send queued messages. Even if no message is queued, this thread will be spawned. - SetReceiveInterval - this option is applicable to all protocols in case of HTTPS protocol, this option acts the same as SetMinimumPollingInterval in case of MQTT and AMQP protocols, this option specifies the interval in milliseconds between spawning a thread that dequeues a message from the SDK's queue of received messages. - 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, and will use that expiry time length for all subsequently generated sas tokens. The value is expected to be of type long. - SetHttpsReadTimeout - this option is applicable for HTTPS. This option specifies the read timeout in milliseconds per https request made by this client. By default, this value is 4 minutes. The value is expected to be of type int. - SetHttpsConnectTimeout - this option is applicable for HTTPS. This option specifies the connect timeout in milliseconds per https request made by this client. By default, this value is 0 (no connect timeout). The value is expected to be of type int. - SetAmqpOpenAuthenticationSessionTimeout - this option is applicable for AMQP with SAS token authentication. This option specifies the timeout in seconds to wait to open the authentication session. By default, this value is 20 seconds. The value is expected to be of type int. - SetAmqpOpenDeviceSessionsTimeout - this option is applicable for AMQP. This option specifies the timeout in seconds to open the device sessions. By default, this value is 60 seconds. The value is expected to be of type int.

Overrides:

DeviceClient.setOption(String optionName, Object value)

Parameters:

optionName - the option name to modify

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

Throws:

java.lang.IllegalArgumentException - if the provided optionName is null

startDeviceTwin

public void startDeviceTwin(IotHubEventCallback deviceTwinStatusCallback, Object deviceTwinStatusCallbackContext, DeviceTwin.TwinPropertiesCallback genericPropertiesCallBack, Object genericPropertyCallBackContext)

Starts the device twin. This device client will receive a callback with the current state of the full twin, including reported properties and desired properties. After that callback is received, this device client will receive a callback each time a desired property is updated. That callback will either contain the full desired properties set, or only the updated desired property depending on how the desired property was changed. IoT Hub supports a PUT and a PATCH on the twin. The PUT will cause this device client to receive the full desired properties set, and the PATCH will cause this device client to only receive the updated desired properties. Similarly, the version of each desired property will be incremented from a PUT call, and only the actually updated desired property will have its version incremented from a PATCH call. The java service client library uses the PATCH call when updated desired properties, but it builds the patch such that all properties are included in the patch. As a result, the device side will receive full twin updates, not partial updates. See PUT and PATCH

Parameters:

deviceTwinStatusCallback - the IotHubEventCallback callback for providing the status of Device Twin operations. Cannot be null.

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

genericPropertiesCallBack - the TwinPropertyCallBack callback for providing any changes in desired properties. Cannot be null.

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

Throws:

java.io.IOException - if the callback is null

java.lang.IllegalArgumentException - if the callback is null

java.lang.UnsupportedOperationException - if the callback is null

startDeviceTwin

public void startDeviceTwin(IotHubEventCallback deviceTwinStatusCallback, Object deviceTwinStatusCallbackContext, DeviceTwin.TwinPropertyCallBack genericPropertyCallBack, Object genericPropertyCallBackContext)

Starts the device twin. This device client will receive a callback with the current state of the full twin, including reported properties and desired properties. After that callback is received, this device client will receive a callback each time a desired property is updated. That callback will either contain the full desired properties set, or only the updated desired property depending on how the desired property was changed. IoT Hub supports a PUT and a PATCH on the twin. The PUT will cause this device client to receive the full desired properties set, and the PATCH will cause this device client to only receive the updated desired properties. Similarly, the version of each desired property will be incremented from a PUT call, and only the actually updated desired property will have its version incremented from a PATCH call. The java service client library uses the PATCH call when updated desired properties, but it builds the patch such that all properties are included in the patch. As a result, the device side will receive full twin updates, not partial updates. See PUT and PATCH

Parameters:

deviceTwinStatusCallback - the IotHubEventCallback callback for providing the status of Device Twin operations. Cannot be null.

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

genericPropertyCallBack - the TwinPropertyCallBack callback for providing any changes in desired properties. Cannot be null.

genericPropertyCallBackContext - the context to be passed to the property callback. Can be null. *

Throws:

java.io.IOException - if the callback is null

java.lang.IllegalArgumentException - if the callback is null

java.lang.UnsupportedOperationException - if the callback is null

subscribeToDeviceMethod

public void subscribeToDeviceMethod(DeviceTwin.DeviceMethodCallback deviceMethodCallback, Object deviceMethodCallbackContext, IotHubEventCallback deviceMethodStatusCallback, Object deviceMethodStatusCallbackContext)

Subscribes to device methods

Parameters:

deviceMethodCallback - Callback on which device methods shall be invoked. Cannot be null.

deviceMethodCallbackContext - Context for device method callback. Can be null.

deviceMethodStatusCallback - Callback for providing IotHub status for device methods. Cannot be null.

deviceMethodStatusCallbackContext - Context for device method status callback. Can be null.

Throws:

java.io.IOException - if called when client is not opened.

java.lang.IllegalArgumentException - if called when client is not opened.

uploadToBlobAsync

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

Deprecated

Use getFileUploadSasUri(FileUploadSasUriRequest request) to get the SAS URI, use the azure storage SDK to upload a file to that SAS URI, and then use completeFileUpload(FileUploadCompletionNotification notification) to notify Iot Hub that your file upload has completed, successfully or otherwise. This method does all three of these tasks for you, but has limited configuration options.

Asynchronously upload a stream to the IoT Hub. NOTE: IotHub does not currently support CA signed devices using file upload. Please use SAS based authentication or self signed certificates.

Parameters:

destinationBlobName - is a string with the name of the file in the storage.

inputStream - is a InputStream with the stream to upload in the blob.

streamLength - is a long with the number of bytes in the stream to upload.

callback - the callback to be invoked when a file is uploaded.

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

Throws:

java.lang.IllegalArgumentException - if the provided blob name, or the file path is null, empty or not valid, or if the callback is null.

java.io.IOException - if the provided blob name, or the file path is null, empty or not valid, or if the callback is null.