Use `URI` all caps in documentation
[iotivity.git] / resource / csdk / connectivity / inc / catcpadapter.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 contains the APIs for TCP Adapter.
24  */
25 #ifndef CA_TCP_ADAPTER_H_
26 #define CA_TCP_ADAPTER_H_
27
28 #include "cacommon.h"
29 #include "caadapterinterface.h"
30 #include "cathreadpool.h"
31 #include "cainterface.h"
32 #include <coap/pdu.h>
33
34 #ifdef __cplusplus
35 extern "C"
36 {
37 #endif
38
39
40 typedef enum CAProtocol
41 {
42     UNKNOWN = 0,
43     TLS,
44     COAP
45 } CAProtocol_t;
46
47 /**
48  * TCP Connection State.
49  */
50 typedef enum
51 {
52     CONNECTING = 0,
53     CONNECTED,
54     DISCONNECTED
55 } CATCPConnectionState_t;
56
57 /**
58  * TCP Capability and Settings message(CSM) exchange state.
59  * Capability and Settings message must be sent
60  * as the first message for both server/client.
61  */
62 typedef enum
63 {
64     NONE = 0,
65     SENT,
66     RECEIVED,
67     SENT_RECEIVED
68 } CACSMExchangeState_t;
69
70 /**
71  * TCP Session Information for IPv4/IPv6 TCP transport
72  */
73 typedef struct CATCPSessionInfo_t
74 {
75     CASecureEndpoint_t sep;             /**< secure endpoint information */
76     CASocketFd_t fd;                    /**< file descriptor info */
77     unsigned char* data;                /**< received data from remote device */
78     size_t len;                         /**< received data length */
79     size_t totalLen;                    /**< total coap data length required to receive */
80     unsigned char tlsdata[18437];       /**< tls data(rfc5246: TLSCiphertext max (2^14+2048+5)) */
81     size_t tlsLen;                      /**< received tls data length */
82     CAProtocol_t protocol;              /**< application-level protocol */
83     CATCPConnectionState_t state;       /**< current tcp session state */
84     CACSMExchangeState_t CSMState;      /**< Capability and Setting Message shared status */
85     bool isClient;                      /**< Host Mode of Operation. */
86     struct CATCPSessionInfo_t *next;    /**< Linked list; for multiple session list. */
87 } CATCPSessionInfo_t;
88
89 /**
90  * API to initialize TCP Interface.
91  * @param[in] registerCallback      Callback to register TCP interfaces to
92  *                                  Connectivity Abstraction Layer.
93  * @param[in] networkPacketCallback Callback to notify request and
94  *                                  response messages from server(s)
95  *                                  started at Connectivity Abstraction Layer.
96  * @param[in] netCallback           Callback to notify the adapter changes
97  *                                  to Connectivity Abstraction Layer.
98  * @param[in] connCallback          Callback to notify the connection changes
99  *                                  to Connectivity Abstraction Layer.
100  * @param[in] errorCallback         Callback to notify the network errors to
101  *                                  Connectivity Abstraction Layer.
102  * @param[in] handle                Threadpool Handle.
103  * @return  ::CA_STATUS_OK or Appropriate error code
104  */
105 CAResult_t CAInitializeTCP(CARegisterConnectivityCallback registerCallback,
106                            CANetworkPacketReceivedCallback networkPacketCallback,
107                            CAAdapterChangeCallback netCallback,
108                            CAConnectionChangeCallback connCallback,
109                            CAErrorHandleCallback errorCallback, ca_thread_pool_t handle);
110
111 /**
112  * Start TCP Interface adapter.
113  * @return  ::CA_STATUS_OK or Appropriate error code.
114  */
115 CAResult_t CAStartTCP(void);
116
117 /**
118  * Disconnect TCP session.
119  * Per RFC 8323 TCP session needs to be disconnected in certain situations
120  * like if CSM message is not the first message for the session.
121  * @param[in]   endpoint       Remote Endpoint information (like ipaddress,
122  *                             port)
123  */
124 CAResult_t CATCPDisconnectSession(const CAEndpoint_t *endpoint);
125
126 /**
127  * Start listening server for receiving connect requests.
128  * Transport Specific Behavior:
129  * TCP Starts Listening Server on a particular interface and prefixed port
130  * number and as per OIC Specification.
131  * @return  ::CA_STATUS_OK or Appropriate error code.
132  */
133 CAResult_t CAStartTCPListeningServer(void);
134
135 /**
136  * Stops listening server from receiving connect requests.
137  * Transport Specific Behavior:
138  * TCP Stops Listening Server on a particular interface and prefixed port
139  * number and as per OIC Specification.
140  * @return  ::CA_STATUS_OK or Appropriate error code.
141  */
142 CAResult_t CAStopTCPListeningServer(void);
143
144 /**
145  * Start discovery servers for receiving advertisements.
146  * Transport Specific Behavior:
147  * TCP Starts Discovery server on a particular interface and prefixed port
148  * number as per OIC Specification.
149  * @return  ::CA_STATUS_OK or Appropriate error code.
150  */
151 CAResult_t CAStartTCPDiscoveryServer(void);
152
153 /**
154  * Sends data to the endpoint using the adapter connectivity.
155  * @param[in]   endpoint       Remote Endpoint information (like ipaddress,
156  *                              port, reference URI and transport type) to
157  *                              which the unicast data has to be sent.
158  * @param[in]   data           Data which is required to be sent.
159  * @param[in]   dataLen        Size of data to be sent.
160  * @param[in]   dataType       Data type which is REQUEST or RESPONSE.
161  * @note  dataLen must be > 0 and <= INT_MAX.
162  * @return  The number of bytes sent on the network, or -1 upon error.
163  */
164 int32_t CASendTCPUnicastData(const CAEndpoint_t *endpoint,
165                              const void *data, uint32_t dataLen,
166                              CADataType_t dataType);
167
168 /**
169  * Send Multicast data to the endpoint using the TCP connectivity.
170  * @param[in]   endpoint       Remote Endpoint information (like ipaddress,
171  *                              port)
172  * @param[in]   data           Data which is required to be sent.
173  * @param[in]   dataLen        Size of data to be sent.
174  * @param[in]   dataType       Data type which is REQUEST or RESPONSE.
175  * @note  dataLen must be > 0 and <= INT_MAX.
176  * @return  The number of bytes sent on the network, or -1 upon error.
177  */
178 int32_t CASendTCPMulticastData(const CAEndpoint_t *endpoint,
179                                const void *data, uint32_t dataLen,
180                                CADataType_t dataType);
181
182 /**
183  * Get TCP Connectivity network information.
184  * @param[out]   info        Local connectivity information structures.
185  * @note info is allocated in this API and should be freed by the caller.
186  * @param[out]   size        Number of local connectivity structures.
187  * @return  ::CA_STATUS_OK or Appropriate error code.
188  */
189 CAResult_t CAGetTCPInterfaceInformation(CAEndpoint_t **info, size_t *size);
190
191 /**
192  * Read Synchronous API callback.
193  * @return  ::CA_STATUS_OK or Appropriate error code.
194  */
195 CAResult_t CAReadTCPData(void);
196
197 /**
198  * Stops Unicast, servers and close the sockets.
199  * @return  ::CA_STATUS_OK or Appropriate error code.
200  */
201 CAResult_t CAStopTCP(void);
202
203 /**
204  * Terminate the TCP connectivity adapter.
205  * Configuration information will be deleted from further use.
206  */
207 void CATerminateTCP(void);
208
209 /**
210  * Set connection status changes callback to process KeepAlive.
211  * connection informations are delivered these callbacks.
212  * @param[in]   ConnHandler     Connection status changes callback.
213  */
214 void CATCPSetKeepAliveCallbacks(CAKeepAliveConnectionCallback ConnHandler);
215
216 /**
217  * Get Capability and Settings message(CSM) exchange state.
218  * @param[in]   endpoint        Remote Endpoint information (like ipaddress,
219  *                              port, reference URI and transport type)
220  *                              to check CSM state in session information.
221  * @return  current CSM exchange state of the session.
222  */
223 CACSMExchangeState_t CAGetCSMState(const CAEndpoint_t *endpoint);
224
225 /**
226 * Update Capability and Settings message(CSM) exchange state when sending or receiving CSM.
227 * @param[in]   endpoint        Remote Endpoint information (like ipaddress,
228 *                              port, reference URI and transport type) to update CSM state.
229 * @param[in]   state           CSM exchange state to be updated.
230 */
231 void CAUpdateCSMState(const CAEndpoint_t *endpoint, CACSMExchangeState_t state);
232
233 #ifdef __cplusplus
234 } /* extern "C" */
235 #endif
236
237 #endif  // CA_TCP_ADAPTER_H_