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