DeviceClient Class
- java.
lang. Object - InternalClient
- com.
microsoft. azure. sdk. iot. device. DeviceClient
- com.
public 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 HTTPS 1.1 and AMQPS 1.0 transports.
Constructor Summary
| Constructor | Description |
|---|---|
| DeviceClient(String connectionString, IotHubClientProtocol protocol) |
Constructor that takes a connection string as an argument. |
| DeviceClient(String connectionString, IotHubClientProtocol protocol, ClientOptions clientOptions) |
Constructor that takes a connection string 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. 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. |
| 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. |
| DeviceClient(String uri, String deviceId, SecurityProvider securityProvider, IotHubClientProtocol protocol) |
Creates a device client that uses the provided security provider for authentication. |
| DeviceClient(String uri, String deviceId, 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. 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. |
| void |
completeFileUpload(FileUploadCompletionNotification notification)
Notify IoT hub that a file upload has been completed, successfully or otherwise. See this documentation for more details. |
|
File |
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. |
| 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. |
| void |
open(boolean withRetry)
Starts asynchronously sending and receiving messages from an IoT hub. If the client is already open, the function shall do nothing. |
|
Device |
setMessageCallback(MessageCallback callback, Object context)
Sets the message callback. |
Inherited Members
Constructor Details
DeviceClient
public DeviceClient(String connectionString, IotHubClientProtocol protocol)
Constructor that takes a connection string as an argument.
Parameters:
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
</code> ,<code>DeviceId
</code> , and<code>SharedAccessKey
</code> . </p>
protocol
- the communication protocol used (i.e. HTTPS).
Throws:
IllegalArgumentException
- if any ofconnectionString
</code> or <code>protocol
</code> are<code>null
</code> ; or if<code>connectionString
</code> is missing one of the following attributes:<code>HostName
</code> ,<code>DeviceId
</code> , or <code>SharedAccessKey
</code> or if the IoT hub hostname does not conform to RFC 3986 or if the provided<code>connectionString
</code> is for an x509 authenticated device </p>
DeviceClient
public DeviceClient(String connectionString, IotHubClientProtocol protocol, ClientOptions clientOptions)
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
</code> ,<code>DeviceId
</code> , and<code>SharedAccessKey
</code> . </p>
protocol
- the communication protocol used (i.e. HTTPS)
clientOptions
- The options that allow configuration of the device client instance during initialization
Throws:
IllegalArgumentException
- if any ofconnectionString
</code> or <code>protocol
</code> are<code>null
</code> ; or if<code>connectionString
</code> is missing one of the following attributes:<code>HostName
</code> ,<code>DeviceId
</code> , or <code>SharedAccessKey
</code> or if the IoT hub hostname does not conform to RFC 3986 or if the provided<code>connectionString
</code> is for an x509 authenticated device </p>
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.
DeviceClient
public DeviceClient(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
Throws:
IOException
- If the SecurityProvider throws any exception while authenticating
DeviceClient
public DeviceClient(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
Throws:
IOException
- If the SecurityProvider throws any exception while authenticating
Method Details
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.
Throws:
UnsupportedOperationException
- if called on a device that is multiplexed.
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:
IotHubClientException
- If this HTTPS request fails to send or if the service rejects the request for any reason.
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:
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.
open
public void open(boolean withRetry)
Starts asynchronously sending and receiving messages from an IoT hub. If the client is already open, the function shall do nothing.
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 setOperationTimeout(long timeout) and the retry policy set in {setRetryPolicy(RetryPolicy 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.
setMessageCallback
public DeviceClient setMessageCallback(MessageCallback callback, Object context)
Sets the message callback.
Parameters:
callback
- the message callback. Can benull
</code> . </p>
context
- the context to be passed to the callback. Can benull
</code> .</p>
Returns:
itself, for fluent setting.
Throws:
IllegalArgumentException
- if the callback isnull
</code> but a context is passed in. </p>
Applies to
Azure SDK for Java