/**
* API for notifying base that resource's attributes have changed.
*
- * @param OCResourceHandle resource handle of the resource
- * @param QualityOfService the quality of communication
+ * @param resourceHandle resource handle of the resource
*
* @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
* NOTE: This API is for server side only.
* NOTE: OCStackResult is defined in ocstack.h.
*/
OCStackResult notifyAllObservers(OCResourceHandle resourceHandle);
+ /**
+ * API for notifying base that resource's attributes have changed.
+ *
+ * @param resourceHandle resource handle of the resource
+ * @param QoS 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.
+ */
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 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 QualityOfService the quality of communication
*
* @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
*
OCResourceHandle resourceHandle,
ObservationIds& observationIds,
const std::shared_ptr<OCResourceResponse> responsePtr);
+ /**
+ * 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.
+ * @param QoS 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.
+ */
OCStackResult notifyListOfObservers(
OCResourceHandle resourceHandle,
ObservationIds& observationIds,
/**
* 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
+ * @note This API applies to client side only.
+ * @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.
+ *
+ * @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
+ * @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.
+ * @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
+ * (NULL/Empty, NULL/Empty) Performs ALL service discovery AND ALL resource
* discovery.
- * (NULL/Empty, Not Empty) - Performs query for a filtered/scoped/particular
+ * (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
+ * (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 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.
*/
OCStackResult findResource(const std::string& host, const std::string& resourceURI,
FindCallback resourceHandler);
+ /**
+ * API for Service and Resource Discovery.
+ *
+ * @note This API applies to client side only.
+ * @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.
+ *
+ * @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 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 The quality of communication
+ *
+ * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
+ */
OCStackResult findResource(const std::string& host, const std::string& resourceURI,
FindCallback resourceHandler, QualityOfService QoS);
* 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
+ ("/oc/core/d")
+ * @param deviceInfoHandler A callback function to receive the results of
+ * getDeviceInfo()
*
*/
OCStackResult getDeviceInfo(const std::string& host, const std::string& deviceURI,
FindDeviceCallback deviceInfoHandler);
+ /**
+ * API for Device Discovery
+ *
+ *
+ * @param host Host IP Address. If null or empty, Multicast is performed.
+ * @param deviceURI Uri containing address to the virtual device in C Stack
+ ("/oc/core/d")
+ * @param deviceInfoHandler A callback function to receive the results of
+ * getDeviceInfo()
+ * @param QoS The quality of communication
+ *
+ */
OCStackResult getDeviceInfo(const std::string& host, const std::string& deviceURI,
FindDeviceCallback deviceInfoHandler, QualityOfService QoS);
* 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.
+ * @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.
*/
/**
* 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.<br>
- * NOTE: OCStackResult is defined in ocstack.h. <br>
- * NOTE: bindResource must be used only after the both collection resource and
+ * bindResource() must be used only after the both collection resource and
* resource to add under a collections are created and respective handles obtained<br>
* <b>Example:</b> <br>
* Step 1: registerResource(homeResourceHandle, "a/home", "home", Link_Interface,
* entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
* Step 3: bindResource(homeResourceHandle, kitchenResourceHandle);<br>
* At the end of Step 3, resource "a/home" will contain a reference to "a/kitchen".<br>
+ *
+ * @param collectionHandle Handle to the collection resource
+ * @param resourceHandle Handle to resource to be added to the collection resource
+ *
+ * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.<br>
+ * @note OCStackResult is defined in ocstack.h. <br>
*/
OCStackResult bindResource(const OCResourceHandle collectionHandle,
const OCResourceHandle resourceHandle);
/**
* Add multiple resources to a 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. <br>
- * NOTE: OCStackResult is defined in ocstack.h. <br>
- * 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 <br>
- * <b> Example: </b> <br>
+ * bindResources() must be used only after the both collection resource and
+ * resource to add under a collections are created and respective handles obtained<br>
+ * <b>Example:</b> <br>
* Step 1: registerResource(homeResourceHandle, "a/home", "home", Link_Interface,
- * homeEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
+ * entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
* Step 2: registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface,
- * kitchenEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
- * Step 3: registerResource(roomResourceHandle, "a/room", "room", Link_Interface,
- * roomEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
- * Step 4: std::vector<OCResourceHandle> rList; rList.push_back(kitchenResourceHandle);
- * rList.push_back(roomResourceHandle);<br>
- * Step 5: bindResource(homeResourceHandle, rList);<br>
- * At the end of Step 5, resource "a/home" will contain a references to "a/kitchen" and
- * "a/room" <br>
+ * entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
+ * Step 3: bindResource(homeResourceHandle, kitchenResourceHandle);<br>
+ * At the end of Step 3, resource "a/home" will contain a reference to "a/kitchen".<br>
+ *
+ * @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. <br>
+ * @note OCStackResult is defined in ocstack.h. <br>
*/
OCStackResult bindResources(const OCResourceHandle collectionHandle,
const std::vector<OCResourceHandle>& addedResourceHandleList);
/**
* Binds an interface to a particular resource
- * @param resourceHandle - handle to the resource
- * @param resourceTypeName - new interface to bind to the resource
+ *
+ * @param resourceHandle Handle to the resource
+ * @param resourceInterfaceName New interface to bind to the resource
- * @return OCStackResult - return value of the API. Returns OCSTACK_OK if success <br>
+ * @return OCStackResult return value of the API. Returns OCSTACK_OK if success <br>
*/
OCStackResult bindInterfaceToResource(const OCResourceHandle& resourceHandle,
const std::string& resourceInterfaceName);
* 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
+ * @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
+ * @param host The IP address/addressable name of the server to subscribe to.
+ * @param presenceHandler Callback function that will receive notifications/subscription
* events
*
- * @return OCStackResult - return value of the API. Returns OCSTACK_OK if success <br>
+ * @return OCStackResult - return value of the API. Returns OCSTACK_OK if successful
*/
OCStackResult subscribePresence(OCPresenceHandle& presenceHandle, const std::string& host,
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.
+ * @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 <br>
+ */
OCStackResult subscribePresence(OCPresenceHandle& presenceHandle, const std::string& host,
const std::string& resourceType, SubscribeCallback presenceHandler);
* The callback function will be invoked with a map of attribute name and values.
* The callback function will also have the result from this Get operation
* This will have error codes
- * @param QualityOfService the quality of communication
* @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
* NOTE: OCStackResult is defined in ocstack.h.
*/
OCStackResult get(const QueryParamsMap& queryParametersMap, GetCallback attributeHandler);
+ /**
+ * Function to get the attributes of a resource.
+ * @param queryParametersMap map which can have the query parameter name and value
+ * @param attributeHandler 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 Get operation
+ * This will have error codes
+ * @param QoS the quality of communication
+ * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
+ * NOTE: OCStackResult is defined in ocstack.h.
+ */
OCStackResult get(const QueryParamsMap& queryParametersMap, GetCallback attributeHandler,
QualityOfService QoS);
* resource container (list will be empty if not a container)
* The callback function will also have the result from this Get operation. This will
* have error codes
- * @param QualityOfService the quality of communication
* @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
* NOTE: OCStackResult is defined in ocstack.h.<br>
* <b>Example:</b><br>
*/
OCStackResult get(const std::string& resourceType, const std::string& resourceInterface,
const QueryParamsMap& queryParametersMap, GetCallback attributeHandler);
+ /**
+ * Function to get the attributes of a resource.
+ *
+ * @param resourceType resourceType of the resource operate on
+ * @param resourceInterface interface type of the resource to operate on
+ * @param queryParametersMap map which can have the query parameter name and value
+ * @param attributeHandler handles callback
+ * The callback function will be invoked with a map of attribute name and values.
+ * The callback function will be invoked with a list of URIs if 'get' is invoked on a
+ * resource container (list will be empty if not a container)
+ * The callback function will also have the result from this Get operation. This will
+ * have error codes
+ * @param QoS the quality of communication
+ * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
+ * NOTE: OCStackResult is defined in ocstack.h.<br>
+ * <b>Example:</b><br>
+ * Consider resource "a/home" (with link interface and resource type as home) contains links
+ * to "a/kitchen" and "a/room".
+ * Step 1: get("home", Link_Interface, &onGet)<br>
+ * Callback onGet will receive a) Empty attribute map because there are no attributes for
+ * a/home b) list with
+ * full URI of "a/kitchen" and "a/room" resources and their properties c) error code for GET
+ * operation<br>
+ * NOTE: A resource may contain single or multiple resource types. Also, a resource may
+ * contain single or multiple interfaces.<br>
+ * Currently, single GET request is allowed to do operate on single resource type or resource
+ * interface. In future, a single GET <br>
+ * can operate on multiple resource types and interfaces. <br>
+ * NOTE: A client can traverse a tree or graph by doing successive GETs on the returned
+ * resources at a node.<br>
+ */
OCStackResult get(const std::string& resourceType, const std::string& resourceInterface,
const QueryParamsMap& queryParametersMap, GetCallback attributeHandler,
QualityOfService QoS);
* This will have error codes
* @param queryParametersMap map which can have the query parameter name and value
* @param attributeHandler attribute handler
- * @param QualityOfService the quality of communication
* @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
* NOTE: OCStackResult is defined in ocstack.h.
*/
OCStackResult put(const OCRepresentation& representation,
const QueryParamsMap& queryParametersMap, PutCallback attributeHandler);
+ /**
+ * Function to set the representation of a resource (via PUT)
+ * @param representation which can either have all the attribute names and values
+ (which will represent entire state of the resource) or a
+ * set of attribute names and values which needs to be modified
+ * The callback function will be invoked with a map of attribute name and values.
+ * The callback function will also have the result from this Put operation
+ * This will have error codes
+ * @param queryParametersMap map which can have the query parameter name and value
+ * @param attributeHandler attribute handler
+ * @param QoS the quality of communication
+ * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
+ * NOTE: OCStackResult is defined in ocstack.h.
+ */
OCStackResult put(const OCRepresentation& representation,
const QueryParamsMap& queryParametersMap, PutCallback attributeHandler,
QualityOfService QoS);
* and values
* (which will represent entire state of the resource) or a
* set of attribute names and values which needs to be modified
- * @param QualityOfService the quality of communication
* @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
* NOTE: OCStackResult is defined in ocstack.h. <br>
*/
OCStackResult put(const std::string& resourceType, const std::string& resourceInterface,
const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
PutCallback attributeHandler);
+ /**
+ * Function to set the attributes of a resource (via PUT)
+ * @param resourceType resource type of the resource to operate on
+ * @param resourceInterface interface type of the resource to operate on
+ * @param representation representation of the resource
+ * @param queryParametersMap Map which can have the query parameter name and value
+ * @param attributeHandler attribute handler
+ * The callback function will be invoked with a map of attribute name and values.
+ * The callback function will also have the result from this Put operation
+ * This will have error codes.
+ * The Representation parameter maps which can either have all the attribute names
+ * and values
+ * (which will represent entire state of the resource) or a
+ * set of attribute names and values which needs to be modified
+ * @param QoS the quality of communication
+ * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
+ * NOTE: OCStackResult is defined in ocstack.h. <br>
+ */
OCStackResult put(const std::string& resourceType, const std::string& resourceInterface,
const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
PutCallback attributeHandler, QualityOfService QoS);
/**
* Function to post on a resource
* @param representation which can either have all the attribute names and values
- (which will represent entire state of the resource) or a
+ * (which will represent entire state of the resource) or a
* set of attribute names and values which needs to be modified
* The callback function will be invoked with a map of attribute name and values.
* The callback function will also have the result from this Put operation
* This will have error codes
* @param queryParametersMap map which can have the query parameter name and value
* @param attributeHandler attribute handler
- * @param QualityOfService the quality of communication
* @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
* NOTE: OCStackResult is defined in ocstack.h.
*/
OCStackResult post(const OCRepresentation& representation,
const QueryParamsMap& queryParametersMap, PostCallback attributeHandler);
+ /**
+ * Function to post on a resource
+ * @param representation which can either have all the attribute names and values
+ * (which will represent entire state of the resource) or a
+ * set of attribute names and values which needs to be modified
+ * The callback function will be invoked with a map of attribute name and values.
+ * The callback function will also have the result from this Put operation
+ * This will have error codes
+ * @param queryParametersMap map which can have the query parameter name and value
+ * @param attributeHandler attribute handler
+ * @param QoS the quality of communication
+ * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
+ * NOTE: OCStackResult is defined in ocstack.h.
+ */
OCStackResult post(const OCRepresentation& representation,
const QueryParamsMap& queryParametersMap, PostCallback attributeHandler,
QualityOfService QoS);
* and values
* (which will represent entire state of the resource) or a
* set of attribute names and values which needs to be modified
- * @param QualityOfService the quality of communication
* @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
* NOTE: OCStackResult is defined in ocstack.h. <br>
*/
OCStackResult post(const std::string& resourceType, const std::string& resourceInterface,
const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
PostCallback attributeHandler);
+ /**
+ * Function to post on a resource
+ * @param resourceType resource type of the resource to operate on
+ * @param resourceInterface interface type of the resource to operate on
+ * @param representation representation of the resource
+ * @param queryParametersMap Map which can have the query parameter name and value
+ * @param attributeHandler attribute handler
+ * The callback function will be invoked with a map of attribute name and values.
+ * The callback function will also have the result from this Put operation
+ * This will have error codes.
+ * The Representation parameter maps which can either have all the attribute names
+ * and values
+ * (which will represent entire state of the resource) or a
+ * set of attribute names and values which needs to be modified
+ * @param QoS the quality of communication
+ * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
+ * NOTE: OCStackResult is defined in ocstack.h. <br>
+ */
OCStackResult post(const std::string& resourceType, const std::string& resourceInterface,
const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
PostCallback attributeHandler, QualityOfService QoS);
/**
* Function to perform DELETE operation
- * @param observeHandler handles callback
+ * @param deleteHandler handles callback
* The callback function will have headerOptions and result from this Delete
* operation. This will have error codes
* @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
* 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
- * @param QualityOfService the quality of communication
* @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
* NOTE: OCStackResult is defined in ocstack.h.
*/
OCStackResult observe(ObserveType observeType, const QueryParamsMap& queryParametersMap,
ObserveCallback observeHandler);
+ /**
+ * Function to set observation on the resource
+ * @param observeType allows the client to specify how it wants to observe.
+ * @param queryParametersMap map which can have the query parameter name and value
+ * @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
+ * @param qos the quality of communication
+ * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
+ * NOTE: OCStackResult is defined in ocstack.h.
+ */
OCStackResult observe(ObserveType observeType, const QueryParamsMap& queryParametersMap,
ObserveCallback observeHandler, QualityOfService qos);
projects / platform / upstream / iotivity.git / commitdiff