resource/csdk/stack/include/ocpayload.h

   1 //******************************************************************
   2 //
   3 // Copyright 2015 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 /**
  22  * @file
  23  *
  24  */
  25
  26 #ifndef OCPAYLOAD_H_
  27 #define OCPAYLOAD_H_
  28
  29 #ifndef __STDC_FORMAT_MACROS
  30 #define __STDC_FORMAT_MACROS
  31 #endif
  32 #ifndef __STDC_LIMIT_MACROS
  33 #define __STDC_LIMIT_MACROS
  34 #endif
  35
  36 #include <stdbool.h>
  37 #include <inttypes.h>
  38 #include "octypes.h"
  39 #include "platform_features.h"
  40
  41 #if defined(__WITH_TLS__) || defined(__WITH_DTLS__)
  42 #include "experimental/securevirtualresourcetypes.h"
  43 #endif
  44
  45 #ifdef __cplusplus
  46 extern "C"
  47 {
  48 #endif
  49
  50 /**
  51  * Macro to verify the validity of cbor operation or out of memory condition
  52  */
  53 #define VERIFY_CBOR_SUCCESS_OR_OUT_OF_MEMORY(log_tag, err, log_message) \
  54     if ((CborNoError != (err)) && !(CborErrorOutOfMemory & (err))) \
  55     { \
  56         if ((log_tag) && (log_message)) \
  57         { \
  58             OIC_LOG_V(ERROR, (log_tag), "%s with cbor error: \'%s\'.", \
  59                     (log_message), (cbor_error_string(err))); \
  60         } \
  61         goto exit; \
  62     } \
  63
  64 /**
  65  * Macro to verify the validity of cbor operation
  66  */
  67 #define VERIFY_CBOR_SUCCESS(log_tag, err, log_message) \
  68     if (CborNoError != (err)) \
  69     { \
  70         if ((log_tag) && (log_message)) \
  71         { \
  72             OIC_LOG_V(ERROR, (log_tag), "%s with cbor error: \'%s\'.", \
  73                     (log_message), (cbor_error_string(err))); \
  74         } \
  75         goto exit; \
  76     } \
  77
  78 #define VERIFY_PARAM_NON_NULL(log_tag, err, log_message) \
  79     if (NULL == (err)) \
  80     { \
  81         OIC_LOG_V(FATAL, (log_tag), "%s", (log_message)); \
  82         goto exit;\
  83     } \
  84
  85 #define VERIFY_CBOR_NOT_OUTOFMEMORY(log_tag, err, log_message) \
  86     if (CborErrorOutOfMemory & (err)) \
  87     { \
  88         if ((log_tag) && (log_message)) \
  89         { \
  90             OIC_LOG_V(ERROR, (log_tag), "%s with cbor error: \'%s\'.", \
  91                     (log_message), (cbor_error_string(err))); \
  92         } \
  93         goto exit; \
  94     } \
  95
  96 typedef struct OCResource OCResource;
  97
  98 void OC_CALL OCPayloadDestroy(OCPayload* payload);
  99
 100 // Representation Payload
 101 OCRepPayload* OC_CALL OCRepPayloadCreate(void);
 102
 103 size_t OC_CALL calcDimTotal(const size_t dimensions[MAX_REP_ARRAY_DEPTH]);
 104
 105 OCRepPayload* OC_CALL OCRepPayloadClone(const OCRepPayload* payload);
 106
 107 OCRepPayload* OC_CALL OCRepPayloadBatchClone(const OCRepPayload* repPayload);
 108
 109 void OC_CALL OCRepPayloadAppend(OCRepPayload* parent, OCRepPayload* child);
 110
 111 bool OC_CALL OCRepPayloadSetUri(OCRepPayload* payload, const char* uri);
 112
 113 bool OC_CALL OCRepPayloadAddResourceType(OCRepPayload* payload, const char* resourceType);
 114 bool OC_CALL OCRepPayloadAddInterface(OCRepPayload* payload, const char* iface);
 115
 116 bool OC_CALL OCRepPayloadAddResourceTypeAsOwner(OCRepPayload* payload, char* resourceType);
 117 bool OC_CALL OCRepPayloadAddInterfaceAsOwner(OCRepPayload* payload, char* iface);
 118
 119 bool OC_CALL OCRepPayloadIsNull(const OCRepPayload* payload, const char* name);
 120 bool OC_CALL OCRepPayloadSetNull(OCRepPayload* payload, const char* name);
 121
 122 bool OC_CALL OCRepPayloadSetPropInt(OCRepPayload* payload, const char* name, int64_t value);
 123 bool OC_CALL OCRepPayloadGetPropInt(const OCRepPayload* payload, const char* name, int64_t* value);
 124
 125 bool OC_CALL OCRepPayloadSetPropDouble(OCRepPayload* payload, const char* name, double value);
 126 bool OC_CALL OCRepPayloadGetPropDouble(const OCRepPayload* payload, const char* name, double* value);
 127
 128 /**
 129  * This function allocates memory for the byte string and sets it in the payload.
 130  *
 131  * @param payload      Pointer to the payload to which byte string needs to be added.
 132  * @param name         Name of the byte string.
 133  * @param value        Byte string and it's length.
 134  *
 135  * @return true on success, false upon failure.
 136  */
 137 bool OC_CALL OCRepPayloadSetPropByteString(OCRepPayload* payload, const char* name, OCByteString value);
 138
 139 /**
 140  * This function sets the byte string in the payload.
 141  *
 142  * @param payload      Pointer to the payload to which byte string needs to be added.
 143  * @param name         Name of the byte string.
 144  * @param value        Byte string and it's length.
 145  *
 146  * @return true on success, false upon failure.
 147  */
 148 bool OC_CALL OCRepPayloadSetPropByteStringAsOwner(OCRepPayload* payload, const char* name,
 149         OCByteString* value);
 150
 151 /**
 152  * This function gets the byte string from the payload.
 153  *
 154  * @param payload      Pointer to the payload from which byte string needs to be retrieved.
 155  * @param name         Name of the byte string.
 156  * @param value        Byte string and it's length.
 157  *
 158  * @note: Caller needs to invoke OCFree on value.bytes after it is finished using the byte string.
 159  *
 160  * @return true on success, false upon failure.
 161  */
 162 bool OC_CALL OCRepPayloadGetPropByteString(const OCRepPayload* payload, const char* name,
 163         OCByteString* value);
 164
 165 bool OC_CALL OCRepPayloadSetPropString(OCRepPayload* payload, const char* name, const char* value);
 166 bool OC_CALL OCRepPayloadSetPropStringAsOwner(OCRepPayload* payload, const char* name, char* value);
 167 bool OC_CALL OCRepPayloadGetPropString(const OCRepPayload* payload, const char* name, char** value);
 168
 169 bool OC_CALL OCRepPayloadSetPropBool(OCRepPayload* payload, const char* name, bool value);
 170 bool OC_CALL OCRepPayloadGetPropBool(const OCRepPayload* payload, const char* name, bool* value);
 171
 172 bool OC_CALL OCRepPayloadSetPropObject(OCRepPayload* payload, const char* name, const OCRepPayload* value);
 173 bool OC_CALL OCRepPayloadSetPropObjectAsOwner(OCRepPayload* payload, const char* name, OCRepPayload* value);
 174 bool OC_CALL OCRepPayloadGetPropObject(const OCRepPayload* payload, const char* name, OCRepPayload** value);
 175
 176 #ifdef __WITH_TLS__
 177 bool OC_CALL OCRepPayloadSetPropPubDataType(OCRepPayload *payload, const char *name, const OicSecKey_t *value);
 178 bool OC_CALL OCRepPayloadSetPropPubDataTypeAsOwner(OCRepPayload *payload, const char *name, const OicSecKey_t *value);
 179 bool OC_CALL OCRepPayloadGetPropPubDataType(const OCRepPayload *payload, const char *name, OicSecKey_t *value);
 180 #endif
 181
 182 /**
 183  * This function allocates memory for the byte string array and sets it in the payload.
 184  *
 185  * @param payload      Pointer to the payload to which byte string array needs to be added.
 186  * @param name         Name of the byte string.
 187  * @param array        Byte string array.
 188  * @param dimensions   Number of byte strings in above array.
 189  *
 190  * @return true on success, false upon failure.
 191  */
 192 bool OC_CALL OCRepPayloadSetByteStringArrayAsOwner(OCRepPayload* payload, const char* name,
 193         OCByteString* array, size_t dimensions[MAX_REP_ARRAY_DEPTH]);
 194
 195 /**
 196  * This function sets the byte string array in the payload.
 197  *
 198  * @param payload      Pointer to the payload to which byte string array needs to be added.
 199  * @param name         Name of the byte string.
 200  * @param array        Byte string array.
 201  * @param dimensions   Number of byte strings in above array.
 202  *
 203  * @return true on success, false upon failure.
 204  */
 205 bool OC_CALL OCRepPayloadSetByteStringArray(OCRepPayload* payload, const char* name,
 206         const OCByteString* array, size_t dimensions[MAX_REP_ARRAY_DEPTH]);
 207
 208 /**
 209  * This function gets the byte string array from the payload.
 210  *
 211  * @param payload      Pointer to the payload from which byte string array needs to be retrieved.
 212  * @param name         Name of the byte string array.
 213  * @param array        Byte string array.
 214  * @param dimensions   Number of byte strings in above array.
 215  *
 216  * @note: Caller needs to invoke OICFree on 'bytes' field of all array elements after it is
 217  *        finished using the byte string array.
 218  *
 219  * @return true on success, false upon failure.
 220  */
 221 bool OC_CALL OCRepPayloadGetByteStringArray(const OCRepPayload* payload, const char* name,
 222         OCByteString** array, size_t dimensions[MAX_REP_ARRAY_DEPTH]);
 223
 224 bool OC_CALL OCRepPayloadSetIntArrayAsOwner(OCRepPayload* payload, const char* name,
 225         int64_t* array, size_t dimensions[MAX_REP_ARRAY_DEPTH]);
 226 bool OC_CALL OCRepPayloadSetIntArray(OCRepPayload* payload, const char* name,
 227         const int64_t* array, size_t dimensions[MAX_REP_ARRAY_DEPTH]);
 228 bool OC_CALL OCRepPayloadGetIntArray(const OCRepPayload* payload, const char* name,
 229         int64_t** array, size_t dimensions[MAX_REP_ARRAY_DEPTH]);
 230
 231 bool OC_CALL OCRepPayloadSetDoubleArrayAsOwner(OCRepPayload* payload, const char* name,
 232         double* array, size_t dimensions[MAX_REP_ARRAY_DEPTH]);
 233 bool OC_CALL OCRepPayloadSetDoubleArray(OCRepPayload* payload, const char* name,
 234         const double* array, size_t dimensions[MAX_REP_ARRAY_DEPTH]);
 235 bool OC_CALL OCRepPayloadGetDoubleArray(const OCRepPayload* payload, const char* name,
 236         double** array, size_t dimensions[MAX_REP_ARRAY_DEPTH]);
 237
 238 bool OC_CALL OCRepPayloadSetStringArrayAsOwner(OCRepPayload* payload, const char* name,
 239         char** array, size_t dimensions[MAX_REP_ARRAY_DEPTH]);
 240 bool OC_CALL OCRepPayloadSetStringArray(OCRepPayload* payload, const char* name,
 241         const char** array, size_t dimensions[MAX_REP_ARRAY_DEPTH]);
 242 bool OC_CALL OCRepPayloadGetStringArray(const OCRepPayload* payload, const char* name,
 243         char*** array, size_t dimensions[MAX_REP_ARRAY_DEPTH]);
 244
 245 bool OC_CALL OCRepPayloadSetBoolArrayAsOwner(OCRepPayload* payload, const char* name,
 246         bool* array, size_t dimensions[MAX_REP_ARRAY_DEPTH]);
 247 bool OC_CALL OCRepPayloadSetBoolArray(OCRepPayload* payload, const char* name,
 248         const bool* array, size_t dimensions[MAX_REP_ARRAY_DEPTH]);
 249 bool OC_CALL OCRepPayloadGetBoolArray(const OCRepPayload* payload, const char* name,
 250         bool** array, size_t dimensions[MAX_REP_ARRAY_DEPTH]);
 251
 252 bool OC_CALL OCRepPayloadSetPropObjectArrayAsOwner(OCRepPayload* payload, const char* name,
 253         OCRepPayload** array, size_t dimensions[MAX_REP_ARRAY_DEPTH]);
 254 bool OC_CALL OCRepPayloadSetPropObjectArray(OCRepPayload* payload, const char* name,
 255         const OCRepPayload** array, size_t dimensions[MAX_REP_ARRAY_DEPTH]);
 256 bool OC_CALL OCRepPayloadGetPropObjectArray(const OCRepPayload* payload, const char* name,
 257         OCRepPayload*** array, size_t dimensions[MAX_REP_ARRAY_DEPTH]);
 258
 259 void OC_CALL OCRepPayloadDestroy(OCRepPayload* payload);
 260
 261 // Discovery Payload
 262 OCDiscoveryPayload* OC_CALL OCDiscoveryPayloadCreate(void);
 263
 264 OCSecurityPayload* OC_CALL OCSecurityPayloadCreate(const uint8_t* securityData, size_t size);
 265 void OC_CALL OCSecurityPayloadDestroy(OCSecurityPayload* payload);
 266
 267 OCIntrospectionPayload* OC_CALL OCIntrospectionPayloadCreateFromCbor(const uint8_t* cborData,
 268                                                              size_t size);
 269 void OC_CALL OCIntrospectionPayloadDestroy(OCIntrospectionPayload* payload);
 270
 271 #ifndef TCP_ADAPTER
 272 void OC_CALL OCDiscoveryPayloadAddResource(OCDiscoveryPayload* payload, const OCResource* res,
 273                                    uint16_t securePort);
 274 #else
 275 void OC_CALL OCDiscoveryPayloadAddResource(OCDiscoveryPayload* payload, const OCResource* res,
 276                                    uint16_t securePort, uint16_t tcpPort);
 277 #endif
 278 void OC_CALL OCDiscoveryPayloadAddNewResource(OCDiscoveryPayload* payload,
 279                                       OCResourcePayload* res);
 280 bool OC_CALL OCResourcePayloadAddStringLL(OCStringLL **payload, const char* type);
 281
 282 size_t OC_CALL OCDiscoveryPayloadGetResourceCount(OCDiscoveryPayload* payload);
 283 OCResourcePayload* OC_CALL OCDiscoveryPayloadGetResource(OCDiscoveryPayload* payload,
 284                                                  size_t index);
 285
 286 size_t OC_CALL OCEndpointPayloadGetEndpointCount(OCEndpointPayload* payload);
 287 OCEndpointPayload* OC_CALL OCEndpointPayloadGetEndpoint(OCEndpointPayload* payload,
 288                                                 size_t index);
 289
 290 void OC_CALL OCResourcePayloadAddNewEndpoint(OCResourcePayload* payload,
 291                                      OCEndpointPayload* endpoint);
 292 void OC_CALL OCDiscoveryEndpointDestroy(OCEndpointPayload* payload);
 293 void OC_CALL OCDiscoveryResourceDestroy(OCResourcePayload* payload);
 294 void OC_CALL OCDiscoveryPayloadDestroy(OCDiscoveryPayload* payload);
 295
 296 // Presence Payload
 297 OCPresencePayload* OC_CALL OCPresencePayloadCreate(uint32_t seqNum, uint32_t maxAge,
 298         OCPresenceTrigger trigger, const char* resourceType);
 299 void OC_CALL OCPresencePayloadDestroy(OCPresencePayload* payload);
 300
 301 // Diagnostic Payload
 302 OCDiagnosticPayload* OC_CALL OCDiagnosticPayloadCreate(const char *message);
 303 void OC_CALL OCDiagnosticPayloadDestroy(OCDiagnosticPayload* payload);
 304
 305 // Helper API
 306 OCStringLL* OC_CALL CloneOCStringLL (OCStringLL* ll);
 307 void OC_CALL OCFreeOCStringLL(OCStringLL* ll);
 308
 309 /**
 310  * This function creates a list from a string (with separated contents if several)
 311  * @param text         single string or CSV text fields
 312  * @return newly allocated linked list
 313  * @note separator is ',' (according to rfc4180, ';' is not valid)
 314  **/
 315 OCStringLL* OC_CALL OCCreateOCStringLL(const char* text);
 316
 317 /**
 318  * This function creates a string from a list (with separated contents if several)
 319  * @param ll           Pointer to list
 320  * @return newly allocated string. Caller takes ownership and must later free this memory with OICFree.
 321  * @note separator is ',' (according to rfc4180)
 322  **/
 323 char* OC_CALL OCCreateString(const OCStringLL* ll);
 324
 325 /**
 326  * This function copies contents
 327  * @param dest existing bytestring.  The existing contents will be OICFree()'d.
 328  * @param source existing bytestring
 329  * @return true of success false on any errors
 330  **/
 331 bool OC_CALL OCByteStringCopy(OCByteString *dest, const OCByteString *source);
 332
 333 /**
 334  * This function creates the payloadArray for links parameter of collection resource.
 335  * @param[in] resourceUri Resource URI (this should be a collection resource)
 336  * @param[in] ehRequest parameter received from Entity Handler for client request
 337  * @param[in] insertSelfLink flag to specify whether links array can contain a self link
 338  * @param[out] createdArraySize return value array size, Null is allowed if no need to know size
 339  *
 340  * @note: API usage
 341  *   OCRepPayload **linkArr = OCLinksPayloadArrayCreate(uri, ehRequest, false, &ArraySize);
 342  *   For links parameter setting  (baseline interface response)
 343  *    OCRepPayloadSetPropObjectArrayAsOwner(payload, OC_RSRVD_LINKS, linkArr, {ArraySize, 0,0});
 344  *   For arrayPayload setting (linklist interface response)
 345  *     payload = linkArr[0]; payload->next = linkArr[1]; ....
 346  *     OICFree(linkArr)
 347  * @note: The destroy of OCRepPayloadArray is not supported. Instead, use
 348  *        OCRepPayloadDestroy(...) to destroy RepPayload of the collection Resource
 349  *
 350  * @return linksRepPayloadArray The *RepPayload Array pointer for links parameter of collection.
 351  **/
 352 OCRepPayload** OC_CALL OCLinksPayloadArrayCreate(const char *resourceUri,
 353                        OCEntityHandlerRequest *ehRequest, bool insertSelfLink, size_t* createdArraySize);
 354
 355 #ifdef __cplusplus
 356 }
 357 #endif
 358
 359 #endif