Use `URI` all caps in documentation
[iotivity.git] / 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