Use `URI` all caps in documentation
[iotivity.git] / resource / csdk / connectivity / inc / caipadapter.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  * This file contains the APIs for IP Adapter.
24  */
25 #ifndef CA_IP_ADAPTER_H_
26 #define CA_IP_ADAPTER_H_
27
28 #include "cacommon.h"
29 #include "caadapterinterface.h"
30 #include "cathreadpool.h"
31
32 #ifdef __cplusplus
33 extern "C"
34 {
35 #endif
36
37 /**
38  * API to initialize IP Interface.
39  * @param[in] registerCallback      Callback to register IP interfaces to
40  *                                   Connectivity Abstraction Layer.
41  * @param[in] networkPacketCallback Callback to notify request and
42  *                                   response messages from server(s)
43  *                                   started at Connectivity Abstraction Layer.
44  * @param[in] netCallback           Callback to notify the network additions
45  *                                   to Connectivity Abstraction Layer.
46  * @param[in] errorCallback         Callback to notify the network errors to
47  *                                   Connectivity Abstraction Layer.
48  * @param[in] handle                Threadpool Handle.
49  * @return  ::CA_STATUS_OK or Appropriate error code
50  */
51 CAResult_t CAInitializeIP(CARegisterConnectivityCallback registerCallback,
52                           CANetworkPacketReceivedCallback networkPacketCallback,
53                           CAAdapterChangeCallback netCallback,
54                           CAErrorHandleCallback errorCallback, ca_thread_pool_t handle);
55
56 /**
57  * Start IP Interface adapter.
58  * @return  ::CA_STATUS_OK or Appropriate error code.
59  */
60 CAResult_t CAStartIP(void);
61
62 /**
63  * Start listening server for receiving multicast search requests.
64  * Transport Specific Behavior:
65  * IP Starts Multicast Server on a particular interface and prefixed port
66  * number and as per OIC Specification.
67  * @return  ::CA_STATUS_OK or Appropriate error code.
68  */
69 CAResult_t CAStartIPListeningServer(void);
70
71 /**
72  * Stop listening server from receiving multicast search requests.
73  * Transport Specific Behavior:
74  * IP closes open multicast socket for a particular interface.
75  * @return  ::CA_STATUS_OK or Appropriate error code.
76  */
77 CAResult_t CAStopIPListeningServer(void);
78
79 /**
80  * Start discovery servers for receiving multicast advertisements.
81  * Transport Specific Behavior:
82  * IP Starts multicast server on a particular interface and prefixed port
83  * number as per OIC Specification.
84  * @return  ::CA_STATUS_OK or Appropriate error code.
85  */
86 CAResult_t CAStartIPDiscoveryServer(void);
87
88 /**
89  * Sends data to the endpoint using the adapter connectivity.
90  * @param[in]   endpoint       Remote Endpoint information (like ipaddress,
91  *                              port, reference URI and transport type) to
92  *                              which the unicast data has to be sent.
93  * @param[in]   data           Data which is required to be sent.
94  * @param[in]   dataLen        Size of data to be sent.
95  * @param[in]   dataType       Data type which is REQUEST or RESPONSE.
96  * @note  dataLen must be > 0.
97  * @return  The number of bytes sent on the network, or -1 upon error.
98  */
99 int32_t CASendIPUnicastData(const CAEndpoint_t *endpoint, const void *data,
100                             uint32_t dataLen, CADataType_t dataType);
101
102 /**
103  * Send Multicast data to the endpoint using the IP connectivity.
104  * @param[in]   endpoint       Remote Endpoint information (like ipaddress,
105  *                              port)
106  * @param[in]   data           Data which is required to be sent.
107  * @param[in]   dataLen        Size of data to be sent.
108  * @param[in]   dataType       Data type which is REQUEST or RESPONSE.
109  * @note  dataLen must be > 0.
110  * @return  The number of bytes sent on the network, or -1 upon error.
111  */
112 int32_t CASendIPMulticastData(const CAEndpoint_t *endpoint, const void *data,
113                               uint32_t dataLen, CADataType_t dataType);
114
115 /**
116  * Get IP Connectivity network information.
117  * @param[out]   info        Local connectivity information structures.
118  * @note info is allocated in this API and should be freed by the caller.
119  * @param[out]   size        Number of local connectivity structures.
120  * @return  ::CA_STATUS_OK or Appropriate error code.
121  */
122 CAResult_t CAGetIPInterfaceInformation(CAEndpoint_t **info, size_t *size);
123
124 /**
125  * Read Synchronous API callback.
126  * @return  ::CA_STATUS_OK or Appropriate error code.
127  */
128 CAResult_t CAReadIPData(void);
129
130 /**
131  * Stops Unicast, Multicast servers and close the sockets.
132  * @return  ::CA_STATUS_OK or Appropriate error code.
133  */
134 CAResult_t CAStopIP(void);
135
136 /**
137  * Check whether the endpoint is my own or not.
138  * @return  true or false.
139  */
140 bool CAIPIsLocalEndpoint(const CAEndpoint_t *ep);
141
142 /**
143  * Terminate the IP connectivity adapter.
144  * Configuration information will be deleted from further use.
145  */
146 void CATerminateIP(void);
147
148 #ifdef __cplusplus
149 } /* extern "C" */
150 #endif
151
152 #endif  // CA_IP_ADAPTER_H_