-/*!
-
-@page OCHowTo How To... Guides
-
-[@ref GuideBuildStack]
-
-
----
-
-@section GuideBuildStack How to build the stack
-
-This guide will provide instructions on how to build the stack. Instructions provided in this guide are tested against Ubuntu 14.10, however, Ubuntu version 12.0.4 and above are supported.
-
-<b> Build Environment </b>
-
-Boost version 1.55 and G++ are required in order to build the stack. Install boot by running the following command in terminal window:
-
- sudo apt-get install libboost-all-dev
-
-Followed by installing G++ by running the following command in the terminal window:
-
- sudo apt-get install build-essential g++
-
-At this point, your development environment should be setup.
-
-<b> Building </b>
-
-Make sure oic-resource and oic-utilites are checked out in the same directory. Provided your build environment is properly setup, navigate into oic-resource repository using the terminal, which includes the make file needed the build the stack and samples. Run the <i>make</i> command which will build all the necessary components for the stack and the sample applications.
-
-All the compiled executables and libraries will be available in the same directory as the make file on successfully completing the build.
-
-*/
+/*!\r
+\r
+@page OCHowTo How To... Guides\r
+\r
+@ref Guide_Stack_Init "How to initialize the stack"\r
+\r
+@ref Guide_Register_Resource "How to register a resource"\r
+\r
+@ref Guide_Find_Resource "How to find a resource"\r
+\r
+@ref Guide_PUT "How to set resource state [PUT]"\r
+\r
+@ref Guide_GET "How to query resource state [GET]"\r
+\r
+@ref Guide_Observe "How to observe resource state [Observe]"\r
+\r
+\r
+\r
+********************************************************************\r
+\r
+@page Guide_Stack_Init Stack Initialization \r
+\r
+@section Stack_Init_SD Sequence Diagram\r
+\r
+@image html seq_stack_init.png\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
+@code {.cpp}\r
+ // Create PlatformConfig object\r
+ PlatformConfig cfg;\r
+ cfg.ipAddress = "134.134.161.33";\r
+ cfg.port = 5683;\r
+ cfg.mode = ModeType::Client;\r
+ cfg.serviceType = ServiceType::InProc;\r
+\r
+ // Create a OCPlatform instance.\r
+ // Note: Platform creation is synchronous call.\r
+\r
+ try\r
+ {\r
+ OCPlatform platform(cfg);\r
+ }catch(OCException& e)\r
+ {\r
+ //Handle error\r
+ }\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
+@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
+@endcode\r
+\r
+\r
+\r
+********************************************************************\r
+\r
+@page Guide_Register_Resource Registering A Resource \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
+\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
+\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
+@image HTML seq_register_resource.png\r
+\r
+Steps:\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
+\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
+\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
+\r
+@section Register_Resource_CPP Register Resource in C++ [Server]\r
+\r
+@code{.cpp}\r
+ OCResourceHandle resourceHandle;\r
+ std::string resourceURI = "/light/1"; \r
+ std::string resourceTypeName = "alpha.light\r
+ std::string resourceInterface = DEFAULT_INTERFACE; \r
+ uint8_t resourceProperty = OC_DISCOVERABLE | OC_OBSERVABLE;\r
+\r
+ OCStackResult result = platform.registerResource(resourceHandle, \r
+ resourceURI,\r
+ resourceTypeName,\r
+ resourceInterface,\r
+ &entityHandler,\r
+ resourceProperty);\r
+\r
+ if (OC_STACK_OK == result)\r
+ {\r
+ //Successfull\r
+ }\r
+\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
+@endcode\r
+\r
+\r
+********************************************************************\r
+\r
+@page Guide_Find_Resource Finding A Resource\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
+\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
+\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
+\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
+\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
+\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
+\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
+\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
+\r
+\r
+\r
+\r
+@section Find_Resource_CPP Register Resource in C++ [Client]\r
+\r
+@code{.cpp}\r
+ // Callback to found resources\r
+ void foundResource(std::shared_ptr<OCResource> resource)\r
+ {\r
+ //Handle resource found\r
+ }\r
+\r
+\r
+ try\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
+\r
+ }catch(OCException& e)\r
+ {\r
+ //Handle Error\r
+ }\r
+\r
+@endcode\r
+\r
+\r
+@section Find_Resource_C Register Resource in C [Client]\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
+\r
+ /* The IP Address is in response->addr */\r
+ /* The JSON Payload is in response->resJSONPayload */\r
+\r
+ return OC_STACK_KEEP_TRANSACTION;\r
+}\r
+\r
+int main() {\r
+ /* Initialize OCStack */\r
+\r
+ /* Start a discovery query*/\r
+ char szQueryUri[64] = { 0 };\r
+ strcpy(szQueryUri, OC_EXPLICIT_DEVICE_DISCOVERY_URI); OCStackResult\r
+\r
+ OCStackResult result = OCDoResource(\r
+ OC_REST_GET,\r
+ szQueryUri,\r
+ 0,\r
+ 0,\r
+ OC_NON_CONFIRMABLE,\r
+ applicationDiscoverCB)\r
+\r
+ if (result != OC_STACK_OK) {\r
+ OC_LOG(ERROR, TAG, "OCStack resource error");\r
+ return 0;\r
+ }\r
+\r
+ /* Call OCProcess() until done */\r
+}\r
+\r
+@endcode\r
+\r
+\r
+********************************************************************\r
+\r
+@page Guide_PUT Setting a resource state [PUT]\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
+@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
+\r
+\r
+\r
+\r
+\r
+**********************************************************************\r
+\r
+@page Guide_GET Quering resource State [GET]\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
+\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
+\r
+@page Guide_Observe Observing resource state [Observe]\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
+@section Observe_Client_CPP Observing resource state [Observe] in C++ [Client]\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
+**********************************************************************\r
+\r
+\r
+*/\r
-/*!
-
-@page OCGuides Programmer's Guide
-
-@section Terminology
-
-<b>Device</b>
-A constrained device that has the Thin Block stack installed which enabled one or more services for other Thin Block or Unified Block devices to consume.
-
-<b>Resource</b>
-A resource is a component in a server that can be viewed and controlled by another Thin Block or Unified Block device. There are different resource types, for example a temperature sensor, a light controller etc.
-
-Resources can be arranged in a hierarchal manner to form a tree of resources. This generic method of structure enables one to model many different topologies of resources.
-
-\li Example: A light controller could be a resource.
-\li Example: A light array could be a set of resources organized in a flat (non-hierarchical manner).
-\li Example: A garage door opener could be a resource, it could host two resource \96 light and lock.
-
-A more detailed description of resources and management of resources along with code snippets is provided later in this document.
-
-<b>Operations</b>
-Operations are actions that a Thin Block or Unified Block can perform on attributes associated with a particular resource. Resource attributes can have different operations on it based on the nature of the resource type fundamentally these are GET and PUT operations. Additionally attributes can also be declared to be observable to support remote devices to subscribe to changes to it.
-
-\li Example: One of the child resources on the garage door opener is the light control; it has a GET operation that allows a device to get the current light state (on / off).
-
-
-
-*/
\ No newline at end of file
+/*!\r
+\r
+\r
+@page OCGuides Programmer's Guide\r
+\r
+\r
+This document captures the architecture and basic operations of the Iotivity Resource API including sample coverage of protocol, flows, APIs and some use cases. It is intended to create context for the developers using IoTvitity API and provide a high level architectural overview of the framework. \r
+\r
+@section Stack_Blocks Stack Blocks\r
+\r
+The Resource API stack consists of several thin layers of software. In unconstrained environments like Android, iOS, Windows, the stack provides APIs in C and C++ which allow developers to talk to both constrained and unconstrained devices via IP networks with potential support for additional network protocols and wireless technologies. In the first release, the key technologies for connectivity include IP, UDP and the Constrained Application Protocol (CoAP).\r
+@image html stack_diagram.png\r
+\r
+@section Terminology Terminology\r
+\r
+<b>Device</b>\r
+A constrained device that has the Thin Block stack installed which enabled one or more services for other Thin Block or Unified Block devices to consume.\r
+\r
+<b>Resource</b>\r
+A resource is a component in a server that can be viewed and controlled by another Thin Block or Unified Block device. There are different resource types, for example a temperature sensor, a light controller etc.\r
+\r
+Resources can be arranged in a hierarchal manner to form a tree of resources. This generic method of structure enables one to model many different topologies of resources.\r
+\r
+@li Example: A light controller could be a resource.\r
+@li Example: A light array could be a set of resources organized in a flat (non-hierarchical manner).\r
+@li Example: A garage door opener could be a resource, it could host two resources \96 light and lock.\r
+\r
+A more detailed description of resources and management of resources along with code snippets is provided later in this document.\r
+\r
+<b>Operations</b>\r
+Operations are actions that a Thin Block or Unified Block can perform on attributes associated with a particular resource. Resource attributes can have different operations on it based on the nature of the resource type fundamentally these are GET and PUT operations. Additionally attributes can also be declared to be observable to support remote devices to subscribe to changes to it.\r
+\r
+@li Example: One of the child resources on the garage door opener is the light control; it has a GET operation that allows a device to get the current light state (on / off).\r
+\r
+@section Functionally Functionally\r
+\r
+The initial release of IoTivity includes functionally for:\r
+ @li @ref Guide_Register_Resource "Resource registration"\r
+ @li @ref Guide_Find_Resource "Resource discovery"\r
+ @li Device discovery with filtering\r
+ @li Property attributes (@ref Guide_GET "get"/ @ref Guide_PUT "set"/ @ref Guide_Observe "observe")\r
+ @li Resource tree (resources having sub-resources)\r
+ @li Presence notification service defined as a virtual resource (not detailed in this document)\r
+\r
+@section External_References External References \r
+\r
+The following references may provide guidance to this document.\r
+ @note In some places, the Iotivity design may differ from the CoRE specifications. In these cases, please consider the CoRE specifications as informative but not definitive on the Iotivity design and architecture.\r
+\r
+ @li The Constrained Application Protocol (CoAP) - https://datatracker.ietf.org/doc/rfc7252\r
+ @li Constrained RESTful Environments (CoRE) Link Format - https://datatracker.ietf.org/doc/rfc6690\r
+ @li Observing Resources in CoAP - https://datatracker.ietf.org/doc/draft-ietf-core-observe\r
+ @li CoRE Interfaces (expired draft) - https://datatracker.ietf.org/doc/draft-ietf-core-interfaces\r
+\r
+\r
+\r
+*/\r
projects / platform / upstream / iotivity.git / commitdiff
