X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=resource%2Finclude%2FOCPlatform.h;h=84e7163c9125bfeef30bf6d4c0c803989843c14a;hb=3c093548382bb2542c87a67e6e5fa32552c29cb3;hp=8639dbee0a35a05e449ff91f46c9e5e1770dc642;hpb=40e5426eb6aec432fffb1911e4cbb9752877989b;p=platform%2Fupstream%2Fiotivity.git diff --git a/resource/include/OCPlatform.h b/resource/include/OCPlatform.h index 8639dbe..84e7163 100644 --- a/resource/include/OCPlatform.h +++ b/resource/include/OCPlatform.h @@ -18,19 +18,21 @@ // //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= -/// @file OCPlatform.h - -/// @brief This file contains the declaration of classes and its members related to -/// OCPlatform. - -#ifndef __OCPLATFORM_H -#define __OCPLATFORM_H +/** + * @file + * + * This file contains the declaration of classes and its members related to + * OCPlatform. + */ + +#ifndef OC_PLATFORM_H_ +#define OC_PLATFORM_H_ #include #include namespace OC { /** - * @brief: This namespace contains the main entrance/functionality of the product. + * This namespace contains the main entrance/functionality of the product. * It may be used with OC::OCPlatform::functionName. To set a custom configuration, * the implementer must make a call to OCPlatform::Configure before the first usage * of a function in this namespace. @@ -38,49 +40,82 @@ namespace OC namespace OCPlatform { /** - * API for overwriting the default configuration of the OCPlatform object. - * Note: Any calls made to this AFTER the first call to OCPlatform::Instance - * will have no affect - */ - void Configure(const PlatformConfig& config); + * API for overwriting the default configuration of the OCPlatform object. + * @note Any calls made to this AFTER the first call to OCPlatform::Instance + * will have no affect + */ + OCStackResult Configure(const PlatformConfig& config); // typedef for handle to cancel presence info with typedef OCDoHandle OCPresenceHandle; /** - * API for notifying base that resource's attributes have changed. - * - * @param OCResourceHandle resource handle of the resource - * @param QualityOfService the quality of communication - * - * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. - * NOTE: This API is for server side only. - * NOTE: OCResourceHandle is defined in ocstack.h. - * NOTE: OCStackResult is defined in ocstack.h. - */ + * API for stop Base layer including resource and connectivity abstraction. + * + * @return Returns ::OC_STACK_OK if success. + */ + OCStackResult stop(); + + /** + * API for start Base layer including resource and connectivity abstraction. + * OCInit will be invoked. + * + * @return Returns ::OC_STACK_OK if success. + */ + OCStackResult start(); + + /** + * API for notifying base that resource's attributes have changed. + * + * @param resourceHandle resource handle of the resource + * + * @return Returns ::OC_STACK_OK if success. + * @note This API is for server side only. + * @note OCResourceHandle is defined in ocstack.h + * @note OCStackResult is defined in ocstack.h. + * @see notifyAllObservers(OCResourceHandle, QualityOfService) + */ OCStackResult notifyAllObservers(OCResourceHandle resourceHandle); + + /** + * @overload + * + * @param resourceHandle resource handle of the resource + * @param QoS the quality of communication + * @see notifyAllObservers(OCResourceHandle) + */ OCStackResult notifyAllObservers(OCResourceHandle resourceHandle, QualityOfService QoS); /** - * API for notifying only specific clients that resource's attributes have changed. - * - * @param OCResourceHandle resource handle of the resource - * @param observationIds std vector of observationIds. These set of ids are ones which - * which will be notified upon resource change. - * @param responsePtr OCResourceResponse pointer used by app to fill the response for this - * resource change. - * @param QualityOfService the quality of communication - * - * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. - * - * NOTE: This API is for server side only. - * NOTE: OCResourceHandle is defined in ocstack.h. - * NOTE: OCStackResult is defined in ocstack.h. - */ + * API for notifying only specific clients that resource's attributes have changed. + * + * @param resourceHandle resource handle of the resource + * @param observationIds std vector of observationIds. These set of ids are ones which + * which will be notified upon resource change. + * @param responsePtr OCResourceResponse pointer used by app to fill the response for this + * resource change. + * + * @return Returns ::OC_STACK_OK if success. + * @note This API is for server side only. + * @note OCResourceHandle is defined in ocstack.h. + * @note OCStackResult is defined in ocstack.h. + * @see notifyListOfObservers(OCResourceHandle, ObservationIds&, const std::shared_ptr, QualityOfService) + */ OCStackResult notifyListOfObservers( OCResourceHandle resourceHandle, ObservationIds& observationIds, const std::shared_ptr responsePtr); + /** + * @overload + * + * @param resourceHandle resource handle of the resource + * @param observationIds std vector of observationIds. These set of ids are ones which + * which will be notified upon resource change. + * @param responsePtr OCResourceResponse pointer used by app to fill the response for this + * resource change. + * @param QoS the quality of communication + * @see notifyListOfObservers(OCResourceHandle, ObservationIds&, const std::shared_ptr) + */ OCStackResult notifyListOfObservers( OCResourceHandle resourceHandle, ObservationIds& observationIds, @@ -88,91 +123,183 @@ namespace OC QualityOfService QoS); /** - * API for Service and Resource Discovery. - * NOTE: This API applies to client side only. - * - * @param host - Host IP Address of a service to direct resource discovery query. If null or - * empty, performs multicast resource discovery query - * @param resourceURI - name of the resource. If null or empty, performs search for all - * resource names - * @param handler - Handles callbacks, success states and failure states. - * - * Four modes of discovery defined as follows: - * (NULL/Empty, NULL/Empty) - Performs ALL service discovery AND ALL resource - * discovery. - * (NULL/Empty, Not Empty) - Performs query for a filtered/scoped/particular - * resource(s) from ALL services. - * (Not Empty, NULL/Empty) - Performs ALL resource discovery on a particular service. - * (Not Empty, Not Empty) - Performs query for a filtered/scoped/particular - * resource(s) - * from a particular service. - * @param QualityOfService the quality of communication - * - * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. - * NOTE: First parameter 'host' currently represents an IP address. This will change in - * future and will refer to endpoint interface so that we can refer to other transports such - * as BTH etc. - * NOTE: OCStackResult is defined in ocstack.h. - */ -#ifdef CA_INT + * API for Service and Resource Discovery. + * @note This API applies to client side only. + * + * @param host Host IP Address of a service to direct resource discovery query. If null or + * empty, performs multicast resource discovery query + * @param resourceURI name of the resource. If null or empty, performs search for all + * resource names + * @param connectivityType ::OCConnectivityType type of connectivity indicating the + * interface. Example: CT_DEFAULT, CT_ADAPTER_IP, CT_ADAPTER_TCP. + * @param resourceHandler Handles callbacks, success states and failure states. + * + * Four modes of discovery defined as follows: + * (NULL/Empty, NULL/Empty) - Performs ALL service discovery AND ALL resource + * discovery. + * (NULL/Empty, Not Empty) - Performs query for a filtered/scoped/particular + * resource(s) from ALL services. + * (Not Empty, NULL/Empty) - Performs ALL resource discovery on a particular service. + * (Not Empty, Not Empty) - Performs query for a filtered/scoped/particular + * resource(s) + * from a particular service. + * + * @return Returns ::OC_STACK_OK if success. + * @note First parameter 'host' currently represents an IP address. This will change in + * future and will refer to endpoint interface so that we can refer to other transports such + * as BTH etc. + * @note OCStackResult is defined in ocstack.h. + * @see findResource(const std::string&, const std::string&, OCConnectivityType, FindCallback, QualityOfService) + */ OCStackResult findResource(const std::string& host, const std::string& resourceURI, - uint8_t connectivityType, FindCallback resourceHandler); + OCConnectivityType connectivityType, FindCallback resourceHandler); + /** + * @overload + * + * @param host Host IP Address of a service to direct resource discovery query. If null or + * empty, performs multicast resource discovery query + * @param resourceURI name of the resource. If null or empty, performs search for all + * resource names + * @param connectivityType ::OCConnectivityType type of connectivity indicating the + * interface. Example: CT_DEFAULT, CT_ADAPTER_IP, CT_ADAPTER_TCP. + * @param resourceHandler Handles callbacks, success states and failure states. + * + * Four modes of discovery defined as follows: + * (NULL/Empty, NULL/Empty) - Performs ALL service discovery AND ALL resource + * discovery. + * (NULL/Empty, Not Empty) - Performs query for a filtered/scoped/particular + * resource(s) from ALL services. + * (Not Empty, NULL/Empty) - Performs ALL resource discovery on a particular service. + * (Not Empty, Not Empty) - Performs query for a filtered/scoped/particular + * resource(s) + * from a particular service. + * @param QoS QualityOfService the quality of communication + * @see findResource(const std::string&, const std::string&, OCConnectivityType, FindCallback) + */ OCStackResult findResource(const std::string& host, const std::string& resourceURI, - uint8_t connectivityType, FindCallback resourceHandler, QualityOfService QoS); -#else + OCConnectivityType connectivityType, FindCallback resourceHandler, + QualityOfService QoS); + OCStackResult findResource(const std::string& host, const std::string& resourceURI, - FindCallback resourceHandler); + OCConnectivityType connectivityType, FindCallback resourceHandler, + FindErrorCallback errorHandler); + OCStackResult findResource(const std::string& host, const std::string& resourceURI, - FindCallback resourceHandler, QualityOfService QoS); -#endif + OCConnectivityType connectivityType, FindCallback resourceHandler, + FindErrorCallback errorHandler, QualityOfService QoS); + + OCStackResult findResourceList(const std::string& host, const std::string& resourceURI, + OCConnectivityType connectivityType, FindResListCallback resourceHandler, + QualityOfService QoS = QualityOfService::LowQos); + + OCStackResult findResourceList(const std::string& host, const std::string& resourceURI, + OCConnectivityType connectivityType, FindResListCallback resourceHandler, + FindErrorCallback errorHandler, QualityOfService QoS = QualityOfService::LowQos); + + OCStackResult setPropertyValue(OCPayloadType type, const std::string& tag, const std::string& value); + OCStackResult setPropertyValue(OCPayloadType type, const std::string& tag, const std::vector& value); + OCStackResult getPropertyValue(OCPayloadType type, const std::string& tag, std::string& value); + OCStackResult getPropertyValue(OCPayloadType type, const std::string& tag, std::vector& value); /** * API for Device Discovery * * - * @param host - Host IP Address. If null or empty, Multicast is performed. - * @param resourceURI - Uri containing address to the virtual device in C Stack - ("/oc/core/d") - * @param QualityOfService the quality of communication + * @param host Host IP Address. If null or empty, Multicast is performed. + * @param deviceURI Uri containing address to the virtual device in C Stack + ("/oic/d") + * @param connectivityType ::OCConnectivityType type of connectivity indicating the + * interface. Example: CT_DEFAULT, CT_ADAPTER_IP, CT_ADAPTER_TCP. + * @param deviceInfoHandler device discovery callback * + * @return Returns ::OC_STACK_OK if success. + * @note OCStackResult is defined in ocstack.h. + * @see getDeviceInfo(const std::string&, const std::string&, OCConnectivityType, FindDeviceCallback, QualityOfService) */ -#ifdef CA_INT OCStackResult getDeviceInfo(const std::string& host, const std::string& deviceURI, - uint8_t connectivityType, FindDeviceCallback deviceInfoHandler); + OCConnectivityType connectivityType, FindDeviceCallback deviceInfoHandler); + /** + * @overload + * + * @param host Host IP Address. If null or empty, Multicast is performed. + * @param deviceURI Uri containing address to the virtual device in C Stack + ("/oic/d") + * @param connectivityType ::OCConnectivityType type of connectivity indicating the + * interface. Example: CT_DEFAULT, CT_ADAPTER_IP, CT_ADAPTER_TCP. + * @param deviceInfoHandler device discovery callback + * @param QoS the quality of communication + * @see getDeviceInfo(const std::string&, const std::string&, OCConnectivityType, FindDeviceCallback) + */ OCStackResult getDeviceInfo(const std::string& host, const std::string& deviceURI, - uint8_t connectivityType, FindDeviceCallback deviceInfoHandler, + OCConnectivityType connectivityType, FindDeviceCallback deviceInfoHandler, QualityOfService QoS); -#else - OCStackResult getDeviceInfo(const std::string& host, const std::string& deviceURI, - FindDeviceCallback deviceInfoHandler); - OCStackResult getDeviceInfo(const std::string& host, const std::string& deviceURI, - FindDeviceCallback deviceInfoHandler, QualityOfService QoS); -#endif + + /** + * API for Platform Discovery + * + * + * @param host Host IP Address. If null or empty, Multicast is performed. + * @param platformURI Uri containing address to the virtual platform in C Stack + ("/oic/p") + * @param connectivityType ::OCConnectivityType type of connectivity indicating the + * interface. Example: CT_DEFAULT, CT_ADAPTER_IP, CT_ADAPTER_TCP. + * @param platformInfoHandler platform discovery callback + * + * @return Returns ::OC_STACK_OK if success. + * + * @note OCStackResult is defined in ocstack.h. + * @see getPlatformInfo(const std::string&, const std::string&, OCConnectivityType, FindPlatformCallback, QualityOfService) + */ + OCStackResult getPlatformInfo(const std::string& host, const std::string& platformURI, + OCConnectivityType connectivityType, FindPlatformCallback platformInfoHandler); + /** + * @overload + * + * @param host Host IP Address. If null or empty, Multicast is performed. + * @param platformURI Uri containing address to the virtual platform in C Stack + ("/oic/p") + * @param connectivityType ::OCConnectivityType type of connectivity indicating the + * interface. Example: CT_DEFAULT, CT_ADAPTER_IP, CT_ADAPTER_TCP. + * @param platformInfoHandler platform discovery callback + * @param QoS the quality of communication + * @see getPlatformInfo(const std::string&, const std::string&, OCConnectivityType, FindPlatformCallback) + */ + OCStackResult getPlatformInfo(const std::string& host, const std::string& platformURI, + OCConnectivityType connectivityType, FindPlatformCallback platformInfoHandler, + QualityOfService QoS); + /** * This API registers a resource with the server - * NOTE: This API applies to server side only. - * - * @param resourceHandle - Upon successful registration, resourceHandle will be filled - * @param resourceURI - The URI of the resource. Example: "a/light". See NOTE below - * @param resourceTypeName - The resource type. Example: "light" - * @param resourceInterface - The resource interface (whether it is collection etc). - * @param entityHandler - entity handler callback. - * @param resourceProperty - indicates the property of the resource. Defined in ocstack.h. + * @note This API applies to server side only. + * + * @param resourceHandle Upon successful registration, resourceHandle will be filled + * @param resourceURI The URI of the resource. Example: "a/light". See NOTE below + * @param resourceTypeName The resource type. Example: "light" + * @param resourceInterface The resource interface (whether it is collection etc). + * @param entityHandler entity handler callback. + * @param resourceProperty indicates the property of the resource. Defined in ocstack.h. * setting resourceProperty as OC_DISCOVERABLE will allow Discovery of this resource * setting resourceProperty as OC_OBSERVABLE will allow observation * settings resourceProperty as OC_DISCOVERABLE | OC_OBSERVABLE will allow both discovery and * observation * - * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. - * NOTE: "a/light" is a relative URI. - * Above relative URI will be prepended (by core) with a host IP + namespace "oc" + * @return Returns ::OC_STACK_OK if success. + * @note "a/light" is a relative URI. + * Above relative URI will be prepended (by core) with a host IP + namespace "oic" * Therefore, fully qualified URI format would be //HostIP-Address/namespace/relativeURI" * Example, a relative URI: 'a/light' will result in a fully qualified URI: - * //192.168.1.1/oc/a/light" + * //192.168.1.1/oic/a/light" * First parameter can take a relative URI and core will take care of preparing the fully * qualified URI OR - * first paramter can take fully qualified URI and core will take that as is for further + * first parameter can take fully qualified URI and core will take that as is for further * operations - * NOTE: OCStackResult is defined in ocstack.h. + * @note OCStackResult is defined in ocstack.h. + * @note entity handler callback : + * When you set specific return value like OC_EH_CHANGED, OC_EH_CONTENT, + * OC_EH_SLOW and etc in entity handler callback, + * ocstack will be not send response automatically to client + * except for error return value like OC_EH_ERROR + * If you want to send response to client with specific result, + * OCDoResponse API should be called with the result value. */ OCStackResult registerResource(OCResourceHandle& resourceHandle, std::string& resourceURI, @@ -183,71 +310,81 @@ namespace OC /** * This API registers a resource with the server - * NOTE: This API applies to server & client side. - - * @param resourceHandle - Upon successful registration, resourceHandle will be filled - * @param OCResource - The instance of OCResource that all data filled. + * @note This API applies to server & client side. + * + * @param resourceHandle Upon successful registration, resourceHandle will be filled + * @param resource The instance of OCResource that all data filled. * - * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. + * @return Returns ::OC_STACK_OK if success. + * @note OCStackResult is defined in ocstack.h. */ - OCStackResult registerResource(OCResourceHandle& resourceHandle, const std::shared_ptr< OCResource > resource); /** - * Register Device Info - * - * @param deviceInfo - structure containing all the device specific information - * - * @return - * OC_STACK_OK - no errors - * OC_STACK_ERROR - stack process error - */ - + * Register Device Info + * + * @param deviceInfo structure containing all the device specific information + * @return Returns ::OC_STACK_OK if no errors and ::OC_STACK_ERROR in case of stack process error + */ OCStackResult registerDeviceInfo(const OCDeviceInfo deviceInfo); /** - * Set default device entity handler + * Register Platform Info * - * @param entityHandler - entity handler to handle requests for - * any undefined resources or default actions. - * if NULL is passed it removes the device default entity handler. + * @param platformInfo structure containing all the platform specific information + * @return Returns ::OC_STACK_OK if no errors and ::OC_STACK_ERROR in case of stack process error + */ + OCStackResult registerPlatformInfo(const OCPlatformInfo platformInfo); + + /** + * Set default device entity handler * - * @return - * OC_STACK_OK - no errors - * OC_STACK_ERROR - stack process error + * @param entityHandler entity handler to handle requests for + * any undefined resources or default actions. + * if NULL is passed it removes the device default entity handler. + * @return Returns ::OC_STACK_OK if no errors and ::OC_STACK_ERROR in case of stack process error + * @note entity handler callback : + * When you set specific return value like OC_EH_CHANGED, OC_EH_CONTENT, + * OC_EH_SLOW and etc in entity handler callback, + * ocstack will be not send response automatically to client + * except for error return value like OC_EH_ERROR + * If you want to send response to client with specific result, + * sendResponse API should be called with the result value. */ OCStackResult setDefaultDeviceEntityHandler(EntityHandler entityHandler); /** * This API unregisters a resource with the server - * NOTE: This API applies to server side only. + * @note This API applies to server side only. * - * @param resourceHandle - This is the resource handle which we which to unregister from the + * @param resourceHandle This is the resource handle which we need to unregister from the * server * - * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. - * NOTE: OCStackResult is defined in ocstack.h. + * @return Returns ::OC_STACK_OK if success. + * @note OCStackResult is defined in ocstack.h. */ OCStackResult unregisterResource(const OCResourceHandle& resourceHandle); /** * Add a resource to a collection resource. * - * @param collectionHandle - handle to the collection resource - * @param addedResourceHandle - handle to resource to be added to the collection resource - * - * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
- * NOTE: OCStackResult is defined in ocstack.h.
- * NOTE: bindResource must be used only after the both collection resource and - * resource to add under a collections are created and respective handles obtained
- * Example:
- * Step 1: registerResource(homeResourceHandle, "a/home", "home", Link_Interface, - * entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);
- * Step 2: registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface, - * entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);
- * Step 3: bindResource(homeResourceHandle, kitchenResourceHandle);
- * At the end of Step 3, resource "a/home" will contain a reference to "a/kitchen".
+ * @param collectionHandle handle to the collection resource + * @param resourceHandle handle to resource to be added to the collection resource + * + * @return Returns ::OC_STACK_OK if success. + * @note OCStackResult is defined in ocstack.h. + * @note bindResource must be used only after the both collection resource and + * resource to add under a collections are created and respective handles obtained + * + * @par Example: + * -# registerResource(homeResourceHandle, "a/home", "home", Link_Interface, + * entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE); + * -# registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface, + * entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE); + * -# bindResource(homeResourceHandle, kitchenResourceHandle); + * @par + * At the end of Step 3, resource "a/home" will contain a reference to "a/kitchen". */ OCStackResult bindResource(const OCResourceHandle collectionHandle, const OCResourceHandle resourceHandle); @@ -255,27 +392,29 @@ namespace OC /** * Add multiple resources to a collection resource. * - * @param collectionHandle - handle to the collection resource + * @param collectionHandle handle to the collection resource * @param addedResourceHandleList reference to list of resource handles to be added to the * collection resource * - * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
- * NOTE: OCStackResult is defined in ocstack.h.
- * NOTE: bindResources must be used only after the both collection resource and + * @return Returns ::OC_STACK_OK if success. + * @note OCStackResult is defined in ocstack.h. + * @note bindResources must be used only after the both collection resource and * list of resources to add under a collection are created and respective handles - * obtained
- * Example:
- * Step 1: registerResource(homeResourceHandle, "a/home", "home", Link_Interface, - * homeEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);
- * Step 2: registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface, - * kitchenEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);
- * Step 3: registerResource(roomResourceHandle, "a/room", "room", Link_Interface, - * roomEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);
- * Step 4: std::vector rList; rList.push_back(kitchenResourceHandle); - * rList.push_back(roomResourceHandle);
- * Step 5: bindResource(homeResourceHandle, rList);
+ * obtained. + * + * @par Example: + * -# registerResource(homeResourceHandle, "a/home", "home", Link_Interface, + * homeEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE); + * -# registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface, + * kitchenEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE); + * -# registerResource(roomResourceHandle, "a/room", "room", Link_Interface, + * roomEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE); + * -# std::vector rList; rList.push_back(kitchenResourceHandle); + * rList.push_back(roomResourceHandle); + * -# bindResource(homeResourceHandle, rList); + * @par * At the end of Step 5, resource "a/home" will contain a references to "a/kitchen" and - * "a/room"
+ * "a/room" */ OCStackResult bindResources(const OCResourceHandle collectionHandle, const std::vector& addedResourceHandleList); @@ -283,21 +422,23 @@ namespace OC /** * Unbind a resource from a collection resource. * - * @param collectionHandle - handle to the collection resource + * @param collectionHandle handle to the collection resource * @param resourceHandle resource handle to be unbound from the collection resource * - * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
- * NOTE: OCStackResult is defined in ocstack.h.
- * NOTE: unbindResource must be used only after the both collection resource and - * resource to unbind from a collection are created and respective handles obtained
- * Example
- * Step 1: registerResource(homeResourceHandle, "a/home", "home", Link_Interface, - * entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);
- * Step 2: registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface, - * entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);
- * Step 3: bindResource(homeResourceHandle, kitchenResourceHandle);
- * Step 4: unbindResource(homeResourceHandle, kitchenResourceHandle);
- * At the end of Step 4, resource "a/home" will no longer reference "a/kitchen".
+ * @return Returns ::OC_STACK_OK if success. + * @note OCStackResult is defined in ocstack.h. + * @note unbindResource must be used only after the both collection resource and + * resource to unbind from a collection are created and respective handles obtained + * + * @par Example: + * -# registerResource(homeResourceHandle, "a/home", "home", Link_Interface, + * entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE); + * -# registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface, + * entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE); + * -# bindResource(homeResourceHandle, kitchenResourceHandle); + * -# unbindResource(homeResourceHandle, kitchenResourceHandle); + * @par + * At the end of Step 4, resource "a/home" will no longer reference "a/kitchen". */ OCStackResult unbindResource(const OCResourceHandle collectionHandle, const OCResourceHandle resourceHandle); @@ -305,49 +446,50 @@ namespace OC /** * Unbind resources from a collection resource. * - * @param collectionHandle - handle to the collection resource + * @param collectionHandle handle to the collection resource * @param resourceHandleList List of resource handles to be unbound from the collection * resource * - * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
- * - * NOTE: OCStackResult is defined in ocstack.h.
- * NOTE: unbindResources must be used only after the both collection resource and + * @return Returns ::OC_STACK_OK if success. + * @note OCStackResult is defined in ocstack.h. + * @note unbindResources must be used only after the both collection resource and * list of resources resource to unbind from a collection are created and respective handles - * obtained.
- * Example
- * Step 1: registerResource(homeResourceHandle, "a/home", "home", Link_Interface, - * homeEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);
- * Step 2: registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface, - * kitchenEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);
- * Step 3: registerResource(roomResourceHandle, "a/room", "room", Link_Interface, - * roomEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);
- * Step 4: std::vector rList; rList.push_back(kitchenResourceHandle); - * rList.push_back(roomResourceHandle);
- * Step 5: bindResource(homeResourceHandle, rList);
- * Step 6: unbindResources(homeResourceHandle, rList);
+ * obtained. + * + * @par Example: + * -# registerResource(homeResourceHandle, "a/home", "home", Link_Interface, + * homeEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE); + * -# registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface, + * kitchenEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE); + * -# registerResource(roomResourceHandle, "a/room", "room", Link_Interface, + * roomEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE); + * -# std::vector rList; rList.push_back(kitchenResourceHandle); + * rList.push_back(roomResourceHandle); + * -# bindResource(homeResourceHandle, rList); + * -# unbindResources(homeResourceHandle, rList); + * @par * At the end of Step 6, resource "a/home" will no longer reference to "a/kitchen" and - * "a/room"
+ * "a/room" */ OCStackResult unbindResources(const OCResourceHandle collectionHandle, const std::vector& resourceHandleList); /** * Binds a type to a particular resource - * @param resourceHandle - handle to the resource - * @param resourceTypeName - new typename to bind to the resource - - * @return OCStackResult - return value of the API. Returns OCSTACK_OK if success
+ * @param resourceHandle handle to the resource + * @param resourceTypeName new typename to bind to the resource + * + * @return Returns ::OC_STACK_OK if success. */ OCStackResult bindTypeToResource(const OCResourceHandle& resourceHandle, const std::string& resourceTypeName); /** * Binds an interface to a particular resource - * @param resourceHandle - handle to the resource - * @param resourceTypeName - new interface to bind to the resource - - * @return OCStackResult - return value of the API. Returns OCSTACK_OK if success
+ * @param resourceHandle handle to the resource + * @param resourceInterfaceName new interface to bind to the resource + * + * @return Returns ::OC_STACK_OK if success. */ OCStackResult bindInterfaceToResource(const OCResourceHandle& resourceHandle, const std::string& resourceInterfaceName); @@ -356,114 +498,251 @@ namespace OC /** * Start Presence announcements. * - * @param ttl - time to live - * @return OCStackResult - Returns OCSTACK_OK if success
+ * @param ttl time to live + * @par + * If ttl is '0', then the default stack value will be used (60 Seconds). + * If ttl is greater than OC_MAX_PRESENCE_TTL_SECONDS, then the ttl will be set to + * OC_MAX_PRESENCE_TTL_SECONDS. + * @par + * @return Returns ::OC_STACK_OK if success. * * Server can call this function when it comes online for the * first time, or when it comes back online from offline mode, * or when it re enters network. * */ - OCStackResult startPresence(const unsigned int ttl); /** * Stop Presence announcements. * - * @return OCStackResult - Returns OCSTACK_OK if success
+ * @return Returns ::OC_STACK_OK if success. * * Server can call this function when it is terminating, * going offline, or when going away from network. * */ - OCStackResult stopPresence(); /** - * subscribes to a server's presence change events. By making this subscription, - * every time a server adds/removes/alters a resource, starts or is intentionally - * stopped (potentially more to be added later). - * - * @param presenceHandle - a handle object that can be used to identify this subscription - * request. It can be used to unsubscribe from these events in the future. - * It will be set upon successful return of this method. - * @param host - The IP address/addressable name of the server to subscribe to. - * @param resourceType - a resource type specified as a filter for subscription callbacks. - * @param presenceHandler - callback function that will receive notifications/subscription - * events - * - * @return OCStackResult - return value of the API. Returns OCSTACK_OK if success
- */ -#ifdef CA_INT - OCStackResult subscribePresence(OCPresenceHandle& presenceHandle, const std::string& host, - uint8_t connectivityType, SubscribeCallback presenceHandler); + * subscribes to a server's presence change events. By making this subscription, + * every time a server adds/removes/alters a resource, starts or is intentionally + * stopped (potentially more to be added later). + * + * @param presenceHandle a handle object that can be used to identify this subscription + * request. It can be used to unsubscribe from these events in the future. + * It will be set upon successful return of this method. + * @param host The IP address/addressable name of the server to subscribe to. + * This should be in the format coap://address:port + * @param connectivityType ::OCConnectivityType type of connectivity indicating the + * interface. Example: CT_DEFAULT, CT_ADAPTER_IP, CT_ADAPTER_TCP. + * @param presenceHandler callback function that will receive notifications/subscription + * events + * + * @return Returns ::OC_STACK_OK if success. + * @copydoc subscribePresence(OCPresenceHandle&, const std::string&, resourceType, OCConnectivityType, SubscribeCallback) + */ OCStackResult subscribePresence(OCPresenceHandle& presenceHandle, const std::string& host, - const std::string& resourceType, uint8_t connectivityType, - SubscribeCallback presenceHandler); -#else + OCConnectivityType connectivityType, SubscribeCallback presenceHandler); + /** + * @overload + * + * @param presenceHandle a handle object that can be used to identify this subscription + * request. It can be used to unsubscribe from these events in the future. + * It will be set upon successful return of this method. + * @param host The IP address/addressable name of the server to subscribe to. + * This should be in the format coap://address:port + * @param resourceType a resource type specified as a filter for subscription callbacks. + * @param connectivityType ::OCConnectivityType type of connectivity indicating the + * interface. Example: CT_DEFAULT, CT_ADAPTER_IP, CT_ADAPTER_TCP. + * @param presenceHandler callback function that will receive notifications/subscription + * events + * @see subscribePresence(OCPresenceHandle&, const std::string&, OCConnectivityType, SubscribeCallback) + */ OCStackResult subscribePresence(OCPresenceHandle& presenceHandle, const std::string& host, + const std::string& resourceType, OCConnectivityType connectivityType, SubscribeCallback presenceHandler); - OCStackResult subscribePresence(OCPresenceHandle& presenceHandle, const std::string& host, - const std::string& resourceType, SubscribeCallback presenceHandler); -#endif + /** - * unsubscribes from a previously subscribed server's presence events. Note that - * you may for a short time still receive events from the server since it may take time - * for the unsubscribe to take effect. - * - * @param presenceHandle - the handle object provided by the subscribePresence call that - * identifies this subscription. - * - * @return OCStackResult - return value of the API. Returns OCSTACK_OK if success
- */ + * unsubscribes from a previously subscribed server's presence events. Note that + * you may for a short time still receive events from the server since it may take time + * for the unsubscribe to take effect. + * + * @param presenceHandle the handle object provided by the subscribePresence call that + * identifies this subscription. + * + * @return Returns ::OC_STACK_OK if success. + */ OCStackResult unsubscribePresence(OCPresenceHandle presenceHandle); +#ifdef WITH_CLOUD /** - * Creates a resource proxy object so that get/put/observe functionality - * can be used without discovering the object in advance. Note that the - * consumer of this method needs to provide all of the details required to - * correctly contact and observe the object. If the consumer lacks any of - * this information, they should discover the resource object normally. - * Additionally, you can only create this object if OCPlatform was initialized - * to be a Client or Client/Server. Otherwise, this will return an empty - * shared ptr. - * - * @param host - a string containing a resolvable host address of the server - * holding the resource. Currently this should be in the format - * coap://address:port, though in the future, we expect this to - * change to //address:port - * - * @param uri - the rest of the resource's URI that will permit messages to be - * properly routed. Example: /a/light + * Subscribes to a server's device presence change events. + * + * @param presenceHandle a handle object that can be used to identify this subscription + * request. It can be used to unsubscribe from these events in the future. + * It will be set upon successful return of this method. + * @param host The IP address/addressable name of the server to subscribe to. + * This should be in the format coap://address:port + * @param di Vector which can have the devices id. + * @param connectivityType ::OCConnectivityType type of connectivity indicating the + * interface. Example: CT_DEFAULT, CT_ADAPTER_IP, CT_ADAPTER_TCP. + * @param observeHandler handles callback + * The callback function will be invoked with a map of attribute name and values. + * The callback function will also have the result from this observe operation + * This will have error codes + * + * @return Returns ::OC_STACK_OK if success. + */ + OCStackResult subscribeDevicePresence(OCPresenceHandle& presenceHandle, + const std::string& host, + const std::vector& di, + OCConnectivityType connectivityType, + ObserveCallback callback); +#endif + + /** + * Creates a resource proxy object so that get/put/observe functionality + * can be used without discovering the object in advance. Note that the + * consumer of this method needs to provide all of the details required to + * correctly contact and observe the object. If the consumer lacks any of + * this information, they should discover the resource object normally. + * Additionally, you can only create this object if OCPlatform was initialized + * to be a Client or Client/Server. Otherwise, this will return an empty + * shared ptr. + * + * @param host a string containing a resolvable host address of the server + * holding the resource. Currently this should be in the format + * coap://address:port, though in the future, we expect this to + * change to //address:port + * + * @param uri the rest of the resource's URI that will permit messages to be + * properly routed. Example: /a/light + * + * @param connectivityType ::OCConnectivityType type of connectivity indicating the + * interface. Example: CT_DEFAULT, CT_ADAPTER_IP, CT_ADAPTER_TCP. + * if you want to use a specific Flag like IPv4, + * you should apply OR operation for the flag in here. + * Example: static_cast(CT_ADAPTER_TCP + * | OC_IP_USE_V4) + * + * @param isObservable a boolean containing whether the resource supports observation + * + * @param resourceTypes a collection of resource types implemented by the resource + * + * @param interfaces a collection of interfaces that the resource supports/implements + * @return OCResource::Ptr a shared pointer to the new resource object + */ + OCResource::Ptr constructResourceObject(const std::string& host, + const std::string& uri, + OCConnectivityType connectivityType, bool isObservable, + const std::vector& resourceTypes, + const std::vector& interfaces); + + /** + * Allows application entity handler to send response to an incoming request. + * + * @param pResponse OCResourceResponse pointer that will permit to set values related + * to resource response. + * + * @return Returns ::OC_STACK_OK if success. + */ + OCStackResult sendResponse(const std::shared_ptr pResponse); + + /** + * Find all the Direct Pairing capable devices. + * + * @param waittime timeoutbefore the callback is called + * @param callback function to callback with discovered devices after timeout + * + * @return Returns ::OC_STACK_OK if success + */ + OCStackResult findDirectPairingDevices(unsigned short waittime, + GetDirectPairedCallback callback); + + /** + * Get all the Direct paired devices. + * + * @param callback function to callback with the list of paired devices + * + * @return Returns ::OC_STACK_OK if success + */ + OCStackResult getDirectPairedDevices(GetDirectPairedCallback callback); + + /** + * Perform the Direct Pairing with the selected peer device + * + * @param peer device to direct pair with + * @param pmSel Selected pairing method + * @param pinNumber pin to validate peer & perform the direct pairing + * @param resultCallback callback function that will get the result of the operation + * + * @return Returns ::OC_STACK_OK if success + */ + OCStackResult doDirectPairing(std::shared_ptr peer, OCPrm_t pmSel, + const std::string& pinNumber, + DirectPairingCallback resultCallback); +#ifdef WITH_CLOUD + /** + * Create an account manager object that can be used for doing request to account server. + * You can only create this object if OCPlatform was initialized to be a Client or + * Client/Server. Otherwise, this will return an empty shared ptr. + * + * @note For now, OCPlatform SHOULD be initialized to be a Client/Server(Both) for the + * methods of this object to work since device id is not generated on Client mode. + * + * @param host Host IP Address of a account server. + * @param connectivityType ::OCConnectivityType type of connectivity indicating the + * interface. Example: CT_DEFAULT, CT_ADAPTER_IP, CT_ADAPTER_TCP. + * if you want to use a specific Flag like IPv4, + * you should apply OR operation for the flag in here. + * Example: static_cast(CT_ADAPTER_TCP + * | OC_IP_USE_V4) + * + * @return OCAccountManager::Ptr a shared pointer to the new account manager object + */ + OCAccountManager::Ptr constructAccountManagerObject(const std::string& host, + OCConnectivityType connectivityType); +#endif // WITH_CLOUD + +#ifdef TCP_ADAPTER + /** + * gets OCRepresentation of KeepAlive resource from given host. + * + * @param host Host IP Address of KeepAlive resource + * @param resultCallback Function to callback with result code and OCRepresentation. + * @return Returns ::OC_STACK_OK if success. + */ + OCStackResult findKeepAliveResource(std::string host, KeepAliveCallback resultCallback); + + /** + * send KeepAlive request to given host. * - * @param isObservable - a boolean containing whether the resource supports observation + * @param rep include interval time of expected pong response + * @param resultCallback handles callback * - * @param resourceTypes - a collection of resource types implemented by the resource + * @return Returns ::OC_STACK_OK on success, some other value upon failure. * - * @param interfaces - a collection of interfaces that the resource supports/implements - * @return OCResource::Ptr - a shared pointer to the new resource object */ -#ifdef CA_INT - OCResource::Ptr constructResourceObject(const std::string& host, const std::string& uri, - uint8_t connectivityType, bool isObservable, - const std::vector& resourceTypes, - const std::vector& interfaces); -#else - OCResource::Ptr constructResourceObject(const std::string& host, const std::string& uri, - bool isObservable, const std::vector& resourceTypes, - const std::vector& interfaces); + OCStackResult sendKeepAliveRequest(std::string host, const OCRepresentation& rep, + KeepAliveCallback resultCallback); #endif /** - * Allows application entity handler to send response to an incoming request. - * - * @param pResponse - OCResourceResponse pointer that will permit to set values related - * to resource response.
- * @return OCStackResult - return value of the API. Returns OCSTACK_OK if success
- */ - OCStackResult sendResponse(const std::shared_ptr pResponse); + * gets the deviceId of the client + * + * @param deviceId pointer. + * @return Returns ::OC_STACK_OK if success. + */ + OCStackResult getDeviceId(OCUUIdentity *deviceId); + + /** + * sets the deviceId of the client + * + * @param deviceId pointer. + * @return Returns ::OC_STACK_OK if success. + */ + OCStackResult setDeviceId(const OCUUIdentity *deviceId); } } -#endif //__OCPLATFORM_H - - +#endif // OC_PLATFORM_H_