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 #define OC_KEY_VALUE_DELIMITER             "="
  40
  41 /**
  42  * Static values for various JSON attributes.
  43  */
  44 #define OC_RESOURCE_OBSERVABLE   1
  45 #define OC_RESOURCE_SECURE       1
  46
  47 /**
  48  *  OIC Virtual resources supported by every OIC device.
  49  */
  50 typedef enum
  51 {
  52     /** unknown URI.*/
  53     OC_UNKNOWN_URI =0,
  54
  55     /** "/oic/res".*/
  56     OC_WELL_KNOWN_URI,
  57
  58     /** "/oic/d" .*/
  59     OC_DEVICE_URI,
  60
  61     /** "/oic/p" .*/
  62     OC_PLATFORM_URI,
  63
  64     /** "/oic/res/d/type" .*/
  65     OC_RESOURCE_TYPES_URI,
  66 #ifdef ROUTING_GATEWAY
  67     /** "/oic/gateway" .*/
  68     OC_GATEWAY_URI,
  69 #endif
  70     #ifdef WITH_PRESENCE
  71     /** "/oic/ad" .*/
  72     OC_PRESENCE,
  73     #endif
  74
  75 #ifdef MQ_BROKER
  76     /** "/oic/ps" .*/
  77     OC_MQ_BROKER_URI,
  78 #endif
  79
  80     /** Max items in the list */
  81     OC_MAX_VIRTUAL_RESOURCES    //<s Max items in the list
  82
  83 } OCVirtualResources;
  84
  85 /**
  86  * The type of query a request/response message is.
  87  */
  88 typedef enum
  89 {
  90     STACK_RES_DISCOVERY_NOFILTER = 0,
  91     STACK_RES_DISCOVERY_IF_FILTER,
  92     STACK_RES_DISCOVERY_RT_FILTER,
  93     STACK_DEVICE_DISCOVERY_DI_FILTER,
  94     STACK_DEVICE_DISCOVERY_DN_FILTER
  95 } StackQueryTypes;
  96
  97 /**
  98  * The type of handling required to handle a request.
  99  */
 100 typedef enum
 101 {
 102     OC_RESOURCE_VIRTUAL = 0,
 103     OC_RESOURCE_NOT_COLLECTION_WITH_ENTITYHANDLER,
 104     OC_RESOURCE_NOT_COLLECTION_DEFAULT_ENTITYHANDLER,
 105     OC_RESOURCE_COLLECTION_WITH_ENTITYHANDLER,
 106     OC_RESOURCE_COLLECTION_DEFAULT_ENTITYHANDLER,
 107     OC_RESOURCE_DEFAULT_DEVICE_ENTITYHANDLER,
 108     OC_RESOURCE_NOT_SPECIFIED
 109 } ResourceHandling;
 110
 111 /**
 112  * Default entity handler (ie. callback) to be used for resources with
 113  * no entity handler.
 114  */
 115 OCEntityHandlerResult defaultResourceEHandler(OCEntityHandlerFlag flag,
 116         OCEntityHandlerRequest * request, void* callbackParam);
 117
 118 /**
 119  * Find and retrieve pointer to a resource associated with a specific resource
 120  * URI.
 121  * @return pointer to found resource
 122  */
 123 OCResource *FindResourceByUri(const char* resourceUri);
 124
 125 /**
 126  * This function checks whether the specified resource URI aligns with a pre-existing
 127  * virtual resource; returns false otherwise.
 128  * @return true or false.
 129  */
 130 bool IsVirtualResource(const char* resourceUri);
 131
 132 /**
 133  * Parameter @ref handling returns by-reference the type of resource handling
 134  * required by the internal stack based on the specified @ref request.
 135  * @return ::OC_STACK_OK for Success, otherwise some error value
 136  */
 137 OCStackResult DetermineResourceHandling (const OCServerRequest *request,
 138                                          ResourceHandling *handling,
 139                                          OCResource **resource);
 140
 141 /**
 142  * Processes the specified @ref request based on the type of resource handling
 143  * @ref resHandling.
 144  * @return ::OC_STACK_OK for Success, otherwise some error value.
 145  */
 146 OCStackResult ProcessRequest(ResourceHandling resHandling,
 147                              OCResource *resource,
 148                              OCServerRequest *request);
 149
 150 /**
 151  * Internal API used to save all of the platform's information for use in platform
 152  * discovery requests.
 153  * @return ::OC_STACK_OK for Success, otherwise some error value.
 154  */
 155 OCStackResult SavePlatformInfo(OCPlatformInfo info);
 156
 157 /**
 158  * Internal API used to save all of the device's information for use in platform
 159  * discovery requests.
 160  * @param info       Device name is received from the application.
 161  *                   DeviceID, spec version and data model version are initialized by the stack.
 162  * @return ::OC_STACK_OK for Success, otherwise some error value.
 163  */
 164 OCStackResult SaveDeviceInfo(OCDeviceInfo info);
 165
 166 /**
 167  * Internal API used to clear the platform information.
 168  */
 169 void DeletePlatformInfo();
 170
 171 /**
 172  * Internal API used to clear the device information.
 173  */
 174 void DeleteDeviceInfo();
 175
 176 /*
 177  * Prepare payload for resource representation.
 178  */
 179 OCStackResult BuildResponseRepresentation(const OCResource *resourcePtr,
 180                     OCRepPayload** payload);
 181
 182 /**
 183  * A helper function that Maps an @ref OCEntityHandlerResult type to an
 184  * @ref OCStackResult type.
 185  */
 186 OCStackResult EntityHandlerCodeToOCStackCode(OCEntityHandlerResult ehResult);
 187
 188 #endif //OC_RESOURCEHANDLER_H
 189