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:46]
Ben Lloyd Pearson structural fixes to ordered list
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|}}
  
-  - The client application calls resource.observe(...) to retrieve a representation from the resources.+  - The client application calls OCResource.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: <​code>​ OCDoResource(OC_REST_GET | OC_REST_OBSERVE,​ "//​192.168.1.11/​light/​1,​ 0, 0, OC_CONFIRMABLE,​ callback);</​code>​   - 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>​
Line 38: 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 server side, server can declare resource property attributes to be observable ​to enable ​remote devices to subscribe to changes.+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.
  
 {{:​iotivity-flow-observe.png?​nolink|}} {{:​iotivity-flow-observe.png?​nolink|}}
  
-=== Sample Application ​===+===== Sample Application ​=====
  
-The following Samples in resource directory provide good examples to use observe APIs.+The simpleserver and simpleclient ​examples ​are a good place to learn about resource observation:​
  
-  * Sample with basic observe feature for server side: resource/​examples/​simpleserver.cpp +  * [[https://​gerrit.iotivity.org/​gerrit/​gitweb?​p=iotivity.git;​a=blob;​f=resource/​examples/​simpleserver.cpp;​hb=HEAD|iotivity/​resource/​examples/​simpleserver.cpp]] 
-  * Sample with basic observe feature for client side: resource/​examples/​simpleclient.cpp+  * [[https://​gerrit.iotivity.org/​gerrit/​gitweb?​p=iotivity.git;​a=blob;​f=resource/​examples/​simpleclient.cpp;​hb=HEAD|iotivity/​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 67: Line 68:
 </​code>​ </​code>​
  
-Step 2: Client ​sets observation on the resource.+Step 2: The client ​sets observation on the resource.
  
 <​code>​ <​code>​
Line 73: 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 86: 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.1490737603.txt.gz · Last modified: 2017/03/28 21:46 by Ben Lloyd Pearson