[JIRA IOT-778] fixed the jira issue related to CASendNotification API.
[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 /**
42  * Callback function type for request delivery.
43  * @param[out]   object       Endpoint object from which the request is received.
44  *                            It contains endpoint address based on the connectivity type.
45  * @param[out]   requestInfo  Info for resource model to understand about the request.
46  */
47 typedef void (*CARequestCallback)(const CAEndpoint_t *object,
48                                   const CARequestInfo_t *requestInfo);
49
50 /**
51  * Callback function type for response delivery.
52  * @param[out]   object           Endpoint object from which the response is received.
53  * @param[out]   responseInfo     Identifier which needs to be mapped with response.
54  */
55 typedef void (*CAResponseCallback)(const CAEndpoint_t *object,
56                                    const CAResponseInfo_t *responseInfo);
57 /**
58  * Callback function type for error.
59  * @param[out]   object           remote device information.
60  * @param[out]   errorInfo        CA Error information.
61  */
62 typedef void (*CAErrorCallback)(const CAEndpoint_t *object,
63                                 const CAErrorInfo_t *errorInfo);
64 #ifdef RA_ADAPTER
65
66 /**
67  * Callback for bound JID
68  * @param[out]   jid           Boud Jabber Identifier.
69  */
70 typedef void (*CAJidBoundCallback)(char *jid);
71
72 /**
73  * CA Remote Access information for XMPP Client
74  *
75  */
76 typedef struct
77 {
78     char *hostName;     /**< XMPP server hostname */
79     uint16_t port;      /**< XMPP server serivce port */
80     char *xmppDomain;  /**< XMPP login domain */
81     char *userName;     /**< login username */
82     char *password;     /**< login password */
83     char *resource;     /**< specific resource for login */
84     char *userJid;     /**< specific JID for login */
85     CAJidBoundCallback jidBoundCallback;  /**< callback when JID bound */
86 } CARAInfo_t;
87
88 #endif //RA_ADAPTER
89
90 /**
91  * Initialize the connectivity abstraction module.
92  * It will initialize adapters, thread pool and other modules based on the platform
93  * compilation options.
94  *
95  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_MEMORY_ALLOC_FAILED
96  */
97 CAResult_t CAInitialize();
98
99 /**
100  * Terminate the connectivity abstraction module.
101  * All threads, data structures are destroyed for next initializations.
102  */
103 void CATerminate();
104
105 /**
106  * Starts listening servers.
107  * This API is used by resource hosting server for listening multicast requests.
108  * Based on the adapters configurations, different kinds of servers are started.
109  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED
110  */
111 CAResult_t CAStartListeningServer();
112
113 /**
114  * Stops the server from receiving the multicast traffic. This is used by sleeping
115  * device to not receives the multicast traffic.
116  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED
117  */
118 CAResult_t CAStopListeningServer();
119
120 /**
121  * Starts discovery servers.
122  * This API is used by resource required clients for listening multicast requests.
123  * Based on the adapters configurations, different kinds of servers are started.
124  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED
125  */
126 CAResult_t CAStartDiscoveryServer();
127
128 /**
129  * Register request callbacks and response callbacks.
130  *          Requests and responses are delivered these callbacks.
131  * @param[in]   ReqHandler    Request callback ( for GET,PUT ..etc).
132  * @param[in]   RespHandler   Response Handler Callback.
133  * @see     CARequestCallback
134  * @see     CAResponseCallback
135  * @see     CAErrorCallback
136  */
137 void CARegisterHandler(CARequestCallback ReqHandler, CAResponseCallback RespHandler,
138                        CAErrorCallback ErrorHandler);
139
140 /**
141  * Create an endpoint description.
142  * @param[in]   flags                 how the adapter should be used.
143  * @param[in]   adapter               which adapter to use.
144  * @param[in]   addr                  string representation of address.
145  * @param[in]   port                  port (for IP_ADAPTER).
146  * @param[in]   endpoint              Endpoint which contains the above.
147  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED
148  * @remark  The created Remote endpoint can be freed using CADestroyEndpoint().
149  * @see     CADestroyEndpoint
150  */
151 CAResult_t CACreateEndpoint(CATransportFlags_t flags,
152                             CATransportAdapter_t adapter,
153                             const char *addr,
154                             uint16_t port,
155                             CAEndpoint_t **object);
156
157 /**
158  * Destroy the remote endpoint created.
159  * @param[in]   object   Remote Endpoint object created with CACreateEndpoint.
160  */
161 void CADestroyEndpoint(CAEndpoint_t *object);
162
163 /**
164  * Generating the token for matching the request and response.
165  * @param[in]   token            Token for the request.
166  * @param[in]   tokenLength      length of the token.
167  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED or
168  *          ::CA_MEMORY_ALLOC_FAILED or ::CA_STATUS_NOT_INITIALIZED
169  * @remark  Token memory is destroyed by the caller using CADestroyToken().
170  * @see     CADestroyToken
171  */
172 CAResult_t CAGenerateToken(CAToken_t *token, uint8_t tokenLength);
173
174 /**
175  * Destroy the token generated by CAGenerateToken.
176  * @param[in]   token    token to be freed.
177  */
178 void CADestroyToken(CAToken_t token);
179
180 /**
181  * Send control Request on a resource.
182  * @param[in]   object       Endpoint where the payload need to be sent.
183  *                           This endpoint is delivered with Request or response callback.
184  * @param[in]   requestInfo  Information for the request.
185  * @return  ::CA_STATUS_OK ::CA_STATUS_FAILED ::CA_MEMORY_ALLOC_FAILED
186  */
187 CAResult_t CASendRequest(const CAEndpoint_t *object, const CARequestInfo_t *requestInfo);
188
189 /**
190  * Send the response.
191  * @param[in]   object           Endpoint where the payload need to be sent.
192  *                               This endpoint is delivered with Request or response callback.
193  * @param[in]   responseInfo     Information for the response.
194  * @return  ::CA_STATUS_OK or  ::CA_STATUS_FAILED or ::CA_MEMORY_ALLOC_FAILED
195  */
196 CAResult_t CASendResponse(const CAEndpoint_t *object, const CAResponseInfo_t *responseInfo);
197
198 /**
199  * Select network to use.
200  * @param[in]   interestedNetwork    Connectivity Type enum.
201  * @return  ::CA_STATUS_OK or ::CA_NOT_SUPPORTED or
202  *          ::CA_STATUS_FAILED or ::CA_NOT_SUPPORTED
203  */
204 CAResult_t CASelectNetwork(CATransportAdapter_t interestedNetwork);
205
206 /**
207  * Select network to unuse.
208  * @param[in]   nonInterestedNetwork     Connectivity Type enum.
209  * @return  ::CA_STATUS_OK or ::CA_NOT_SUPPORTED or ::CA_STATUS_FAILED
210  */
211 CAResult_t CAUnSelectNetwork(CATransportAdapter_t nonInterestedNetwork);
212
213 /**
214  * Get network information.
215  * It should be destroyed by the caller as it Get Information.
216  * @param[out]   info     LocalConnectivity objects
217  * @param[out]   size     No Of Array objects
218  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED or
219  *          ::CA_STATUS_INVALID_PARAM or ::CA_MEMORY_ALLOC_FAILED
220  */
221 CAResult_t CAGetNetworkInformation(CAEndpoint_t **info, uint32_t *size);
222
223 /**
224  * To Handle the Request or Response.
225  * @return   ::CA_STATUS_OK
226  */
227 CAResult_t CAHandleRequestResponse();
228
229 #ifdef RA_ADAPTER
230 /**
231  * Set Remote Access information for XMPP Client.
232  * @param[in]   caraInfo          remote access info.
233  *
234  * @return  ::CA_STATUS_OK
235  */
236 CAResult_t CASetRAInfo(const CARAInfo_t *caraInfo);
237 #endif
238
239
240
241 #ifdef __cplusplus
242 } /* extern "C" */
243 #endif
244
245 #endif /* CA_INTERFACE_H_ */
246