[IOT-1531]PAL API for get link-local zone id from ifindex
[iotivity.git] / resource / csdk / connectivity / api / cainterface.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 /**
22  * @file
23  *
24  * This file contains the APIs for Resource Model to use.
25  */
26
27 #ifndef CA_INTERFACE_H_
28 #define CA_INTERFACE_H_
29
30 /**
31  * Connectivity Abstraction Interface APIs.
32  */
33 #include "cacommon.h"
34 #include "casecurityinterface.h"
35
36 #ifdef __cplusplus
37 extern "C"
38 {
39 #endif
40
41 #ifdef RA_ADAPTER
42
43 /**
44  * Callback for bound JID
45  * @param[out]   jid           Boud Jabber Identifier.
46  */
47 typedef void (*CAJidBoundCallback)(char *jid);
48
49 /**
50  * CA Remote Access information for XMPP Client
51  *
52  */
53 typedef struct
54 {
55     char *hostName;     /**< XMPP server hostname */
56     uint16_t port;      /**< XMPP server serivce port */
57     char *xmppDomain;  /**< XMPP login domain */
58     char *userName;     /**< login username */
59     char *password;     /**< login password */
60     char *resource;     /**< specific resource for login */
61     char *userJid;     /**< specific JID for login */
62     CAJidBoundCallback jidBoundCallback;  /**< callback when JID bound */
63 } CARAInfo_t;
64
65 #endif //RA_ADAPTER
66
67 #ifdef TCP_ADAPTER
68 /**
69  * Callback function to pass the connection information from CA to RI.
70  * @param[out]   object           remote device information.
71  * @param[out]   isConnected      Whether keepalive message needs to be sent.
72  * @param[out]   isClient         Host Mode of Operation.
73  */
74 typedef void (*CAKeepAliveConnectionCallback)(const CAEndpoint_t *object, bool isConnected,
75                                               bool isClient);
76
77 /**
78  * Register connection status changes callback to process KeepAlive.
79  * connection informations are delivered these callbacks.
80  * @param[in]   ConnHandler     Connection status changes callback.
81  */
82 void CARegisterKeepAliveHandler(CAKeepAliveConnectionCallback ConnHandler);
83 #endif
84 /**
85  * Initialize the connectivity abstraction module.
86  * It will initialize adapters, thread pool and other modules based on the platform
87  * compilation options.
88  * @param[in]   transportType  transport type to initialize.
89  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_MEMORY_ALLOC_FAILED
90  */
91 CAResult_t CAInitialize(CATransportAdapter_t transportType);
92
93 /**
94  * Terminate the connectivity abstraction module.
95  * All threads, data structures are destroyed for next initializations.
96  */
97 void CATerminate();
98
99 /**
100  * Starts listening servers.
101  * This API is used by resource hosting server for listening multicast requests.
102  * Based on the adapters configurations, different kinds of servers are started.
103  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_STATUS_NOT_INITIALIZED
104  */
105 CAResult_t CAStartListeningServer();
106
107 /**
108  * Stops the server from receiving the multicast traffic. This is used by sleeping
109  * device to not receives the multicast traffic.
110  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_STATUS_NOT_INITIALIZED
111  */
112 CAResult_t CAStopListeningServer();
113
114 /**
115  * Starts discovery servers.
116  * This API is used by resource required clients for listening multicast requests.
117  * Based on the adapters configurations, different kinds of servers are started.
118  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_STATUS_NOT_INITIALIZED
119  */
120 CAResult_t CAStartDiscoveryServer();
121
122 /**
123  * Register request callbacks and response callbacks.
124  *          Requests and responses are delivered these callbacks.
125  * @param[in]   ReqHandler    Request callback ( for GET,PUT ..etc).
126  * @param[in]   RespHandler   Response Handler Callback.
127  * @param[in]   ErrorHandler  Error Handler Callback.
128  * @see     CARequestCallback
129  * @see     CAResponseCallback
130  * @see     CAErrorCallback
131  */
132 void CARegisterHandler(CARequestCallback ReqHandler, CAResponseCallback RespHandler,
133                        CAErrorCallback ErrorHandler);
134
135 /**
136  * Create an endpoint description.
137  * @param[in]   flags                 how the adapter should be used.
138  * @param[in]   adapter               which adapter to use.
139  * @param[in]   addr                  string representation of address.
140  * @param[in]   port                  port (for IP_ADAPTER).
141  * @param[out]  object                Endpoint which contains the above.
142  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_STATUS_INVALID_PARAM
143  * @remark  The created Remote endpoint can be freed using CADestroyEndpoint().
144  * @see     CADestroyEndpoint
145  */
146 CAResult_t CACreateEndpoint(CATransportFlags_t flags,
147                             CATransportAdapter_t adapter,
148                             const char *addr,
149                             uint16_t port,
150                             CAEndpoint_t **object);
151
152 /**
153  * Destroy the remote endpoint created.
154  * @param[in]   object   Remote Endpoint object created with CACreateEndpoint.
155  */
156 void CADestroyEndpoint(CAEndpoint_t *object);
157
158 /**
159  * Generating the token for matching the request and response.
160  * @param[out]  token            Token for the request.
161  * @param[in]   tokenLength      length of the token.
162  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED or
163  *          ::CA_MEMORY_ALLOC_FAILED or ::CA_STATUS_INVALID_PARAM
164  * @remark  Token memory is destroyed by the caller using CADestroyToken().
165  * @see     CADestroyToken
166  */
167 CAResult_t CAGenerateToken(CAToken_t *token, uint8_t tokenLength);
168
169 /**
170  * Destroy the token generated by CAGenerateToken.
171  * @param[in]   token    token to be freed.
172  */
173 void CADestroyToken(CAToken_t token);
174
175 /**
176  * Send control Request on a resource.
177  * @param[in]   object       Endpoint where the payload need to be sent.
178  *                           This endpoint is delivered with Request or response callback.
179  * @param[in]   requestInfo  Information for the request.
180  * @return ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_STATUS_NOT_INITIALIZED or
181            ::CA_SEND_FAILED or ::CA_STATUS_INVALID_PARAM or ::CA_MEMORY_ALLOC_FAILED
182  */
183 CAResult_t CASendRequest(const CAEndpoint_t *object, const CARequestInfo_t *requestInfo);
184
185 /**
186  * Send the response.
187  * @param[in]   object           Endpoint where the payload need to be sent.
188  *                               This endpoint is delivered with Request or response callback.
189  * @param[in]   responseInfo     Information for the response.
190  * @return ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_STATUS_NOT_INITIALIZED or
191            ::CA_SEND_FAILED or ::CA_STATUS_INVALID_PARAM or ::CA_MEMORY_ALLOC_FAILED
192  */
193 CAResult_t CASendResponse(const CAEndpoint_t *object, const CAResponseInfo_t *responseInfo);
194
195 /**
196  * Select network to use.
197  * @param[in]   interestedNetwork    Connectivity Type enum.
198  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_STATUS_NOT_INITIALIZED or
199  *          ::CA_NOT_SUPPORTED or ::CA_ADAPTER_NOT_ENABLED or ::CA_MEMORY_ALLOC_FAILED
200  */
201 CAResult_t CASelectNetwork(CATransportAdapter_t interestedNetwork);
202
203 /**
204  * Select network to unuse.
205  * @param[in]   nonInterestedNetwork     Connectivity Type enum.
206  * @return  ::CA_STATUS_OK or ::CA_NOT_SUPPORTED or ::CA_STATUS_FAILED or
207             ::CA_STATUS_NOT_INITIALIZED
208  */
209 CAResult_t CAUnSelectNetwork(CATransportAdapter_t nonInterestedNetwork);
210
211 /**
212  * Get network information.
213  * It should be destroyed by the caller as it Get Information.
214  * @param[out]   info     LocalConnectivity objects
215  * @param[out]   size     No Of Array objects
216  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_STATUS_NOT_INITIALIZED or
217  *          ::CA_STATUS_INVALID_PARAM or ::CA_MEMORY_ALLOC_FAILED
218  */
219 CAResult_t CAGetNetworkInformation(CAEndpoint_t **info, uint32_t *size);
220
221 /**
222  * Get supported network adapter.
223  *
224  * @return  Bit combinations of CATransportAdapter_t enumeration which indicate enabled adapter.
225  */
226 CATransportAdapter_t CAGetSelectedNetwork();
227
228 /**
229  * To Handle the Request or Response.
230  * @return   ::CA_STATUS_OK or ::CA_STATUS_NOT_INITIALIZED
231  */
232 CAResult_t CAHandleRequestResponse();
233
234 #ifdef RA_ADAPTER
235 /**
236  * Set Remote Access information for XMPP Client.
237  * @param[in]   caraInfo          remote access info.
238  *
239  * @return  ::CA_STATUS_OK or ::CA_STATUS_INVALID_PARAM
240  */
241 CAResult_t CASetRAInfo(const CARAInfo_t *caraInfo);
242 #endif
243
244 /**
245  * This function sets uri being used for proxy.
246  *
247  * @param uri            NULL terminated resource uri for CoAP-HTTP Proxy.
248  *
249  * @return  ::CA_STATUS_OK or ::CA_STATUS_INVALID_PARAM
250  */
251 CAResult_t CASetProxyUri(const char *uri);
252
253 /**
254  * This function return zone id related from ifindex and address.
255  *
256  * @param ifindex[in]     interface index.
257  * @param zoneId[out]     pointer of zoneId string.
258  *
259  * @return  ::CA_STATUS_OK or ::CA_STATUS_INVALID_PARAM
260  */
261 CAResult_t CAGetLinkLocalZoneId(uint32_t ifindex, char **zoneId);
262
263 #ifdef __cplusplus
264 } /* extern "C" */
265 #endif
266
267 #endif /* CA_INTERFACE_H_ */
268