User Tools

Site Tools


resource_observe

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
resource_observe [2017/03/28 21:43]
Ben Lloyd Pearson
resource_observe [2017/12/18 08:42] (current)
Taehyoung Shim [Sample Application] QueryParamsMqp() "us" -> "use"
Line 1: Line 1:
-====== Resource ​Observe ​======+====== Resource ​Observation ​======
  
  
Line 6: Line 6:
 The handling of observation registration is application specific. It should not be assumed that a resource is observable, or a resource can handle any specific number of observers. If the server responds with a success (2.xx) code, the registration is considered successful. The handling of observation registration is application specific. It should not be assumed that a resource is observable, or a resource can handle any specific number of observers. If the server responds with a success (2.xx) code, the registration is considered successful.
  
-Notifications from the server to the client may be confirmable or non-confirmable. If the client returns a RST message, the observation registration should be dropped immediately. If the client fails to acknowledge a number of confirmable requests, the server should assume that the client has abandoned the observation and drop the registration.+Notifications from the server to the client may be CON (confirmableor NON (non-confirmable) message. If the client returns a RST (Reset) ​message, the observation registration should be dropped immediately. If the client fails to acknowledge a number of confirmable requests, the server should assume that the client has abandoned the observation and drop the registration.
  
-If the observed resource is removed, the server sends a NOTFOUND ​status to all observers.+If the observed resource is removed, the server sends a NOT FOUND status ​(4.04) ​to all observers.
  
 If an observed resource fails to notify a client before the max-age of a resource value update, the client should attempt to re-register the observation. If an observed resource fails to notify a client before the max-age of a resource value update, the client should attempt to re-register the observation.
  
-=== Sequence Diagram ===+===== Sequence Diagram ​=====
 {{:​observe.png?​800|}} {{:​observe.png?​800|}}
  
-Steps: +  ​- The client application calls OCResource.observe(...) to retrieve a representation from the resources.
- +
-  ​- The client application calls resource.observe(...) to retrieve a representation from the resources.+
   - The call is marshalled to the stack which is either running in-process or out-of-process (daemon).   - The call is marshalled to the stack which is either running in-process or out-of-process (daemon).
-  - The C API is called to dispatch the request. The call may look like this: OCDoResource(OC_REST_GET | OC_REST_OBSERVE,​ "//​192.168.1.11/​light/​1,​ 0, 0, OC_CONFIRMABLE,​ callback); +  - The C API is called to dispatch the request. The call may look like this: <​code> ​OCDoResource(OC_REST_GET | OC_REST_OBSERVE,​ "//​192.168.1.11/​light/​1,​ 0, 0, OC_CONFIRMABLE,​ callback);</​code>​
-  - +
   - Where CoAP is used as a transport, the lower stack will send a GET request to the target server. The primary difference between a GET request and an observe request is that the observe request contains an observe option indicating that, in addition to querying this resource, the client wishes to get notifications if/when the resource state changes.   - Where CoAP is used as a transport, the lower stack will send a GET request to the target server. The primary difference between a GET request and an observe request is that the observe request contains an observe option indicating that, in addition to querying this resource, the client wishes to get notifications if/when the resource state changes.
   - On the server side, the OCProcess() function (message pump) receives and parses the request from the socket, then dispatches it to the correct entity handler based on the URI of the request. The request to the entity handler will indicate that the request is both a query and subscription request. The entity handler MAY take note of this, but it is not responsible to tracking the observers. The stack tracks the observers of record.   - On the server side, the OCProcess() function (message pump) receives and parses the request from the socket, then dispatches it to the correct entity handler based on the URI of the request. The request to the entity handler will indicate that the request is both a query and subscription request. The entity handler MAY take note of this, but it is not responsible to tracking the observers. The stack tracks the observers of record.
Line 41: Line 38:
   - OCCancel() finds the observation that is associated with the operation and sends an observe deregistration request to the server.   - OCCancel() finds the observation that is associated with the operation and sends an observe deregistration request to the server.
  
 +===== Call Flow =====
  
-=== Call Flow === +Once initialization has been setup on the server side, the server can declare resource property attributes to be observable ​and allow remote devices to subscribe to changes.
- +
-Once initialization has been setup server side, server can declare resource property attributes to be observable ​to enable ​remote devices to subscribe to changes.+
  
 {{:​iotivity-flow-observe.png?​nolink|}} {{:​iotivity-flow-observe.png?​nolink|}}
  
-=== Sample Application ​===+===== Sample Application ===== 
 + 
 +The simpleserver and simpleclient examples are a good place to learn about resource observation:​
  
-The following Samples in resource ​directory provide good examples ​to use observe APIs.+  * [[https://​gerrit.iotivity.org/​gerrit/​gitweb?​p=iotivity.git;​a=blob;​f=resource/​examples/​simpleserver.cpp;​hb=HEAD|iotivity/​resource/​examples/​simpleserver.cpp]] 
 +  * [[https://​gerrit.iotivity.org/​gerrit/​gitweb?​p=iotivity.git;​a=blob;​f=resource/​examples/​simpleclient.cpp;​hb=HEAD|iotivity/​resource/examples/​simpleclient.cpp]]
  
-  * Sample with basic observe feature for server side: resource/​examples/​simpleserver.cpp 
-  * Sample with basic observe feature for client side: resource/​examples/​simpleclient.cpp 
  
-Step 1: Server ​declares the resource attribute as "​OC_OBSERVABLE" ​while creating resource.+Step 1: The server ​declares the resource attribute as "​OC_OBSERVABLE" ​when creating ​the resource.
   ​   ​
 <​code>​ <​code>​
Line 71: Line 68:
 </​code>​ </​code>​
  
-Step 2: Client ​sets observation on the resource.+Step 2: The client ​sets observation on the resource.
  
 <​code>​ <​code>​
Line 77: Line 74:
 </​code>​ </​code>​
  
-The client specifies how it wants to observe via OBSERVE_TYPE_TO_USE. QueryParamsMap() ​us the map which can have the query parameter name and value. observeHandler is the callback ​handling ​observation result. qos is to specify ​the communication quality, e.g. specifying the notification to be confirmable or non-confirmable.+The client specifies how it wants to observe via OBSERVE_TYPE_TO_USE. QueryParamsMap() ​use the map which can have the query parameter name and value. observeHandler is the callback ​that handles the observation result. qos is specifies ​the communication quality, e.g. specifying the notification to be confirmable or non-confirmable.
  
-An example of observehandler can look like -+An example of observehandler can look like the following:
  
 <​code>​ <​code>​
Line 90: Line 87:
 } }
 </​code>​ </​code>​
-=== References : ===+===== Next Steps ===== 
 + 
 +Once you've completed this section, proceed to the next section on [[resource_presence|resource presence]] 
 + 
 +===== Additional Resources =====
  
 Previously published documentation which this (living) wiki page is based on : Previously published documentation which this (living) wiki page is based on :
  
 [[https://​www.iotivity.org/​documentation/​linux/​programmers-guide/​observing-resource-state-observe]] [[https://​www.iotivity.org/​documentation/​linux/​programmers-guide/​observing-resource-state-observe]]
resource_observe.1490737389.txt.gz · Last modified: 2017/03/28 21:43 by Ben Lloyd Pearson