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 #ifdef __cplusplus
  29 extern "C" {
  30 #endif // __cplusplus
  31
  32 /**
  33  * Common JSON string components used by the stack to build JSON strings.
  34  * These details are exposed in ocstackconfig.h file in the form of documentation.
  35  * Remember to update the documentation there if these are changed.
  36  */
  37 #define OC_JSON_PREFIX                     "{\"oic\":["
  38 #define OC_JSON_PREFIX_LEN                 (sizeof(OC_JSON_PREFIX) - 1)
  39 #define OC_JSON_SUFFIX                     "]}"
  40 #define OC_JSON_SUFFIX_LEN                 (sizeof(OC_JSON_SUFFIX) - 1)
  41 #define OC_JSON_SEPARATOR                  ','
  42 #define OC_JSON_SEPARATOR_STR              ","
  43
  44 /**
  45  * Static values for various JSON attributes.
  46  */
  47 #define OC_RESOURCE_OBSERVABLE   1
  48 #define OC_RESOURCE_SECURE       1
  49
  50 /**
  51  * Device properties persistent store name.
  52  */
  53 #define OC_DEVICE_PROPS_FILE_NAME  "device_properties.dat"
  54
  55 /**
  56  * Device properties name
  57  */
  58 #define OC_JSON_DEVICE_PROPS_NAME "DeviceProperties"
  59
  60 /**
  61  *  OIC Virtual resources supported by every OIC device.
  62  */
  63 typedef enum
  64 {
  65     /** unknown URI.*/
  66     OC_UNKNOWN_URI =0,
  67
  68     /** "/oic/res".*/
  69     OC_WELL_KNOWN_URI,
  70
  71     /** "/oic/d" .*/
  72     OC_DEVICE_URI,
  73
  74     /** "/oic/p" .*/
  75     OC_PLATFORM_URI,
  76
  77     /** "/oic/res/d/type" .*/
  78     OC_RESOURCE_TYPES_URI,
  79 #ifdef ROUTING_GATEWAY
  80     /** "/oic/gateway" .*/
  81     OC_GATEWAY_URI,
  82 #endif
  83 #ifdef WITH_PRESENCE
  84     /** "/oic/ad" .*/
  85     OC_PRESENCE,
  86 #endif
  87
  88 #ifdef MQ_BROKER
  89     /** "/oic/ps" .*/
  90     OC_MQ_BROKER_URI,
  91 #endif
  92
  93 #ifdef TCP_ADAPTER
  94     /** "/oic/ping" .*/
  95     OC_KEEPALIVE_RESOURCE_URI,
  96 #endif
  97
  98     /** "/oic/introspection" .*/
  99     OC_INTROSPECTION_URI,
 100
 101     /** "/oic/introspection/payload" .*/
 102     OC_INTROSPECTION_PAYLOAD_URI,
 103
 104     /** Max items in the list */
 105     OC_MAX_VIRTUAL_RESOURCES    //<s Max items in the list
 106
 107 } OCVirtualResources;
 108
 109 /**
 110  * The type of query a request/response message is.
 111  */
 112 typedef enum
 113 {
 114     STACK_RES_DISCOVERY_NOFILTER = 0,
 115     STACK_RES_DISCOVERY_IF_FILTER,
 116     STACK_RES_DISCOVERY_RT_FILTER,
 117     STACK_DEVICE_DISCOVERY_DI_FILTER,
 118     STACK_DEVICE_DISCOVERY_DN_FILTER
 119 } StackQueryTypes;
 120
 121 /**
 122  * The type of handling required to handle a request.
 123  */
 124 typedef enum
 125 {
 126     OC_RESOURCE_VIRTUAL = 0,
 127     OC_RESOURCE_NOT_COLLECTION_WITH_ENTITYHANDLER,
 128     OC_RESOURCE_NOT_COLLECTION_DEFAULT_ENTITYHANDLER,
 129     OC_RESOURCE_COLLECTION_WITH_ENTITYHANDLER,
 130     OC_RESOURCE_COLLECTION_DEFAULT_ENTITYHANDLER,
 131     OC_RESOURCE_DEFAULT_DEVICE_ENTITYHANDLER,
 132     OC_RESOURCE_NOT_SPECIFIED
 133 } ResourceHandling;
 134
 135 /**
 136  * This function returns the virtual resource of the given URI.
 137  * @return the virtual resource or ::OC_UNKNOWN_URI
 138  */
 139 OCVirtualResources GetTypeOfVirtualURI(const char* resourceUri);
 140
 141 /**
 142  * Default entity handler (ie. callback) to be used for resources with
 143  * no entity handler.
 144  */
 145 OCEntityHandlerResult defaultResourceEHandler(OCEntityHandlerFlag flag,
 146         OCEntityHandlerRequest * request, void* callbackParam);
 147
 148 /**
 149  * Find and retrieve pointer to a resource associated with a specific resource
 150  * URI.
 151  * @return pointer to found resource
 152  */
 153 OCResource *FindResourceByUri(const char* resourceUri);
 154
 155 /**
 156  * This function checks whether the specified resource URI aligns with a pre-existing
 157  * virtual resource; returns false otherwise.
 158  * @return true or false.
 159  */
 160 bool IsVirtualResource(const char* resourceUri);
 161
 162 /**
 163  * Parameter handling returns by-reference the type of resource handling
 164  * required by the internal stack based on the specified request.
 165  *
 166  * @param request the OCServerRequest to the internal stack
 167  * @param handling the resource handling required by the internal stack
 168  * @param resource the OCResource from the stack
 169  *
 170  * @return ::OC_STACK_OK for Success, otherwise some error value
 171  */
 172 OCStackResult DetermineResourceHandling (const OCServerRequest *request,
 173                                          ResourceHandling *handling,
 174                                          OCResource **resource);
 175
 176 /**
 177  * Processes the specified request based on the type of resource handling
 178  * resHandling.
 179  *
 180  * @param resHandling the type of resource handling to be used
 181  * @param resource the resource to process the request on
 182  * @param request the request to process
 183  *
 184  * @return ::OC_STACK_OK for Success, otherwise some error value.
 185  */
 186 OCStackResult ProcessRequest(ResourceHandling resHandling,
 187                              OCResource *resource,
 188                              OCServerRequest *request);
 189
 190 /**
 191  * Internal API used to save all of the platform's information for use in platform
 192  * discovery requests.
 193  * @return ::OC_STACK_OK for Success, otherwise some error value.
 194  */
 195 OCStackResult SavePlatformInfo(OCPlatformInfo info);
 196
 197 /**
 198  * Internal API used to save all of the device's information for use in platform
 199  * discovery requests.
 200  * @param info       Device name is received from the application.
 201  *                   DeviceID, spec version and data model version are initialized by the stack.
 202  * @return ::OC_STACK_OK for Success, otherwise some error value.
 203  */
 204 OCStackResult SaveDeviceInfo(OCDeviceInfo info);
 205
 206 /**
 207  * Internal API used to clear the platform information.
 208  */
 209 void DeletePlatformInfo();
 210
 211 /**
 212  * Internal API used to clear the device information.
 213  */
 214 void DeleteDeviceInfo();
 215
 216 /*
 217  * Prepare payload for resource representation.
 218  */
 219 OCStackResult BuildResponseRepresentation(const OCResource *resourcePtr,
 220                     OCRepPayload** payload, OCDevAddr *devAddr);
 221
 222 /**
 223  * A helper function that Maps an @ref OCEntityHandlerResult type to an
 224  * @ref OCStackResult type.
 225  */
 226 OCStackResult EntityHandlerCodeToOCStackCode(OCEntityHandlerResult ehResult);
 227
 228 /**
 229  * Data structure for holding enhanced device information
 230  */
 231 typedef struct _OCDeviceProperties
 232 {
 233     /** Protocol Independent Id.*/
 234     char protocolIndependentId[UUID_STRING_SIZE];
 235 } OCDeviceProperties;
 236
 237 /**
 238  * Internal API used to initialize device properties.
 239  * @return ::OC_STACK_OK for Success, otherwise some error value
 240  */
 241 OCStackResult InitializeDeviceProperties();
 242
 243 /**
 244  * Internal API used to clean up device properties.
 245  * @param deviceProperties Pointer to OCDeviceProperties to clean up.
 246  */
 247 void CleanUpDeviceProperties(OCDeviceProperties **deviceProperties);
 248
 249 /**
 250  * This method converts OCDeviceProperties into CBOR format.
 251  * @param deviceProperties   Pointer to OCDeviceProperties to convert to CBOR.
 252  * @param payload            JSON payload converted to CBOR. Passed parameter should not be NULL.
 253  * @note Caller needs to invoke OICFree when they are finished using the returned string.
 254  * @param size               Size of the cbor payload. Passed parameter should not be NULL.
 255  * @return ::OC_STACK_OK for Success, otherwise some error value.
 256  */
 257 OCStackResult DevicePropertiesToCBORPayload(const OCDeviceProperties *deviceProperties, uint8_t **payload, size_t *size);
 258
 259 /**
 260  * This method converts CBOR data into OCDeviceProperties format.
 261  * @param payload            CBOR payload to convert to OCDeviceProperties.
 262  * @param size               Size of the cborPayload.
 263  * @param deviceProperties   CBOR payload converted to OCDeviceProperties. Passed parameter should not be NULL.
 264  * @note Caller needs to invoke CleanUpDeviceProperties after they are finished using the returned pointer.
 265  * @return ::OC_STACK_OK for Success, otherwise some error value.
 266  */
 267 OCStackResult CBORPayloadToDeviceProperties(const uint8_t *payload, size_t size, OCDeviceProperties **deviceProperties);
 268
 269 #ifdef __cplusplus
 270 }
 271 #endif // __cplusplus
 272 #endif //OC_RESOURCEHANDLER_H