1 /* ****************************************************************
3 * Copyright 2014 Samsung Electronics All Rights Reserved.
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
19 ******************************************************************/
24 * This file provides APIs ethernet client/server/network monitor modules.
27 #ifndef _CA_ETHERNET_INTERFACE_H_
28 #define _CA_ETHERNET_INTERFACE_H_
33 #include "uthreadpool.h" /* for thread pool */
41 * @enum CAAdapterServerType_t
42 * @brief Enum for defining different server types.
46 CA_UNICAST_SERVER = 0, /**< Unicast Server */
47 CA_MULTICAST_SERVER, /**< Multicast Server */
48 CA_SECURED_UNICAST_SERVER /**< Secured Unicast Server */
49 } CAAdapterServerType_t;
52 * @brief Callback to be notified on reception of any data from remote OIC devices.
53 * @param ipAddress [IN] IP address of remote OIC device.
54 * @param port [IN] Port number on which data is received.
55 * @param data [IN] Data received from remote OIC device.
56 * @param dataLength [IN] Length of data in bytes.
57 * @param isSecured [IN] Indicates the data is secure or not.
59 * @pre Callback must be registered using CAEthernetSetPacketReceiveCallback()
61 typedef void (*CAEthernetPacketReceivedCallback)(const char *ipAddress, const uint16_t port,
62 const void *data, const uint32_t dataLength,
63 const bool isSecured);
66 * @brief Callback to be notified when exception occures on multicast/unicast server.
67 * @param type [IN] Type of server(#CAAdapterServerType_t)
69 * @pre Callback must be registered using CAEthernetSetExceptionCallback()
71 typedef void (*CAEthernetExceptionCallback)(CAAdapterServerType_t type);
74 * @brief Initialize Ethernet server
75 * @param threadPool [IN] Thread pool for managing Unicast/Multicast server threads.
76 * @return #CA_STATUS_OK or Appropriate error code
77 * @retval #CA_STATUS_OK Successful
78 * @retval #CA_STATUS_INVALID_PARAM Invalid input data
79 * @retval #CA_STATUS_FAILED Initialization failed
81 CAResult_t CAEthernetInitializeServer(const u_thread_pool_t threadPool);
84 * @brief Terminate Ethernet server
87 void CAEthernetTerminateServer(void);
90 * @brief Start multicast server for specified multicast address and port
92 * @param localAddress [IN] Local adapter address to which server to be binded.
93 * @param multicastAddress [IN] Multicast group address.
94 * @param multicastPort [IN,OUT] Port number on which server will be running. If binding
95 the port failed, server starts in the next available port.
96 * @param serverFD [OUT] Multicast server socket FD.
98 * @return #CA_STATUS_OK or Appropriate error code
99 * @retval #CA_STATUS_OK Successful
100 * @retval #CA_STATUS_INVALID_PARAM Invalid input data
101 * @retval #CA_SERVER_STARTED_ALREADY Multicast server is already started and running.
102 * @retval #CA_STATUS_FAILED Operation failed
104 CAResult_t CAEthernetStartMulticastServer(const char *localAddress,
105 const char *multicastAddress, const uint16_t multicastPort, int32_t *serverFD);
108 * @brief Start unicast server for specified local address and port
110 * @param localAddress [IN] Local adapter address to which server to be binded.
111 * @param port [IN,OUT] Port number on which server will be running. If binding
112 the port failed, server starts in the next available port.
113 * @param forceStart [IN] Indicate whether to start server forcesfully on specified port
115 * @param secured [IN] True if the secure server to be started, otherwise false.
116 * @param serverFD [OUT] Unicast server socket FD.
118 * @return #CA_STATUS_OK or Appropriate error code
119 * @retval #CA_STATUS_OK Successful
120 * @retval #CA_STATUS_INVALID_PARAM Invalid input data
121 * @retval #CA_SERVER_STARTED_ALREADY Unicast server is already started and running.
122 * @retval #CA_STATUS_FAILED Operation failed
124 CAResult_t CAEthernetStartUnicastServer(const char *localAddress, uint16_t *port,
125 bool forceStart, bool secured, int32_t *serverFD);
128 * @brief Stop multicast server.
130 * @return #CA_STATUS_OK or Appropriate error code
131 * @retval #CA_STATUS_OK Successful
132 * @retval #CA_STATUS_FAILED Operation failed
134 CAResult_t CAEthernetStopMulticastServer(void);
137 * @brief Stop unicast server.
139 * @return #CA_STATUS_OK or Appropriate error code
140 * @retval #CA_STATUS_OK Successful
141 * @retval #CA_STATUS_FAILED Operation failed
143 CAResult_t CAEthernetStopUnicastServer();
146 * @brief Stop secured unicast server.
148 * @return #CA_STATUS_OK or Appropriate error code
149 * @retval #CA_STATUS_OK Successful
150 * @retval #CA_STATUS_FAILED Operation failed
152 CAResult_t CAEthernetStopSecureUnicastServer();
155 * @brief Get the Unicast Server Information if it is started
157 * @param secure [IN] True if the secure server information needed, otherwise false.
158 * @param ipAddress [OUT]IP address on which server is binded and running.
159 * @param port [OUT]Port number on which server is running
160 * @param serverFD [OUT]Server socket fd.
162 * @return #CA_STATUS_OK or Appropriate error code
163 * @retval #CA_STATUS_OK Successful
164 * @retval #CA_STATUS_INVALID_PARAM Invalid input data
165 * @retval #CA_STATUS_FAILED Operation failed
166 * @remarks ipAddress must be freed using free().
168 CAResult_t CAEthernetGetUnicastServerInfo(bool secure, char **ipAddress,
169 uint16_t *port,int32_t *serverFD);
172 * @brief Set this callback for receiving data packets from peer devices.
174 * @param callback [IN] Callback to be notified on reception of unicast/multicast data packets.
178 void CAEthernetSetPacketReceiveCallback(CAEthernetPacketReceivedCallback callback);
181 * @brief Set this callback for receiving exception notifications.
183 * @param callback [IN] Callback to be notified on occurance of exception on running servers.
187 void CAEthernetSetExceptionCallback(CAEthernetExceptionCallback callback);
190 * @brief Set socket description for sending unicast UDP data. Once the Unicast server is started,
191 * the same socket descriptor is used for sending the Unicast UDP data.
193 * @param socketFD [IN] Socket descriptor used for sending UDP data.
196 void CAEthernetSetUnicastSocket(const int32_t socketFD);
199 * @brief Set the port number for sending unicast UDP data
200 * @param port [IN] Port number used for sending UDP data.
203 void CAEthernetSetUnicastPort(const uint16_t port);
207 * @brief Set socket description for sending secured (encrypted) unicast UDP data
209 * @param socketFD [IN] Socket descriptor used for sending secured (encrypted) UDP data.
212 void CAEthernetSetSecureUnicastSocket(const int32_t socketFD);
216 * @brief API to send unicast UDP data
218 * @param remoteAddress [IN] IP address to which data needs to be sent.
219 * @param port [IN] Port to which data needs to be send.
220 * @param data [IN] Data to be send.
221 * @param dataLength [IN] Length of data in bytes
222 * @param isMulticast [IN] Whether data needs to be sent to multicast ip
223 * @param isSecure [IN] Whether data to be sent on secured channel.
225 * @return The number of bytes sent on the network. Returns 0 on error.
226 * @remarks isSecure will be ignored when isMulticast is true.
228 uint32_t CAEthernetSendData(const char *remoteAddress, const uint16_t port,
229 const void *data, const uint32_t dataLength,
230 bool isMulticast, bool isSecure);
233 * @brief Callback to be notified when Ethernet adapter connection state changes.
235 * @param ipAddress [IN] IP address of remote OIC device.
236 * @param status [IN] Connection status either #CA_INTERFACE_UP or #CA_INTERFACE_DOWN.
238 * @pre Callback must be registered using CAEthernetSetConnectionStateChangeCallback()
240 typedef void (*CAEthernetConnectionStateChangeCallback)(const char *ipAddress,
241 const CANetworkStatus_t status);
244 * @brief Initialize Ethernet network monitor
246 * @param threadPool [IN] Thread pool for managing network monitor thread.
248 * @return #CA_STATUS_OK or Appropriate error code
249 * @retval #CA_STATUS_OK Successful
250 * @retval #CA_STATUS_INVALID_PARAM Invalid input data
251 * @retval #CA_STATUS_FAILED Initialization failed
253 CAResult_t CAEthernetInitializeNetworkMonitor(const u_thread_pool_t threadPool);
256 * @brief Terminate Ethernet network monitor
259 void CAEthernetTerminateNetworkMonitor(void);
262 * @brief Start network monitoring process.
264 * @return #CA_STATUS_OK or Appropriate error code
265 * @retval #CA_STATUS_OK Successful
266 * @retval #CA_STATUS_FAILED Operation failed
268 CAResult_t CAEthernetStartNetworkMonitor(void);
271 * @brief Stop network monitoring process.
273 * @return #CA_STATUS_OK or Appropriate error code
274 * @retval #CA_STATUS_OK Successful
275 * @retval #CA_STATUS_FAILED Operation failed
277 CAResult_t CAEthernetStopNetworkMonitor(void);
280 * @brief Get local adapter network information.
282 * @param interfaceName [OUT] Local adapter interface name
283 * @param ipAddress [OUT] IP address
285 * @return #CA_STATUS_OK or Appropriate error code
286 * @retval #CA_STATUS_OK Successful
287 * @retval #CA_STATUS_INVALID_PARAM Invalid input data
288 * @retval #CA_STATUS_FAILED Operation failed
289 * @remarks interfaceName and ipAddress must be freed using free().
291 CAResult_t CAEthernetGetInterfaceInfo(char **interfaceName, char **ipAddress);
294 * @brief Get local adapter network subnet mask.
296 * @param subnetMask [OUT] Local adapter interface subnet mask
298 * @return #CA_STATUS_OK or Appropriate error code
299 * @retval #CA_STATUS_OK Successful
300 * @retval #CA_STATUS_INVALID_PARAM Invalid input data
301 * @retval #CA_STATUS_FAILED Operation failed
302 * @remarks subnetMask must be freed using free().
304 CAResult_t CAEthernetGetInterfaceSubnetMask(char **subnetMask);
307 * @brief Get Ethernet adapter connection state.
309 * @return True if Ethernet adapter is connected, otherwise false
311 bool CAEthernetIsConnected(void);
314 * @brief Set callback for receiving local ethernet adapter connection status.
316 * @param callback [IN] Callback to be notified when local Ethernet adapter connection state changes.
319 void CAEthernetSetConnectionStateChangeCallback
320 (CAEthernetConnectionStateChangeCallback callback);
326 #endif //_CA_ETHERNET_INTERFACE_H_