InternalClient Class

  • Reference
Package:
com.microsoft.azure.sdk.iot.device
  • java.lang.Object
    • com.microsoft.azure.sdk.iot.device.InternalClient

public class InternalClient

Field Summary

Modifier and Type Field and Description
final int DEFAULT_TIMEOUT_MILLISECONDS

Method Summary

Modifier and Type Method and Description
void close()

Close the client.

ClientConfiguration getConfig()

Getter for the device client config.
ProductInfo getProductInfo()
Twin getTwin()

Get the twin for this client. This client must have subscribed to desired properties before this method can be called.
Twin getTwin(int timeoutMilliseconds)

Get the twin for this client. This client must have subscribed to desired properties before this method can be called.
void getTwinAsync(GetTwinCallback twinCallback, Object callbackContext)

Get the twin for this client asynchronously. This client must have subscribed to desired properties before this method can be called.
void getTwinAsync(GetTwinCorrelatingMessageCallback twinCallback, Object callbackContext)

Get the twin for this client asynchronously. This client must have subscribed to desired properties before this method can be called.

This overload utilizes a more verbose callback than getTwinAsync(GetTwinCallback twinCallback, Object callbackContext) and is only intended for users who need insight on the state of this process every step of the way.

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.
void sendEvent(Message message)

Synchronously sends a message to IoT hub.
void sendEvent(Message message, int timeoutMilliseconds)

Synchronously sends a message to IoT hub.
void sendEventAsync(Message message, MessageSentCallback callback, Object callbackContext)

Asynchronously sends a message to IoT hub.
void sendEvents(List<Message> messages)

Synchronously sends a batch of messages to IoT hub

This operation is only supported over HTTPS.

Maximum payload size for HTTPS is 255KB
void sendEvents(List<Message> messages, int timeoutMilliseconds)

Synchronously sends a batch of messages to IoT hub

This operation is only supported over HTTPS.

Maximum payload size for HTTPS is 255KB
void sendEventsAsync(List<Message> messages, MessagesSentCallback callback, Object callbackContext)

Asynchronously sends a batch of messages to the IoT hub

This operation is only supported over HTTPS. This API call is an all-or-nothing single HTTPS message and the callback will be triggered once this batch message has been sent.

Maximum payload size for HTTPS is 255KB
void setConnectionStatusChangeCallback(IotHubConnectionStatusChangeCallback callback, Object callbackContext)

Sets the callback to be executed when the connection status of the device changes. The callback will be fired with a status and a reason why the device's status changed. When the callback is fired, the provided context will be provided alongside the status and reason.

This connection status callback is not triggered by any upstream connection change events. For example, if if the connection status callback is set for a module on an IoT Edge device and that IoT Edge device loses connection to the cloud, this connection status callback won't onStatusChanged since the connection between the module and the IoT Edge device hasn't changed.

Note that the thread used to deliver this callback should not be used to call open()/closeNow() on the client that this callback belongs to. All open()/close() operations should be done on a separate thread
void setOperationTimeout(long timeout)

Set the length of time, in milliseconds, that any given operation will expire in. These operations include reconnecting upon a connection drop and sending a message.

void setRetryPolicy(RetryPolicy retryPolicy)

Sets the given retry policy on the underlying transport See more details about the default retry policy and about using custom retry policies here
void subscribeToDesiredProperties(DesiredPropertiesCallback desiredPropertiesCallback, Object desiredPropertiesCallbackContext)

Start receiving desired property updates for this client. After subscribing to desired properties, this client can freely send reported property updates and make getTwin calls.
void subscribeToDesiredProperties(DesiredPropertiesCallback desiredPropertiesCallback, Object desiredPropertiesCallbackContext, int timeoutMilliseconds)

Start receiving desired property updates for this client. After subscribing to desired properties, this client can freely send reported property updates and make getTwin calls.
void subscribeToDesiredPropertiesAsync(DesiredPropertiesCallback desiredPropertiesCallback, Object desiredPropertiesCallbackContext, SubscriptionAcknowledgedCallback subscriptionAcknowledgedCallback, Object desiredPropertiesSubscriptionCallbackContext)

Start receiving desired property updates for this client asynchronously. After subscribing to desired properties, this client can freely send reported property updates and make getTwin calls.
void subscribeToMethods(MethodCallback methodCallback, Object methodCallbackContext)

Subscribes to direct methods
void subscribeToMethods(MethodCallback methodCallback, Object methodCallbackContext, int timeoutMilliseconds)

Subscribes to direct methods
void subscribeToMethodsAsync(MethodCallback methodCallback, Object methodCallbackContext, SubscriptionAcknowledgedCallback methodStatusCallback, Object methodStatusCallbackContext)

Subscribes to direct methods
ReportedPropertiesUpdateResponse updateReportedProperties(TwinCollection reportedProperties)

Patch this client's twin with the provided reported properties. This client must have subscribed to desired properties before this method can be called.
ReportedPropertiesUpdateResponse updateReportedProperties(TwinCollection reportedProperties, int timeoutMilliseconds)

Patch this client's twin with the provided reported properties. This client must have subscribed to desired properties before this method can be called. This client must have subscribed to desired properties before this method can be called.
void updateReportedPropertiesAsync(TwinCollection reportedProperties, ReportedPropertiesCallback reportedPropertiesCallback, Object callbackContext)

Patch this client's twin with the provided reported properties asynchronously. This client must have subscribed to desired properties before this method can be called.
void updateReportedPropertiesAsync(TwinCollection reportedProperties, ReportedPropertiesUpdateCorrelatingMessageCallback reportedPropertiesUpdateCorrelatingMessageCallback, Object callbackContext)

Patch this client's twin with the provided reported properties asynchronously. This client must have subscribed to desired properties before this method can be called.

This overload utilizes a more verbose callback than updateReportedPropertiesAsync(TwinCollection reportedProperties, ReportedPropertiesCallback reportedPropertiesCallback, Object callbackContext) and is only intended for users who need insight on the state of this process every step of the way.

Field Details

DEFAULT_TIMEOUT_MILLISECONDS

protected static final int DEFAULT_TIMEOUT_MILLISECONDS= 60 * 1000

Method Details

close

public void close()

Close the client.

getConfig

public ClientConfiguration getConfig()

Getter for the device client config.

Returns:

the value of the config.

getProductInfo

public ProductInfo getProductInfo()

getTwin

public Twin getTwin()

Get the twin for this client. This client must have subscribed to desired properties before this method can be called.

Returns:

The twin for this client

Throws:

InterruptedException - if the operation is interrupted while waiting on the getTwin request to be acknowledged by the service.
IllegalStateException - if this client is not open or if this client has not subscribed to desired properties yet.
IotHubClientException - if the request is rejected by the service for any reason of if the synchronous operation times out.

getTwin

public Twin getTwin(int timeoutMilliseconds)

Get the twin for this client. This client must have subscribed to desired properties before this method can be called.

Parameters:

timeoutMilliseconds - The maximum number of milliseconds this call will wait for the service to return the twin. If 0, then it will wait indefinitely.

Returns:

The twin for this client

Throws:

InterruptedException - if the operation is interrupted while waiting on the getTwin request to be acknowledged by the service.
IllegalStateException - if this client is not open or if this client has not subscribed to desired properties yet.
IotHubClientException - if the request is rejected by the service for any reason of if the synchronous operation times out.

getTwinAsync

public void getTwinAsync(GetTwinCallback twinCallback, Object callbackContext)

Get the twin for this client asynchronously. This client must have subscribed to desired properties before this method can be called.

Parameters:

twinCallback - The callback to be executed once the twin is received from the service.
callbackContext - The context that will be included in the callback of twinCallback. May be null.

Throws:

IllegalStateException - if this client is not open or if this client has not subscribed to desired properties yet.

getTwinAsync

public void getTwinAsync(GetTwinCorrelatingMessageCallback twinCallback, Object callbackContext)

Get the twin for this client asynchronously. This client must have subscribed to desired properties before this method can be called.

This overload utilizes a more verbose callback than getTwinAsync(GetTwinCallback twinCallback, Object callbackContext) and is only intended for users who need insight on the state of this process every step of the way.

Parameters:

twinCallback - The callback to be executed once the state of the getTwin request message has changed. This provides context on when the message is queued, sent, acknowledged, etc.
callbackContext - The context that will be included in each callback of twinCallback. May be null.

Throws:

IllegalStateException - if this client is not open or if this client has not subscribed to desired properties yet.

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.

sendEvent

public void sendEvent(Message message)

Synchronously sends a message to IoT hub.

Parameters:

message - the message to be sent.

Throws:

InterruptedException - if the operation is interrupted while waiting on the telemetry to be acknowledged by the service.
IllegalStateException - if the client has not been opened yet or is already closed.
IotHubClientException - if the request is rejected by the service for any reason of if the synchronous operation times out.

sendEvent

public void sendEvent(Message message, int timeoutMilliseconds)

Synchronously sends a message to IoT hub.

Parameters:

message - the message to be sent.
timeoutMilliseconds - The maximum number of milliseconds to wait for the service to acknowledge this message. If 0, then it will wait indefinitely.

Throws:

InterruptedException - if the operation is interrupted while waiting on the telemetry to be acknowledged by the service.
IllegalStateException - if the client has not been opened yet or is already closed.
IotHubClientException - if the request is rejected by the service for any reason of if the synchronous operation times out.

sendEventAsync

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

Asynchronously sends a message to IoT hub.

Parameters:

message - the message to be sent.
callback -

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

</code> . </p>

callbackContext -

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

</code> if no callback is provided.</p>

Throws:

IllegalArgumentException -

if the message provided isnull  

</code> . </p>

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

sendEvents

public void sendEvents(List messages)

Synchronously sends a batch of messages to IoT hub

This operation is only supported over HTTPS.

Maximum payload size for HTTPS is 255KB

Parameters:

messages - the messages to be sent.

Throws:

InterruptedException - if the operation is interrupted while waiting on the telemetry to be acknowledged by the service.
IllegalStateException - if the client has not been opened yet or is already closed.
IotHubClientException - if the request is rejected by the service for any reason of if the synchronous operation times out.
UnsupportedOperationException - if the client is not using HTTPS.

sendEvents

public void sendEvents(List messages, int timeoutMilliseconds)

Synchronously sends a batch of messages to IoT hub

This operation is only supported over HTTPS.

Maximum payload size for HTTPS is 255KB

Parameters:

messages - the messages to be sent.
timeoutMilliseconds - The maximum number of milliseconds to wait for the service to acknowledge this batch message. If 0, then it will wait indefinitely.

Throws:

InterruptedException - if the operation is interrupted while waiting on the telemetry to be acknowledged by the service.
IllegalStateException - if the client has not been opened yet or is already closed.
IotHubClientException - if the request is rejected by the service for any reason of if the synchronous operation times out.
UnsupportedOperationException - if the client is not using HTTPS.

sendEventsAsync

public void sendEventsAsync(List messages, MessagesSentCallback callback, Object callbackContext)

Asynchronously sends a batch of messages to the IoT hub

This operation is only supported over HTTPS. This API call is an all-or-nothing single HTTPS message and the callback will be triggered once this batch message has been sent.

Maximum payload size for HTTPS is 255KB

Parameters:

messages - the list of message to be sent.
callback -

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

</code> . </p>

callbackContext -

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

</code> if no callback is provided.</p>

Throws:

IllegalArgumentException -

if the message provided isnull  

</code> . </p>

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

setConnectionStatusChangeCallback

public void setConnectionStatusChangeCallback(IotHubConnectionStatusChangeCallback callback, Object callbackContext)

Sets the callback to be executed when the connection status of the device changes. The callback will be fired with a status and a reason why the device's status changed. When the callback is fired, the provided context will be provided alongside the status and reason.

This connection status callback is not triggered by any upstream connection change events. For example, if if the connection status callback is set for a module on an IoT Edge device and that IoT Edge device loses connection to the cloud, this connection status callback won't onStatusChanged since the connection between the module and the IoT Edge device hasn't changed.

Note that the thread used to deliver this callback should not be used to call open()/closeNow() on the client that this callback belongs to. All open()/close() operations should be done on a separate thread

Parameters:

callback - The callback to be fired when the connection status of the device changes. Can be null to unset this listener as long as the provided callbackContext is also null.
callbackContext -

a context to be passed to the callback. Can benull  

</code> . </p>

setOperationTimeout

public void setOperationTimeout(long timeout)

Set the length of time, in milliseconds, that any given operation will expire in. These operations include reconnecting upon a connection drop and sending a message.

Parameters:

timeout - the length in time, in milliseconds, until a given operation shall expire

Throws:

IllegalArgumentException - if the provided timeout is 0 or negative

setRetryPolicy

public void setRetryPolicy(RetryPolicy retryPolicy)

Sets the given retry policy on the underlying transport See more details about the default retry policy and about using custom retry policies here

Parameters:

retryPolicy - the new interval in milliseconds

subscribeToDesiredProperties

public void subscribeToDesiredProperties(DesiredPropertiesCallback desiredPropertiesCallback, Object desiredPropertiesCallbackContext)

Start receiving desired property updates for this client. After subscribing to desired properties, this client can freely send reported property updates and make getTwin calls.

Parameters:

desiredPropertiesCallback - The callback to execute each time a desired property update message is received from the service. This will contain one or many properties updated at once.
desiredPropertiesCallbackContext - The context that will be included in the callback of desiredPropertiesCallback. May be null.

Throws:

InterruptedException - if the operation is interrupted while waiting on the subscription request to be acknowledged by the service.
IllegalStateException - if this client is not open.
IotHubClientException - if the request is rejected by the service for any reason of if the synchronous operation times out.

subscribeToDesiredProperties

public void subscribeToDesiredProperties(DesiredPropertiesCallback desiredPropertiesCallback, Object desiredPropertiesCallbackContext, int timeoutMilliseconds)

Start receiving desired property updates for this client. After subscribing to desired properties, this client can freely send reported property updates and make getTwin calls.

Parameters:

desiredPropertiesCallback - The callback to execute each time a desired property update message is received from the service. This will contain one or many properties updated at once.
desiredPropertiesCallbackContext - The context that will be included in the callback of desiredPropertiesCallback. May be null.
timeoutMilliseconds - The maximum number of milliseconds this call will wait for the service to acknowledge the subscription request. If 0, then it will wait indefinitely.

Throws:

InterruptedException - if the operation is interrupted while waiting on the subscription request to be acknowledged by the service.
IllegalStateException - if this client is not open.
IotHubClientException - if the request is rejected by the service for any reason of if the synchronous operation times out.

subscribeToDesiredPropertiesAsync

public void subscribeToDesiredPropertiesAsync(DesiredPropertiesCallback desiredPropertiesCallback, Object desiredPropertiesCallbackContext, SubscriptionAcknowledgedCallback subscriptionAcknowledgedCallback, Object desiredPropertiesSubscriptionCallbackContext)

Start receiving desired property updates for this client asynchronously. After subscribing to desired properties, this client can freely send reported property updates and make getTwin calls.

Parameters:

desiredPropertiesCallback - The callback to execute each time a desired property update message is received from the service. This will contain one or many properties updated at once.
desiredPropertiesCallbackContext - The context that will be included in each callback of desiredPropertiesCallback. May be null.
subscriptionAcknowledgedCallback - The callback to execute once the service has acknowledged the subscription request.
desiredPropertiesSubscriptionCallbackContext - The context that will be included in the callback of desiredPropertiesSubscriptionCallback. May be null.

Throws:

IllegalStateException - if this client is not open.

subscribeToMethods

public void subscribeToMethods(MethodCallback methodCallback, Object methodCallbackContext)

Subscribes to direct methods

Parameters:

methodCallback -

Callback on which direct methods shall be invoked. Cannot benull  

</code> . </p>

methodCallbackContext -

Context for device method callback. Can benull  

</code> .</p>

Throws:

InterruptedException - if the operation is interrupted while waiting on the subscription request to be acknowledged by the service.
IllegalStateException - if this client is not open.
IotHubClientException - if the request is rejected by the service for any reason of if the synchronous operation times out.

subscribeToMethods

public void subscribeToMethods(MethodCallback methodCallback, Object methodCallbackContext, int timeoutMilliseconds)

Subscribes to direct methods

Parameters:

methodCallback -

Callback on which direct methods shall be invoked. Cannot benull  

</code> . </p>

methodCallbackContext -

Context for device method callback. Can benull  

</code> . </p>

timeoutMilliseconds - The maximum number of milliseconds this call will wait for the service to return the twin. If 0, then it will wait indefinitely.

Throws:

InterruptedException - if the operation is interrupted while waiting on the subscription request to be acknowledged by the service.
IllegalStateException - if this client is not open.
IotHubClientException - if the request is rejected by the service for any reason of if the synchronous operation times out.

subscribeToMethodsAsync

public void subscribeToMethodsAsync(MethodCallback methodCallback, Object methodCallbackContext, SubscriptionAcknowledgedCallback methodStatusCallback, Object methodStatusCallbackContext)

Subscribes to direct methods

Parameters:

methodCallback -

Callback on which direct methods shall be invoked. Cannot benull  

</code> . </p>

methodCallbackContext -

Context for device method callback. Can benull  

</code> . </p>

methodStatusCallback -

Callback for providing IotHub status for direct methods. Cannot benull  

</code> . </p>

methodStatusCallbackContext -

Context for device method status callback. Can benull  

</code> .</p>

Throws:

IllegalStateException - if called when client is not opened.
IllegalArgumentException - if either callback are null.

updateReportedProperties

public ReportedPropertiesUpdateResponse updateReportedProperties(TwinCollection reportedProperties)

Patch this client's twin with the provided reported properties. This client must have subscribed to desired properties before this method can be called.

Parameters:

reportedProperties - The reported property key/value pairs to add/update in the twin. To delete a particular reported property, set the value to null.

Returns:

The new reported properties version.

Throws:

InterruptedException - if the operation is interrupted while waiting on the reported property update request to be acknowledged by the service.
IllegalStateException - if this client is not open or if this client has not subscribed to desired properties yet.
IotHubClientException - if the request is rejected by the service for any reason of if the synchronous operation times out.

updateReportedProperties

public ReportedPropertiesUpdateResponse updateReportedProperties(TwinCollection reportedProperties, int timeoutMilliseconds)

Patch this client's twin with the provided reported properties. This client must have subscribed to desired properties before this method can be called. This client must have subscribed to desired properties before this method can be called.

Parameters:

reportedProperties - The reported property key/value pairs to add/update in the twin. To delete a particular reported property, set the value to null.
timeoutMilliseconds - The maximum number of milliseconds this call will wait for the service to acknowledge the reported properties update request. If 0, then it will wait indefinitely.

Returns:

The new reported properties version.

Throws:

InterruptedException - if the operation is interrupted while waiting on the reported property update request to be acknowledged by the service.
IllegalStateException - if this client is not open or if this client has not subscribed to desired properties yet.
IotHubClientException - if the request is rejected by the service for any reason of if the synchronous operation times out.

updateReportedPropertiesAsync

public void updateReportedPropertiesAsync(TwinCollection reportedProperties, ReportedPropertiesCallback reportedPropertiesCallback, Object callbackContext)

Patch this client's twin with the provided reported properties asynchronously. This client must have subscribed to desired properties before this method can be called.

Parameters:

reportedProperties - The reported property key/value pairs to add/update in the twin. To delete a particular reported property, set the value to null.
reportedPropertiesCallback - The callback to be executed once the reported properties update request has been acknowledged by the service.
callbackContext - The context that will be included in the callback of reportedPropertiesCallback. May be null.

Throws:

IllegalStateException - if this client is not open or if this client has not subscribed to desired properties yet.

updateReportedPropertiesAsync

public void updateReportedPropertiesAsync(TwinCollection reportedProperties, ReportedPropertiesUpdateCorrelatingMessageCallback reportedPropertiesUpdateCorrelatingMessageCallback, Object callbackContext)

Patch this client's twin with the provided reported properties asynchronously. This client must have subscribed to desired properties before this method can be called.

This overload utilizes a more verbose callback than updateReportedPropertiesAsync(TwinCollection reportedProperties, ReportedPropertiesCallback reportedPropertiesCallback, Object callbackContext) and is only intended for users who need insight on the state of this process every step of the way.

Parameters:

reportedProperties - The reported property key/value pairs to add/update in the twin. To delete a particular reported property, set the value to null.
reportedPropertiesUpdateCorrelatingMessageCallback - The callback to be executed once the state of the reported properties update request message has changed. This provides context on when the message is queued, sent, acknowledged, etc.
callbackContext - The context that will be included in each callback of updateReportedPropertiesCallback. May be null.

Throws:

IllegalStateException - if this client is not open or if this client has not subscribed to desired properties yet.

Applies to