Cloud: support for multiple servers
When provisioning to an OCF Cloud is initiated, the URI of the OCF Cloud is sourced from the cis property of the Cloud Configuration resource. (The identity of the OCF Cloud is stored in the sid property of the resource). Previously, the device could only store a single (URI, ID) pair. A scenario might arise where the primary cloud server is unavailable; in this case, the device detects the loss of the cloud connection and attempts to reconnect at periodic intervals. However, if a backup cloud server is available, we want the device to attempt to connect there if the primary server is down. To address this scenario, support for setting multiple cloud servers and selecting between them was added.
The Cloud Configuration resource has been extended with the x.org.iotivity.servers property, which is a list of available cloud servers. Each item in this list is a pair consisting of a URI and an ID. The URIs must be unique, while the IDs may not be.
An example of the JSON representation of the Cloud Configuration resource extended for multiple servers in (retrievable by a GET request):
{
...
"cis": "coap+tcp://127.0.0.1:5683",
"sid": "00000000-0000-0000-0000-000000000001",
"x.org.iotivity.servers": [
{
"uri": "coap+tcp://127.0.0.1:5683",
"id": "00000000-0000-0000-0000-000000000001"
},
{
"uri": "coap+tcp://mock.cloud:5683",
"id": "01020304-0506-0708-090a-0b0c0e0f1000"
}
]
...
}All available cloud servers are listed in the x.org.iotivity.servers property. To determine which server is currently selected, examine the cis and sid properties. The cis property contains the URI of the selected server, and the sid property contains the ID of the selected server.
As a minor optimization, when your device contains only a single available server, the x.org.iotivity.servers property is not returned in the response to a GET request on the resource. However, the cis and sid properties are returned and contain the values from the selected server. This ensures backward compatibility of devices with a single available cloud server.
A new C API is available to modify the cloud servers in the oc_cloud.h public header.
-
oc_cloud_add_server: Adds a server to the list of available cloud servers. -
oc_cloud_remove_server: Removes a server from the list. -
oc_cloud_select_server: Selects a server from the list. -
oc_cloud_selected_server: Returns the selected server. -
oc_cloud_iterate_servers: Iterates over the list.
Calling oc_cloud_provision_conf_resource with valid parameters updates the Cloud Resource configuration, and this update also changes the list of available cloud servers. The original list of servers is replaced with a list containing a single server, whose properties are set to the values of the parameters provided to the function call.
TODO
TODO
TODO
TODO
