\r
@page OCHowTo How To... Guides\r
\r
+@ref Guide_Representative_Devices "Sample representative devices used in these tutorials"\r
+\r
@ref Guide_Stack_Init "How to initialize the stack"\r
\r
@ref Guide_Register_Resource "How to register a resource"\r
\r
********************************************************************\r
\r
-@page Guide_Stack_Init Stack Initialization \r
+\r
+@page Guide_Representative_Devices Representative Devices\r
+\r
+The best way to understand the concepts for IoTivity is through following an example and understanding the use case. The following devices are referred to throughout this document for use cases and basic operations. The details are listed here for reference so that implementers can compare the responses from these devices with their configuration to develop an understanding of what the responses mean.\r
+\r
+@section Rep_Light_Device Light devices (192.168.1.11-13)\r
+\r
+A lighting device that can handle up to two light bulbs with dimmers. Each light bulb resource has two attributes:\r
+\li Power: controls power and can have a value of 0 (off) or 1 (on)\r
+\li Level: current dimmer level with a value from 1 (low) to 10 (full)\r
+\r
+The separation of the attributes allows the light to return to the previous light level when the power is toggled.\r
+\r
+@subsection Rep_Light_Device_Description Description of resources on this device type\r
+\r
+<table cellspacing="0" cellpadding="0" border=1 >\r
+\r
+<tr>\r
+<td valign="top" ><b>Resource</b></td>\r
+<td valign="top" ><b>Description</b></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>/oc/core</p></td>\r
+<td valign="top" ><p>Standard resource listing in JSON format.</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>/oc/core/d</p></td>\r
+<td valign="top" ><p>Virtual (hidden) resource that describes the device. It is searchable and supports the JSON attributes listed in the appendix.</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>/lights</p></td>\r
+<td valign="top" ><p>The resource collection that contains light resources</p>\r
+\r
+<p>rt=alpha.light</p>\r
+\r
+<p>if=oc.mi.ll (linked-list)</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>/light/1</p></td>\r
+<td valign="top" ><p>The resource associated with the first light bulb attached to this device </p>\r
+\r
+<p>rt=alpha.light</p>\r
+\r
+<p>if=oc.mi.def (default)</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>/light/2</p></td>\r
+<td valign="top" ><p>The resource associated with the second light bulb attached to this device</p>\r
+\r
+<p>rt=alpha.light</p>\r
+\r
+<p>if=oc.mi.def (default)</p></td>\r
+</tr>\r
+\r
+</table>\r
+\r
+\r
+\r
+@subsection Rep_Light_Device_Resource_11 Resource(s) at 192.168.1.11\r
+\r
+This device contains a single light resource. The following lists the valid resources and their typical state:\r
+\r
+<table cellspacing="0" cellpadding="0" border=1>\r
+\r
+<tr>\r
+<td valign="top" ><b>Resource</b></td>\r
+<td valign="top" ><b>Representation</b></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>/oc/core</p></td>\r
+<td valign="top" ><p>[</p>\r
+\r
+<p>{ "href" : "/lights", "rt" : ["alpha.light"], "if" : ["oc.mi.ll"]},</p>\r
+\r
+<p>{ "href" : "/light/1", "rt" : ["alpha.light"], "if" : ["oc.mi.def"], "obs" : 1}</p>\r
+\r
+<p>]</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>/oc/core/d</p></td>\r
+<td valign="top" ><p>{</p>\r
+\r
+<p>"di" : "12345678-1234-1234-0000000000000011",</p>\r
+\r
+<p>"dn" : "Alpha Light Controller",</p>\r
+\r
+<p>"dd" : "A Light Controller"</p>\r
+\r
+<p>}</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>/light/1</p></td>\r
+<td valign="top" ><p>{ "power" : 0, "level" : 4 }</p></td>\r
+</tr>\r
+\r
+</table>\r
+\r
+\r
+\r
+\r
+@subsection Rep_Light_Device_Resource_12 Resource(s) at 192.168.1.12\r
+\r
+This device contains a single light resource. The following lists the valid resources and their typical state:\r
+\r
+<table cellspacing="0" cellpadding="0" border=1>\r
+\r
+<tr>\r
+<td valign="top" ><b>Resource</b></td>\r
+<td valign="top" ><b>Representation</b></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>/oc/core</p></td>\r
+<td valign="top" ><p>[</p>\r
+\r
+<p>{ "href" : "/lights", "rt" : ["alpha.light"], "if" : ["oc.mi.ll"]},</p>\r
+\r
+<p>{ "href" : "/light/2", "rt" : ["alpha.light"], "if" : ["oc.mi.def"], "obs":1}</p>\r
+\r
+<p>]</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>/oc/core/d</p></td>\r
+<td valign="top" ><p>{</p>\r
+\r
+<p>"di" : "12345678-1234-1234-0000000000000012",</p>\r
+\r
+<p>"dn" : "Alpha Light Controller",</p>\r
+\r
+<p>"dd" : "A Light Controller"</p>\r
+\r
+<p>}</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>/light/2</p></td>\r
+<td valign="top" ><p>{ "power" : 1, "level" : 6 }</p></td>\r
+</tr>\r
+\r
+</table>\r
+\r
+\r
+\r
+@subsection Rep_Light_Device_Resource_13 Resource(s) at 192.168.1.13\r
+\r
+This device contains two light resources. The following lists the valid resources and their typical state:\r
+\r
+<table cellspacing="0" cellpadding="0" border=1> \r
+\r
+<tr>\r
+<td valign="top" ><p>Resource</p></td>\r
+<td valign="top" ><p>Representation</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>/oc/core</p></td>\r
+<td valign="top" ><p>[</p>\r
+\r
+<p>{ "href" : "/lights", "rt" : ["alpha.light"], "if" : ["oc.mi.ll"]},</p>\r
+\r
+<p>{ "href" : "/light/1", "rt" : ["alpha.light"], "if" : ["oc.mi.def"], "obs":1},</p>\r
+\r
+<p>{ "href" : "/light/2", "rt" : ["alpha.light"], "if" : ["oc.mi.def"], "obs":1}</p>\r
+\r
+<p>]</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>/oc/core/d</p></td>\r
+<td valign="top" ><p>{</p>\r
+\r
+<p>"di" : "12345678-1234-1234-0000000000000013",</p>\r
+\r
+<p>"dn" : "Alpha Light Controller",</p>\r
+\r
+<p>"dd" : "A Light Controller"</p>\r
+\r
+<p>}</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>/light/1</p></td>\r
+<td valign="top" ><p>{ "power" : 0, "level" : 8 }</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>/light/2</p></td>\r
+<td valign="top" ><p>{ "power" : 1, "level" : 10 }</p></td>\r
+</tr>\r
+\r
+</table>\r
+\r
+\r
+\r
+@page Guide_Stack_Init Stack Initialization\r
\r
@section Stack_Init_SD Sequence Diagram\r
\r
@note API calls take only important parameters. We omitted some of the parameters for clarity.\r
\r
The asynchronous processing block handles incoming network traffic including packet processing, scheduled tasks including communication timeouts and callbacks to the application resulting from these activities.\r
-\r
-@section Stack_Init_CPP Stack Initilization in C++\r
+ \r
+@section Stack_Init_CPP Stack Initialization in C++\r
\r
@code {.cpp}\r
// Create PlatformConfig object\r
\r
// Create a OCPlatform instance.\r
// Note: Platform creation is synchronous call.\r
-\r
try\r
{\r
OCPlatform platform(cfg);\r
{\r
//Handle error\r
}\r
-@endcode\r
+ @endcode\r
\r
Stack initialization in C++ consists of:\r
-@li Creating a OCPlatform object with Platform configuration which allows to definition of role operation (server or client), stack operation (in-process or out-of-process), etc.\r
+@li Creating a OCPlatform object with Platform configuration which allows definition of role operation (server or client), stack operation (in-process or out-of-process), etc.\r
@note\r
@li This is a synchronous call. The application will receive an exception if platform object creation fails.\r
@li The C++ SDK handles all of the memory allocation and collection. Therefore, the application need not worry about memory management related to the stack.\r
@li Platform creation happens on the main thread while the message pump happens on a worker thread.\r
\r
\r
-@section Stack_Init_C Stack Initilization in C\r
\r
-@code {.c}\r
- uint8_t ifname[] = "eth0";\r
- uint8_t addr[20];\r
- uint16_t port = 5683;\r
\r
- /*Get IP address initialize stack */\r
- OCGetInterfaceAddress(ifname, sizeof(ifname), AF_INET, addr, sizeof(addr));\r
\r
- /* Initialize OCStack*/\r
- if (OCInit((char *) addr, port, OC_CLIENT) != OC_STACK_OK) {\r
- /* Handle stack initialization failure */\r
- return 0;\r
- }\r
+********************************************************************\r
\r
-@endcode\r
+@page Guide_Register_Resource Registering A Resource\r
\r
+Registering a resource requires two basic items:\r
+\li A handler to process requests from the stack, and\r
+\li A URI path to register the resource. \r
+The URI path should be rooted (in other words, start with a slash). The stack will construct the fully qualified URI by adding the URI authority to the provided URI path. For example, given a service running on port 5683 in a device at IP address 192.168.1.1, if the application registers a resource with a URI path "/light/1", the resulting fully qualified URI is "oc://192.168.1.1:5683/light/1", which uniquely identifies the resource's location (IP address port and path).\r
+@note Only one resource can be registered at a given URI.\r
+ \r
+@image HTML seq_register_resource_2.png\r
\r
+@section Register_Resource_SD Sequence Diagram\r
+The following call sequence diagram outlines the operations performed in the stack when a resource is registered:\r
\r
-********************************************************************\r
+@image HTML seq_register_resource.png\r
\r
-@page Guide_Register_Resource Registering A Resource \r
+<b>Step 1</b>:\r
+Assuming the application has created a valid OCPlatform object, the application registers a new resource with the stack by calling OCPlatform::registerResource(...).\r
\r
-Registering a resource requires two basic items: a handler that will be called to process requests from the stack and a URI path at which the resource will be registered. \r
+In this example, the call would take the form:\r
\r
-The URI path should be rooted (meaning starts with a slash). The stack will construct the fully qualified URI by adding the URI authority to the provided URI path. For example, given a service running on port 5683 in a device at IP address 192.168.1.1, if the application registers a resource with a URI path "/light/1", resulting fully qualified URI would be "oc://192.168.1.1:5683/light/1" which uniquely identifies the resource\92s location (IP address port and path). Please note that only one resource can be registered at a given URI.\r
+ platform.registerResource(&handle, "/light/1", "light", "oc.mi.def", handler, OC_DISCOVERABLE)\r
\r
-@section Register_Resource_SD Sequence Diagram\r
-The following call sequence diagram outlines the operations performed in the stack when a resource is registered:\r
+The handle is a reference to the resource that is used on other APIs. The URI path ("/light/1") is where on this server that the resource can be located. The URI path is unique; this call will fail if the application attempts to register another resource using an existing URI. The resource type ("light") and interface ("oc.mi.def") are properties of the resource used in the discovery process. The handler is a function called from the stack to process requests. The flags control how the stack should handle the resource. The OC_DISCOVERABLE flag indicates that the resource should be reported if a client performs a resource discovery on this server.\r
\r
-@image HTML seq_register_resource.png\r
+<b>Step 2</b>:\r
\r
-Steps:\r
+The OCPlatform::registerResource(...) method delegates the call to the appropriate instance of the stack (in-process or out-of-process via IPC).\r
\r
-1) Assuming the application has created a valid OCPlatform object, the application registers a new resource with the stack by calling OCPlatform::registerResource(...). In this example, the call would take the form platform.registerResource(&handle, "/light/1", "light", "oc.mi.a", handler, OC_DISCOVERABLE). The handle is a reference to the resource that is used on other APIs. The URI path ("/light/1") is where on this server that the resource can be located. The URI path is unique and this call will fail if the application attempts to register another resource using an existing URI. The resource type ("light") and interface ("oc.mi.a") are properties of the resource used in the discovery process. The handler is a function called from the stack to process requests. The flags control how the stack should handle the resource. The OC_DISCOVERABLE flag indicates that the resource should be reported if a client performs a resource discovery on this server.\r
+<b>Step 3</b>:\r
+The internal registerResource(...) method constructs a C++ entity handler and registers it with the C SDK using OCCreateResource(...).\r
\r
-2) The OCPlatform::registerResource(...) method delegates the call to the appropriate instance of the stack (in-process or out-of-process via IPC).\r
+In this example, the call would take the form:\r
\r
-3) The internal registerResource(...) method constructs a C++ entity handler and registers it with the C SDK using OCCreateResource(...). In this example, the call would take the form OCCreateResource(&handle, "light", "oc.mi.a", "/light/1", handler, OC_ DISCOVERABLE). Many of these parameters are passed through to the C SDK directly. However, the entity handler is a proxy function for the handler passed from OCPlatform::registerResource(...).\r
+ OCCreateResource(&handle, "light", "oc.mi.def", "/light/1", handler, OC_ DISCOVERABLE)\r
\r
+Many of these parameters are passed through to the C SDK directly. However, the entity handler is a proxy function for the handler passed from OCPlatform::registerResource(...).\r
+ \r
@section Register_Resource_CPP Register Resource in C++ [Server]\r
\r
@code{.cpp}\r
\r
@endcode\r
\r
-@section Register_Resource_C Register Resource in C [Server]\r
-@code{.c}\r
-void MyEntityHandler(OCEntityHandlerFlag flag, OCEntityHandlerRequest * request){\r
- \r
-}\r
\r
-void createLightResource() {\r
- OCResourceHandle handle;\r
\r
- OCStackResult res = OCCreateResource(&handle,\r
- "alpha.light",\r
- "oc.mi.a",\r
- "/light/1",\r
- OC_DISCOVERABLE|OC_OBSERVABLE);\r
-}\r
+********************************************************************\r
\r
+@page Guide_Find_Resource Finding A Resource\r
\r
-@endcode\r
+This operation returns all resources of given type on the network service. This operation is sent via multicast to all services. However, the filter limits the responders to just those that support the resource type in the query. Currently only exact matches are supported.\r
\r
+@image HTML seq_find_resource_2.png\r
\r
-********************************************************************\r
+@section Find_Resource_SD Sequence Diagram\r
\r
-@page Guide_Find_Resource Finding A Resource\r
+The following sequence diagram illustrates the resource discovery process over the network when using CoAP. The mechanism is different for Bluetooth, SSDP/HTTP, etc. In the case of CoAP, a 'get' request is sent via multicast to all IoTivity devices. Each device processes the query and responds if the request filter is satisfied. \r
+\r
+In the following example, the client requests all of the light resources with a resource type (rt). Both lights respond to the request, but the fan does not.\r
+\r
+@image HTML seq_find_resource_3.png\r
\r
-This operation will return all of the resources of a given type on the network service. This operation is sent via multicast to all services. However, the filter limits the responders to just those that support the resource type in the query. Again, currently, only exact matches are supported.\r
\r
-@section Find_Resource_SD Sequence Diagram\r
The following sequence diagram describes the call sequence for discovery from the client side.\r
@image HTML seq_find_resource.png\r
\r
Notes:\r
+\li Assuming that the client has a properly initialized OCPlatform object, a C++ SDK client can discover resources by calling OCPlatform::findResources(...).\r
\r
-1) Assuming that the client has a properly initialized OCPlatform object, a C++ SDK client can discover resources by calling OCPlatform::findResources(...). In this example, the call would take the form platform.findResources("", "/oc/core?rt=light", findHandler). The first parameter is the URI authority (target host) which in the case where it is empty indicates that this is for all nodes. The second parameter "/oc/core?rt=light" is the URI path and URI query. The URI path ("/oc/core") indicates the resource and the URI query ("rt=light") is the filter.\r
+In this example, the call would take the form:\r
\r
-2) The SDK call findResources(...) internally delegates the call directly to the in-process or to the out-of process stack via IPC based on the stack configuration.\r
+ platform.findResources("", "/oc/core?rt=alpha.light", findHandler)\r
\r
-3) Within the stack, findResource(...) calls the C API function OCDoResource(...). In this example, the call would be OCDoResource(&handle, OC_REST_GET, "/oc/core?rt=light", 0, 0, OC_NON_CONFIRMABLE, ...)\r
+The first parameter is the URI authority (target host), which, when empty, indicates that this is for all nodes. The second parameter ("/oc/core?rt=alpha.light") is the URI path and URI query. The URI path ("/oc/core") indicates the resource and the URI query ("rt=alpha.light") is the filter.\r
\r
-4) OCDoResource determines which transport is needed to dispatch the request and delegates the call. In the case of CoAP, the following calls are made:\r
- a. Calls OCDoCoapResource(OC_REST_GET, OC_NON_CONFIRMABLE, token, "/oc/core?rt=light", 0). The token in this example is a nonce that ties a CoAP response back to the CoAP request. Internally, this method creates the CoAP PDU for dispatching.\r
- b. Calls coap_send(context, host, pdu) which is a wrapper for the implementation below.\r
- c. Calls coap_send_impl(context, host, packet) which dispatches the packet to the socket and does the appropriate CoAP bookkeeping.\r
- d. Calls OCSend(socket, buffer, size...) which is a wrapper for the socket implementation as the functions for dispatching a UDP packet can vary in the embedded systems.\r
+\li The SDK call findResources(...) internally delegates the call directly to the in-process or to the out-of process stack via IPC based on the stack configuration.\r
+\li Within the stack, findResource(...) calls the C API function OCDoResource(...). In this example, the call is OCDoResource(&handle, OC_REST_GET, "/oc/core?rt=alpha.light", 0, 0, OC_NON_CONFIRMABLE, ...)\r
+\li OCDoResource determines which transport is needed to dispatch the request and delegates the call. In the case of CoAP, the following calls are made:\r
+ - Calls OCDoCoapResource(OC_REST_GET, OC_NON_CONFIRMABLE, token, "/oc/core?rt=alpha.light", 0). The token in this example is a nonce that ties a CoAP response back to the CoAP request. Internally, this method creates the CoAP PDU for dispatching.\r
+ - Calls coap_send(context, host, pdu), which is a wrapper for the implementation below.\r
+ - Calls coap_send_impl(context, host, packet), which dispatches the packet to the socket and does the appropriate CoAP bookkeeping.\r
+ - Calls OCSend(socket, buffer, size...), which is a wrapper for the socket implementation as the functions for dispatching a UDP packet can vary in the embedded systems.\r
+\li Servers that offer the resource on the network will reply to the query. The message pump that is evoked from the OCProcess(...) function in the C SDK receives these response packets and dispatches them to the callback associated with the original request based on the CoAP message ID. These responses will come back at the timing defined by their servers. The client stack has timeouts for these responses that are listed in the appendices.\r
+\li As previously mentioned, the stack matches the response to the original request using the message ID and send the results to the callback associated with the request. At this level, the raw payload is presented in JSON format. It is the responsibility of the callback passed to OCDoResource(...) to parse this result.\r
+\li The C++ SDK provides a callback to OCDoResource(...) that will parse the results, construct collections of OCResource objects from the response, and pass them to a C++ client using the handler passed to the platform.findResource(...) method. The handler will be called once for each resource server that responds to the query.\r
\r
-5) Servers that offer the resource on the network will reply to the query. The message pump which is evoked from the OCProcess(...) function in the C SDK, receive these response packets and dispatch them to the callback associated to the original request based on the CoAP message id. These responses will come back at the timing defined by their servers. The client stack has timeouts for these responses which are listed in the appendices.\r
+Notes:\r
+\li Some of the API call parameters have been omitted for brevity.\r
+\li The findResource() method can be used in the following ways:\r
+ - Find all resources on the network that match the provided criteria\r
+ - Query a specific (single) server for the resources that it provides matching the provided criteria\r
+\li The findResource() method may be used multiple times to find a resource\r
+\li The findResource() callback is called from the message pump thread in multithreaded environments\r
+\li Blocking in the findResource() callback will block other stack processing including servicing the network I/O which can cause delays and missed packets.\r
\r
-6) As mentioned above the stack matches the response to the original request using the message id and send the results to the callback associated with the request. At this level, the raw payload in JSON format is presented. It is the responsibility of the callback passed to OCDoResource(...) to perform the parsing of this result.\r
+<b>Detailed server call sequence diagram</b>\r
+The following sequence diagram illustrates the call sequence for discovery from the server side. \r
\r
-7) The C++ SDK provides a callback to OCDoResource(...) that will parse the results and construct collections of OCResource objects from the response and pass them to a C++ client using the handler passed to the platform.findResource(...) method. Please note that the handler will be called once for each resource server that responses to the query.\r
-\r
-Notes:\r
-@li Some of the parameters of the API calls above have been omitted for brevity.\r
-@li The findResource() method can be used in the following ways:\r
-@li Find all resources on the network that match the provided criteria\r
-@li Query a specific (single) server for the resources that it provides the provided criteria\r
-@li The findResource() method may be used multiple times whenever a resource needs be found\r
-@li The findResource() callback may continue to report discovered resources up to 100 seconds\r
-@li The findResource() callback will called from the message pump thread in multithreaded environments\r
-@li Blocking in the findResource() callback will block other stack processing including servicing the network I/O which cannot only cause delays but also missed packets.\r
+@note When the request is sent to all nodes, all nodes will run through this sequence.\r
\r
+@image HTML seq_find_resource_4.png\r
\r
+Notes:\r
+\li The discovery request under CoAP is handled like any other resource GET request. The request can be received via unicast or multicast, but the response, if any, is always sent via unicast.\r
+\li The stack dispatches the request to an entity handler that is defined by the stack.\r
+\li The handler for "/oc/core", processes the URI query, if any, and builds a list of resources that match the criteria and returns the result in JSON to the network transport.\r
+\li In the case of CoAP, if the request is made to all nodes (multicast) and the resource list is empty, no response is sent to the clients. If the request is directed (unicast) or the resource list has results, the response is sent unicast back the client.\r
\r
\r
@section Find_Resource_CPP Register Resource in C++ [Client]\r
\r
@code{.cpp}\r
- // Callback to found resources\r
+// Callback to found resources\r
void foundResource(std::shared_ptr<OCResource> resource)\r
{\r
- //Handle resource found\r
+ \r
+ std::string resourceURI;\r
+ std::string hostAddress;\r
+ try\r
+ {\r
+ // Do some operations with resource object.\r
+ if(resource)\r
+ {\r
+ std::cout<<"DISCOVERED Resource:"<<std::endl;\r
+ // Get the resource URI\r
+ resourceURI = resource->uri();\r
+ std::cout << "\tURI of the resource: " << resourceURI << std::endl;\r
+\r
+ // Get the resource host address\r
+ hostAddress = resource->host();\r
+ std::cout << "\tHost address of the resource: " << hostAddress << std::endl;\r
+\r
+ // Get the resource types\r
+ std::cout << "\tList of resource types: " << std::endl;\r
+ for(auto &resourceTypes : resource->getResourceTypes())\r
+ {\r
+ std::cout << "\t\t" << resourceTypes << std::endl;\r
+ }\r
+\r
+ // Get the resource interfaces\r
+ std::cout << "\tList of resource interfaces: " << std::endl;\r
+ for(auto &resourceInterfaces : resource->getResourceInterfaces())\r
+ {\r
+ std::cout << "\t\t" << resourceInterfaces << std::endl;\r
+ }\r
+\r
+ if(resourceURI == "/a/light1")\r
+ {\r
+ // Found interested resource\r
+ }\r
+ }\r
+ else\r
+ {\r
+ // Resource is invalid\r
+ std::cout << "Resource is invalid" << std::endl;\r
+ }\r
+\r
+ }\r
+ catch(std::exception& e)\r
+ {\r
+ //log\r
+ }\r
+\r
}\r
\r
\r
OCPlatform platform(cfg);\r
\r
// Find all resources\r
- platform.findResource("", "coap://224.0.1.187/oc/core?rt=core.light", &foundResource);\r
+ platform.findResource("", "coap://224.0.1.187/oc/core?rt=alpha.light", &foundResource);\r
\r
}catch(OCException& e)\r
{\r
//Handle Error\r
}\r
\r
+\r
@endcode\r
\r
+@section Find_Resource_OTA_Request Over the air Request\r
\r
-@section Find_Resource_C Register Resource in C [Client]\r
+The request is sent to all nodes on the network:\r
\r
-@code{.c}\r
-/* This is a function called back when a device is discovered */\r
-OCStackApplicationResult applicationDiscoverCB(OCClientResponse* response) {\r
- OC_LOG(INFO, TAG, "Found resource\85 ");\r
+<table cellspacing="0" cellpadding="0" border=1>\r
\r
- /* The IP Address is in response->addr */\r
- /* The JSON Payload is in response->resJSONPayload */\r
+<tr>\r
+<td valign="top" ><p>Field</p></td>\r
+<td valign="top" ><p>Value</p></td>\r
+<td valign="top" ><p>Note(s)</p></td>\r
+</tr>\r
\r
- return OC_STACK_KEEP_TRANSACTION;\r
-}\r
+<tr>\r
+<td valign="top" ><p>Address</p></td>\r
+<td valign="top" ><p>224.0.1.187:5683</p></td>\r
+<td valign="top" ><p>Multicast packet</p></td>\r
+</tr>\r
\r
-int main() {\r
- /* Initialize OCStack */\r
+<tr>\r
+<td valign="top" ><p>Header</p></td>\r
+<td valign="top" ><p>NON, GET, MID=0x7d40</p></td>\r
+<td valign="top" ><p>Multicast discovery request should be non-confirmable</p></td>\r
+</tr>\r
\r
- /* Start a discovery query*/\r
- char szQueryUri[64] = { 0 };\r
- strcpy(szQueryUri, OC_EXPLICIT_DEVICE_DISCOVERY_URI); OCStackResult\r
+<tr>\r
+<td valign="top" ><p>URI-Path</p></td>\r
+<td valign="top" ><p>oc</p></td>\r
+<td rowspan="3" valign="top" ><p>"/oc/core?rt=alpha.light"</p></td>\r
+</tr>\r
\r
- OCStackResult result = OCDoResource(\r
- OC_REST_GET,\r
- szQueryUri,\r
- 0,\r
- 0,\r
- OC_NON_CONFIRMABLE,\r
- applicationDiscoverCB)\r
+<tr>\r
+<td valign="top" ><p>URI-Path</p></td>\r
+<td valign="top" ><p>core</p></td>\r
+</tr>\r
\r
- if (result != OC_STACK_OK) {\r
- OC_LOG(ERROR, TAG, "OCStack resource error");\r
- return 0;\r
- }\r
+<tr>\r
+<td valign="top" ><p>URI-Query</p></td>\r
+<td valign="top" ><p>rt=alpha.light</p></td>\r
+<td valign="middle" ><p><br />\r
+</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Accept</p></td>\r
+<td valign="top" ><p>application/json</p></td>\r
+<td valign="top" ><p><br />\r
+</p></td>\r
+</tr>\r
+\r
+\r
+</table>\r
+\r
+\r
+\r
+@section Find_Resource_OTA_Response Over the air Response(s)\r
+\r
+Assuming that all of the representative devices (see @ref Guide_Representative_Devices "Representative Devices") are online, three responses are expected. Only the three devices with light resources respond; the list of resources has been filtered to contain just the resources that match the criteria.\r
+\r
+<b>From 192.168.1.11</b>:\r
+\r
+<table cellspacing="0" cellpadding="0" border=1> \r
+<tr>\r
+<td valign="top" ><p>Field</p></td>\r
+<td valign="top" ><p>Value</p></td>\r
+<td valign="top" ><p>Explanation</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Address</p></td>\r
+<td valign="top" ><p>192.168.1.1:5683</p></td>\r
+<td valign="top" ><p>Client Address</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Header</p></td>\r
+<td valign="top" ><p>ACK, CONTENT, MID=0x7d40</p></td>\r
+<td valign="top" ><p>Success w/content</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Content</p>\r
+\r
+<p>Format</p></td>\r
+<td valign="top" ><p>application/json</p></td>\r
+<td valign="top" ><p><br />\r
+</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Payload</p></td>\r
+<td valign="top" ><p>[</p>\r
+\r
+<p>{ "href" : "/light/1", "rt":["alpha.light"], "if":["oc.mi.def"], "obs":1}</p>\r
+\r
+<p>]</p></td>\r
+<td valign="top" ><p><br />\r
+</p></td>\r
+</tr>\r
+\r
+</table>\r
+\r
+<b>From 192.168.1.12</b>:\r
+\r
+<table cellspacing="0" cellpadding="0" border=1>\r
+\r
+<tr>\r
+<td valign="top" ><p>Field</p></td>\r
+<td valign="top" ><p>Value</p></td>\r
+<td valign="top" ><p>Explanation</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Address</p></td>\r
+<td valign="top" ><p>192.168.1.1:5683</p></td>\r
+<td valign="top" ><p>Client Address</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Header</p></td>\r
+<td valign="top" ><p>ACK, CONTENT, MID=0x7d40</p></td>\r
+<td valign="top" ><p>Success w/content</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Content</p>\r
+\r
+<p>Format</p></td>\r
+<td valign="top" ><p>application/json</p></td>\r
+<td valign="top" ><p><br />\r
+</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Payload</p></td>\r
+<td valign="top" ><p>[</p>\r
+\r
+<p>{ "href" : "/light/2", "rt":["alpha.light"], "if":["oc.mi.def"], "obs":1}</p>\r
+\r
+<p>]</p></td>\r
+<td valign="top" ><p><br />\r
+</p></td>\r
+</tr>\r
+\r
+</table>\r
\r
- /* Call OCProcess() until done */\r
-}\r
\r
-@endcode\r
+\r
+<b>From 192.168.1.13</b>:\r
+\r
+<table cellspacing="0" cellpadding="0" border=1> \r
+<tr>\r
+<td valign="top" ><p>Field</p></td>\r
+<td valign="top" ><p>Value</p></td>\r
+<td valign="top" ><p>Explanation</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Address</p></td>\r
+<td valign="top" ><p>192.168.1.1:5683</p></td>\r
+<td valign="top" ><p>Client Address</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Header</p></td>\r
+<td valign="top" ><p>ACK, CONTENT, MID=0x7d40</p></td>\r
+<td valign="top" ><p>Success w/content</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Content</p>\r
+\r
+<p>Format</p></td>\r
+<td valign="top" ><p>application/json</p></td>\r
+<td valign="top" ><p><br />\r
+</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Payload</p></td>\r
+<td valign="top" ><p>[</p>\r
+\r
+<p>{ "href" : "/light/1", "rt":["alpha.light"], "if":["oc.mi.def"], "obs":1},</p>\r
+\r
+<p>{ "href" : "/light/2", "rt":["alpha.light"], "if":["oc.mi.def"], "obs":1}</p>\r
+\r
+<p>]</p></td>\r
+<td valign="top" ><p><br />\r
+</p></td>\r
+</tr>\r
+\r
+</table>\r
+\r
\r
\r
********************************************************************\r
\r
@page Guide_PUT Setting a resource state [PUT]\r
\r
+This operation sets the value of a simple resource. In this example, we turn on a light resource and set the brightness to 50%.\r
+\r
@section PUT_SD Sequence Diagram\r
\r
@image HTML seq_put.png\r
\r
-@section PUT_Server_CPP Set Resource's State [PUT] in C++ [Server]\r
+Steps:\r
+1. The client application calls resource.put(...) to set representation of resource. \r
+Example call: \r
+resource.put(attributeMap, queryParamsMap, &onPut); \r
+2. Client SDK internally calls the setResourceAttributes function of the client wrapper.\r
+Example call:\r
+OCDoResource(OC_REST_PUT, "//192.168.1.11/light/1, 0, 0, OC_CONFIRMABLE, callback);\r
+3. Send PUT request to remote device\r
+4. The OCProcess() service function (server-side message pump) reads the packet from the socket and dispatches the request to the entity handler for the provided URI.\r
+5. The entity handler, which was provided by an upper layer when the resource was registered, parses the representation and in the case of the C++ API passes the results to the upper layer handler. In a C only environment, the results would also be processed in the entity handler.\r
+6. The upper layer entity handler written by the app developer/vendor is invoked, and response is formed accordingly.\r
+7. The upper layer entity handler returns success or failure with a response.\r
+8. Returns success or failure to lower layer for transmission to client.\r
+9. Returns success or failure to lower layer for transmission to client.\r
+10. Returns success or failure to lower layer for transmission to client.\r
+11. Result is formatted and sent over network to client\r
+12. The OCProcess() service function (client-side message pump) reads results and passes the results back to the client application via the callback passed to OCDoResource\r
+\r
+\r
@section PUT__Client_CPP Set Resource's State [PUT] in C++ [Client]\r
\r
-@section PUT_Server_C Set Resource's State [PUT] in C [Server]\r
-@section PUT_Client_C Set Resource's State [PUT] in C [Client]\r
+@code{.cpp}\r
+void putLightRepresentation(std::shared_ptr<OCResource> resource)\r
+{\r
+ if(resource)\r
+ {\r
+ OCRepresentation rep;\r
+\r
+ std::cout << "Putting light representation..."<<std::endl;\r
+ // Create AttributeMap\r
+ AttributeMap attributeMap;\r
+ // Add the attribute name and values in the attribute map\r
+ AttributeValues stateVal;\r
+ stateVal.push_back("true");\r
+\r
+ AttributeValues powerVal;\r
+ powerVal.push_back("10");\r
+\r
+ attributeMap["state"] = stateVal;\r
+ attributeMap["power"] = powerVal;\r
+\r
+ // Create QueryParameters Map and add query params (if any)\r
+ QueryParamsMap queryParamsMap;\r
+\r
+ rep.setAttributeMap(attributeMap);\r
\r
+ // Invoke resource's put API with attribute map, query map and the callback parameter\r
+ resource->put(rep, queryParamsMap, &onPut);\r
+ }\r
+}\r
+\r
+// callback handler on PUT request\r
+void onPut(const OCRepresentation& rep, const int eCode)\r
+{\r
+ if(eCode == SUCCESS_RESPONSE)\r
+ {\r
+ std::cout << "PUT request was successful" << std::endl;\r
+\r
+ AttributeMap attributeMap = rep.getAttributeMap();\r
+\r
+ for(auto it = attributeMap.begin(); it != attributeMap.end(); ++it)\r
+ {\r
+ std::cout << "\tAttribute name: "<< it->first << " value: ";\r
+ for(auto valueItr = it->second.begin(); valueItr != it->second.end(); ++valueItr)\r
+ {\r
+ std::cout <<"\t"<< *valueItr << " ";\r
+ }\r
+\r
+ std::cout << std::endl;\r
+ }\r
+\r
+ std::vector<OCRepresentation> children = rep.getChildren();\r
+\r
+ for(auto oit = children.begin(); oit != children.end(); ++oit)\r
+ {\r
+ attributeMap = oit->getAttributeMap();\r
+\r
+ for(auto it = attributeMap.begin(); it != attributeMap.end(); ++it)\r
+ {\r
+ std::cout << "\tAttribute name: "<< it->first << " value: ";\r
+ for(auto valueItr = it->second.begin(); valueItr != it->second.end(); ++valueItr)\r
+ {\r
+ std::cout <<"\t"<< *valueItr << " ";\r
+ }\r
+\r
+ std::cout << std::endl;\r
+ }\r
+ }\r
+\r
+ }\r
+ else\r
+ {\r
+ std::cout << "onPut Response error: " << eCode << std::endl;\r
+ std::exit(-1);\r
+ }\r
+}\r
+\r
+@endcode\r
\r
+@section PUT_Server_CPP Set Resource's State [PUT] in C++ [Server]\r
+\r
+@code{.cpp}\r
+//Entity handle sample for PUT\r
+ if(requestType == "PUT")\r
+ {\r
+ cout << "\t\t\trequestType : PUT\n";\r
+\r
+ // Check for query params (if any)\r
+ QueryParamsMap queryParamsMap = request->getQueryParameters();\r
+\r
+ cout << "\t\t\tquery params: \n";\r
+ for(auto it = queryParamsMap.begin(); it != queryParamsMap.end(); it++)\r
+ {\r
+ cout << "\t\t\t\t" << it->first << ":" << it->second << endl;\r
+ }\r
+\r
+ // Get the representation from the request\r
+ OCRepresentation rep = request->getResourceRepresentation();\r
+\r
+ myLightResource.setRepresentation(rep); // See code snippet below\r
+\r
+ // Do related operations related to PUT request // See code snippet below\r
+ rep = myLightResource.getRepresentation();\r
+\r
+ if(response)\r
+ {\r
+ \r
+ response->setErrorCode(200);\r
+\r
+ auto findRes = queryParamsMap.find("if");\r
+\r
+ if(findRes != queryParamsMap.end())\r
+ {\r
+ response->setResourceRepresentation(rep, findRes->second);\r
+ }\r
+ else\r
+ {\r
+ response->setResourceRepresentation(rep, DEFAULT_INTERFACE);\r
+ }\r
+ }\r
+}\r
+\r
+ void setRepresentation(OCRepresentation& light)\r
+ {\r
+ AttributeMap attributeMap = light.getAttributeMap();\r
+\r
+ if(attributeMap.find("state") != attributeMap.end() && attributeMap.find("power") != attributeMap.end())\r
+ {\r
+ cout << "\t\t\t" << "Received representation: " << endl;\r
+ cout << "\t\t\t\t" << "power: " << attributeMap["power"][0] << endl;\r
+ cout << "\t\t\t\t" << "state: " << attributeMap["state"][0] << endl;\r
+\r
+ m_state = attributeMap["state"][0].compare("true") == 0;\r
+ m_power= std::stoi(attributeMap["power"][0]);\r
+ }\r
+ }\r
+\r
+ OCRepresentation getRepresentation()\r
+ {\r
+ OCRepresentation light;\r
+\r
+ light.setUri(m_lightUri);\r
+\r
+ std::vector<std::string> interfaces;\r
+ //interfaces.push_back(m_lightInterface);\r
+\r
+ light.setResourceInterfaces(interfaces);\r
+\r
+ std::vector<std::string> types;\r
+ //types.push_back(m_lightType);\r
+\r
+ light.setResourceTypes(types);\r
+\r
+ AttributeMap attributeMap;\r
+ AttributeValues stateVal;\r
+ if(m_state)\r
+ {\r
+ stateVal.push_back("true");\r
+ }\r
+ else\r
+ {\r
+ stateVal.push_back("false");\r
+ }\r
+\r
+ AttributeValues powerVal;\r
+ powerVal.push_back(to_string(m_power));\r
+\r
+ attributeMap["state"] = stateVal;\r
+ attributeMap["power"] = powerVal;\r
+\r
+ light.setAttributeMap(attributeMap);\r
+\r
+ return light;\r
+ }\r
+\r
+@endcode\r
+\r
+\r
+@section PUT_OTA_Response Over the air request\r
+\r
+In this example, we are pushing state to one of the lights. At this point, the resource was discovered by its type, and we understand its interface and the attributes exposed by the resource.\r
+\r
+<table cellspacing="0" cellpadding="0" border=1> \r
+\r
+<tr>\r
+<td valign="top" ><p>Field</p></td>\r
+<td valign="top" ><p>Value</p></td>\r
+<td valign="top" ><p>Note(s)</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Address</p></td>\r
+<td valign="top" ><p>192.168.1.13:5683</p></td>\r
+<td valign="top" ><p>Unicast packet</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Header</p></td>\r
+<td valign="top" ><p>CON, PUT, MID=0x7d41</p></td>\r
+<td valign="top" ><p>Confirmation is requested</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>URI-Path</p></td>\r
+<td valign="top" ><p>light</p></td>\r
+<td rowspan="2" valign="top" ><p>"/light/1"</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>URI-Path</p></td>\r
+<td valign="top" ><p>1</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Content-Type</p></td>\r
+<td valign="top" ><p>application/json</p></td>\r
+<td valign="top" ><p><br />\r
+</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Payload</p></td>\r
+<td valign="top" ><p>{</p>\r
+\r
+<p>"power" : 1,</p>\r
+\r
+<p>"level" : 5</p>\r
+\r
+<p>}</p></td>\r
+<td valign="top" ><p><br />\r
+</p></td>\r
+</tr>\r
+\r
+</table>\r
+\r
+\r
+@section PUT_OTA_Response Over the air response(s)\r
+\r
+Assuming that the request is valid and the resource is able to complete the transition, the following represents a successful change in state.\r
+\r
+<b>From 192.168.1.13</b>:\r
+\r
+<table cellspacing="0" cellpadding="0" border=1> \r
+\r
+<tr>\r
+<td valign="top" ><p>Field</p></td>\r
+<td valign="top" ><p>Value</p></td>\r
+<td valign="top" ><p>Explanation</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Address</p></td>\r
+<td valign="top" ><p>192.168.1.1:5683</p></td>\r
+<td valign="top" ><p>Client Address</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Header</p></td>\r
+<td valign="top" ><p>ACK, CHANGED, MID=0x7d41</p></td>\r
+<td valign="top" ><p>Success (changed)</p></td>\r
+</tr>\r
+\r
+</table>\r
\r
\r
\r
**********************************************************************\r
\r
-@page Guide_GET Quering resource State [GET]\r
+@page Guide_GET Querying resource State [GET]\r
+\r
+This operation fetches the value of a simple resource. In this example, we fetch the state from the light resource.\r
\r
@section GET_SD Sequence Diagram\r
@image HTML seq_get.png\r
\r
-@section GET_Server_CPP Quering resource State [GET] in C++ [Server]\r
-@section GET_Client_CPP Quering resource State [GET] in C++ [Client]\r
+Steps:\r
+1. The client application calls resource.get(...) to retrieve a representation from the resources.\r
+2. The call is marshalled to the stack which is either running in-process or out-of-process (daemon).\r
+3. The C API is called to dispatch the request. The call may look like the following:\r
+OCDoResource(OC_REST_GET, "//192.168.1.11/light/1, 0, 0, OC_CONFIRMABLE, callback); \r
+4. Where CoAP is used as a transport, the lower stack will send a GET request to the target server.\r
+5. 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.\r
+6. Where the C++ API is used, the C++ entity handler parses the payload and marshals it to the client application depending on if the server stack is running in-process or out-of-process (daemon).\r
+7. The C++ SDK passes it up the C++ handler associated with the OCResource.\r
+8. The handler returns the result code and representation to the SDK.\r
+9. The SDK marshals the result code and representation to the C++ entity handler.\r
+10. The entity handler returns the result code and representation to the CoAP protocol.\r
+11. The CoAP protocol transports the results to the client device.\r
+12. The results are returned the OCDoResource callback.\r
+13. The results are returned to the C++ client application's asyncResultCallback.\r
+\r
+@section GET_Client_CPP Querying resource State [GET] in C++ [Client]\r
+@code{.cpp}\r
+// Local function to get representation of light resource\r
+void getLightRepresentation(std::shared_ptr<OCResource> resource)\r
+{\r
+ if(resource)\r
+ {\r
+ std::cout << "Getting Light Representation..."<<std::endl;\r
+ // Invoke resource's get API with the callback parameter\r
+\r
+ QueryParamsMap test;\r
+ resource->get(test, &onGet);\r
+ }\r
+}\r
+\r
+// callback handler on GET request\r
+void onGet(const OCRepresentation& rep, const int eCode)\r
+{\r
+ if(eCode == SUCCESS_RESPONSE)\r
+ {\r
+ std::cout << "GET request was successful" << std::endl;\r
+\r
+ AttributeMap attributeMap = rep.getAttributeMap();\r
+\r
+ std::cout << "Resource URI: " << rep.getUri() << std::endl;\r
+\r
+ for(auto it = attributeMap.begin(); it != attributeMap.end(); ++it)\r
+ {\r
+ std::cout << "\tAttribute name: "<< it->first << " value: ";\r
+ for(auto valueItr = it->second.begin(); valueItr != it->second.end(); ++valueItr)\r
+ {\r
+ std::cout <<"\t"<< *valueItr << " ";\r
+ }\r
+\r
+ std::cout << std::endl;\r
+ }\r
+\r
+ std::vector<OCRepresentation> children = rep.getChildren();\r
+\r
+ for(auto oit = children.begin(); oit != children.end(); ++oit)\r
+ {\r
+ std::cout << "Child Resource URI: " << oit->getUri() << std::endl;\r
+\r
+ attributeMap = oit->getAttributeMap();\r
+\r
+ for(auto it = attributeMap.begin(); it != attributeMap.end(); ++it)\r
+ {\r
+ std::cout << "\tAttribute name: "<< it->first << " value: ";\r
+ for(auto valueItr = it->second.begin(); valueItr != it->second.end(); ++valueItr)\r
+ {\r
+ std::cout <<"\t"<< *valueItr << " ";\r
+ }\r
+\r
+ std::cout << std::endl;\r
+ }\r
+ }\r
+\r
+ putLightRepresentation(curResource);\r
+ }\r
+ else\r
+ {\r
+ std::cout << "onGET Response error: " << eCode << std::endl;\r
+ std::exit(-1);\r
+ }\r
+}\r
+\r
+\r
+@endcode\r
+\r
+@section GET_Server_CPP Querying resource State [GET] in C++ [Server]\r
+@code{.cpp}\r
+\r
+// Handling GET request in Entity handler \r
+if(requestType == "GET")\r
+ {\r
+ cout << "\t\t\trequestType : GET\n";\r
+\r
+ // Check for query params (if any)\r
+ QueryParamsMap queryParamsMap = request->getQueryParameters();\r
+\r
+ cout << "\t\t\tquery params: \n";\r
+ for(QueryParamsMap::iterator it = queryParamsMap.begin(); it != queryParamsMap.end(); it++)\r
+ {\r
+ cout << "\t\t\t\t" << it->first << ":" << it->second << endl;\r
+ }\r
+\r
+ // Process query params and do required operations ..\r
+\r
+ // Get the representation of this resource at this point and send it as response\r
+ // AttributeMap attributeMap;\r
+ OCRepresentation rep;\r
+ rep = myLightResource.getRepresentation();\r
+\r
+ if(response)\r
+ {\r
+ // TODO Error Code\r
+ response->setErrorCode(200);\r
+\r
+ auto findRes = queryParamsMap.find("if");\r
+\r
+ if(findRes != queryParamsMap.end())\r
+ {\r
+ response->setResourceRepresentation(rep, findRes->second);\r
+ }\r
+ else\r
+ {\r
+ response->setResourceRepresentation(rep, DEFAULT_INTERFACE);\r
+ }\r
+ }\r
+ }\r
+\r
+\r
+@endcode\r
+\r
+\r
+@section GET_OTA_Response Over the air request\r
+\r
+In this example, we are querying state from one of the lights. At this point, the resource was discovered by its type, and we understand its interface and the attributes that the resource exposes.\r
+\r
+<table cellspacing="0" cellpadding="0" border=1>\r
+\r
+<tr>\r
+<td valign="top" ><p>Field</p></td>\r
+<td valign="top" ><p>Value</p></td>\r
+<td valign="top" ><p>Note(s)</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Address</p></td>\r
+<td valign="top" ><p>192.168.1.11:5683</p></td>\r
+<td valign="top" ><p>Unicast packet</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Header</p></td>\r
+<td valign="top" ><p>CON, GET, MID=0x7d42</p></td>\r
+<td valign="top" ><p>Confirmation is requested</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>URI-Path</p></td>\r
+<td valign="top" ><p>light</p></td>\r
+<td rowspan="2" valign="top" ><p>"/light/1"</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>URI-Path</p></td>\r
+<td valign="top" ><p>1</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Accept</p></td>\r
+<td valign="top" ><p>application/json</p></td>\r
+<td valign="top" ><p><br />\r
+</p></td>\r
+</tr>\r
+\r
+</table>\r
+\r
+\r
+\r
+@section GET_OTA_Response Over the air response(s)\r
+\r
+Assuming that the request is valid, we expect the following reply from the resource.\r
+\r
+<b>From 192.168.1.11</b>:\r
+\r
+<table cellspacing="0" cellpadding="0" border=1> \r
+<tr>\r
+<td valign="top" ><p>Field</p></td>\r
+<td valign="top" ><p>Value</p></td>\r
+<td valign="top" ><p>Explanation</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Address</p></td>\r
+<td valign="top" ><p>192.168.1.1:5683</p></td>\r
+<td valign="top" ><p>Client Address</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Header</p></td>\r
+<td valign="top" ><p>ACK, CONTENT, MID=0x7d42</p></td>\r
+<td valign="top" ><p>Success w/Content</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Content</p>\r
+\r
+<p>Type</p></td>\r
+<td valign="top" ><p>application/json</p></td>\r
+<td valign="top" ><p><br />\r
+</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Payload</p></td>\r
+<td valign="top" ><p>{</p>\r
+\r
+<p>"power" : 0,</p>\r
+\r
+<p>"level" : 10</p>\r
+\r
+<p>}</p></td>\r
+<td valign="top" ><p><br />\r
+</p></td>\r
+</tr>\r
+\r
+</table>\r
\r
-@section GET_Server_C Quering resource State [GET] in C [Server]\r
-@section GET_Client_C Quering resource State [GET] in C [Client]\r
\r
\r
\r
\r
@page Guide_Observe Observing resource state [Observe]\r
\r
+This operation fetches and registers as an observer for the value of a simple resource. In this example, we fetch the state of the light resource. For more implementation details, see "Observing Resources in CoAP" listed in the referenced documents. (https://datatracker.ietf.org/doc/draft-ietf-core-observe/?include_text=1)\r
+\r
+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.\r
+\r
+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.\r
+\r
+If the observed resource is removed, the server sends a NOTFOUND status to all observers.\r
+\r
+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.\r
+\r
+\r
@section Observe_SD Sequence Diagram\r
@image HTML seq_observe.png\r
\r
-@section Observe_Server_CPP Observing resource state [Observe] in C++ [Server]\r
+Steps:\r
+1. The client application calls resource.observe(...) to retrieve a representation from the resources.\r
+2. The call is marshalled to the stack which is either running in-process or out-of-process (daemon).\r
+3. The C API is called to dispatch the request. The call may look like this:\r
+OCDoResource(OC_REST_GET | OC_REST_OBSERVE, "//192.168.1.11/light/1, 0, 0, OC_CONFIRMABLE, callback);\r
+4. 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.\r
+5. 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.\r
+6. Where the C++ API is used the C++ entity handler parses the payload and marshals it to the client application depending on if the server stack is running in-process or out-of-process (daemon).\r
+7. The C++ SDK passes it up the C++ handler associated with the OCResource.\r
+8. The handler returns the result code and representation to the SDK.\r
+9. The SDK marshals the result code and representation to the C++ entity handler.\r
+10. The entity handler returns the result code and representation to the CoAP protocol.\r
+11. The CoAP protocol transport the results to the client device.\r
+12. The results are returned to the OCDoResource callback.\r
+13. The results are returned to the C++ client application's asyncResultCallback.\r
+14. If the entity handler has registered observers, it will periodically be called with the observe flag set so that it may sample or poll underlying hardware to determine if the state has changes.\r
+15. When the application has deemed that the resource state has changed either via polling (entity handler observe) or via external signal, the application should call OCNotifyObservers(). This tells the stack the observers need updating.\r
+16. For each observer of a changed resource, the entity handler is called to generate a representation that is transmitted to the observing clients. \r
+17. Where CoAP is used as a transport, a packet with content is sent to the devices that have observing clients. The packets may be confirmable or non-confirmable based on application needs.\r
+18. The client-side OCProcess function (message pump) receives the message and matches it to the original request based on the CoAP token ID and dispatches the appropriate \r
+C API callback.\r
+19. The C API callback passes the final results to the C++ client application's asyncResultCallback.\r
+20. When the C++ client no longer desires to receive notifications from the server, it calls observation cancellation method cancelObserve(). \r
+21. The C++ cancellation method calls the OCCancel() function from the C API.\r
+22. OCCancel() finds the observation that is associated with the operation and sends an observe deregistration request to the server.\r
+\r
+\r
@section Observe_Client_CPP Observing resource state [Observe] in C++ [Client]\r
+@code{.cpp}\r
+ if (OBSERVE_TYPE_TO_USE == ObserveType::Observe)\r
+ std::cout << endl << "Observe is used." << endl << endl;\r
+ else if (OBSERVE_TYPE_TO_USE == ObserveType::ObserveAll)\r
+ std::cout << endl << "ObserveAll is used." << endl << endl;\r
+\r
+ QueryParamsMap test;\r
+\r
+ curResource->observe(OBSERVE_TYPE_TO_USE, test, &onObserve);\r
+\r
+// callback\r
+void onObserve(const OCRepresentation& rep, const int& eCode, const int& sequenceNumber)\r
+{\r
+ if(eCode == SUCCESS_RESPONSE)\r
+ {\r
+ AttributeMap attributeMap = rep.getAttributeMap();\r
+\r
+ std::cout << "OBSERVE RESULT:"<<std::endl;\r
+ std::cout << "\tSequenceNumber: "<< sequenceNumber << endl;\r
+ for(auto it = attributeMap.begin(); it != attributeMap.end(); ++it)\r
+ {\r
+ std::cout << "\tAttribute name: "<< it->first << " value: ";\r
+ for(auto valueItr = it->second.begin(); valueItr != it->second.end(); ++valueItr)\r
+ {\r
+ std::cout <<"\t"<< *valueItr << " ";\r
+ }\r
+\r
+ std::cout << std::endl;\r
+ }\r
+\r
+ if(observe_count() > 30)\r
+ {\r
+ std::cout<<"Cancelling Observe..."<<std::endl;\r
+ OCStackResult result = curResource->cancelObserve();\r
+\r
+ std::cout << "Cancel result: "<< result <<std::endl;\r
+ sleep(10);\r
+ std::cout << "DONE"<<std::endl;\r
+ std::exit(0);\r
+ }\r
+ }\r
+ else\r
+ {\r
+ std::cout << "onObserve Response error: " << eCode << std::endl;\r
+ std::exit(-1);\r
+ }\r
+}\r
+\r
+\r
+@endcode\r
+\r
+\r
+\r
+@section Observe_Server_CPP Observing resource state [Observe] in C++ [Server]\r
+@code{.cpp}\r
+// Handling observe in server's entity handler \r
+if(requestFlag == RequestHandlerFlag::ObserverFlag)\r
+ {\r
+ pthread_t threadId;\r
+\r
+ cout << "\t\trequestFlag : Observer\n";\r
+ gObservation = 1;\r
+\r
+ static int startedThread = 0;\r
+\r
+ // Observation happens on a different thread in ChangeLightRepresentation function.\r
+ // If we have not created the thread already, we will create one here.\r
+ if(!startedThread)\r
+ {\r
+ pthread_create (&threadId, NULL, ChangeLightRepresentation, (void *)NULL);\r
+ startedThread = 1;\r
+ }\r
+\r
+// ChangeLightRepresentaion is an observation function,\r
+// which notifies any changes to the resource to stack\r
+// via notifyObservers\r
+void * ChangeLightRepresentation (void *param)\r
+{\r
+ // This function continuously monitors for the changes\r
+ while (1)\r
+ {\r
+ sleep (5);\r
+\r
+ if (gObservation)\r
+ {\r
+ // If under observation if there are any changes to the light resource\r
+ // we call notifyObservors\r
+ //\r
+ // For demostration we are changing the power value and notifying.\r
+ myLightResource.m_power += 10;\r
+\r
+ cout << "\nPower updated to : " << myLightResource.m_power << endl;\r
+ cout << "Notifying observers with resource handle: " << myLightResource.getHandle() << endl;\r
+\r
+ OCStackResult result = OCPlatform::notifyObservers(myLightResource.getHandle());\r
+\r
+ if(OC_STACK_NO_OBSERVERS == result)\r
+ {\r
+ cout << "No More observers, stopping notifications" << endl;\r
+ gObservation = 0;\r
+ }\r
+ }\r
+ }\r
+\r
+ return NULL;\r
+}\r
+\r
+\r
+@endcode\r
+\r
+\r
+\r
+\r
+@section Oberve_OTA_Response Over the air request\r
+\r
+The following observation request is basically a GET request with the observation option set.\r
+\r
+<table cellspacing="0" cellpadding="0" border=1> \r
+<tr>\r
+<td valign="top" ><p>Fields</p></td>\r
+<td valign="top" ><p>Value</p></td>\r
+<td valign="top" ><p>Notes</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Address</p></td>\r
+<td valign="top" ><p>192.168.1.11:5683</p></td>\r
+<td valign="top" ><p>Unicast packet</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Header</p></td>\r
+<td valign="top" ><p>CON, GET, MID=0x7d44, TOK=0x3f</p></td>\r
+<td valign="top" ><p>Confirmation requested</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Observe</p></td>\r
+<td valign="top" ><p>Register (0)</p></td>\r
+<td valign="top" ><p>This indicates registration</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>URI-Path</p></td>\r
+<td valign="top" ><p>Light</p></td>\r
+<td valign="top" ><p>"/light/1 "</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>URI-Path</p></td>\r
+<td valign="top" ><p>1</p></td>\r
+<td valign="top" ><p><br />\r
+</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Accept</p></td>\r
+<td valign="top" ><p>application/json</p></td>\r
+<td valign="top" ><p>Requesting result in JSON</p></td>\r
+</tr>\r
+\r
+</table>\r
+\r
+\r
+\r
+@section Observe_OTA_Response Over the air response(s)\r
+\r
+A successful observe request would be similar to the following:\r
+\r
+<table cellspacing="0" cellpadding="0" border=1> \r
+<tr>\r
+<td valign="top" ><p>Field</p></td>\r
+<td valign="top" ><p>Value</p></td>\r
+<td valign="top" ><p>Explanation</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Address</p></td>\r
+<td valign="top" ><p>192.168.1.1:5683</p></td>\r
+<td valign="top" ><p>Client Address</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Header</p></td>\r
+<td valign="top" ><p>ACK, CONTENT, MID=0x7d44, TOK=0x3f</p></td>\r
+<td valign="top" ><p>Success w/content</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Observe</p></td>\r
+<td valign="top" ><p>12</p></td>\r
+<td valign="top" ><p>Sequence number for ordering</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Max-Age</p></td>\r
+<td valign="top" ><p>30</p></td>\r
+<td valign="top" ><p>Indicates that the value is fresh for 30 seconds.</p>\r
+\r
+<p>It also indicates that the server should send an</p>\r
+\r
+<p>update within this time period.</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Content</p>\r
+\r
+<p>Type</p></td>\r
+<td valign="top" ><p>application/json</p></td>\r
+<td valign="top" ><p><br />\r
+</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Payload</p></td>\r
+<td valign="top" ><p>{</p>\r
+\r
+<p>"power" : 0,</p>\r
+\r
+<p>"level" : 10</p>\r
+\r
+<p>}</p></td>\r
+<td valign="top" ><p><br />\r
+</p></td>\r
+</tr>\r
+\r
+</table>\r
+\r
+<b>Subsequent Notifications from 192.168.1.1 </b>\r
+\r
+If the light resource is being observed and the light transitions from an off state to an on state, a notification is sent to the client from the server. The following is an example of such a notification:\r
+\r
+\r
+<table cellspacing="0" cellpadding="0" border=1> \r
+<tr>\r
+<td valign="top" ><p>Field</p></td>\r
+<td valign="top" ><p>Value</p></td>\r
+<td valign="top" ><p>Explanation</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Address</p></td>\r
+<td valign="top" ><p>192.168.1.1:5683</p></td>\r
+<td valign="top" ><p>Client Address</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Header</p></td>\r
+<td valign="top" ><p>CON, CONTENT, MID=0x7D45, TOK=0x3f</p></td>\r
+<td valign="top" ><p>Content, Can be confirmable or non-confirmable</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Observe</p></td>\r
+<td valign="top" ><p>15</p></td>\r
+<td valign="top" ><p>Monotonically increasing until overflow</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Max-Age</p></td>\r
+<td valign="top" ><p>30</p></td>\r
+<td valign="top" ><p>Indicates that the value is fresh for 30 seconds.</p>\r
+\r
+<p>It also indicates that the server should send an</p>\r
+\r
+<p>update within this time period.</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Payload</p></td>\r
+<td valign="top" ><p>{</p>\r
+\r
+<p>"power" : 1,</p>\r
+\r
+<p>"level" : 10</p>\r
+\r
+<p>}</p></td>\r
+<td valign="top" ><p><br />\r
+</p></td>\r
+</tr>\r
+\r
+</table>\r
+\r
+Since the above notification was marked confirmable, the client should acknowledge the notification with a packet such as the following:\r
+\r
+<table cellspacing="0" cellpadding="0" border=1> \r
+\r
+<tr>\r
+<td valign="top" ><p>Field</p></td>\r
+<td valign="top" ><p>Value</p></td>\r
+<td valign="top" ><p>Explanation</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Address</p></td>\r
+<td valign="top" ><p>192.168.1.11:5683</p></td>\r
+<td valign="top" ><p>Unicast packet</p></td>\r
+</tr>\r
+\r
+<tr>\r
+<td valign="top" ><p>Header</p></td>\r
+<td valign="top" ><p>ACK, MID=0x7D45, TOK=0x3f</p></td>\r
+<td valign="top" ><p>Success</p></td>\r
+</tr>\r
+\r
+</table>\r
+\r
\r
-@section Observe_Server_C Observing resource state [Observe] in C [Server]\r
-@section Observe_Client_C Observing resource state [Observe] in C [Client]\r
\r
\r
\r
projects / platform / upstream / iotivity.git / commitdiff
