User Tools

Site Tools


resource_presence

Resource Presence

Presence is “active” or “advertisement” discovery. It happens at device level. Although application triggers the operation, it is the stack that sends the notification. It operates in server/client model. Server notifies its presence and the client to subscribe to/unsubscribe from a device's presence events. The resource to enable discovery is hosted local to the client who initiates the discovery request. The publishing device (server) is responsible for the published information.

Call Flow

  • (1) OCPlatform::startPresence(30)
  • (2) OCStartPresence(30)
  • (3) Presence Notification
  • (4) OCPlatform::subscribePresence(presenceHandle, hostAddress, connectivityType, presenceHandler)
  • (5) OCDoResource(ocdoHandle, OC_REST_PRESENCE,host, resourceTpype, connectivityType, &cbdata, presenceHandler);
  • (6) OCPlatform::registerResource(m_resourceHandle, resourceURI, resourceTypeName, resourceInterface, &entityHandler, resourceProperty);
  • (7) OCDoResource(…)
  • (8) Presence Notification

APIs

APIs Functionalities Examples Client/Server API
OCStackResult startPresence(const unsigned int announceDurationSeconds) Start Presence announcements. OCPlatform::startPresence(30) Server
OCStackResult stopPresence() Stop Presence announcements. OCPlatform::stopPresence() Server
OCStackResult subscribePresence(OCPresenceHandle& presenceHandle, const std::string& host, OCConnectivityType connectivityType, SubscribeCallback presenceHandler) subscribe OCPlatform::subscribePresence(presenceHandle, hostAddress, connectivityType, presenceHandle) Client
OCStackResult subscribePresence(OCPresenceHandle& presenceHandle, const std::string& host, const std::string& resourceType, OCConnectivityType connectivityType, SubscribeCallback presenceHandle) subscribe OCPlatform::subscribePresence(presenceHandle, hostaddress, resourceType, connectivityType, presenceHandler) Client
OCStackResult unsubscribePresence(OCPresenceHandle presenceHandle) unsubscribe OCPlatform::unsubscribePresence(presenceHandle) Client

Presence Resource

The presence resource is modelled as a collection with uri of “/oic/ad', and each resource of type “oic.wk.ad”. Examples of presence resource could be:

    std::array<std::string, numPresenceResources> resourceURI { {
        "/a/fan",
        "/a/led" } };
    std::array<std::string, numPresenceResources> resourceTypeName { {
        "core.fan",
        "core.led" } };

Sample Application :

Presence samples provides examples to use presence APIs. They are also good examples showing the call flows described above.

  • Sample with basic presence feature for server side: resource/examples/presenceserver.cpp
  • Sample with basic presence feature for client side: resource/examples/presenceclient.cpp

Server side

Server starts presence advertisement with TTL (time to live) in seconds. e.g.

startPresence(30);

and can stop it by calling

stopPresence();

While registering/creating presence resources, server needs to gone through each resource in the collection. e.g.

for(int i=0; i<numPresenceResources; i++)
    {
        result = OCPlatform::registerResource(handle,
                resourceURI.at(i), resourceTypeName.at(i), resourceInterface,
                &entityHandler, resourceProperty);
        if (result != OC_STACK_OK)
        {
            cout << "Resource creation was unsuccessful with resource URI "
                    << resourceURI.at(i);
        }
    }

Client side

Client can choose to subscribe to the presence notification via unicast by giving specific host address, e.g.

OCPlatform::subscribePresence(presenceHandle, hostAddress,
                            connectivityType, &presenceHandler);

or multicast, e.g.

OCPlatform::subscribePresence(presenceHandle, hostAddress,
                            connectivityType, &presenceHandler);

Where presenceHandler is the callback function for presence, e.g.

void presenceHandler(OCStackResult result, const unsigned int nonce, const std::string& hostAddress)
{
    //function body
}
resource_presence.txt · Last modified: 2016/07/25 15:52 by Ziran Sun