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     OC_UNKNOWN_URI =0,
  53     OC_WELL_KNOWN_URI,          ///< "/oic/res"
  54     OC_DEVICE_URI,              ///< "/oic/d"
  55     OC_PLATFORM_URI,            ///< "/oic/p"
  56     OC_RESOURCE_TYPES_URI,      ///< "/oic/res/types/d"
  57 #ifdef WITH_PRESENCE
  58     OC_PRESENCE,                ///< "/oic/ad"
  59 #endif
  60 } OCVirtualResources;
  61
  62 /**
  63  * The type of query a request/response message is.
  64  */
  65 typedef enum
  66 {
  67     STACK_RES_DISCOVERY_NOFILTER = 0,
  68     STACK_RES_DISCOVERY_IF_FILTER,
  69     STACK_RES_DISCOVERY_RT_FILTER,
  70     STACK_DEVICE_DISCOVERY_DI_FILTER,
  71     STACK_DEVICE_DISCOVERY_DN_FILTER
  72 } StackQueryTypes;
  73
  74 /**
  75  * The type of handling required to handle a request.
  76  */
  77 typedef enum
  78 {
  79     OC_RESOURCE_VIRTUAL = 0,
  80     OC_RESOURCE_NOT_COLLECTION_WITH_ENTITYHANDLER,
  81     OC_RESOURCE_NOT_COLLECTION_DEFAULT_ENTITYHANDLER,
  82     OC_RESOURCE_COLLECTION_WITH_ENTITYHANDLER,
  83     OC_RESOURCE_COLLECTION_DEFAULT_ENTITYHANDLER,
  84     OC_RESOURCE_DEFAULT_DEVICE_ENTITYHANDLER,
  85     OC_RESOURCE_NOT_SPECIFIED
  86 } ResourceHandling;
  87
  88 /**
  89  * Default entity handler (ie. callback) to be used for resources with
  90  * no entity handler.
  91  */
  92 OCEntityHandlerResult defaultResourceEHandler(OCEntityHandlerFlag flag,
  93         OCEntityHandlerRequest * request, void* callbackParam);
  94
  95 /**
  96  * Find and retrieve pointer to a resource associated with a specific resource
  97  * URI.
  98  */
  99 OCResource *FindResourceByUri(const char* resourceUri);
 100
 101 /**
 102  * Returns true if the specificed resource URI aligns with a pre-existing
 103  * virtual resource; returns false otherwise.
 104  */
 105 bool IsVirtualResource(const char* resourceUri);
 106
 107 /**
 108  * Parameter @ref handling returns by-reference the type of resource handling
 109  * required by the internal stack based on the specified @ref request.
 110  */
 111 OCStackResult DetermineResourceHandling (const OCServerRequest *request,
 112                                          ResourceHandling *handling,
 113                                          OCResource **resource);
 114
 115 /**
 116  * Processes the specified @ref request based on the type of resource handling
 117  * @ref resHandling.
 118  */
 119 OCStackResult ProcessRequest(ResourceHandling resHandling,
 120                              OCResource *resource,
 121                              OCServerRequest *request);
 122
 123 /**
 124  * Internal API used to save all of the platform's information for use in platform
 125  * discovery requests.
 126  */
 127 OCStackResult SavePlatformInfo(OCPlatformInfo info);
 128
 129 /**
 130  * Internal API used to save all of the device's information for use in platform
 131  * discovery requests.
 132  * The device name is received from the appliation.
 133  * The deviceID, spec version and data model verson are initialized by the stack.
 134  */
 135 OCStackResult SaveDeviceInfo(OCDeviceInfo info);
 136
 137 /**
 138  * Internal API used to clear the platform information.
 139  */
 140 void DeletePlatformInfo();
 141
 142 /**
 143  * Internal API used to clear the device information.
 144  */
 145 void DeleteDeviceInfo();
 146
 147 /*
 148  * Prepare payload for resource representation.
 149  */
 150 OCStackResult BuildResponseRepresentation(const OCResource *resourcePtr,
 151                     OCRepPayload** payload);
 152
 153 /**
 154  * Prepares a Payload for response.
 155  */
 156 OCStackResult BuildVirtualResourceResponse(const OCResource *resourcePtr,
 157                                            OCDiscoveryPayload* payload,
 158                                            OCDevAddr *endpoint);
 159
 160 /**
 161  * A helper function that Maps an @ref OCEntityHandlerResult type to an
 162  * @ref OCStackResult type.
 163  */
 164 OCStackResult EntityHandlerCodeToOCStackCode(OCEntityHandlerResult ehResult);
 165
 166 #endif //OC_RESOURCEHANDLER_H
 167