From b5f0ab9e378a6361628fe7b139cc2847e2ced19a Mon Sep 17 00:00:00 2001 From: Joseph Morrow Date: Thu, 19 Mar 2015 10:57:59 -0400 Subject: [PATCH] Added proper doxygen documentation to the file ocresourcehandler.h. Change-Id: Iaef7aa463856615bfe4696cb3ec517e18188f28d Signed-off-by: Joseph Morrow Reviewed-on: https://gerrit.iotivity.org/gerrit/491 Tested-by: jenkins-iotivity Reviewed-by: Sudarshan Prasad Reviewed-by: Erich Keane --- .../stack/include/internal/ocresourcehandler.h | 80 ++++++++++++++++++---- resource/csdk/stack/src/ocresource.c | 8 +-- 2 files changed, 71 insertions(+), 17 deletions(-) diff --git a/resource/csdk/stack/include/internal/ocresourcehandler.h b/resource/csdk/stack/include/internal/ocresourcehandler.h index 7a2859e..67bae55 100644 --- a/resource/csdk/stack/include/internal/ocresourcehandler.h +++ b/resource/csdk/stack/include/internal/ocresourcehandler.h @@ -25,6 +25,9 @@ #include "ocstackinternal.h" #include "ocserverrequest.h" +/** + * Attributes used to form a proper OIC conforming JSON message. + */ #define OC_RSRVD_OC "oc" #define OC_RSRVD_PAYLOAD "payload" #define OC_RSRVD_HREF "href" @@ -39,7 +42,6 @@ #define OC_RSRVD_INTERFACE_LL "oc.mi.ll" #define OC_RSRVD_INTERFACE_BATCH "oc.mi.b" #define OC_RSRVD_INTERFACE_GROUP "oc.mi.grp" - #define OC_RSRVD_MFG_DATE "mndt" #define OC_RSRVD_FW_VERSION "mnfv" #define OC_RSRVD_HOST_NAME "hn" @@ -49,13 +51,14 @@ #define OC_RSRVD_PLATFORM_VERSION "mnpv" #define OC_RSRVD_SUPPORT_URL "mnsl" #define OC_RSRVD_VERSION "icv" - - #define OC_RSRVD_OBSERVABLE "obs" #define OC_RSRVD_SECURE "sec" #define OC_RSRVD_HOSTING_PORT "port" #define OC_RSRVD_SERVER_INSTANCE_ID "sid" +/** + * Common JSON string components used by the stack to build JSON strings. + */ #define OC_JSON_PREFIX "{\"oc\":[" #define OC_JSON_PREFIX_LEN (sizeof(OC_JSON_PREFIX) - 1) #define OC_JSON_SUFFIX "]}" @@ -63,9 +66,15 @@ #define OC_JSON_SEPARATOR ',' #define OC_JSON_SEPARATOR_STR "," +/** + * Static values for various JSON attributes. + */ #define OC_RESOURCE_OBSERVABLE 1 #define OC_RESOURCE_SECURE 1 +/** + * The type of query a request/response message is. + */ typedef enum { STACK_RES_DISCOVERY_NOFILTER = 0, @@ -75,6 +84,9 @@ typedef enum STACK_DEVICE_DISCOVERY_DN_FILTER } StackQueryTypes; +/** + * The type of handling required to handle a request. + */ typedef enum { OC_RESOURCE_VIRTUAL = 0, @@ -86,29 +98,71 @@ typedef enum OC_RESOURCE_NOT_SPECIFIED } ResourceHandling; +/** + * Default entity handler (ie. callback) to be used for resources with + * no entity handler. + */ OCEntityHandlerResult defaultResourceEHandler(OCEntityHandlerFlag flag, OCEntityHandlerRequest * request); -const char * GetVirtualResourceUri( OCVirtualResources resource); +/** + * Get string value associated with a virtual resource type. + */ +const char * GetVirtualResourceUri(OCVirtualResources resource); + +/** + * Find and retrieve pointer to a resource associated with a specific resource + * URI. + */ OCResource *FindResourceByUri(const char* resourceUri); -uint8_t IsVirtualResource(const char* resourceUri); +/** + * Returns true if the specificed resource URI aligns with a pre-existing + * virtual resource; returns false otherwise. + */ +bool IsVirtualResource(const char* resourceUri); + +/** + * Parameter @ref handling returns by-reference the type of resource handling + * required by the internal stack based on the specified @ref request. + */ OCStackResult DetermineResourceHandling (OCServerRequest *request, ResourceHandling *handling, OCResource **resource); -OCStackResult -ProcessRequest(ResourceHandling resHandling, OCResource *resource, OCServerRequest *request); - +/** + * Processes the specified @ref request based on the type of resource handling + * @ref resHandling. + */ +OCStackResult ProcessRequest(ResourceHandling resHandling, + OCResource *resource, + OCServerRequest *request); + +/** + * Internal API used to save all of the device's information for use in device + * discovery requests. + */ OCStackResult SaveDeviceInfo(OCDeviceInfo deviceInfo); +/** + * Internal API used to clear the device information. + */ void DeleteDeviceInfo(); -OCStackResult -BuildVirtualResourceResponse(OCResource *resourcePtr, uint8_t filterOn, - char *filterValue, char * out, uint16_t *remaining, - CAConnectivityType_t connType ); - +/** + * Prepares a JSON string for response. + */ +OCStackResult BuildVirtualResourceResponse(OCResource *resourcePtr, + uint8_t filterOn, + char *filterValue, + char * out, + uint16_t *remaining, + CAConnectivityType_t connType); + +/** + * A helper function that Maps an @ref OCEntityHandlerResult type to an + * @ref OCStackResult type. + */ OCStackResult EntityHandlerCodeToOCStackCode(OCEntityHandlerResult ehResult); #endif //OC_RESOURCEHANDLER_H diff --git a/resource/csdk/stack/src/ocresource.c b/resource/csdk/stack/src/ocresource.c index bc440c8..f022841 100644 --- a/resource/csdk/stack/src/ocresource.c +++ b/resource/csdk/stack/src/ocresource.c @@ -395,21 +395,21 @@ const char * GetVirtualResourceUri( OCVirtualResources resource) return NULL; } -uint8_t IsVirtualResource(const char* resourceUri) +bool IsVirtualResource(const char* resourceUri) { if(!resourceUri) { - return 0; + return false; } for (int i = 0; i < OC_MAX_VIRTUAL_RESOURCES; i++) { if (strcmp(resourceUri, GetVirtualResourceUri((OCVirtualResources)i)) == 0) { - return 1; + return true; } } - return 0; + return false; } uint8_t IsCollectionResource (OCResource *resource) -- 2.7.4