Merge branch 'master' into windows-port
[platform/upstream/iotivity.git] / resource / csdk / stack / include / rdpayload.h
1 //******************************************************************
2 //
3 // Copyright 2015 Samsung Electronics 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_RDPAYLOAD_H_
22 #define OC_RDPAYLOAD_H_
23
24 #include <cbor.h>
25 #include "octypes.h"
26 #include "logger.h"
27
28 #ifdef __cplusplus
29 extern "C" {
30 #endif // __cplusplus
31
32 /**
33  * Converts RD payload from structure to CBOR format. It creates the outPayload
34  * which is then transmitted over the wire.
35  *
36  * @param rdPayload Contains structure holding values of OCRDPayload.
37  * @param outPayload The payload in the CBOR format converting OCRDPayload
38  * structure.
39  * @param size Length of the payload.
40  *
41  * @return ::CborNoError returns if successful and other Cbor error in  case of error.
42  * failed in creating CBOR.
43  */
44 CborError OCRDPayloadToCbor(const OCRDPayload *rdPayload, uint8_t *outPayload, size_t *size);
45
46 /**
47  * Converts CBOR to OCRDPayload.
48  *
49  * @param rdCBORPayload Payload received from other end in CBOR format.
50  * @param outPayload Parsing the values from CBOR into OCRDPayload structure.
51  *
52  * @return ::OC_STACK_OK returns if successful and OC_STACK_ERROR returns if
53  * failed in parsing CBOR.
54  */
55 OCStackResult OCRDCborToPayload(const CborValue *cborPayload, OCPayload **outPayload);
56
57 /**
58  * Initializes RD payload structure.
59  *
60  * @param payloadType Defines whether payload is RD_PAYLOAD_TYPE_DISCOVERY or
61  * RD_PAYLOAD_TYPE_PUBLISH.
62  *
63  * @return Allocated memory for the OCRDPayload and NULL in case if failed to
64  * allocate memory
65  */
66 OCRDPayload *OCRDPayloadCreate();
67
68 /**
69  * Initializes RD Discovery payload structure and sets the bias factor.
70  *
71  * @param name Name of the discovery device payload.
72  * @param identity Device identity of the discovery device.
73  * @param biasFactor Value specifies the selection factor. It is weigthage of
74  * CPU, Memory, Network, Load and Power capability of the RD server.
75  *
76  * @return Allocated memory for the OCRDDiscoveryPayload and NULL in case if
77  * failed to allocate memory.
78  */
79 OCRDDiscoveryPayload *OCRDDiscoveryPayloadCreate(const char *name, const char *identity, int biasFactor);
80
81 /**
82  * Free memory allocation of the RDPayload and its internal structure.
83  *
84  * @param payload Pointer to already allocated memory for OCRDPayload.
85  */
86 void OCRDPayloadDestroy(OCRDPayload *payload);
87
88 /**
89  * Copies tag paramter to creates OCTagsPayload.
90  *
91  * @param deviceName The device name as set during enrollment.
92  * @param id The device UUID
93  * @param baseURI baseURI pointing to the resource directory location.
94  * @param bitmap The bitmap value include observe, discovery and secure bit set.
95  * @param port The secure port in case above bitmap is set to secure.
96  * @param ins Unique value per collection.
97  * @param rts Defines allowed resource types.
98  * @param drel Defines defaultr relationship.
99  * @param ttl Time to leave for the . Used only in resource directory.
100  *
101  * @retun Allocated memory for OCTagsPayload or else NULL in case of error.
102  */
103 OCTagsPayload* OCCopyTagsResources(const char *deviceName, const unsigned char *id,
104     const char *baseURI, uint8_t bitmap, uint16_t port, uint8_t ins, const char *rts, const char *drel, uint32_t ttl);
105
106 /**
107  * Copies link resource to create LinksPayload.
108  *
109  * @param href URI of the resource
110  * @param rt Array of String pointing to resource types.
111  * @param itf Array of String pointing to interface
112  * @param rel Relation
113  * @param obs Whether to observe or not.
114  * @param title Title
115  * @param uri URI
116  * @param ins Unique value per link.
117  * @param mt Media Type
118
119  * @retun Allocated memory for OCLinksPayload or else NULL in case of error.
120  */
121 OCLinksPayload* OCCopyLinksResources(const char *href, OCStringLL *rt, OCStringLL *itf,
122     const char *rel, bool obs, const char *title, const char *uri, uint8_t ins, OCStringLL *mt);
123
124 /**
125  * Creates a resource collection object.
126  *
127  * @param tags Pointer pointing to tags payload.
128  * @param links Pointer pointing to links payload.
129  *
130  * @return Memory allocation for OCResourceCollectionPayload, else NULL.
131  */
132 OCResourceCollectionPayload* OCCopyCollectionResource(OCTagsPayload *tags, OCLinksPayload *links);
133
134 /**
135  * Destroys tags payload including internal structure allocated
136  *
137  * @param tags - Allocated memory of the tags payload.
138  */
139 void OCFreeTagsResource(OCTagsPayload *tags);
140
141 /**
142  * Destroys allocated links payload including internal structure allocated.
143  *
144  * @param links - Allocated memory to the links payload.
145  */
146 void OCFreeLinksResource(OCLinksPayload *links);
147
148 /**
149  * ResourceCollection payload destroy. Includes free up tags and links structure.
150  *
151  * @param payload Pointer pointing to allocated memroy of ResourceCollection.
152  */
153 void OCFreeCollectionResource(OCResourceCollectionPayload *payload);
154
155 /**
156  * Discovery collection payload destroy includes internal structure OCResourceCollectionPayload.
157  *
158  * @param payload Pointer pointing to allocated memory of OCDiscoveryPayload.
159  */
160 void OCDiscoveryCollectionPayloadDestroy(OCDiscoveryPayload* payload);
161
162 /**
163  * Prints tags payload.
164  *
165  * @param level LogLevel for the print.
166  * @param tags Structure of the tags payload.
167  */
168 OC_EXPORT void OCTagsLog(const LogLevel level, const OCTagsPayload *tags);
169
170 /**
171  * Prints links payload.
172  *
173  * @param level LogLevel for the print.
174  * @param tags Structure of the links payload.
175  */
176 OC_EXPORT void OCLinksLog(const LogLevel level, const OCLinksPayload *links);
177
178 #ifdef __cplusplus
179 }
180 #endif // __cplusplus
181
182 #endif /* OC_RDPAYLOAD_H_ */