AbstractVirtualDevice

public protocol AbstractVirtualDevice

AbstractVirtualDevice is a representation of a device model implemented by a device. A device model is a specification of the attributes, formats, and resources available on the device.

The AbstractVirtualDevice API is common to both the enterprise client and the device client. The semantics of the API are also the same. The processing model on the enterprise client is different, however, from the processing model on the device client.

On the enterprise client, an enterprise application calls the AbstractVirtualDevice set methods in order to affect a change on the physical device. The enterprise client application receives confirmation of that the change was accepted via a callback with a ChangeEvent. The callback indicates to the enterprise client that the value of the attribute on the device has changed. This callback may come as a result of the enterprise client calling set on the attribute, or it may come unsolicited as a result of the device-client updating the value from the physical device.

The enterprise client may also receive a callback with an ErrorEvent if the attribute value change was not accepted. This could be because the request timed out, the connection failed, or the change was explicitly rejected. The callback indicates to the enterprise client that it should roll-back the attribute value to the last known value.

On the device client, the application will call set on an AbstractVirtualDevice attribute. This will cause a message to be sent to the server. The callback is invoked with an ErrorEvent if there is an error sending the message to the server. Any enterprise application that is monitoring the device will be notified via the callback with a ChangeEvent that the value has changed. When the client-library receives a request from the server, the request is forwarded to a handler which invokes the callback on the requested attribute. A GET request simply calls get() on the attribute.

getDeviceModel()
Get the device model of this device object.
Declaration
Swift

func getDeviceModel() -> DeviceModel
Return Value

the device model
getEndpointId()
Get the endpoint id of the device. This is the identifier that the server creates when a device that has been registered with the server is activated.
Declaration
Swift

func getEndpointId() -> String
Return Value

the device’s endpoint id


                    
                    
                    get(attributeName:)

Get the value of an attribute. This method returns the current value held by the virtual device model. For an enterprise client, no REST API call is made to the server. For a device client, no call is made to the physical device.

Throws

ClientError.argument if attributeName is not a device attribute.

Declaration

Swift

func get(attributeName: String) throws -> Any?

Parameters


                                attributeName

the name of an attribute from the device type model

Return Value

the attribute value


                    
                    
                    getLastKnown(attributeName:)

Get the last known value of an attribute. This method returns the last known value of an attribute.

In the case where the enterprise client sets the value of an attribute, the last known value is the value before a callback event set with setOnChange(callback:) is received for the attribute. In the event the attribute value could not be set, the current value is rolled back to the last known value.

For a device client, the last known value is always the same as the current value. The last known value is held by the AbstractVirtualDevice instance. No REST API call is made to the server.

Throws

ClientError.argument if attributeName is not a device attribute.

Declaration

Swift

func getLastKnown(attributeName: String) throws -> Any?

Parameters


                                attributeName

the name of an attribute from the device type model

Return Value

the attribute value


                    
                    
                    set(attributeName:attributeValue:)

Set the value of an attribute. This method is used by the application to synchronize the AbstractVirtualDevice state with the physical device. This results in a REST API call to the server. For an enterprise client, an endpoint resource REST API call is made to the server. For a device client, an endpoint DATA message REST API call is made to the server. The value is validated according to the constraints in the device model. If the value is not valid, an errorVirtualDeviceIssue is raised.

Throws

ClientError.argument if attempting to set a read-only attribute, or setting an invalid value

Declaration

Swift

func set(attributeName: String, attributeValue: Any?) throws -> VirtualDevice

Parameters

`attributeName`	the name of an attribute from the device type model
`value`	the value to set

Return Value

the VirtualDevice instance

update()
Set a mark for beginning an update transaction. By default, each call to set automatically sends the value to the server. The update call allows more than one value to be set on this AbstractVirtualDevice object without sending values to the server. The values are sent to the server when the finish() method is called, which also marks the end of the update transaction.

For example:
```
 virtualDevice.update().set(attributeName:"min", attributeValue:10)
                        .set(attributeName:"max", attributeValue:20)
                        .finish();
```
Seealso

finish()
Declaration
Swift

func update() -> VirtualDevice
Return Value

this AbstractVirtualDevice instance
finish()
Causes the values set in an update transaction to be sent to the server and clears the update-transaction mark.
Throws

ClientError.network if a MessageDispatcher cannot be obtained.

ClientError.argument if an attributes is nil or is the empty string or if an attribute type is string, if newValue is nil or the empty string.
Seealso
update()
Declaration
Swift

func finish() throws


                    
                    
                    setOnChange(attributeName:callback:)

Set a callback that is invoked when the value of the given attribute in the device model changes.

Note that it is possible to set a callback for a specific attribute and to set a callback for all attributes via setOnChange(callback:). If there is a callback for the specific attribute and for all attributes, both callbacks will be invoked.

Throws

ClientError.argument if attributeName is not a device attribute.

Seealso

setOnChange(callback:)

Declaration

Swift

func setOnChange(attributeName: String, callback: @escaping (ChangeEvent) -> Void) throws

Parameters

`attributeName`	the name of an attribute from the device type model
`callback`	a callback to invoke when an attribute value changes


                    
                    
                    setOnChange(callback:)

Set a callback that is invoked when the value of any attribute in the device model changes. The callback may be nil.

Note that it is possible to set a callback for all attributes and to set a callback for a specific attribute via setOnChange(attributeName:callback:). If there is a callback for the specific attribute and for all attributes, both callbacks will be invoked.

Seealso

setOnChange(attributeName:, callback:)

Declaration

Swift

func setOnChange(callback: @escaping (ChangeEvent) -> Void)

Parameters


                                callback

a callback to invoke when an attribute value changes


                    
                    
                    setOnError(attributeName:callback:)

Set a callback that is invoked if an error occurs when setting the value of the given attribute in the device model, or an error occurs when raising an Alert.

Note that it is possible to set a callback for a specific attribute and to set a callback for all attributes via setOnError(callback:). If there is a callback for the specific attribute and for all attributes, both callbacks will be invoked.

Throws

ClientError.argument if attributeName is not a device attribute.

Seealso

setOnError(callback:)

Declaration

Swift

func setOnError(attributeName: String, callback: @escaping (ErrorEvent) -> Void) throws

Parameters

`attributeName`	the name of an attribute from the device model
`callback`	a callback to invoke when there is an error setting the attribute value


                    
                    
                    setOnError(callback:)

Set a callback that is invoked if an error occurs when setting the value of any attribute in the device model, or an error occurs when raising an Alert. The callback may be nil.

Note that it is possible to set a callback for all attributes and to set a callback for a specific attribute via setOnError(attributeName:callback:). If there is a callback for the specific attribute and for all attributes, both callbacks will be invoked.

Seealso

setOnError(attributeName:, callback:)

Declaration

Swift

func setOnError(callback: @escaping (ErrorEvent) -> Void)

Parameters


                                callback

a callback to invoke when there is an error setting a value