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>
Throws:
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:
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>
Throws:
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:
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:
DeviceClient
public DeviceClient(String uri, String deviceId, SecurityProvider securityProvider, IotHubClientProtocol protocol)
Creates a device client that uses the provided security provider for authentication.
Parameters:
Throws:
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:
Throws:
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:
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:
Throws:
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:
Returns:
Throws:
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:
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:
Throws:
setMessageCallback
public DeviceClient setMessageCallback(MessageCallback callback, Object context)
Sets the message callback.
Parameters:
the message callback. Can benull
</code> . </p>
the context to be passed to the callback. Can benull
</code> .</p>
Returns:
Throws:
if the callback isnull
</code> but a context is passed in. </p>
Applies to
Azure SDK for Java