Gleb Klochkov
/
Climatcontroll_Main
Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Embed:
(wiki syntax)
Show/hide line numbers
fnet_socket.h
00001 /************************************************************************** 00002 * 00003 * Copyright 2011-2016 by Andrey Butok. FNET Community. 00004 * Copyright 2008-2010 by Andrey Butok. Freescale Semiconductor, Inc. 00005 * Copyright 2003 by Andrey Butok. Motorola SPS. 00006 * 00007 *************************************************************************** 00008 * 00009 * Licensed under the Apache License, Version 2.0 (the "License"); you may 00010 * not use this file except in compliance with the License. 00011 * You may obtain a copy of the License at 00012 * 00013 * http://www.apache.org/licenses/LICENSE-2.0 00014 * 00015 * Unless required by applicable law or agreed to in writing, software 00016 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 00017 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00018 * See the License for the specific language governing permissions and 00019 * limitations under the License. 00020 * 00021 **********************************************************************/ 00022 /*! 00023 * @brief Socket API. 00024 * 00025 ***************************************************************************/ 00026 00027 #ifndef _FNET_SOCKET_H_ 00028 00029 #define _FNET_SOCKET_H_ 00030 00031 #include "fnet_ip.h" 00032 #include "fnet_ip6.h" 00033 00034 /*! @addtogroup fnet_socket 00035 * The Socket Application Program Interface (API) defines the way, in which the 00036 * application program interacts with the TCP/IP stack. It has the 00037 * BSD-like, non-blocking socket interface that makes porting of existing network applications 00038 * to the FNET more convenient.@n 00039 * @n 00040 * The following table summarizes the supported socket API functions: 00041 * <table> 00042 * <caption>Socket functions</caption> 00043 * <tr class="fnet_td_grey"> 00044 * <th ALIGN=CENTER>Category</th><th ALIGN=CENTER>FNET Routine</th><th ALIGN=CENTER>BSD Routine</th><th ALIGN=CENTER>Meaning</th><th ALIGN=CENTER>Server</th> 00045 * <th ALIGN=CENTER>Client</th><th ALIGN=CENTER>@ref SOCK_STREAM</th> <th ALIGN=CENTER>@ref SOCK_DGRAM</th> 00046 * </tr> 00047 * <tr> 00048 * <td>setup</td><td>@ref fnet_socket()</td><td>socket()</td><td>Creates a new unnamed socket within 00049 * a specified communication domain family.</td><td>X</td><td>X</td><td>X</td> 00050 * <td>X</td> 00051 * </tr> 00052 * <tr> 00053 * <td>setup</td><td>@ref fnet_socket_bind()</td><td>bind()</td><td>Assigns a local address to 00054 * a socket.</td><td>X</td><td>X</td><td>X</td><td>X</td> 00055 * </tr> 00056 * <tr> 00057 * <td>server</td><td>@ref fnet_socket_listen()</td><td>listen()</td><td> Prepares a socket to accept 00058 * the incoming connections.</td><td>X</td><td>@n</td><td>X</td><td>@n</td> 00059 * </tr> 00060 * <tr> 00061 * <td>server</td><td>@ref fnet_socket_accept()</td><td>accept()</td><td>Accepts the connections.</td> 00062 * <td>X</td><td>@n</td><td>X</td><td>@n</td> 00063 * </tr> 00064 * <tr> 00065 * <td>client</td><td>@ref fnet_socket_connect()</td><td>connect()</td><td> Establishes a connection to 00066 * a foreign socket.</td><td>@n</td><td>X</td><td>X</td><td>X</td> 00067 * </tr> 00068 * <tr> 00069 * <td>input</td><td>@ref fnet_socket_recv()</td><td>recv()</td><td>Receives the data.</td><td>X</td> 00070 * <td>X</td><td>X</td><td>X</td> 00071 * </tr> 00072 * <tr> 00073 * <td>input</td><td>@ref fnet_socket_recvfrom()</td><td>recvfrom()</td><td>Receives the data and address of 00074 * the sender.</td><td>X</td><td>X</td><td>@n</td><td>X</td> 00075 * </tr> 00076 * <tr> 00077 * <td>output</td><td>@ref fnet_socket_send()</td><td>send()</td><td>Sends the data.</td><td>X</td> 00078 * <td>X</td><td>X</td><td>X</td> 00079 * </tr> 00080 * <tr> 00081 * <td>output</td><td>@ref fnet_socket_sendto()</td><td>sendto()</td><td>Sends the data to a specified 00082 * address.</td><td>X</td><td>X</td><td>@n</td><td>X</td> 00083 * </tr> 00084 * <tr> 00085 * <td>termination</td><td>@ref fnet_socket_shutdown()</td><td>shutdown()</td><td>Terminates a connection 00086 * in one or both directions.</td><td>X</td><td>X</td><td>X</td><td>X</td> 00087 * </tr> 00088 * <tr> 00089 * <td>termination</td><td>@ref fnet_socket_close()</td><td>closesocket()</td><td>Terminates a connection 00090 * and releases the socket.</td><td>X</td><td>X</td><td>X</td><td>X</td> 00091 * </tr> 00092 * <tr> 00093 * <td>administration</td><td>@ref fnet_socket_setopt()</td><td>fnet_socket_setopt()</td><td>Sets socket or protocol 00094 * options.</td><td>X</td><td>X</td><td>X</td><td>X</td> 00095 * </tr> 00096 * <tr> 00097 * <td>administration</td><td>@ref fnet_socket_getopt()</td><td>getsockopt()</td><td>Gets socket or protocol 00098 * options.</td><td>X</td><td>X</td><td>X</td><td>X</td> 00099 * </tr> 00100 * <tr> 00101 * <td>administration</td><td>@ref fnet_socket_getname()</td><td>getsockname()</td><td>Gets a local address 00102 * assigned to a socket.</td><td>X</td><td>X</td><td>X</td><td>X</td> 00103 * </tr> 00104 * <tr> 00105 * <td>administration</td><td>@ref fnet_socket_getpeername()</td><td>getpeername()</td><td>Gets a foreign address 00106 * assigned to a socket.</td><td>X</td><td>X</td><td>X</td><td>X</td> 00107 * </tr> 00108 * </table> 00109 * Configuration parameters: 00110 * - @ref FNET_CFG_SOCKET_MAX 00111 * - @ref FNET_CFG_SOCKET_TCP_TX_BUF_SIZE 00112 * - @ref FNET_CFG_SOCKET_TCP_RX_BUF_SIZE 00113 * - @ref FNET_CFG_SOCKET_UDP_TX_BUF_SIZE 00114 * - @ref FNET_CFG_SOCKET_UDP_RX_BUF_SIZE 00115 * - @ref FNET_CFG_SOCKET_TCP_MSS 00116 * - @ref FNET_CFG_RAW 00117 * - @ref FNET_CFG_SOCKET_BSD_NAMES 00118 * - @ref FNET_CFG_SOCKET_CALLBACK_ON_RX 00119 */ 00120 /*! @{ */ 00121 00122 /* Special addresses */ 00123 00124 /**************************************************************************/ /*! 00125 * @brief It means to use any network interface. 00126 ******************************************************************************/ 00127 #define INADDR_ANY (fnet_ip4_addr_t)(0x00000000U) 00128 00129 /**************************************************************************/ /*! 00130 * @brief Broadcast address. @n 00131 * It can be used to send the broadcast UDP datagrams over an IP network. 00132 ******************************************************************************/ 00133 #define INADDR_BROADCAST (fnet_ip4_addr_t)(0xffffffffU) 00134 00135 /**************************************************************************/ /*! 00136 * @brief Address family type. 00137 * @see AF_UNSPEC, AF_INET, AF_INET6, AF_SUPPORTED 00138 ******************************************************************************/ 00139 typedef fnet_uint16_t fnet_address_family_t; 00140 00141 /**************************************************************************/ /*! 00142 * @brief cope zone index type, defining network interface. 00143 ******************************************************************************/ 00144 typedef fnet_uint32_t fnet_scope_id_t; 00145 00146 /**************************************************************************/ /*! 00147 * @brief Unspecified address family. 00148 ******************************************************************************/ 00149 #define AF_UNSPEC (0U) 00150 /**************************************************************************/ /*! 00151 * @brief IPv4 address family. 00152 ******************************************************************************/ 00153 #define AF_INET (1U) 00154 /**************************************************************************/ /*! 00155 * @brief IPv6 address family. 00156 ******************************************************************************/ 00157 #define AF_INET6 (2U) 00158 /**************************************************************************/ /*! 00159 * @brief Bitmask of supported address families. 00160 * @showinitializer 00161 ******************************************************************************/ 00162 #define AF_SUPPORTED ((fnet_address_family_t)((fnet_address_family_t)(AF_INET6*(fnet_address_family_t)FNET_CFG_IP6) | (fnet_address_family_t)(AF_INET*(fnet_address_family_t)FNET_CFG_IP4))) 00163 00164 /**************************************************************************/ /*! 00165 * @brief Size of sa_data[] field of @ref sockaddr structure. @n 00166 * It used to cover sockaddr_in and sockaddr_in6. 00167 * @showinitializer 00168 ******************************************************************************/ 00169 #if FNET_CFG_IP6 00170 #define FNET_SA_DATA_SIZE (sizeof(struct in6_addr)) 00171 #else /* IPv4 */ 00172 #define FNET_SA_DATA_SIZE (sizeof(struct in_addr)) 00173 #endif 00174 00175 /**************************************************************************/ /*! 00176 * @def FNET_IP_ADDR_STR_SIZE 00177 * @brief Size of the string buffer that will contain 00178 * null-terminated ASCII string of an IP address. It depends on 00179 * if disabled or enabled IPv6. 00180 * @see fnet_inet_ntoa, fnet_inet_ntop 00181 * @showinitializer 00182 ******************************************************************************/ 00183 #if FNET_CFG_IP6 00184 #define FNET_IP_ADDR_STR_SIZE FNET_IP6_ADDR_STR_SIZE 00185 #else /* IPv4 */ 00186 #define FNET_IP_ADDR_STR_SIZE FNET_IP4_ADDR_STR_SIZE 00187 #endif 00188 00189 #define FNET_IP_ADDR_STR_SIZE_MAX FNET_IP6_ADDR_STR_SIZE 00190 00191 /**************************************************************************/ /*! 00192 * @brief IPv4 address structure. 00193 * 00194 * @see sockaddr_in 00195 * 00196 * Actually, it represents an IPv4 address (in network endian). 00197 ******************************************************************************/ 00198 struct in_addr 00199 { 00200 fnet_ip4_addr_t s_addr; /**< @brief 32-bit IPv4 address (in network byte order). 00201 */ 00202 }; 00203 00204 /**************************************************************************/ /*! 00205 * @brief IPv4 Socket address structure. 00206 * 00207 * @see sockaddr 00208 * 00209 * To make manipulation of the @ref sockaddr structure easier, the TCP/IPv4 stack 00210 * also defines the equivalent structure @ref sockaddr_in 00211 * ("in" means "Internet"). 00212 ******************************************************************************/ 00213 struct sockaddr_in 00214 { 00215 fnet_address_family_t sin_family; /**< @brief Specifies the address family. @n 00216 * It must ne set to @ref AF_INET.*/ 00217 fnet_uint16_t sin_port; /**< @brief 16-bit port number used to 00218 * demultiplex the transport-level messages 00219 * (in network byte order).*/ 00220 fnet_scope_id_t sin_scope_id; /**< @brief Scope zone index, defining network interface.*/ 00221 struct in_addr sin_addr; /**< @brief 32-bit internet address.*/ 00222 }; 00223 00224 00225 /************************************************************************ 00226 * IPv6 00227 *************************************************************************/ 00228 00229 00230 /**************************************************************************/ /*! 00231 * @brief IPv6 address structure. 00232 * 00233 * @see sockaddr_in6 00234 * 00235 * Actually, it represents an IPv6 address. 00236 ******************************************************************************/ 00237 struct in6_addr 00238 { 00239 fnet_ip6_addr_t s6_addr; /**< @brief 128-bit IPv6 address.*/ 00240 }; 00241 00242 /**************************************************************************/ /*! 00243 * @brief IPv6 Socket address structure. 00244 * 00245 * @see sockaddr 00246 * 00247 * To make manipulation of the @ref sockaddr structure easier, the TCP/IPv6 stack 00248 * also defines the equivalent structure @ref sockaddr_in6 00249 * ("in" means "Internet"). 00250 ******************************************************************************/ 00251 struct sockaddr_in6 00252 { 00253 fnet_address_family_t sin6_family; /**< @brief Specifies the address family. @n 00254 * It must ne set to @ref AF_INET6. */ 00255 fnet_uint16_t sin6_port; /**< @brief 16-bit port number used to 00256 * demultiplex the transport-level messages 00257 * (in network byte order).*/ 00258 fnet_scope_id_t sin6_scope_id; /**< @brief Scope zone index, defining network interface.*/ 00259 struct in6_addr sin6_addr; /**< @brief 128-bit IPv6 internet address.*/ 00260 }; 00261 00262 /**************************************************************************/ /*! 00263 * @brief Socket address structure. 00264 * 00265 * @see sockaddr_in, sockaddr_in6 00266 * 00267 * The original goal of the @ref sockaddr structure is to support multiple 00268 * protocols. For the TCP/IP stack @c sa_data, it contains a destination address 00269 * and port number for a socket. 00270 ******************************************************************************/ 00271 struct sockaddr 00272 { 00273 fnet_address_family_t sa_family; /**< @brief Address family. Specifies the 00274 * address family, to which the address belongs. @n 00275 * It is defined by @ref fnet_address_family_t.*/ 00276 fnet_uint16_t sa_port; /**< @brief 16-bit port number used to 00277 * demultiplex the transport-level messages 00278 * (in network byte order).*/ 00279 fnet_scope_id_t sa_scope_id; /**< @brief Scope zone index, defining network interface.*/ 00280 fnet_uint8_t sa_data[FNET_SA_DATA_SIZE];/**< @brief Address value. For the TCP/IP stack, 00281 * it contains the destination address and port 00282 * number for a socket.*/ 00283 }; 00284 00285 /**************************************************************************/ /*! 00286 * @brief IPv4 multicast group information. 00287 * 00288 * The structure is used with the @ref IP_ADD_MEMBERSHIP and 00289 * @ref IP_DROP_MEMBERSHIP socket options. 00290 * 00291 * @see IP_ADD_MEMBERSHIP, IP_DROP_MEMBERSHIP 00292 * 00293 ******************************************************************************/ 00294 struct ip_mreq 00295 { 00296 struct in_addr imr_multiaddr; /**< @brief IPv4 multicast address of group. */ 00297 fnet_scope_id_t imr_interface; /**< @brief Interface index. It equals to the scope zone index, defining network interface.@n 00298 * If this member is zero, the default interface is used. */ 00299 }; 00300 00301 /**************************************************************************/ /*! 00302 * @brief IPv6 multicast group information. 00303 * 00304 * The structure is used with the @ref IPV6_JOIN_GROUP and 00305 * @ref IPV6_LEAVE_GROUP socket options. 00306 * 00307 * @see IPV6_JOIN_GROUP, IPV6_LEAVE_GROUP 00308 * 00309 ******************************************************************************/ 00310 struct ipv6_mreq 00311 { 00312 struct in6_addr ipv6imr_multiaddr; /**< @brief IPv6 multicast address of group. */ 00313 fnet_scope_id_t ipv6imr_interface; /**< @brief Interface index. It equals to the scope zone index, defining network interface.@n 00314 * If this member is zero, the default interface is used. */ 00315 }; 00316 00317 /**************************************************************************/ /*! 00318 * @brief Socket types. 00319 ******************************************************************************/ 00320 typedef enum 00321 { 00322 SOCK_UNSPEC = (0U), /**< @brief Unspecified socket type. 00323 */ 00324 SOCK_STREAM = (1U), /**< @brief Stream socket.@n 00325 * Provides reliable, two-way, connection-based 00326 * byte stream. It corresponds to the TCP protocol 00327 */ 00328 SOCK_DGRAM = (2U), /**< @brief Datagram socket.@n 00329 * Provides unreliable, connectionless datagrams. 00330 * It corresponds to the UDP protocol. 00331 */ 00332 SOCK_RAW = (3U) /**< @brief Raw socket.@n 00333 * Raw sockets allow an application to have direct access to 00334 * lower-level communication protocols. 00335 * Raw sockets are intended to take advantage of some protocol feature 00336 * that is not directly accessible through a normal interface, 00337 * or to build new protocols on top of existing low-level protocols.@n 00338 * It can be enabled by the @ref FNET_CFG_RAW option. 00339 */ 00340 } fnet_socket_type_t; 00341 00342 /**************************************************************************/ /*! 00343 * @brief Socket state. 00344 ******************************************************************************/ 00345 typedef enum 00346 { 00347 SS_UNCONNECTED = (0), /**< @brief Not connected to any socket. 00348 */ 00349 SS_CONNECTING = (1), /**< @brief In process of connecting. 00350 */ 00351 SS_CONNECTED = (2), /**< @brief Connected to a socket. 00352 */ 00353 SS_LISTENING = (3) /**< @brief In listening state. 00354 */ 00355 } fnet_socket_state_t; 00356 00357 /**************************************************************************/ /*! 00358 * @brief Protocol numbers and Level numbers for the @ref fnet_socket_setopt() 00359 * and the @ref fnet_socket_getopt(). 00360 ******************************************************************************/ 00361 typedef enum 00362 { 00363 IPPROTO_IP = (0), /**< @brief IPv4 options level number 00364 * for @ref fnet_socket_getopt() and @ref fnet_socket_setopt(). 00365 */ 00366 IPPROTO_ICMP = (1), /**< @brief ICMPv4 protocol number. 00367 */ 00368 IPPROTO_IGMP = (2), /**< @brief IGMP protocol number. 00369 */ 00370 IPPROTO_TCP = (6), /**< @brief TCP protocol number; TCP options level number 00371 * for @ref fnet_socket_getopt() and @ref fnet_socket_setopt(). 00372 */ 00373 IPPROTO_UDP = (17),/**< @brief UDP protocol number. 00374 */ 00375 IPPROTO_IPV6 = (41), /**< @brief IPv6 options level number 00376 * for @ref fnet_socket_getopt() and @ref fnet_socket_setopt(). 00377 */ 00378 IPPROTO_ICMPV6 = (58),/**< @brief ICMPv6 protocol number. 00379 */ 00380 SOL_SOCKET = (255255) /**< @brief Socket options level number for 00381 * @ref fnet_socket_getopt() and @ref fnet_socket_setopt(). 00382 */ 00383 } fnet_protocol_t; 00384 00385 /**************************************************************************/ /*! 00386 * @brief Socket options for the @ref fnet_socket_setopt() and the @ref fnet_socket_getopt(). 00387 * 00388 * <table> 00389 *<caption>Socket SOL_SOCKET, IPPROTO_TCP, IPPROTO_IP and IPPROTO_IPV6 level options</caption> 00390 *<tr class="fnet_td_grey"> 00391 *<th ALIGN=CENTER>Option</th><th ALIGN=CENTER>Option Type</th><th ALIGN=CENTER> 00392 * Default Value</th><th ALIGN=CENTER>Read/Write</th> 00393 *</tr> 00394 *<tr> 00395 *<td>@ref SO_ACCEPTCONN</td><td>fnet_uint32_t</td><td>0</td><td>R</td> 00396 *</tr> 00397 *<tr> 00398 *<td>@ref SO_KEEPALIVE</td><td>fnet_uint32_t</td><td>1</td><td>RW</td> 00399 *</tr> 00400 *<tr> 00401 *<td>@ref SO_DONTROUTE</td><td>fnet_uint32_t</td><td>0</td><td>RW</td> 00402 *</tr> 00403 *<tr> 00404 *<td>@ref SO_LINGER</td><td>struct @ref linger</td><td>{0,0}</td><td>RW</td> 00405 *</tr> 00406 *<tr> 00407 *<td>@ref SO_OOBINLINE</td><td>fnet_uint32_t</td><td>0</td><td>RW</td> 00408 *</tr> 00409 *<tr> 00410 *<td>@ref SO_SNDBUF</td><td>fnet_uint32_t</td> 00411 *<td>@ref FNET_CFG_SOCKET_UDP_TX_BUF_SIZE for UDP @n @ref FNET_CFG_SOCKET_TCP_TX_BUF_SIZE for TCP</td><td>RW</td> 00412 *</tr> 00413 *<tr> 00414 *<td>@ref SO_RCVBUF</td><td>fnet_uint32_t</td> 00415 *<td>@ref FNET_CFG_SOCKET_UDP_RX_BUF_SIZE for UDP @n @ref FNET_CFG_SOCKET_TCP_RX_BUF_SIZE for TCP</td><td>RW</td> 00416 *</tr> 00417 *<tr> 00418 *<td>@ref SO_STATE</td><td>@ref fnet_socket_state_t</td><td>@ref SS_UNCONNECTED</td><td>R</td> 00419 *</tr> 00420 *<tr> 00421 *<td>@ref SO_ERROR</td><td>@ref fnet_error_t</td><td>@ref FNET_ERR_OK</td><td>R</td> 00422 *</tr> 00423 *<tr> 00424 *<td>@ref SO_TYPE</td><td>@ref fnet_socket_type_t</td><td>@ref SOCK_DGRAM for 00425 * UDP @n @ref SOCK_STREAM for TCP</td><td>R</td> 00426 *</tr> 00427 *<tr> 00428 *<td>@ref SO_RCVNUM</td><td>fnet_uint32_t</td><td>0</td><td>R</td> 00429 *</tr> 00430 *<tr> 00431 *<td>@ref SO_SNDNUM</td><td>fnet_uint32_t</td><td>0</td><td>R</td> 00432 *</tr> 00433 *<tr> 00434 *<td>@ref TCP_MSS</td><td>fnet_uint32_t</td><td>536</td><td>RW</td> 00435 *</tr> 00436 *<tr> 00437 *<td>@ref TCP_BSD</td><td>fnet_uint32_t</td><td>1</td><td>RW</td> 00438 *</tr> 00439 *<tr> 00440 *<td>@ref TCP_NODELAY</td><td>fnet_uint32_t</td><td>1</td><td>RW</td> 00441 *</tr> 00442 *<tr> 00443 *<td>@ref TCP_FINRCVD</td><td>fnet_uint32_t</td><td>0</td><td>R</td> 00444 *</tr> 00445 *<tr> 00446 *<td>@ref TCP_URGRCVD</td><td>fnet_uint32_t</td><td>0</td><td>R</td> 00447 *</tr> 00448 *<tr> 00449 *<td>@ref TCP_KEEPIDLE</td><td>fnet_uint32_t</td><td>7200</td><td>RW</td> 00450 *</tr> 00451 *<tr> 00452 *<td>@ref TCP_KEEPINTVL</td><td>fnet_uint32_t</td><td>75</td><td>RW</td> 00453 *</tr> 00454 *<tr> 00455 *<td>@ref TCP_KEEPCNT</td><td>fnet_uint32_t</td><td>8</td><td>RW</td> 00456 *</tr> 00457 *<tr> 00458 *<td>@ref IP_TOS</td><td>fnet_uint32_t</td><td>0</td><td>RW</td> 00459 *</tr> 00460 *<tr> 00461 *<td>@ref IP_TTL</td><td>fnet_uint32_t</td><td>64</td><td>RW</td> 00462 *</tr> 00463 *<tr> 00464 *<td>@ref IP_MULTICAST_TTL</td><td>fnet_uint32_t</td><td>1</td><td>RW</td> 00465 *</tr> 00466 *<tr> 00467 *<td>@ref IP_ADD_MEMBERSHIP</td><td>@ref ip_mreq</td><td>N/A</td><td>W</td> 00468 *</tr> 00469 *<tr> 00470 *<td>@ref IP_DROP_MEMBERSHIP</td><td>@ref ip_mreq</td><td>N/A</td><td>W</td> 00471 *</tr> 00472 *<tr> 00473 *<td>@ref IPV6_UNICAST_HOPS</td><td>fnet_uint32_t</td><td>0 (64)</td><td>RW</td> 00474 *</tr> 00475 *<tr> 00476 *<td>@ref IPV6_MULTICAST_HOPS</td><td>fnet_uint32_t</td><td>1</td><td>RW</td> 00477 *</tr> 00478 *<tr> 00479 *<td>@ref IPV6_JOIN_GROUP</td><td>@ref ipv6_mreq</td><td>N/A</td><td>W</td> 00480 *</tr> 00481 *<tr> 00482 *<td>@ref IPV6_LEAVE_GROUP</td><td>@ref ipv6_mreq</td><td>N/A</td><td>W</td> 00483 *</tr> 00484 *</table> 00485 ******************************************************************************/ 00486 typedef enum 00487 { 00488 SO_ACCEPTCONN, /**< @brief Returns @c 1 if a socket is in 00489 * listening mode and returns @c 0 when vice versa. 00490 * This is the read-only option and it is 00491 * valid only for connection-oriented protocols (TCP). 00492 */ 00493 SO_KEEPALIVE, /**< @brief This option enables keep-alive probes 00494 * for a socket connection. These probes are used 00495 * to maintain a TCP connection and regularly 00496 * test the connection to ensure that it's 00497 * still available. It is only valid for 00498 * connection-oriented protocols (TCP). 00499 */ 00500 SO_DONTROUTE, /**< @brief This option enables bypassing of a routing algorithm. 00501 * It means that the network interface tries to send a datagram without 00502 * a gateway. 00503 */ 00504 SO_LINGER, /**< @brief This option controls the action 00505 * taken when unsent data is present, and 00506 * @ref fnet_socket_close() is called. This option 00507 * is defined by the @ref linger structure. 00508 */ 00509 SO_OOBINLINE, /**< @brief This option specifies that out-of-band (OOB) 00510 * data will be received in line with regular data. 00511 * It is valid only for the TCP protocol. @n 00512 * This option is avalable only if 00513 * @ref FNET_CFG_TCP_URGENT is set to @c 1. 00514 */ 00515 SO_SNDBUF, /**< @brief This option defines the maximum per-socket 00516 * buffer size for output data. 00517 */ 00518 SO_RCVBUF, /**< @brief This option defines the maximum per-socket 00519 * buffer size for input data. 00520 */ 00521 SO_STATE, /**< @brief This option defines the current state of the socket.@n 00522 * This is the read-only option and it is defined by the @ref fnet_socket_state_t type. 00523 */ 00524 SO_ERROR, /**< @brief This option returns a per-socket-based error code.@n 00525 * The error code is defined by the @ref fnet_error_t type.@n 00526 * After the error value has been read in the @ref fnet_socket_getopt function, it is cleared. 00527 * But a successful call using the socket routines does not clear 00528 * the socket-based error. 00529 */ 00530 SO_TYPE, /**< @brief This option defines the type of the socket. 00531 * This is a read-only option and it is defined by the @ref fnet_socket_type_t type. 00532 */ 00533 SO_RCVNUM, /**< @brief This option is used to determine the amount of data 00534 * pending in the socket-input buffer.@n 00535 * This is a read-only option. 00536 */ 00537 SO_SNDNUM,/**< @brief This option is used to determine the amount of data 00538 * in the socket output buffer. @n 00539 * This is a read-only option. 00540 */ 00541 /* TCP level (IPPROTO_TCP) options */ 00542 00543 TCP_MSS, /**< @brief This option defines the maximum size of 00544 * the input segments (MSS). @n 00545 * The TCP Maximum Segment Size (MSS) defines the maximum amount 00546 * of data that a host is willing to accept in a single TCP segment.@n 00547 * This Maximum Segment Size (MSS) announcement is sent from the 00548 * data receiver to the data sender and says "I can accept TCP segments 00549 * up to size X". The size (X) may be larger or smaller than the 00550 * default.@n 00551 * The MSS counts only data octets in the segment, it does not count the 00552 * TCP header or the IP header.@n 00553 * The default value is defined by the @ref FNET_CFG_SOCKET_TCP_MSS 00554 * user-configuration option. @n 00555 * This option can be set to: 00556 * - @c 0 = The selection of the MSS is 00557 * automatic and is based on the MTU of the outgoing 00558 * interface minus 40 (does not include 00559 * the 20 byte IP header and the 20 byte TCP header).@n 00560 * It is done to assist in avoiding of IP fragmentation 00561 * at the endpoints of the TCP connection. 00562 * - Non-zero value (up to 64K) = The TCP segment could be as large as 64K 00563 * (the maximum IP datagram size), but it could be fragmented 00564 * at the IP layer in order to be transmitted 00565 * across the network to the receiving host. 00566 */ 00567 TCP_BSD, /**< @brief If this option is set to @c 1, the BSD interpretation of 00568 * the urgent pointer is used. In this case the 00569 * urgent pointer of the TCP segment points to 00570 * the next byte following after the urgent byte. 00571 * Most of the TCP implementations use this 00572 * interpretation by default.@n 00573 * If this option is set to @c 0, the interpretation of 00574 * the TCP specification is used. In this case the 00575 * urgent pointer of the TCP segment points 00576 * to the urgent byte. @n 00577 * This option is avalable only if 00578 * @ref FNET_CFG_TCP_URGENT is set to @c 1. 00579 */ 00580 TCP_NODELAY, /**< @brief If this option is set to @c 1, the Nagle algorithm 00581 * is disabled (and vice versa). @n 00582 * The Nagle algorithm is effective in reducing the number 00583 * of small packets sent by the host by essentially buffering 00584 * send data, if there is unacknowledged data already "in flight", 00585 * or until a full-size packet can be sent.@n 00586 * But for some applications this algorithm can impede 00587 * performance, especially for a bulky data transfer. 00588 */ 00589 TCP_FINRCVD, /**< @brief This option is set when the final (FIN) segment arrives. @n 00590 * This option indicates that another side will not send any data 00591 * in the current connection.@n 00592 * This is the read-only option. 00593 */ 00594 TCP_URGRCVD, /**< @brief This option is set when the urgent byte arrives, and 00595 * reset when this byte is read.@n 00596 * This option can be set only if the @ref SO_OOBINLINE option is set to @c 0.@n 00597 * This is the read-only option. @n 00598 * This option is avalable only if 00599 * @ref FNET_CFG_TCP_URGENT is set to @c 1. 00600 */ 00601 TCP_KEEPIDLE, /**< @brief When the @ref SO_KEEPALIVE option is enabled, TCP probes a connection that 00602 * has been idle for some amount of time. The default value for this idle 00603 * period is @c 7200 seconds (2 hours). The @ref TCP_KEEPIDLE option can be used to affect this 00604 * value for a given socket, and specifies the number of seconds of idle 00605 * time between keepalive probes. 00606 */ 00607 TCP_KEEPINTVL, /**< @brief When the @ref SO_KEEPALIVE option is enabled, TCP probes a connection that 00608 * has been idle for some amount of time. If the remote system does not 00609 * respond to a keepalive probe, TCP retransmits the probe after some 00610 * amount of time. The default value for this retransmit interval is @c 75 00611 * seconds. The @ref TCP_KEEPINTVL option can be used to affect this value for 00612 * a given socket, and specifies the number of seconds to wait before 00613 * retransmitting a keepalive probe. 00614 */ 00615 TCP_KEEPCNT, /**< @brief When the @ref SO_KEEPALIVE option is enabled, TCP probes a connection that 00616 * has been idle for some amount of time. If the remote system does not 00617 * respond to a keepalive probe, TCP retransmits the probe a certain 00618 * number of times before a connection is considered to be broken. The 00619 * default value for this keepalive probe retransmit limit is @c 8. The 00620 * @ref TCP_KEEPCNT option can be used to affect this value for a given socket, 00621 * and specifies the maximum number of keepalive probes to be sent. 00622 */ 00623 00624 /* IPv4 level (IPPROTO_IP) options */ 00625 00626 IP_TOS , /**< @brief This option defines the IPv4 TOS 00627 * (type-of-service) field for outgoing datagrams. 00628 */ 00629 IP_TTL , /**< @brief This option defines the IPv4 TTL 00630 * (time-to-live) vlaue for outgoing datagrams. 00631 */ 00632 IP_MULTICAST_TTL , /**< @brief This option allows to change IPv4 "time to live" (TTL) 00633 * value for outgoing multicast datagrams. 00634 * Otherwise, multicast datagrams are sent with a default value of 1, 00635 * to prevent them to be forwarded beyond the local network.@n 00636 * This option is available only if @ref FNET_CFG_MULTICAST is set to @c 1. 00637 */ 00638 IP_ADD_MEMBERSHIP, /**< @brief Join the socket to the IPv4 multicast group on 00639 * the specified interface. It tells the system to receive packets on 00640 * the network whose destination is the group address (but not its own). 00641 * It is valid only for the SOCK_DGRAM (UDP) sockets.@n 00642 * This option is available only if @ref FNET_CFG_MULTICAST is set to @c 1. 00643 */ 00644 IP_DROP_MEMBERSHIP, /**< @brief Drops membership to a IPv4 multicast group and interface.@n 00645 * This option is available only if @ref FNET_CFG_MULTICAST is set to @c 1. 00646 */ 00647 /* IPv6 level (IPPROTO_IPV6) options */ 00648 00649 IPV6_UNICAST_HOPS, /**< @brief This option defines hop limit used 00650 * for outgoing unicast IPv6 packets. @n 00651 * Its value can be from 0 till 255.@n 00652 * By default the option is set to 0. It means that the hop limit is defined 00653 * by local IPv6 router, otherwise it equals to 64. 00654 */ 00655 IPV6_MULTICAST_HOPS, /**< @brief Set the hop limit to use for outgoing multicast IPv6 packets.@n 00656 * If IPV6_MULTICAST_HOPS is not set, the default is 1. 00657 */ 00658 IPV6_JOIN_GROUP, /**< @brief (RFC3493) Join a multicast group on a specified local interface.@n 00659 * It is valid only for the SOCK_DGRAM (UDP) sockets. 00660 */ 00661 IPV6_LEAVE_GROUP /**< @brief (RFC3493) Leave a multicast group on a specified interface.@n 00662 * It is valid only for the SOCK_DGRAM (UDP) sockets. 00663 */ 00664 } fnet_socket_options_t; 00665 00666 /**************************************************************************/ /*! 00667 * @brief This structure is used for the @ref SO_LINGER option. 00668 ******************************************************************************/ 00669 struct linger 00670 { 00671 fnet_bool_t l_onoff; /**< @brief Determines, whether the option will be 00672 * turned on @c FNET_TRUE, or off @c FNET_FALSE. 00673 */ 00674 fnet_uint16_t l_linger; /**< @brief Specifies the amount of time (in seconds) 00675 * to wait when the connection is closed and unsent data 00676 * is discarded. 00677 * If @c l_onoff is @c 0, the @c l_linger value is ignored 00678 * and the stack continues to try to send the data as usually. 00679 */ 00680 }; 00681 00682 /**************************************************************************/ /*! 00683 * @brief Socket descriptor. 00684 ******************************************************************************/ 00685 typedef void* fnet_socket_t; 00686 00687 /**************************************************************************/ /*! 00688 * @brief The flags parameters for receiving and sending functions 00689 * @ref fnet_socket_recv(), @ref fnet_socket_recvfrom(), @ref fnet_socket_send(), and @ref fnet_socket_sendto(). 00690 * 00691 * The optional flag specifies the way, in which the call is made. 00692 * It can be constructed by using the bitwise OR. 00693 ******************************************************************************/ 00694 typedef enum 00695 { 00696 MSG_OOB = (0x1U), /**< @brief Process out-of-band 00697 * data instead of regular data. @n 00698 * This option is avalable only if 00699 * @ref FNET_CFG_TCP_URGENT is set to @c 1. 00700 */ 00701 MSG_PEEK = (0x2U), /**< @brief Receive a copy of the 00702 * data without consuming it. 00703 */ 00704 MSG_DONTROUTE = (0x4U) /**< @brief Send without using 00705 * routing tables. 00706 */ 00707 } fnet_msg_flags_t; 00708 00709 /**************************************************************************/ /*! 00710 * @brief The flags used by @ref fnet_socket_shutdown(). 00711 * 00712 * They describe what types of socket operation will no longer be allowed. 00713 ******************************************************************************/ 00714 typedef enum 00715 { 00716 SD_READ = (0x1U), /**< @brief Data receiving is disabled. 00717 */ 00718 SD_WRITE = (0x2U), /**< @brief Data sending is disabled. 00719 */ 00720 SD_BOTH = (SD_READ | SD_WRITE) /**< @brief Both receiving and 00721 * sending are disabled. 00722 */ 00723 } fnet_sd_flags_t; 00724 00725 #if defined(__cplusplus) 00726 extern "C" { 00727 #endif 00728 00729 /***************************************************************************/ /*! 00730 * 00731 * @brief Creates a socket. 00732 * 00733 * 00734 * @param family Address family that the socket will use, defined 00735 * by the @ref fnet_address_family_t. 00736 * 00737 * @param type Type specification for the new socket, defined by @ref 00738 * fnet_socket_type_t. It can be @ref SOCK_STREAM (TCP) or 00739 * @ref SOCK_DGRAM (UDP). 00740 * 00741 * @param protocol Protocol to be used with the socket that is specific to 00742 * the indicated address family. This stack supports 00743 * @ref IPPROTO_TCP and @ref IPPROTO_UDP.@n 00744 * This parameter is optional, and can be set to zero, as 00745 * the @c type already defines the proper protocol. 00746 * 00747 * @return This function returns: 00748 * - Socket descriptor referencing the new socket, if no error occurs. 00749 * - @ref FNET_NULL if an error occurs. @n 00750 * The specific error code can be retrieved using the @ref fnet_error_get(). 00751 * 00752 * @see fnet_socket_close() 00753 * 00754 ****************************************************************************** 00755 * 00756 * This function creates a socket and returns its descriptor.@n 00757 * The @ref fnet_socket() function causes a socket descriptor and any related 00758 * resources to be allocated and bound to a specific transport-service 00759 * provider that supports the requested combination of address family, 00760 * socket type, and protocol parameters.@n 00761 * @n 00762 * After a socket is created: 00763 * - Connection-oriented sockets, such as the @ref SOCK_STREAM, provide 00764 * full-duplex connections. Before any data can be sent or received, 00765 * it must be in a connected state . A connection to 00766 * another socket is established with the @ref fnet_socket_connect() call. 00767 * Once connected, the data can be transferred using the @ref fnet_socket_send() and the @ref 00768 * fnet_socket_recv() calls. When a session has been completed, the @ref fnet_socket_close() 00769 * must be performed. 00770 * - Connectionless, message-oriented sockets, such as the @ref SOCK_DGRAM, allow 00771 * sending and receiving of datagrams to and from arbitrary peers using 00772 * the @ref fnet_socket_sendto() and the @ref fnet_socket_recvfrom(). If such a socket is connected 00773 * to a specific peer, datagrams can be sent to that peer using the 00774 * @ref fnet_socket_send(), and can be received only from this peer using the @ref fnet_socket_recv(). 00775 * 00776 ******************************************************************************/ 00777 fnet_socket_t fnet_socket( fnet_address_family_t family, fnet_socket_type_t type, fnet_uint32_t protocol ); 00778 00779 /***************************************************************************/ /*! 00780 * 00781 * @brief Assigns a local address to a socket. 00782 * 00783 * 00784 * @param s Descriptor, identifying a socket to bind. 00785 * 00786 * @param name The address to be assigned to the socket, from the @ref 00787 * sockaddr structure. 00788 * 00789 * @param namelen The length of the @c name parameter. 00790 * Normally @c namelen is set to @c sizeof(name). 00791 * 00792 * @return This function returns: 00793 * - @ref FNET_OK if no error occurs. 00794 * - @ref FNET_ERR if an error occurs. @n 00795 * The specific error code can be retrieved using the @ref fnet_error_get(). 00796 * 00797 * @see fnet_socket() 00798 * 00799 ****************************************************************************** 00800 * 00801 * This function associates a local address with the socket.@n 00802 * The @ref fnet_socket_bind() function is used on an unconnected socket before 00803 * subsequent calls to the @ref fnet_socket_connect() or the @ref fnet_socket_listen() functions. 00804 * It is used to bind to either connection-oriented (stream) or connectionless 00805 * (datagram) sockets.@n 00806 * Within the @ref sockaddr structure, the address may be the address assigned 00807 * to a network interface on the host or the @ref INADDR_ANY. 00808 * Using the @ref INADDR_ANY causes the stack to use the default network 00809 * interface address. Using a port number of 0 causes the service provider 00810 * to assign a unique port to the socket with a value between 1024 and 5000. 00811 * 00812 ******************************************************************************/ 00813 fnet_return_t fnet_socket_bind( fnet_socket_t s, const struct sockaddr *name, fnet_size_t namelen ); 00814 00815 /***************************************************************************/ /*! 00816 * 00817 * @brief Places the socket into a state, where it is listening for 00818 * an incoming connection. 00819 * 00820 * 00821 * @param s Descriptor identifying a socket that will be 00822 * used for listening. 00823 * 00824 * @param backlog Maximum length of the queue of pending connections. 00825 * 00826 * 00827 * @return This function returns: 00828 * - @ref FNET_OK if no error occurs. 00829 * - @ref FNET_ERR if an error occurs. @n 00830 * The specific error code can be retrieved using the @ref fnet_error_get(). 00831 * 00832 * @see fnet_socket(), fnet_socket_bind(), fnet_socket_accept() 00833 * 00834 ****************************************************************************** 00835 * 00836 * Only connection-oriented sockets (@ref SOCK_STREAM) are used with the 00837 * @ref fnet_socket_listen().@n 00838 * The socket is put into passive mode, where the incoming connection 00839 * requests are acknowledged and queued pending acceptance by the listening socket. 00840 * The @ref fnet_socket_listen() function is typically used by servers that can have 00841 * more than one connection request at a time. @n 00842 * An application can call @ref fnet_socket_listen() more than once on the same socket. 00843 * If there are more pending connections than the new backlog value, 00844 * the excess pending connections will be reset and dropped. 00845 * 00846 ******************************************************************************/ 00847 fnet_return_t fnet_socket_listen( fnet_socket_t s, fnet_size_t backlog ); 00848 00849 /***************************************************************************/ /*! 00850 * 00851 * @brief Accepts a connection on the specified socket. 00852 * 00853 * 00854 * @param s Descriptor, identifying an unconnected socket. 00855 * 00856 * @param addr Optional pointer to a buffer that receives the address 00857 * of the remote host at the other end of the connection. 00858 * 00859 * @param addrlen Optional pointer to an integer that contains the 00860 * length of the @c addr parameter. 00861 * 00862 * 00863 * @return This function returns: 00864 * - Socket descriptor referencing the new socket, if no error occurs. 00865 * - @ref FNET_NULL if an error occurs. @n 00866 * The specific error code can be retrieved using @ref fnet_error_get(). 00867 * 00868 * @see fnet_socket(), fnet_socket_bind() 00869 * 00870 ****************************************************************************** 00871 * 00872 * The function extracts the first connection in the queue of pending 00873 * connections on the listening socket @c s, and returns the new socket descriptor.@n 00874 * The newly-created socket is the socket that will handle the actual 00875 * connection and has the same properties as the socket @c s. 00876 * The original socket remains open and listens for new connection requests. 00877 * If no pending connections are present in the queue of the socket, 00878 * the @ref fnet_socket_accept() returns FNET_NULL and the specific error code is set to 00879 * @ref FNET_ERR_AGAIN.@n 00880 * The parameter @c addr is a result parameter that is filled in with the 00881 * address of the remote host. The @c addrlen should initially contain the 00882 * amount of space pointed to by the @c addr; on return it will contain the 00883 * actual length of the address returned (in bytes).@n 00884 * The @ref fnet_socket_accept() function is used only with connection-oriented socket 00885 * types (@ref SOCK_STREAM).@n 00886 * If @c addr and/or @c addrlen are equal to @c 0, then no information 00887 * about the remote address of the accepted socket is returned. 00888 * 00889 ******************************************************************************/ 00890 fnet_socket_t fnet_socket_accept( fnet_socket_t s, struct sockaddr *addr, fnet_size_t *addrlen ); 00891 00892 /***************************************************************************/ /*! 00893 * 00894 * @brief Establishes a connection with the specified socket. 00895 * 00896 * 00897 * @param s Descriptor identifying an unconnected socket. 00898 * 00899 * @param name Address (name) of the socket, with which the connection 00900 * should be established. 00901 * 00902 * @param namelen Length of the @c name. 00903 * 00904 * 00905 * @return This function returns: 00906 * - @ref FNET_OK if no error occurs. 00907 * - @ref FNET_ERR if an error occurs. @n 00908 * The specific error code can be retrieved using the @ref fnet_error_get(). 00909 * 00910 * @see fnet_socket(), fnet_socket_bind() 00911 * 00912 ****************************************************************************** 00913 * 00914 * For connection-oriented sockets (@ref SOCK_STREAM), this function activates 00915 * an active connection with the foreign host. 00916 * 00917 * When the socket call completes successfully, the socket is ready to send 00918 * and receive data. Any attempt to reconnect the active connection will fail 00919 * with the error code @ref FNET_ERR_ISCONN. For connection-oriented 00920 * sockets, it is often not possible to complete the connection 00921 * immediately. Until the connection attempt 00922 * completes on a socket, all subsequent calls to @ref fnet_socket_connect() 00923 * on the same socket will fail with the error code @ref FNET_ERR_INPROGRESS, 00924 * or succeed with @ref FNET_ERR_ISCONN when the connection completes successfully. 00925 * Use the @ref fnet_socket_getopt() function to determine the completion of the 00926 * connection request by checking the @ref SO_STATE to see if the socket is 00927 * connected (@ref SS_CONNECTED), is still connecting (@ref SS_CONNECTING) 00928 * or the connection has failed (@ref SS_UNCONNECTED). @n 00929 * @n 00930 * For a connectionless socket (@ref SOCK_DGRAM), the operation performed 00931 * by @ref fnet_socket_connect() is merely to establish a default destination address 00932 * that can be used on subsequent @ref fnet_socket_send() and @ref fnet_socket_recv() calls. 00933 * Any datagrams received from an address other than the destination address 00934 * specified will be discarded. The default destination can be changed by 00935 * simply calling the @ref fnet_socket_connect() again, even if the socket is connected already. 00936 * Any datagrams queued for receipt are discarded from the previous 00937 * @ref fnet_socket_connect(). For connectionless sockets, the @c name can indicate any 00938 * valid address, including a broadcast address.@n 00939 * @n 00940 * If the socket @c s is unbound, unique values are assigned to the local 00941 * association by the stack, and the socket is marked as bound. 00942 * 00943 ******************************************************************************/ 00944 fnet_return_t fnet_socket_connect( fnet_socket_t s, struct sockaddr *name, fnet_size_t namelen ); 00945 00946 /***************************************************************************/ /*! 00947 * 00948 * @brief Receives the data from a connected socket. 00949 * 00950 * 00951 * @param s Descriptor identifying a connected socket. 00952 * 00953 * @param buf Buffer for the incoming data. 00954 * 00955 * @param len Length of the @c buf. 00956 * 00957 * @param flags Optional flag specifying the way, in which the call is made. 00958 * It can be constructed by using the bitwise OR operator with 00959 * any of the values defined by the @ref fnet_msg_flags_t. 00960 * 00961 * 00962 * @return This function returns: 00963 * - The number of bytes received, if no error occurs. 00964 * The return value is set to zero, if there 00965 * is no input data. 00966 * - @ref FNET_ERR if an error occurs. @n 00967 * The specific error code can be retrieved using the @ref fnet_error_get(). 00968 * 00969 * @see fnet_socket_connect(), fnet_socket_recvfrom() 00970 * 00971 ****************************************************************************** 00972 * 00973 * For connection-oriented sockets (@ref SOCK_STREAM), calling the @ref fnet_socket_recv() 00974 * will return as much information as is currently available up to the size 00975 * of the buffer supplied.@n 00976 * @n 00977 * For connectionless sockets (@ref SOCK_DGRAM), the data is extracted from the 00978 * first enqueued datagram (message), whose destination address is specified 00979 * by the @ref fnet_socket_connect() function. 00980 * If the datagram is larger than the supplied buffer, the buffer is filled 00981 * with the first part of the datagram, and the @ref fnet_socket_recv() generates the error 00982 * @ref FNET_ERR_MSGSIZE and the excess data is lost.@n 00983 * @n 00984 * The @c flags parameter can be used to influence the behavior of the function 00985 * invocation beyond the options specified for the associated socket. 00986 * 00987 ******************************************************************************/ 00988 fnet_int32_t fnet_socket_recv( fnet_socket_t s, fnet_uint8_t *buf, fnet_size_t len, fnet_flag_t flags ); 00989 00990 /***************************************************************************/ /*! 00991 * 00992 * @brief Receives the data and captures the address, from which the data 00993 * was sent. 00994 * 00995 * 00996 * @param s Descriptor, identifying a bound socket. 00997 * 00998 * @param buf Buffer for the incoming data. 00999 * 01000 * @param len Length of the @c buf. 01001 * 01002 * @param flags Optional flag specifying the way in which the call is made. 01003 * It can be constructed by using the bitwise OR operator with 01004 * any of the values defined by the @ref fnet_msg_flags_t. 01005 * 01006 * @param from Optional pointer to a buffer that will hold the 01007 * source address upon return. 01008 * 01009 * @param fromlen Optional pointer to the size of the @c from buffer. 01010 * 01011 * 01012 * @return This function returns: 01013 * - The number of bytes received, if no error occurs. 01014 * The return value is set to zero, if the socket is nonblocking and there 01015 * is no input data. 01016 * - @ref FNET_ERR if an error occurs. @n 01017 * The specific error code can be retrieved using the @ref fnet_error_get(). 01018 * 01019 * @see fnet_socket_bind(), fnet_socket_recv() 01020 * 01021 ****************************************************************************** 01022 * 01023 * For connection-oriented sockets (@ref SOCK_STREAM), calling the @ref fnet_socket_recvfrom() 01024 * will return as much information as is currently available up to the size of 01025 * the buffer supplied. The @ref fnet_socket_recvfrom() call is rarely used for 01026 * stream sockets, because the routine provides the peer-socket information, 01027 * and stream sockets are tied to a specific peer.@n 01028 * @n 01029 * For connectionless sockets (@ref SOCK_DGRAM), the data is extracted from the 01030 * first enqueued datagram. 01031 * If the datagram is larger than the buffer supplied, the buffer is filled 01032 * with the first part of the datagram, and the @ref fnet_socket_recvfrom() generates the 01033 * error @ref FNET_ERR_MSGSIZE and the excess data is lost.@n 01034 * @n 01035 * If the @c from parameter is non-zero, the network address of the peer 01036 * that sent the data is copied to the corresponding @ref sockaddr structure. 01037 * The value pointed to by @c fromlen is initialized to the size of this 01038 * structure and is modified on return, to indicate the actual size of 01039 * the address stored in the @ref sockaddr structure.@n 01040 * @n 01041 * The flags parameter can be used to influence the behavior of the function 01042 * invocation beyond the options specified for the associated socket. 01043 * 01044 ******************************************************************************/ 01045 fnet_int32_t fnet_socket_recvfrom( fnet_socket_t s, fnet_uint8_t *buf, fnet_size_t len, fnet_flag_t flags, struct sockaddr *from, fnet_size_t *fromlen ); 01046 01047 /***************************************************************************/ /*! 01048 * 01049 * @brief Sends the data on a connected socket. 01050 * 01051 * 01052 * @param s Descriptor, identifying a connected socket. 01053 * 01054 * @param buf Buffer containing the data to be transmitted. 01055 * 01056 * @param len Length of the data in @c buf. 01057 * 01058 * @param flags Optional flag specifying the way in which the call is made. 01059 * It can be constructed by using the bitwise OR operator with 01060 * any of the values defined by the @ref fnet_msg_flags_t. 01061 * 01062 * 01063 * @return This function returns: 01064 * - The total number of bytes sent, if no error occurs. 01065 * It can be less than the number indicated by @c len. 01066 * - @ref FNET_ERR if an error occurs. @n 01067 * The specific error code can be retrieved using the @ref fnet_error_get(). 01068 * 01069 * @see fnet_socket_connect(), fnet_socket_sendto() 01070 * 01071 ****************************************************************************** 01072 * 01073 * For stream-oriented sockets (@ref SOCK_STREAM), the number of 01074 * actually sent bytes can be between @c 0 and the requested length, depending on 01075 * buffer availability on both client and server machines.@n 01076 * @n 01077 * For message-oriented sockets (@ref SOCK_DGRAM), care must be taken not to 01078 * exceed the maximum datagram size, which can be obtained by using the @ref 01079 * fnet_socket_getopt() to retrieve the value of the socket option @ref SO_SNDBUF. 01080 * If the data is too long to pass atomically through the underlying 01081 * datagram protocol, the error @ref FNET_ERR_MSGSIZE is returned 01082 * and no data is transmitted.@n 01083 * Calling the @ref fnet_socket_send() with a zero @c len parameter is permissible. 01084 * In such cases, the @ref fnet_socket_send() will return zero as a valid value, and 01085 * for message-oriented sockets (@ref SOCK_DGRAM) a zero-length transport 01086 * datagram is sent.@n 01087 * @n 01088 * The @c flags parameter can be used to influence the behavior of the function 01089 * invocation beyond the options specified for the associated socket. 01090 * 01091 ******************************************************************************/ 01092 fnet_int32_t fnet_socket_send( fnet_socket_t s, fnet_uint8_t *buf, fnet_size_t len, fnet_flag_t flags ); 01093 01094 /***************************************************************************/ /*! 01095 * 01096 * @brief Sends the data to a specific destination. 01097 * 01098 * 01099 * @param s Descriptor, identifying a socket. 01100 * 01101 * @param buf Buffer containing the data to be transmitted. 01102 * 01103 * @param len Length of the data in @c buf. 01104 * 01105 * @param flags Optional flag specifying the way, in which the call is made. 01106 * It can be constructed by using the bitwise OR operator with 01107 * any of the values defined by the @ref fnet_msg_flags_t. 01108 * 01109 * @param to Pointer to the address of the target socket. 01110 * 01111 * @param tolen Size of the address in @c to. 01112 * 01113 * 01114 * @return This function returns: 01115 * - The total number of bytes sent, if no error occurs. 01116 * It can be lesser than the number indicated by @c len. 01117 * - @ref FNET_ERR if an error occurs. @n 01118 * The specific error code can be retrieved using the @ref fnet_error_get(). 01119 * 01120 * @see fnet_socket_connect(), fnet_socket_send() 01121 * 01122 ****************************************************************************** 01123 * 01124 * For nonb-locking stream-oriented sockets (@ref SOCK_STREAM), the number of 01125 * actually sent bytes can be between @c 1 and the requested length, depending on 01126 * buffer availability on both client and server machines.@n 01127 * @n 01128 * For message-oriented sockets (@ref SOCK_DGRAM), care must be taken not not 01129 * exceed the maximum datagram size, which can be obtained by using the @ref 01130 * fnet_socket_getopt() to retrieve the value of the socket option @ref SO_SNDBUF. 01131 * If the data is too long to pass atomically through the underlying 01132 * datagram protocol, the error @ref FNET_ERR_MSGSIZE is returned 01133 * and no data is transmitted.@n 01134 * Calling @ref fnet_socket_sendto() with a zero @c len parameter is permissible. 01135 * In such cases, the @ref fnet_socket_sendto() will return zero as a valid value, and 01136 * for message-oriented sockets (@ref SOCK_DGRAM), a zero-length transport 01137 * datagram is sent.@n 01138 * @n 01139 * The @ref fnet_socket_sendto() function is normally used on a connectionless socket 01140 * (@ref SOCK_DGRAM) to send a datagram to a specific peer socket identified 01141 * by the @c to parameter. Even if the connectionless socket has been previously 01142 * connected to a specific address, the @c to parameter overrides the 01143 * destination address for that particular datagram only.@n 01144 * On a connection-oriented socket (@ref SOCK_STREAM), the @c to and @c tolen 01145 * parameters are ignored, making the @ref fnet_socket_sendto() equivalent to @ref fnet_socket_send().@n 01146 * @n 01147 * The @c flags parameter can be used to influence the behavior of the function 01148 * invocation beyond the options specified for the associated socket. 01149 * 01150 ******************************************************************************/ 01151 fnet_int32_t fnet_socket_sendto( fnet_socket_t s, fnet_uint8_t *buf, fnet_size_t len, fnet_flag_t flags, const struct sockaddr *to, fnet_size_t tolen ); 01152 01153 /***************************************************************************/ /*! 01154 * 01155 * @brief Terminates the connection in one or both directions. 01156 * 01157 * 01158 * @param s Descriptor, identifying a socket. 01159 * 01160 * @param how Flag that describes what types of operation will no longer 01161 * be allowed, it's defined by the @ref fnet_sd_flags_t. 01162 * 01163 * 01164 * @return This function returns: 01165 * - @ref FNET_OK if no error occurs. 01166 * - @ref FNET_ERR if an error occurs. @n 01167 * The specific error code can be retrieved using the @ref fnet_error_get(). 01168 * 01169 * @see fnet_socket_close() 01170 * 01171 ****************************************************************************** 01172 * 01173 * This function is used on all types of sockets to disable reception, 01174 * transmission, or both.@n 01175 * If the @c how parameter is @ref SD_READ, subsequent calls to the @ref fnet_socket_recv() 01176 * function on the socket will be unallowed. If the @c how parameter is 01177 * @ref SD_WRITE, subsequent calls to the @ref fnet_socket_send() function are unallowed. 01178 * Setting the @c how to the @ref SD_BOTH disables both sends and receives as 01179 * described above.@n 01180 * The @ref fnet_socket_shutdown() function does not close the socket. Any resources 01181 * attached to the socket will not be freed until the @ref fnet_socket_close() is invoked. 01182 * 01183 ******************************************************************************/ 01184 fnet_return_t fnet_socket_shutdown( fnet_socket_t s, fnet_sd_flags_t how ); 01185 01186 /***************************************************************************/ /*! 01187 * 01188 * @brief Closes an existing socket. 01189 * 01190 * @param s Descriptor, identifying a socket to close. 01191 * 01192 * @return This function returns: 01193 * - @ref FNET_OK if no error occurs. 01194 * - @ref FNET_ERR if an error occurs. @n 01195 * The specific error code can be retrieved using the @ref fnet_error_get(). 01196 * 01197 * @see fnet_socket() 01198 * 01199 ****************************************************************************** 01200 * 01201 * This function releases the socket descriptor @c s, so that further 01202 * references to @c s fail with the error @ref FNET_ERR_BAD_DESC.@n 01203 * An application should always have a matching call to the @ref fnet_socket_close() for 01204 * each successful call to the @ref fnet_socket() to return any socket resources to 01205 * the system.@n 01206 * @n 01207 * For the @ref SOCK_STREAM sockets, the @ref SO_LINGER option controls the action 01208 * of the closing, when unsent data is present on the socket and the @ref 01209 * fnet_socket_close() function is performed. This option has effect on 01210 * TCP sockets only. To enable or disable the @ref SO_LINGER option, the application 01211 * should use the @ref linger structure. This structure includes the 01212 * @c l_onoff and the @c l_linger fields. If the @c l_onoff has a non-zero value, 01213 * then the @ref SO_LINGER is enabled. Otherwise, the @ref SO_LINGER option is 01214 * disabled. The @c l_linger field includes the timeout in seconds. 01215 * If the @ref SO_LINGER option is not used 01216 * , the remaining data of the output buffer can be sent after the execution 01217 * of the @ref fnet_socket_close() in the background.@n 01218 * If a timeout expires and unsent data is present, the hard reset occurs and 01219 * unsent data will be deleted.@n 01220 * If the @ref SO_LINGER option is used with a zero timeout interval, the 01221 * hard reset occurs immediately and unsent data will be deleted. 01222 * 01223 ******************************************************************************/ 01224 fnet_return_t fnet_socket_close( fnet_socket_t s ); 01225 01226 /***************************************************************************/ /*! 01227 * 01228 * @brief Sets a socket option. 01229 * 01230 * 01231 * @param s Descriptor identifying a socket. 01232 * 01233 * @param level Level, at which the option is defined. 01234 * The supported levels are @ref SOL_SOCKET, 01235 * @ref IPPROTO_IP, @ref IPPROTO_IPV6 or @ref IPPROTO_TCP. 01236 * 01237 * @param optname Socket option for which the value is to be set. 01238 * 01239 * @param optval Pointer to a buffer, in which the value for the requested 01240 * option is supplied. 01241 * 01242 * @param optvallen Size of the @c optval buffer. 01243 * 01244 * 01245 * @return This function returns: 01246 * - @ref FNET_OK if no error occurs. 01247 * - @ref FNET_ERR if an error occurs. @n 01248 * The specific error code can be retrieved using the @ref fnet_error_get(). 01249 * 01250 * @see fnet_socket_getopt() 01251 * 01252 ****************************************************************************** 01253 * 01254 * This function sets the current value for a socket option associated with the 01255 * specified socket.@n 01256 * The various socket options are described by the @ref fnet_socket_options_t. 01257 * 01258 ******************************************************************************/ 01259 fnet_return_t fnet_socket_setopt( fnet_socket_t s, fnet_protocol_t level, fnet_socket_options_t optname, const void *optval, fnet_size_t optvallen ); 01260 01261 /***************************************************************************/ /*! 01262 * 01263 * @brief Gets a socket option. 01264 * 01265 * 01266 * @param s Descriptor identifying a socket. 01267 * 01268 * @param level Level, at which the option is defined. 01269 * The supported levels are the @ref SOL_SOCKET, 01270 * @ref IPPROTO_IP, @ref IPPROTO_IPV6 or @ref IPPROTO_TCP. 01271 * 01272 * @param optname Socket option, for which the value is to be retrievied. 01273 * 01274 * @param optval Pointer to a buffer in which the value for the requested 01275 * option has to be returned. 01276 * 01277 * @param optvallen Pointer to the size of the @c optval buffer. 01278 * 01279 * 01280 * @return This function returns: 01281 * - @ref FNET_OK if no error occurs. 01282 * - @ref FNET_ERR if an error occurs. @n 01283 * The specific error code can be retrieved using the @ref fnet_error_get(). 01284 * 01285 * @see fnet_socket_setopt() 01286 * 01287 ****************************************************************************** 01288 * 01289 * This function retrieves the current value for a socket option associated 01290 * with the socket @c s, and stores the result in the @c optval.@n 01291 * The various socket options are described by the @ref fnet_socket_options_t. 01292 * 01293 ******************************************************************************/ 01294 fnet_return_t fnet_socket_getopt( fnet_socket_t s, fnet_protocol_t level, fnet_socket_options_t optname, void *optval, fnet_size_t *optvallen ); 01295 01296 /***************************************************************************/ /*! 01297 * 01298 * @brief Retrieves the name of a peer connected to a socket. 01299 * 01300 * 01301 * @param s Descriptor identifying a connected socket. 01302 * 01303 * @param name Structure that receives the name (address) of the peer. 01304 * 01305 * @param namelen Pointer to the size of the @c name structure. 01306 * 01307 * 01308 * @return This function returns: 01309 * - @ref FNET_OK if no error occurs. 01310 * - @ref FNET_ERR if an error occurs. @n 01311 * The specific error code can be retrieved using the @ref fnet_error_get(). 01312 * 01313 * @see fnet_socket_getname() 01314 * 01315 ****************************************************************************** 01316 * 01317 * This function retrieves the name of the peer connected to the socket @c s 01318 * and stores it in the @ref sockaddr structure identified by @c name.@n 01319 * The @ref fnet_socket_getpeername() function can be used only with a connected socket. 01320 * For datagram sockets, only the name of a peer specified in a previous 01321 * @ref fnet_socket_connect() call will be returned - any name specified by a previous 01322 * @ref fnet_socket_sendto() call will not be returned by the @ref fnet_socket_getpeername(). 01323 * 01324 ******************************************************************************/ 01325 fnet_return_t fnet_socket_getpeername( fnet_socket_t s, struct sockaddr *name, fnet_size_t *namelen ); 01326 01327 /***************************************************************************/ /*! 01328 * 01329 * @brief Retrieves the current name for the specified socket. 01330 * 01331 * 01332 * @param s Descriptor identifying a socket. 01333 * 01334 * @param name Structure that receives the name (address) of the 01335 * socket @c s. 01336 * 01337 * @param namelen Pointer to the size of the @c name structure. 01338 * 01339 * 01340 * @return This function returns: 01341 * - @ref FNET_OK if no error occurs. 01342 * - @ref FNET_ERR if an error occurs. @n 01343 * The specific error code can be retrieved using the @ref fnet_error_get(). 01344 * 01345 * @see fnet_socket_getpeername() 01346 * 01347 ****************************************************************************** 01348 * 01349 * This function retrieves the current name for the specified socket @c s 01350 * and stores it in the @c name.@n 01351 * It is used on a bound or connected socket. 01352 * 01353 ******************************************************************************/ 01354 fnet_return_t fnet_socket_getname( fnet_socket_t s, struct sockaddr *name, fnet_size_t *namelen ); 01355 01356 /***************************************************************************/ /*! 01357 * 01358 * @brief Compares socket addresses. 01359 * 01360 * @param addr1 First socket address to be compared. 01361 * 01362 * @param addr2 Second socket address to be compared. 01363 * 01364 * @return This function returns: 01365 * - @ref FNET_TRUE if addresses are equal. 01366 * - @ref FNET_FALSE if addresses are not equal. 01367 * 01368 ****************************************************************************** 01369 * 01370 * This function compares specified socket addresses, depending on address family. @n 01371 * Port number and Scope Id do not take part in process of comparison. 01372 * 01373 ******************************************************************************/ 01374 fnet_bool_t fnet_socket_addr_are_equal(const struct sockaddr *addr1, const struct sockaddr *addr2); 01375 01376 /***************************************************************************/ /*! 01377 * 01378 * @brief Determines, if socket address is unspecified. 01379 * 01380 * @param addr Socket address. 01381 * 01382 * @return This function returns: 01383 * - @c FNET_TRUE if the address is unspecified. 01384 * - @c FNET_FALSE if the address is specified. 01385 * 01386 ****************************************************************************** 01387 * 01388 * This function determines if the socket address is unspecified 01389 * (IP address is set to all zeros) or not. 01390 * 01391 ******************************************************************************/ 01392 fnet_bool_t fnet_socket_addr_is_unspecified(const struct sockaddr *addr); 01393 01394 /***************************************************************************/ /*! 01395 * 01396 * @brief Determines, if socket address is multicast. 01397 * 01398 * @param addr Socket address. 01399 * 01400 * @return This function returns: 01401 * - @c FNET_TRUE if the address is multicast. 01402 * - @c FNET_FALSE if the address is not multicast. 01403 * 01404 ****************************************************************************** 01405 * 01406 * This function determines if the socket address is multicast or not. 01407 * 01408 ******************************************************************************/ 01409 fnet_bool_t fnet_socket_addr_is_multicast(const struct sockaddr *addr); 01410 01411 #if FNET_CFG_SOCKET_CALLBACK_ON_RX || defined(__DOXYGEN__) 01412 /***************************************************************************/ /*! 01413 * 01414 * @brief Registers the "Socket Rx" event handler callback. 01415 * 01416 * @param callback Pointer to the event-handler callback function. 01417 * 01418 ****************************************************************************** 01419 * 01420 * This function registers the @c handler callback function for 01421 * the "Socket Rx" event.@n 01422 * This event occurs when the socket layer receives any packet for any existing socket. 01423 * It can be a packet with or without data-payload including ACK, FIN and SYN.@n 01424 * For example, it can be used to wake-up a sleeping RTOS application waiting for a network activity. 01425 * To stop the event handling, set @c callback parameter to zero value. 01426 * 01427 ******************************************************************************/ 01428 void fnet_socket_set_callback_on_rx( void(*callback)(void)); 01429 #endif 01430 01431 /* BSD Socket API names */ 01432 #if FNET_CFG_SOCKET_BSD_NAMES 01433 #define socket fnet_socket 01434 #define bind fnet_socket_bind 01435 #define listen fnet_socket_listen 01436 #define accept fnet_socket_accept 01437 #define connect fnet_socket_connect 01438 #define recv fnet_socket_recv 01439 #define recvfrom fnet_socket_recvfrom 01440 #define send fnet_socket_send 01441 #define sendto fnet_socket_sendto 01442 #define shutdown fnet_socket_shutdown 01443 #define closesocket fnet_socket_close 01444 #define setsockopt fnet_socket_setopt 01445 #define getsockopt fnet_socket_getopt 01446 #define getpeername fnet_socket_getpeername 01447 #define getsockname fnet_socket_getname 01448 #endif 01449 01450 #if defined(__cplusplus) 01451 } 01452 #endif 01453 01454 /*! @} */ 01455 01456 #endif /* _FNET_SOCKET_H_ */
Generated on Tue Jul 12 2022 14:23:48 by
1.7.2