Use `URI` all caps in documentation
[iotivity.git] / resource / csdk / connectivity / inc / catcpinterface.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 /**
22  * @file
23  * This file provides APIs TCP client/server/network monitor modules.
24  */
25
26 #ifndef CA_TCP_INTERFACE_H_
27 #define CA_TCP_INTERFACE_H_
28
29 #include <stdbool.h>
30
31 #include "cacommon.h"
32 #include "catcpadapter.h"
33 #include "cathreadpool.h"
34 #include "uarraylist.h"
35
36 #ifdef __cplusplus
37 extern "C"
38 {
39 #endif
40
41 /**
42  * Callback to be notified on reception of any data from remote OIC devices.
43  *
44  * @param[in]  endpoint      network endpoint description.
45  * @param[in]  data          Data received from remote OIC device.
46  * @param[in]  dataLength    Length of data in bytes.
47  * @pre  Callback must be registered using CAIPSetPacketReceiveCallback().
48  */
49 typedef void (*CATCPPacketReceivedCallback)(const CASecureEndpoint_t *endpoint,
50                                             const void *data,
51                                             size_t dataLength);
52
53 /**
54   * Callback to notify error in the TCP adapter.
55   *
56   * @param[in]  endpoint      network endpoint description.
57   * @param[in]  data          Data sent/received.
58   * @param[in]  dataLength    Length of data in bytes.
59   * @param[in]  result        result of request from R.I.
60   * @pre  Callback must be registered using CAIPSetPacketReceiveCallback().
61  */
62 typedef void (*CATCPErrorHandleCallback)(const CAEndpoint_t *endpoint, const void *data,
63                                          size_t dataLength, CAResult_t result);
64
65 /**
66   * Callback to notify connection information in the TCP adapter.
67   *
68   * @param[in]  endpoint        network endpoint description.
69   * @param[in]  isConnected     Whether keepalive message needs to be sent.
70   * @param[in]  isClient        Host Mode of Operation.
71   * @see  Callback must be registered using CATCPSetKeepAliveCallback().
72  */
73 typedef void (*CATCPConnectionHandleCallback)(const CAEndpoint_t *endpoint, bool isConnected,
74                                               bool isClient);
75
76 /**
77  * set error callback to notify error in TCP adapter.
78  *
79  * @param[in]  errorHandleCallback Callback function to notify the error
80  * in the TCP adapter.
81  */
82 void CATCPSetErrorHandler(CATCPErrorHandleCallback errorHandleCallback);
83
84 /**
85  * set keepalive callback to notify connection information in TCP adapter.
86  *
87  * @param[in]  keepaliveHandler Callback function to notify the connection information.
88  * in the TCP adapter.
89  */
90 void CATCPSetKeepAliveCallback(CAKeepAliveConnectionCallback keepaliveHandler);
91
92 /**
93  * Start TCP server.
94  *
95  * @param   threadPool   Thread pool for managing Unicast server threads.
96  * @return ::CA_STATUS_OK or Appropriate error code.
97  * @retval ::CA_STATUS_OK  Successful.
98  * @retval ::CA_STATUS_INVALID_PARAM Invalid input data.
99  * @retval ::CA_STATUS_FAILED Initialization failed.
100  */
101 CAResult_t CATCPStartServer(const ca_thread_pool_t threadPool);
102
103
104 /**
105  * Stop TCP server.
106  */
107 void CATCPStopServer(void);
108
109 /**
110  * Set this callback for receiving data packets from peer devices.
111  *
112  * @param[in]  callback    Callback to be notified on reception of unicast data packets.
113  */
114 void CATCPSetPacketReceiveCallback(CATCPPacketReceivedCallback callback);
115
116 /**
117  * Set this callback for receiving the changed connection information from peer devices.
118  *
119  * @param[in]  connHandler    Callback to be notified when connection state changes.
120  */
121 void CATCPSetConnectionChangedCallback(CATCPConnectionHandleCallback connHandler);
122
123 /**
124  * API to send unicast TCP data.
125  *
126  * @param[in]  endpoint          complete network address to send to.
127  * @param[in]  data              Data to be send.
128  * @param[in]  dataLength        Length of data in bytes.
129  * @return  Sent data length or -1 on error.
130  */
131 ssize_t CATCPSendData(CAEndpoint_t *endpoint, const void *data, size_t dataLength);
132
133 /**
134  * Get a list of CAInterface_t items.
135  *
136  * @return  List of CAInterface_t items.
137  */
138 u_arraylist_t *CATCPGetInterfaceInformation(int desiredIndex);
139
140 /**
141  * Connect to TCP Server.
142  *
143  * @param[in]   endpoint    remote endpoint information.
144  * @return  Created socket file descriptor.
145  */
146 CASocketFd_t CAConnectTCPSession(const CAEndpoint_t *endpoint);
147
148 /**
149  * Disconnect from TCP Server.
150  *
151  * @param[in]   removedData       removed session information from list.
152  * @return  ::CA_STATUS_OK or Appropriate error code.
153  */
154 CAResult_t CADisconnectTCPSession(CATCPSessionInfo_t *removedData);
155
156 /**
157  * Disconnect all connection from TCP Server.
158  */
159 void CATCPDisconnectAll(void);
160
161 /**
162  * Get TCP connection information from list.
163  *
164  * @param[in]   endpoint    remote endpoint information.
165  * @return  TCP Session Information structure.
166  */
167 CATCPSessionInfo_t *CAGetTCPSessionInfoFromEndpoint(const CAEndpoint_t *endpoint);
168
169 /**
170  * Get total length from CoAP over TCP header.
171  *
172  * @param[in]   recvBuffer    received header data.
173  * @return  total data length
174  */
175 size_t CAGetTotalLengthFromHeader(const unsigned char *recvBuffer);
176
177 /**
178  * Get code from CoAP over TCP header.
179  *
180  * @param[in]   recvBuffer    received header data.
181  * @return  method/response code
182  */
183 uint32_t CAGetCodeFromHeader(const unsigned char *recvBuffer);
184
185 /**
186  * Get socket file descriptor from remote device information.
187  *
188  * @param[in]   endpoint    Remote Endpoint information (such as ipaddress,
189  *                          port, reference URI and transport type) to
190  *                          which the unicast data has to be sent.
191  * @return  Created socket file descriptor.
192  */
193 CASocketFd_t CAGetSocketFDFromEndpoint(const CAEndpoint_t *endpoint);
194
195 /**
196  * Find the session with endpoint info and remove it from list.
197  *
198  * @param[in]   endpoint    Remote Endpoint information (such as ipaddress,
199  *                          port, reference URI and transport type) to
200  *                          which the unicast data has to be sent.
201  * @return  ::CA_STATUS_OK or Appropriate error code.
202  */
203 CAResult_t CASearchAndDeleteTCPSession(const CAEndpoint_t *endpoint);
204
205 /**
206  * Get total payload length from CoAP over TCP header.
207  *
208  * @param[in]   data    Data to be send.
209  * @param[in]   dlen    Total data length.
210  * @return  Payload length or 0 on error.
211  */
212 size_t CACheckPayloadLengthFromHeader(const void *data, size_t dlen);
213
214 /**
215  * Construct CoAP header and payload from buffer
216  *
217  * @param[in] svritem - used socket, buffer, current received message length and protocol
218  * @param[in,out]  data  - data buffer, this value is updated as data is copied to svritem
219  * @param[in,out]  dataLength  - length of data, this value decreased as data is copied to svritem
220  * @return             - CA_STATUS_OK or appropriate error code
221  */
222 CAResult_t CAConstructCoAP(CATCPSessionInfo_t *svritem, unsigned char **data,
223                           size_t *dataLength);
224
225 /**
226  * Clean socket state data
227  *
228  * @param[in,out] svritem - socket state data
229  */
230 void CACleanData(CATCPSessionInfo_t *svritem);
231
232 #ifdef __cplusplus
233 }
234 #endif
235
236 #endif /* CA_TCP_INTERFACE_H_ */
237