resource/csdk/stack/include/internal/ocresourcehandler.h

   1 //******************************************************************
   2 //
   3 // Copyright 2014 Intel Mobile Communications GmbH All Rights Reserved.
   4 //
   5 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
   6 //
   7 // Licensed under the Apache License, Version 2.0 (the "License");
   8 // you may not use this file except in compliance with the License.
   9 // You may obtain a copy of the License at
  10 //
  11 //      http://www.apache.org/licenses/LICENSE-2.0
  12 //
  13 // Unless required by applicable law or agreed to in writing, software
  14 // distributed under the License is distributed on an "AS IS" BASIS,
  15 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16 // See the License for the specific language governing permissions and
  17 // limitations under the License.
  18 //
  19 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  20
  21 #ifndef OC_RESOURCEHANDLER_H
  22 #define OC_RESOURCEHANDLER_H
  23
  24 #include "ocstack.h"
  25 #include "ocstackinternal.h"
  26 #include "ocserverrequest.h"
  27
  28 /**
  29  * Common JSON string components used by the stack to build JSON strings.
  30  * These details are exposed in ocstackconfig.h file in the form of documentation.
  31  * Remember to update the documentation there if these are changed.
  32  */
  33 #define OC_JSON_PREFIX                     "{\"oic\":["
  34 #define OC_JSON_PREFIX_LEN                 (sizeof(OC_JSON_PREFIX) - 1)
  35 #define OC_JSON_SUFFIX                     "]}"
  36 #define OC_JSON_SUFFIX_LEN                 (sizeof(OC_JSON_SUFFIX) - 1)
  37 #define OC_JSON_SEPARATOR                  ','
  38 #define OC_JSON_SEPARATOR_STR              ","
  39
  40 /**
  41  * Static values for various JSON attributes.
  42  */
  43 #define OC_RESOURCE_OBSERVABLE   1
  44 #define OC_RESOURCE_SECURE       1
  45
  46 /**
  47  * The type of query a request/response message is.
  48  */
  49 typedef enum
  50 {
  51     STACK_RES_DISCOVERY_NOFILTER = 0,
  52     STACK_RES_DISCOVERY_IF_FILTER,
  53     STACK_RES_DISCOVERY_RT_FILTER,
  54     STACK_DEVICE_DISCOVERY_DI_FILTER,
  55     STACK_DEVICE_DISCOVERY_DN_FILTER
  56 } StackQueryTypes;
  57
  58 /**
  59  * The type of handling required to handle a request.
  60  */
  61 typedef enum
  62 {
  63     OC_RESOURCE_VIRTUAL = 0,
  64     OC_RESOURCE_NOT_COLLECTION_WITH_ENTITYHANDLER,
  65     OC_RESOURCE_NOT_COLLECTION_DEFAULT_ENTITYHANDLER,
  66     OC_RESOURCE_COLLECTION_WITH_ENTITYHANDLER,
  67     OC_RESOURCE_COLLECTION_DEFAULT_ENTITYHANDLER,
  68     OC_RESOURCE_DEFAULT_DEVICE_ENTITYHANDLER,
  69     OC_RESOURCE_NOT_SPECIFIED
  70 } ResourceHandling;
  71
  72 /**
  73  * Default entity handler (ie. callback) to be used for resources with
  74  * no entity handler.
  75  */
  76 OCEntityHandlerResult defaultResourceEHandler(OCEntityHandlerFlag flag,
  77         OCEntityHandlerRequest * request, void* callbackParam);
  78
  79 /**
  80  * Get string value associated with a virtual resource type.
  81  */
  82 const char * GetVirtualResourceUri(OCVirtualResources resource);
  83
  84 /**
  85  * Find and retrieve pointer to a resource associated with a specific resource
  86  * URI.
  87  */
  88 OCResource *FindResourceByUri(const char* resourceUri);
  89
  90 /**
  91  * Returns true if the specificed resource URI aligns with a pre-existing
  92  * virtual resource; returns false otherwise.
  93  */
  94 bool IsVirtualResource(const char* resourceUri);
  95
  96 /**
  97  * Parameter @ref handling returns by-reference the type of resource handling
  98  * required by the internal stack based on the specified @ref request.
  99  */
 100 OCStackResult DetermineResourceHandling (const OCServerRequest *request,
 101                                          ResourceHandling *handling,
 102                                          OCResource **resource);
 103
 104 /**
 105  * Processes the specified @ref request based on the type of resource handling
 106  * @ref resHandling.
 107  */
 108 OCStackResult ProcessRequest(ResourceHandling resHandling,
 109                              OCResource *resource,
 110                              OCServerRequest *request);
 111
 112 /**
 113  * Internal API used to save all of the platform's information for use in platform
 114  * discovery requests.
 115  */
 116 OCStackResult SavePlatformInfo(OCPlatformInfo info);
 117
 118 /**
 119  * Internal API used to save all of the device's information for use in platform
 120  * discovery requests.
 121  * The device name is received from the appliation.
 122  * The deviceID, spec version and data model verson are initialized by the stack.
 123  */
 124 OCStackResult SaveDeviceInfo(OCDeviceInfo info);
 125
 126 /**
 127  * Internal API used to clear the platform information.
 128  */
 129 void DeletePlatformInfo();
 130
 131 /**
 132  * Internal API used to clear the device information.
 133  */
 134 void DeleteDeviceInfo();
 135
 136 /**
 137  * Prepares a JSON string for response.
 138  */
 139 OCStackResult BuildVirtualResourceResponse(const OCResource *resourcePtr,
 140                                            uint8_t filterOn,
 141                                            const char *filterValue,
 142                                            char * out,
 143                                            uint16_t *remaining,
 144                                            CATransportAdapter_t adapter);
 145
 146 /**
 147  * A helper function that Maps an @ref OCEntityHandlerResult type to an
 148  * @ref OCStackResult type.
 149  */
 150 OCStackResult EntityHandlerCodeToOCStackCode(OCEntityHandlerResult ehResult);
 151
 152 #endif //OC_RESOURCEHANDLER_H
 153