Use `URI` all caps in documentation
[iotivity.git] / resource / csdk / connectivity / inc / caprotocolmessage.h
1 /******************************************************************
2  *
3  * Copyright 2014 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  * @file
22  * This file contains common function for handling protocol messages.
23  */
24
25 #ifndef CA_PROTOCOL_MESSAGE_H_
26 #define CA_PROTOCOL_MESSAGE_H_
27
28 #include "cacommon.h"
29 #ifndef WITH_UPSTREAM_LIBCOAP
30 #include "coap/config.h"
31 #endif
32 #include <coap/coap.h>
33
34 #ifdef __cplusplus
35 extern "C"
36 {
37 #endif
38
39 typedef uint32_t code_t;
40
41 #define CA_RESPONSE_CLASS(C) (((C) >> 5)*100)
42 #define CA_RESPONSE_CODE(C) (CA_RESPONSE_CLASS(C) + (C - COAP_RESPONSE_CODE(CA_RESPONSE_CLASS(C))))
43
44 #define HAVE_TIME_H 1
45
46 #ifdef WITH_TCP
47 static const uint8_t PAYLOAD_MARKER = 1;
48 #endif
49
50 /**
51  * generates pdu structure from the given information.
52  * @param[in]   code                 code of the pdu packet.
53  * @param[in]   info                 pdu information.
54  * @param[in]   endpoint             endpoint information.
55  * @return  generated pdu.
56  */
57 coap_pdu_t *CAGeneratePDU(uint32_t code, const CAInfo_t *info, const CAEndpoint_t *endpoint,
58                           coap_list_t **optlist, coap_transport_t *transport);
59
60 /**
61  * extracts request information from received pdu.
62  * @param[in]   pdu                   received pdu.
63  * @param[in]   endpoint              endpoint information.
64  * @param[out]  outReqInfo            request info structure made from received pdu.
65  * @return  CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h).
66  */
67 CAResult_t CAGetRequestInfoFromPDU(const coap_pdu_t *pdu, const CAEndpoint_t *endpoint,
68                                    CARequestInfo_t *outReqInfo);
69
70 /**
71  * extracts response information from received pdu.
72  * @param[in]   pdu                   received pdu.
73  * @param[out]  outResInfo            response info structure made from received pdu.
74  * @param[in]   endpoint              endpoint information.
75  * @return  CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h).
76  */
77 CAResult_t CAGetResponseInfoFromPDU(const coap_pdu_t *pdu, CAResponseInfo_t *outResInfo,
78                                     const CAEndpoint_t *endpoint);
79
80 /**
81  * extracts error information from received pdu.
82  * @param[in]   pdu                   received pdu.
83  * @param[in]   endpoint              endpoint information.
84  * @param[out]  errorInfo             error info structure made from received pdu.
85  * @return  CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h).
86  */
87 CAResult_t CAGetErrorInfoFromPDU(const coap_pdu_t *pdu, const CAEndpoint_t *endpoint,
88                                  CAErrorInfo_t *errorInfo);
89
90 /**
91  * extracts signaling information from received pdu.
92  * @param[in]   pdu                   received pdu.
93  * @param[in]   endpoint              endpoint information.
94  * @param[out]  outSigInfo            signaling info structure made from received pdu.
95  * @return  CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h).
96  */
97 CAResult_t CAGetSignalingInfoFromPDU(const coap_pdu_t *pdu, const CAEndpoint_t *endpoint,
98                                      CASignalingInfo_t *outSigInfo);
99
100 /**
101  * creates pdu from the request information.
102  * @param[in]   code                 request or response code.
103  * @param[in]   info                 information to create pdu.
104  * @param[in]   endpoint             endpoint information.
105  * @param[out]  options              options for the request and response.
106  * @return  generated pdu.
107  */
108 coap_pdu_t *CAGeneratePDUImpl(code_t code, const CAInfo_t *info,
109                               const CAEndpoint_t *endpoint, coap_list_t *options,
110                               coap_transport_t *transport);
111
112 /**
113  * parse the URI and creates the options.
114  * @param[in]    uriInfo             URI information.
115  * @param[out]   options             options information.
116  * @return  CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h).
117  */
118 CAResult_t CAParseURI(const char *uriInfo, coap_list_t **options);
119
120 /**
121  * Helper that uses libcoap to parse either the path or the parameters of a URI
122  * and populate the supplied options list.
123  *
124  * @param[in]   str                  the input partial URI string (either path or query).
125  * @param[in]   length               the length of the supplied partial URI.
126  * @param[in]   target               the part of the URI to parse (either COAP_OPTION_URI_PATH.
127  *                                   or COAP_OPTION_URI_QUERY).
128  * @param[out]  optlist              options information.
129  * @return  CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h).
130  */
131 CAResult_t CAParseUriPartial(const unsigned char *str, size_t length, uint16_t target,
132                              coap_list_t **optlist);
133
134 /**
135  * create option list from header information in the info.
136  * @param[in]   code                 URI information.
137  * @param[in]   info                 information of the request/response.
138  * @param[out]  optlist              options information.
139  * @return  CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h).
140  */
141 CAResult_t CAParseHeadOption(uint32_t code, const CAInfo_t *info, coap_list_t **optlist);
142
143 /**
144  * Helper to parse content format and accept format header options
145  * and populate the supplied options list.
146  *
147  * @param[in]   formatOption         CoAP format header option.
148  * @param[in]   format               content or accept format.
149  * @param[in]   versionOption        CoAP version header option.
150  * @param[in]   version              value of version.
151  * @param[out]  optlist              options information.
152  * @return  CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h).
153  */
154
155 CAResult_t CAParsePayloadFormatHeadOption(uint16_t formatOption, CAPayloadFormat_t format,
156         uint16_t versionOption, uint16_t version, coap_list_t **optlist);
157
158 /**
159  * creates option node from key length and data.
160  * @param[in]   key                  key for the that needs to be sent.
161  * @param[in]   length               length of the data that needs to be sent.
162  * @param[in]   data                 data that needs to be sent.
163  * @return  created list.
164  */
165 coap_list_t *CACreateNewOptionNode(uint16_t key, uint32_t length, const char *data);
166
167 /**
168  * order the inserted options.
169  * need to replace queue head if new node has to be added before the existing queue head.
170  * @param[in]   a                    option 1 for insertion.
171  * @param[in]   b                    option 2 for insertion.
172  * @return  0 or 1.
173  */
174 int CAOrderOpts(void *a, void *b);
175
176 /**
177  * number of options count.
178  * @param[in]   opt_iter            option iteration for count.
179  * @param[out]  optionCount         number of options.
180  * @return CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h).
181  */
182 CAResult_t CAGetOptionCount(coap_opt_iterator_t opt_iter, uint8_t *optionCount);
183
184 /**
185  * gets option data.
186  * @param[in]   key                  ID of the option
187  * @param[in]   data                 data that is received.
188  * @param[in]   length               length of the data.
189  * @param[out]  option               result of the operation.
190  * @param[in]   buflen               buffer length of the result.
191  * @return  option count.
192  */
193 uint32_t CAGetOptionData(uint16_t key, const uint8_t *data, uint32_t len,
194                          uint8_t *option, uint32_t buflen);
195
196 /**
197  * extracts request information from received pdu.
198  * @param[in]    pdu                  received pdu.
199  * @param[in]    endpoint             endpoint information.
200  * @param[out]   outCode              code of the received pdu.
201  * @param[out]   outInfo              request info structure made from received pdu.
202  * @return  CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h).
203  */
204 CAResult_t CAGetInfoFromPDU(const coap_pdu_t *pdu, const CAEndpoint_t *endpoint,
205                             uint32_t *outCode, CAInfo_t *outInfo);
206
207 /**
208  * create pdu from received data.
209  * @param[in]   data                received data.
210  * @param[in]   length              length of the data received.
211  * @param[out]  outCode             code received.
212  * @param[in]   endpoint            endpoint information.
213  * @return  coap_pdu_t value.
214  */
215 coap_pdu_t *CAParsePDU(const char *data, size_t length, uint32_t *outCode,
216                        const CAEndpoint_t *endpoint);
217
218 /**
219  * get Token from received data(pdu).
220  * @param[in]    pdu_hdr             header of received pdu.
221  * @param[out]   outInfo             information with token received.
222  * @param[in]    endpoint            endpoint information.
223  * @return  CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h).
224  */
225 CAResult_t CAGetTokenFromPDU(const coap_hdr_transport_t *pdu_hdr,
226                              CAInfo_t *outInfo,
227                              const CAEndpoint_t *endpoint);
228
229 /**
230  * generates the token.
231  * @param[out]   token           generated token.
232  * @param[in]    tokenLength     length of the token.
233  * @return  CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h).
234  */
235 CAResult_t CAGenerateTokenInternal(CAToken_t *token, uint8_t tokenLength);
236
237 /**
238  * destroys the token.
239  * @param[in]   token           generated token.
240  */
241 void CADestroyTokenInternal(CAToken_t token);
242
243 /**
244  * gets message type from PDU binary data.
245  * @param[in]   pdu                 pdu data.
246  * @param[in]   size                size of pdu data.
247  * @return  message type.
248  */
249 CAMessageType_t CAGetMessageTypeFromPduBinaryData(const void *pdu, uint32_t size);
250
251 /**
252  * gets message ID PDU binary data.
253  * @param[in]   pdu                 pdu data.
254  * @param[in]   size                size of pdu data.
255  * @return  message ID.
256  */
257 uint16_t CAGetMessageIdFromPduBinaryData(const void *pdu, uint32_t size);
258
259 /**
260  * gets code PDU binary data.
261  * @param[in]   pdu                 pdu data.
262  * @param[in]   size                size of pdu data.
263  * @return  code.
264  */
265 CAResponseResult_t CAGetCodeFromPduBinaryData(const void *pdu, uint32_t size);
266
267 /**
268  * convert format from CoAP media type encoding to CAPayloadFormat_t.
269  * @param[in]   format              coap format code.
270  * @return format.
271  */
272 CAPayloadFormat_t CAConvertFormat(uint16_t format);
273
274 #ifdef WITH_TCP
275 /**
276  * check whether CoAP over TCP is supported or not.
277  * @param[in]   adapter             transport adapter type.
278  * @return true or false.
279  */
280 bool CAIsSupportedCoAPOverTCP(CATransportAdapter_t adapter);
281 #endif
282
283 #ifdef WITH_BWT
284 /**
285  * check whether blockwise transfer is supported or not.
286  * @param[in]   adapter             transport adapter type.
287  * @return true or false.
288  */
289 bool CAIsSupportedBlockwiseTransfer(CATransportAdapter_t adapter);
290 #endif
291
292 #ifdef __cplusplus
293 } /* extern "C" */
294 #endif
295
296 #endif /* CA_PROTOCOL_MESSAGE_H_ */