DirectlyConnectedDevice

public class DirectlyConnectedDevice : Client

A directly-connected device is able to send messages to, and receive messages from, the IoT server. A directly-connected device has a physical-device identifier that is registered with the server. When the directly-connected device is activated on the server, the server assigns a logical-endpoint identifier. This logical-endpoint identifier is required for sending messages to, and receiving messages from, the server.

  • Constructs a new DirectlyConnectedDevice instance that will load the device configuration from the given path and password.

    Throws

    • ClientError.file if the provisioning file is not present
    • ClientError.security if the provisioning file can’t be decrypted or there are invalid information in the file

    Declaration

    Swift

    public convenience init(path: String, password: String) throws

    Parameters

    path

    the path to the provisioning file
    password

    the password to protect the provisioning file during the creation of the file

  • Activate the device. The device will be activated on the server if necessary. When the device is activated on the server, the server assigns an endpoint identifier to the device.

    If the device is already activated, this method will throw an ClientError.state. The user should call the isActivated() method prior to calling activate.

    The callback closure can run any code that is required after device activation, such as device registration (indirect enrollment).

    Throws

    ClientError.state if the device is already activated or if close has been called.

    Seealso

    isActivated

    Declaration

    Swift

    public func activate(deviceModels:[String]? = nil,
    callback: @escaping (String?, ClientError?) -> ()) throws

    Parameters

    deviceModels

    should contain the device model type URNs of this directly connected device. The device is activated with the given device models. The deviceModels parameter is zero or more, comma separated, device model URNs.
    callback

    The function to be executed after completion of activation. If activation is not successful then the object will be nil and an error object is passed in the form callback(endpoint, error) and the reason can be taken from error

  • Returns whether the device has been activated against IOT CS server.

    Declaration

    Swift

    public func isActivated() -> Bool

    Return Value

    whether the device has been activated against IOT CS server.

  • Return the logical-endpoint identifier of this directly-connected device. The logical-endpoint identifier is assigned by the server as part of the activation process.

    If close has been called, the return value is undefined.

    Seealso

    activate(callback:deviceModels:)

    Declaration

    Swift

    public func getEndpointId() -> String

    Return Value

    the logical-endpoint identifier of this directly-connected device.

  • Create an AbstractVirtualDevice instance with the given device model for the given device identifier. This method creates a new VirtualDevice instance for the given parameters. The client library does not cache previously created VirtualDevice objects.

    Throws

    • ClientError.network if a VirtualDevice cannot be created.
    • ClientError.state if close has been called.

    Declaration

    Swift

    public func createVirtualDevice(deviceId: String,
                        deviceModel: DeviceModel) throws -> VirtualDevice

    Parameters

    deviceId

    The device identifier of the device being modeled
    deviceModel

    The device model URN that this device implements

    Return Value

    a new VirtualDevice

  • Get the DeviceModel for the device model urn. This method may return nil if there is no device model for the URN. nil may also be returned if the device model is a “draft” and the property Config.ALLOW_DRAFT_DEVICE_MODELS is set to false, which is the default.

    Throws

    throws:

    • ClientError.state if close has been called

    On error callback receives a ClientError.network error if: the object is not found (StatusCode.NOT_FOUND), the request fails (!StatusCode.OK), or if the returned data is nil or JSON parsing fails

    Declaration

    Swift

    public func getDeviceModel(deviceModelUrn: String,
        callback: @escaping (DeviceModel?, ClientError?) -> Void) throws

    Parameters

    deviceModelUrn

    The URN of the device model
    callback

    This function is called with the retrieved device model.If retrieving the device model is not successful then the object will be nil and an error object is passed in the form callback(device, error) and the reason can be taken from error

  • Release the resources held by the client This call is idempotent

    Throws

    ClientError.network if a MessageDispatcher cannot be obtained.

    Declaration

    Swift

    public func close() throws

  • Create a new StorageObject that will have a name with the given object name prefixed with the device’s endpoint ID and a directory separator. The prefix addition can be disabled by setting the Config.DISABLE_STORAGE_OBJECT_PREFIX to true.

    If contentType is nil, the mime-type defaults to “application/octet-stream”.

    Throws

    throws:

    • `ClientError.network if there is an exception raised by the runtime, or an abnormal response from the storage cloud
    • ClientError.security if there is an exception establishing a secure connection to the storage cloud
    • ClientError.state if close has been called

    Declaration

    Swift

    public func createStorageObject(name:String,
                                contentType:String? = StorageObject.OCTET_STREAM)
                                throws  -> StorageObject

    Parameters

    name

    the unique name to be used to reference the content in storage
    contentType

    The mime-type of the content or nil

  • Undocumented

    Declaration

    Swift

    public func offer(message: Message) throws