BA
/
SerialCom
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.
Fork of
OmniWheels
by 
Gustav Atmel
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 Fri Jul 22 2022 04:53:49 by
1.7.2