com.microsoft.azure.sdk.iot.service.devicetwin

Class DeviceMethod

java.lang.Object

com.microsoft.azure.sdk.iot.service.devicetwin.DeviceMethod

public class DeviceMethod
extends Object

Use the DeviceMethod client to directly invoke methods on devices and modules in IoT hub.

Constructor Summary

Constructors

Constructor and Description
DeviceMethod(String connectionString) Create a DeviceMethod instance from the information in the connection string.
DeviceMethod(String hostName, com.azure.core.credential.AzureSasCredential azureSasCredential) Create a new DeviceMethod instance.
DeviceMethod(String hostName, com.azure.core.credential.AzureSasCredential azureSasCredential, DeviceMethodClientOptions options) Create a new DeviceMethod instance.
DeviceMethod(String connectionString, DeviceMethodClientOptions options) Create a DeviceMethod instance from the information in the connection string.
DeviceMethod(String hostName, com.azure.core.credential.TokenCredential credential) Create a new DeviceMethod instance.
DeviceMethod(String hostName, com.azure.core.credential.TokenCredential credential, DeviceMethodClientOptions options) Create a new DeviceMethod instance.

Method Summary

Modifier and Type	Method and Description
static DeviceMethod	createFromConnectionString(String connectionString) Deprecated. because this method declares a thrown IOException even though it never throws an IOException. Users are recommended to use DeviceMethod(String) instead since it does not declare this exception even though it constructs the same DeviceMethod.
static DeviceMethod	createFromConnectionString(String connectionString, DeviceMethodClientOptions options) Deprecated. because this method declares a thrown IOException even though it never throws an IOException. Users are recommended to use DeviceMethod(String, DeviceMethodClientOptions) instead since it does not declare this exception even though it constructs the same DeviceMethod.
MethodResult	invoke(String deviceId, String methodName, Long responseTimeoutInSeconds, Long connectTimeoutInSeconds, Object payload) Directly invokes a method on the device and return its result.
MethodResult	invoke(String deviceId, String moduleId, String methodName, Long responseTimeoutInSeconds, Long connectTimeoutInSeconds, Object payload) Directly invokes a method on the module and return its result.
Job	scheduleDeviceMethod(String queryCondition, String methodName, Long responseTimeoutInSeconds, Long connectTimeoutInSeconds, Object payload, Date startTimeUtc, long maxExecutionTimeInSeconds) Creates a new Job to invoke method on one or multiple devices.

Methods inherited from class java.lang.Object

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

Constructor Detail

DeviceMethod

public DeviceMethod(String connectionString)

Create a DeviceMethod instance from the information in the connection string.

Parameters:

connectionString - is the IoTHub connection string.

DeviceMethod

public DeviceMethod(String connectionString,
                    DeviceMethodClientOptions options)

Create a DeviceMethod instance from the information in the connection string.

Parameters:

connectionString - is the IoTHub connection string.

options - the configurable options for each operation on this client. May not be null.

DeviceMethod

public DeviceMethod(String hostName,
                    com.azure.core.credential.TokenCredential credential)

Create a new DeviceMethod instance.

Parameters:

hostName - The hostname of your IoT Hub instance (For instance, "your-iot-hub.azure-devices.net")

credential - The custom TokenCredential that will provide authentication tokens to this library when they are needed. The provided tokens must be Json Web Tokens.

DeviceMethod

public DeviceMethod(String hostName,
                    com.azure.core.credential.TokenCredential credential,
                    DeviceMethodClientOptions options)

Create a new DeviceMethod instance.

Parameters:

hostName - The hostname of your IoT Hub instance (For instance, "your-iot-hub.azure-devices.net")

credential - The custom TokenCredential that will provide authentication tokens to this library when they are needed. The provided tokens must be Json Web Tokens.

options - The connection options to use when connecting to the service.

DeviceMethod

public DeviceMethod(String hostName,
                    com.azure.core.credential.AzureSasCredential azureSasCredential)

Create a new DeviceMethod instance.

Parameters:

hostName - The hostname of your IoT Hub instance (For instance, "your-iot-hub.azure-devices.net")

azureSasCredential - The SAS token provider that will be used for authentication.

DeviceMethod

public DeviceMethod(String hostName,
                    com.azure.core.credential.AzureSasCredential azureSasCredential,
                    DeviceMethodClientOptions options)

Create a new DeviceMethod instance.

Parameters:

hostName - The hostname of your IoT Hub instance (For instance, "your-iot-hub.azure-devices.net")

azureSasCredential - The SAS token provider that will be used for authentication.

options - The connection options to use when connecting to the service.

Method Detail

createFromConnectionString

@Deprecated
public static DeviceMethod createFromConnectionString(String connectionString)
                                                            throws IOException

Deprecated. because this method declares a thrown IOException even though it never throws an IOException. Users are recommended to use DeviceMethod(String) instead since it does not declare this exception even though it constructs the same DeviceMethod.

Create a DeviceMethod instance from the information in the connection string.

Parameters:

connectionString - is the IoTHub connection string.

Returns:

an instance of the DeviceMethod.

Throws:

IOException - This exception is never thrown.

createFromConnectionString

@Deprecated
public static DeviceMethod createFromConnectionString(String connectionString,
                                                                   DeviceMethodClientOptions options)
                                                            throws IOException

Deprecated. because this method declares a thrown IOException even though it never throws an IOException. Users are recommended to use DeviceMethod(String, DeviceMethodClientOptions) instead since it does not declare this exception even though it constructs the same DeviceMethod.

Create a DeviceMethod instance from the information in the connection string.

Parameters:

connectionString - is the IoTHub connection string.

options - the configurable options for each operation on this client. May not be null.

Returns:

an instance of the DeviceMethod.

Throws:

IOException - This exception is never thrown.

invoke

public MethodResult invoke(String deviceId,
                           String methodName,
                           Long responseTimeoutInSeconds,
                           Long connectTimeoutInSeconds,
                           Object payload)
                    throws IotHubException,
                           IOException

Directly invokes a method on the device and return its result.

Parameters:

deviceId - is the device where the request is send to.

methodName - is the name of the method that shall be invoked on the device.

responseTimeoutInSeconds - is the maximum waiting time for a response from the device in seconds.

connectTimeoutInSeconds - is the maximum waiting time for a response from the connection in seconds.

payload - is the the method parameter.

Returns:

the status and payload resulted from the method invoke.

Throws:

IotHubException - This exception is thrown if the response verification failed.

IOException - This exception is thrown if the IO operation failed.

invoke

public MethodResult invoke(String deviceId,
                           String moduleId,
                           String methodName,
                           Long responseTimeoutInSeconds,
                           Long connectTimeoutInSeconds,
                           Object payload)
                    throws IotHubException,
                           IOException

Directly invokes a method on the module and return its result.

Parameters:

deviceId - is the device where the module is related to.

moduleId - is the module where the request is sent to.

methodName - is the name of the method that shall be invoked on the device.

responseTimeoutInSeconds - is the maximum waiting time for a response from the device in seconds.

connectTimeoutInSeconds - is the maximum waiting time for a response from the connection in seconds.

payload - is the the method parameter.

Returns:

the status and payload resulted from the method invoke.

Throws:

IotHubException - This exception is thrown if the response verification failed.

IOException - This exception is thrown if the IO operation failed.

scheduleDeviceMethod

public Job scheduleDeviceMethod(String queryCondition,
                                String methodName,
                                Long responseTimeoutInSeconds,
                                Long connectTimeoutInSeconds,
                                Object payload,
                                Date startTimeUtc,
                                long maxExecutionTimeInSeconds)
                         throws IOException,
                                IotHubException

Creates a new Job to invoke method on one or multiple devices.

Parameters:

queryCondition - Query condition to evaluate which devices to run the job on. It can be null or empty.

methodName - Method name to be invoked.

responseTimeoutInSeconds - Maximum interval of time, in seconds, that the Direct Method will wait for answer. It can be null.

connectTimeoutInSeconds - Maximum interval of time, in seconds, that the Direct Method will wait for the connection. It can be null.

payload - Object that contains the payload defined by the user. It can be null.

startTimeUtc - Date time in Utc to start the job.

maxExecutionTimeInSeconds - Max execution time in seconds, i.e., ttl duration the job can run.

Returns:

a Job class that represent this job on IotHub.

Throws:

IOException - if the function contains invalid parameters.

IotHubException - if the http request failed.