/platform/FNET/fnet_stack/stack/fnet_socket.h
C Header | 1512 lines | 174 code | 58 blank | 1280 comment | 5 complexity | cf7ed5ddff4fe02eb8c9698813fbcdb5 MD5 | raw file
Possible License(s): GPL-3.0, LGPL-3.0
Large files files are truncated, but you can click here to view the full file
- /**************************************************************************
- *
- * Copyright 2011-2015 by Andrey Butok. FNET Community.
- * Copyright 2008-2010 by Andrey Butok. Freescale Semiconductor, Inc.
- * Copyright 2003 by Andrey Butok. Motorola SPS.
- *
- ***************************************************************************
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Lesser General Public License Version 3
- * or later (the "LGPL").
- *
- * As a special exception, the copyright holders of the FNET project give you
- * permission to link the FNET sources with independent modules to produce an
- * executable, regardless of the license terms of these independent modules,
- * and to copy and distribute the resulting executable under terms of your
- * choice, provided that you also meet, for each linked independent module,
- * the terms and conditions of the license of that module.
- * An independent module is a module which is not derived from or based
- * on this library.
- * If you modify the FNET sources, you may extend this exception
- * to your version of the FNET sources, but you are not obligated
- * to do so. If you do not wish to do so, delete this
- * exception statement from your version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- *
- * You should have received a copy of the GNU General Public License
- * and the GNU Lesser General Public License along with this program.
- * If not, see <http://www.gnu.org/licenses/>.
- *
- **********************************************************************/ /*!
- *
- * @file fnet_socket.h
- *
- * @author Andrey Butok
- *
- * @brief Socket API.
- *
- ***************************************************************************/
-
- #ifndef _FNET_SOCKET_H_
-
- #define _FNET_SOCKET_H_
-
- #include "fnet_ip.h"
- #include "fnet_ip6.h"
-
- /*! @addtogroup fnet_socket
- * The Socket Application Program Interface (API) defines the way, in which the
- * application program interacts with the TCP/IP stack. It has the
- * BSD-like, non-blocking socket interface that makes porting of existing network applications
- * to the FNET more convenient.@n
- * @n
- * The following table summarizes the supported socket API functions:
- * <table>
- * <caption>Socket functions</caption>
- * <tr class="fnet_td_grey">
- * <th ALIGN=CENTER>Category</th><th ALIGN=CENTER>Routine</th>
- * <th ALIGN=CENTER>Meaning</th><th ALIGN=CENTER>Server</th>
- * <th ALIGN=CENTER>Client</th><th ALIGN=CENTER>@ref SOCK_STREAM</th>
- * <th ALIGN=CENTER>@ref SOCK_DGRAM</th>
- * </tr>
- * <tr>
- * <td>setup</td><td>@ref socket()</td><td>Creates a new unnamed socket within
- * a specified communication domain family.</td><td>X</td><td>X</td><td>X</td>
- * <td>X</td>
- * </tr>
- * <tr>
- * <td>setup</td><td>@ref bind()</td><td>Assigns a local address to
- * a socket.</td><td>X</td><td>X</td><td>X</td><td>X</td>
- * </tr>
- * <tr>
- * <td>server</td><td>@ref listen()</td><td> Prepares a socket to accept
- * the incoming connections.</td><td>X</td><td>@n</td><td>X</td><td>@n</td>
- * </tr>
- * <tr>
- * <td>server</td><td>@ref accept()</td><td>Accepts the connections.</td>
- * <td>X</td><td>@n</td><td>X</td><td>@n</td>
- * </tr>
- * <tr>
- * <td>client</td><td>@ref connect()</td><td> Establishes a connection to
- * a foreign socket.</td><td>@n</td><td>X</td><td>X</td><td>X</td>
- * </tr>
- * <tr>
- * <td>input</td><td>@ref recv()</td><td>Receives the data.</td><td>X</td>
- * <td>X</td><td>X</td><td>X</td>
- * </tr>
- * <tr>
- * <td>input</td><td>@ref recvfrom()</td><td>Receives the data and address of
- * the sender.</td><td>X</td><td>X</td><td>@n</td><td>X</td>
- * </tr>
- * <tr>
- * <td>output</td><td>@ref send()</td><td>Sends the data.</td><td>X</td>
- * <td>X</td><td>X</td><td>X</td>
- * </tr>
- * <tr>
- * <td>output</td><td>@ref sendto()</td><td>Sends the data to a specified
- * address.</td><td>X</td><td>X</td><td>@n</td><td>X</td>
- * </tr>
- * <tr>
- * <td>termination</td><td>@ref shutdown()</td><td>Terminates a connection
- * in one or both directions.</td><td>X</td><td>X</td><td>X</td><td>X</td>
- * </tr>
- * <tr>
- * <td>termination</td><td>@ref closesocket()</td><td>Terminates a connection
- * and releases the socket.</td><td>X</td><td>X</td><td>X</td><td>X</td>
- * </tr>
- * <tr>
- * <td>administration</td><td>@ref setsockopt()</td><td>Sets socket or protocol
- * options.</td><td>X</td><td>X</td><td>X</td><td>X</td>
- * </tr>
- * <tr>
- * <td>administration</td><td>@ref getsockopt()</td><td>Gets socket or protocol
- * options.</td><td>X</td><td>X</td><td>X</td><td>X</td>
- * </tr>
- * <tr>
- * <td>administration</td><td>@ref getsockname()</td><td>Gets a local address
- * assigned to a socket.</td><td>X</td><td>X</td><td>X</td><td>X</td>
- * </tr>
- * <tr>
- * <td>administration</td><td>@ref getpeername()</td><td>Gets a foreign address
- * assigned to a socket.</td><td>X</td><td>X</td><td>X</td><td>X</td>
- * </tr>
- * </table>
- * Configuration parameters:
- * - @ref FNET_CFG_SOCKET_MAX
- * - @ref FNET_CFG_SOCKET_TCP_TX_BUF_SIZE
- * - @ref FNET_CFG_SOCKET_TCP_RX_BUF_SIZE
- * - @ref FNET_CFG_SOCKET_UDP_TX_BUF_SIZE
- * - @ref FNET_CFG_SOCKET_UDP_RX_BUF_SIZE
- * - @ref FNET_CFG_SOCKET_TCP_MSS
- * - @ref FNET_CFG_RAW
- */
- /*! @{ */
-
-
- /* Special addresses */
-
- /**************************************************************************/ /*!
- * @brief It means to use any network interface.
- ******************************************************************************/
- #define INADDR_ANY (unsigned long)(0x00000000U)
-
- /**************************************************************************/ /*!
- * @brief Broadcast address. @n
- * It can be used to send the broadcast UDP datagrams over an IP network.
- ******************************************************************************/
- #define INADDR_BROADCAST (unsigned long)(0xffffffffU)
-
- /**************************************************************************/ /*!
- * @brief Address family type.
- * @see AF_UNSPEC, AF_INET, AF_INET6, AF_SUPPORTED
- ******************************************************************************/
- typedef unsigned short fnet_address_family_t;
-
- /**************************************************************************/ /*!
- * @brief Unspecified address family.
- ******************************************************************************/
- #define AF_UNSPEC (0U)
- /**************************************************************************/ /*!
- * @brief IPv4 address family.
- ******************************************************************************/
- #define AF_INET (1U)
- /**************************************************************************/ /*!
- * @brief IPv6 address family.
- ******************************************************************************/
- #define AF_INET6 (2U)
- /**************************************************************************/ /*!
- * @brief Bitmask of supported address families.
- * @showinitializer
- ******************************************************************************/
- #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)))
-
-
- /* Size of sa_data[]*/
- #if FNET_CFG_IP6
- #define FNET_SA_DATA_SIZE (20U) /* To cover sockaddr_in and sockaddr_in6. */
- #else /* IPv4 */
- #define FNET_SA_DATA_SIZE (4U)
- #endif
-
- /**************************************************************************/ /*!
- * @def FNET_IP_ADDR_STR_SIZE
- * @brief Size of the string buffer that will contain
- * null-terminated ASCII string of an IP address. It depends on
- * if disabled or enabled IPv6.
- * @see fnet_inet_ntoa, fnet_inet_ntop
- * @showinitializer
- ******************************************************************************/
- #if FNET_CFG_IP6
- #define FNET_IP_ADDR_STR_SIZE FNET_IP6_ADDR_STR_SIZE
- #else /* IPv4 */
- #define FNET_IP_ADDR_STR_SIZE FNET_IP4_ADDR_STR_SIZE
- #endif
-
- /**************************************************************************/ /*!
- * @brief Socket address structure.
- *
- * @see sockaddr_in, sockaddr_in6
- *
- * The original goal of the @ref sockaddr structure is to support multiple
- * protocols. For the TCP/IP stack @c sa_data, it contains a destination address
- * and port number for a socket.
- ******************************************************************************/
- struct sockaddr
- {
- fnet_address_family_t sa_family;/**< @brief Address family. Specifies the
- * address family, to which the address belongs. @n
- * It is defined by @ref fnet_address_family_t.
- */
- unsigned short sa_port; /**< @brief 16-bit port number used to
- * demultiplex the transport-level messages
- * (in network byte order).
- */
- char sa_data[FNET_SA_DATA_SIZE];/**< @brief Address value. For the TCP/IP stack,
- * it contains the destination address and port
- * number for a socket.
- */
- };
-
- /**************************************************************************/ /*!
- * @brief IPv4 address structure.
- *
- * @see sockaddr_in
- *
- * Actually, it represents an IPv4 address (in network endian).
- ******************************************************************************/
- struct in_addr
- {
- fnet_ip4_addr_t s_addr; /**< @brief 32-bit IPv4 address (in network byte order).
- */
- };
-
- /**************************************************************************/ /*!
- * @brief IPv4 Socket address structure.
- *
- * @see sockaddr
- *
- * To make manipulation of the @ref sockaddr structure easier, the TCP/IPv4 stack
- * also defines the equivalent structure @ref sockaddr_in
- * ("in" means "Internet").
- ******************************************************************************/
- struct sockaddr_in
- {
- fnet_address_family_t sin_family; /**< @brief Specifies the address family. @n
- * It must ne set to @ref AF_INET.
- */
- unsigned short sin_port; /**< @brief 16-bit port number used to
- * demultiplex the transport-level messages
- * (in network byte order).
- */
- struct in_addr sin_addr; /**< @brief 32-bit internet address.
- */
- };
-
-
- /************************************************************************
- * IPv6
- *************************************************************************/
-
-
- /**************************************************************************/ /*!
- * @brief IPv6 address structure.
- *
- * @see sockaddr_in6
- *
- * Actually, it represents an IPv6 address.
- ******************************************************************************/
- struct in6_addr
- {
- fnet_ip6_addr_t s6_addr; /**< @brief 128-bit IPv6 address.*/
- };
-
- /**************************************************************************/ /*!
- * @brief IPv6 Socket address structure.
- *
- * @see sockaddr
- *
- * To make manipulation of the @ref sockaddr structure easier, the TCP/IPv6 stack
- * also defines the equivalent structure @ref sockaddr_in6
- * ("in" means "Internet").
- ******************************************************************************/
- struct sockaddr_in6
- {
- fnet_address_family_t sin6_family; /**< @brief Specifies the address family. @n
- * It must ne set to @ref AF_INET6.
- */
- unsigned short sin6_port; /**< @brief 16-bit port number used to
- * demultiplex the transport-level messages
- * (in network byte order).
- */
- struct in6_addr sin6_addr; /**< @brief 128-bit IPv6 internet address.
- */
- unsigned long sin6_scope_id; /**< @brief Scope zone index, defining network interface.
- */
- };
-
- /**************************************************************************/ /*!
- * @brief IPv4 multicast group information.
- *
- * The structure is used with the @ref IP_ADD_MEMBERSHIP and
- * @ref IP_DROP_MEMBERSHIP socket options.
- *
- * @see IP_ADD_MEMBERSHIP, IP_DROP_MEMBERSHIP
- *
- ******************************************************************************/
- struct ip_mreq
- {
- struct in_addr imr_multiaddr; /**< @brief IPv4 multicast address of group. */
- struct in_addr imr_interface; /**< @brief Local IPv4 address of interface on which
- * the multicast group should be joined or dropped.@n
- * If this member specifies an IPv4 address of 0.0.0.0
- * or @ref INADDR_ANY,
- * the default interface is used. */
- };
-
- /**************************************************************************/ /*!
- * @brief IPv6 multicast group information.
- *
- * The structure is used with the @ref IPV6_JOIN_GROUP and
- * @ref IPV6_LEAVE_GROUP socket options.
- *
- * @see IPV6_JOIN_GROUP, IPV6_LEAVE_GROUP
- *
- ******************************************************************************/
- struct ipv6_mreq
- {
- struct in6_addr ipv6imr_multiaddr; /**< @brief IPv6 multicast address of group. */
- unsigned int ipv6imr_interface; /**< @brief Interface index. It equals to the scope zone index, defining network interface.@n
- * If this member is zero, the default interface is used. */
- };
-
- /**************************************************************************/ /*!
- * @brief Socket types.
- ******************************************************************************/
- typedef enum
- {
- SOCK_UNSPEC = (0U), /**< @brief Unspecified socket type.
- */
- SOCK_STREAM = (1U), /**< @brief Stream socket.@n
- * Provides reliable, two-way, connection-based
- * byte stream. It corresponds to the TCP protocol
- */
- SOCK_DGRAM = (2U), /**< @brief Datagram socket.@n
- * Provides unreliable, connectionless datagrams.
- * It corresponds to the UDP protocol.
- */
- SOCK_RAW = (3U) /**< @brief Raw socket.@n
- * Raw sockets allow an application to have direct access to
- * lower-level communication protocols.
- * Raw sockets are intended to take advantage of some protocol feature
- * that is not directly accessible through a normal interface,
- * or to build new protocols on top of existing low-level protocols.@n
- * It can be enabled by the @ref FNET_CFG_RAW option.
- */
- } fnet_socket_type_t;
-
- /**************************************************************************/ /*!
- * @brief Socket state.
- ******************************************************************************/
- typedef enum
- {
- SS_UNCONNECTED = (0), /**< @brief Not connected to any socket.
- */
- SS_CONNECTING = (1), /**< @brief In process of connecting.
- */
- SS_CONNECTED = (2), /**< @brief Connected to a socket.
- */
- SS_LISTENING = (3) /**< @brief In listening state.
- */
- } fnet_socket_state_t;
-
- /**************************************************************************/ /*!
- * @brief Protocol numbers and Level numbers for the @ref setsockopt()
- * and the @ref getsockopt().
- ******************************************************************************/
- typedef enum
- {
- IPPROTO_IP = (0), /**< @brief IPv4 options level number
- * for @ref getsockopt() and @ref setsockopt().
- */
- IPPROTO_ICMP = (1), /**< @brief ICMPv4 protocol number.
- */
- IPPROTO_IGMP = (2), /**< @brief IGMP protocol number.
- */
- IPPROTO_TCP = (6), /**< @brief TCP protocol number; TCP options level number
- * for @ref getsockopt() and @ref setsockopt().
- */
- IPPROTO_UDP = (17),/**< @brief UDP protocol number.
- */
- IPPROTO_IPV6 = (41), /**< @brief IPv6 options level number
- * for @ref getsockopt() and @ref setsockopt().
- */
- IPPROTO_ICMPV6 = (58),/**< @brief ICMPv6 protocol number.
- */
- SOL_SOCKET = (255255) /**< @brief Socket options level number for
- * @ref getsockopt() and @ref setsockopt().
- */
- } fnet_protocol_t;
-
- /**************************************************************************/ /*!
- * @brief Socket level (@ref SOL_SOCKET) options for the @ref setsockopt() and the @ref getsockopt().
- *
- * <table>
- *<caption>Socket SOL_SOCKET level options</caption>
- *<tr class="fnet_td_grey">
- *<th ALIGN=CENTER>Option</th><th ALIGN=CENTER>Option Type</th><th ALIGN=CENTER>
- * Default Value</th><th ALIGN=CENTER>Read/Write</th>
- *</tr>
- *<tr>
- *<td>@ref SO_ACCEPTCONN</td><td>int</td><td>0</td><td>R</td>
- *</tr>
- *<tr>
- *<td>@ref SO_KEEPALIVE</td><td>int</td><td>1</td><td>RW</td>
- *</tr>
- *<tr>
- *<td>@ref SO_DONTROUTE</td><td>int</td><td>0</td><td>RW</td>
- *</tr>
- *<tr>
- *<td>@ref SO_LINGER</td><td>struct @ref linger</td><td>{0,0}</td><td>RW</td>
- *</tr>
- *<tr>
- *<td>@ref SO_OOBINLINE</td><td>int</td><td>0</td><td>RW</td>
- *</tr>
- *<tr>
- *<td>@ref SO_SNDBUF</td><td>unsigned long</td>
- *<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>
- *</tr>
- *<tr>
- *<td>@ref SO_RCVBUF</td><td>unsigned long</td>
- *<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>
- *</tr>
- *<tr>
- *<td>@ref SO_STATE</td><td>@ref fnet_socket_state_t</td><td>@ref SS_UNCONNECTED</td><td>R</td>
- *</tr>
- *<tr>
- *<td>@ref SO_ERROR</td><td>@ref fnet_error_t</td><td>@ref FNET_ERR_OK</td><td>R</td>
- *</tr>
- *<tr>
- *<td>@ref SO_TYPE</td><td>@ref fnet_socket_type_t</td><td>@ref SOCK_DGRAM for
- * UDP @n @ref SOCK_STREAM for TCP</td><td>R</td>
- *</tr>
- *<tr>
- *<td>@ref SO_RCVNUM</td><td>unsigned long</td><td>0</td><td>R</td>
- *</tr>
- *<tr>
- *<td>@ref SO_SNDNUM</td><td>unsigned long</td><td>0</td><td>R</td>
- *</tr>
- *</table>
- ******************************************************************************/
- typedef enum
- {
- SO_ACCEPTCONN = (1), /**< @brief Returns @c 1 if a socket is in
- * listening mode and returns @c 0 when vice versa.
- * This is the read-only option and it is
- * valid only for connection-oriented protocols (TCP).
- */
- SO_KEEPALIVE = (2), /**< @brief This option enables keep-alive probes
- * for a socket connection. These probes are used
- * to maintain a TCP connection and regularly
- * test the connection to ensure that it's
- * still available. It is only valid for
- * connection-oriented protocols (TCP).
- */
- SO_DONTROUTE = (4), /**< @brief This option enables bypassing of a routing algorithm.
- * It means that the network interface tries to send a datagram without
- * a gateway.
- */
- SO_LINGER = (8), /**< @brief This option controls the action
- * taken when unsent data is present, and
- * @ref closesocket() is called. This option
- * is defined by the @ref linger structure.
- */
- #if FNET_CFG_TCP_URGENT || defined(__DOXYGEN__)
- SO_OOBINLINE = (10), /**< @brief This option specifies that out-of-band (OOB)
- * data will be received in line with regular data.
- * It is valid only for the TCP protocol. @n
- * This option is avalable only if
- * @ref FNET_CFG_TCP_URGENT is set to @c 1.
- */
- #endif /* FNET_CFG_TCP_URGENT */
- SO_SNDBUF = (1001), /**< @brief This option defines the maximum per-socket
- * buffer size for output data.
- */
- SO_RCVBUF = (1002), /**< @brief This option defines the maximum per-socket
- * buffer size for input data.
- */
- SO_STATE = (1003), /**< @brief This option defines the current state of the socket.@n
- * This is the read-only option and it is defined by the @ref fnet_socket_state_t type.
- */
- SO_ERROR = (1006), /**< @brief This option returns a per-socket-based error code.@n
- * The error code is defined by the @ref fnet_error_t type.@n
- * After the error value has been read in the @ref getsockopt function, it is cleared.
- * But a successful call using the socket routines does not clear
- * the socket-based error.
- */
- SO_TYPE = (1007), /**< @brief This option defines the type of the socket.
- * This is a read-only option and it is defined by the @ref fnet_socket_type_t type.
- */
- SO_RCVNUM = (1008), /**< @brief This option is used to determine the amount of data
- * pending in the socket-input buffer.@n
- * This is a read-only option.
- */
- SO_SNDNUM = (1009) /**< @brief This option is used to determine the amount of data
- * in the socket output buffer. @n
- * This is a read-only option.
- */
- } fnet_socket_options_t;
-
-
- /**************************************************************************/ /*!
- * @brief TCP level (@ref IPPROTO_TCP) options for the @ref setsockopt()
- * and the @ref getsockopt().
- *
- * <table>
- *<caption>Socket IPPROTO_TCP level options</caption>
- *<tr class="fnet_td_grey">
- *<th ALIGN=CENTER>Option</th><th ALIGN=CENTER>Option Type</th><th ALIGN=CENTER>
- * Default Value</th><th ALIGN=CENTER>Read/Write</th>
- *</tr>
- *<tr>
- *<td>@ref TCP_MSS</td><td>unsigned short</td><td>536</td><td>RW</td>
- *</tr>
- *<tr>
- *<td>@ref TCP_BSD</td><td>int</td><td>1</td><td>RW</td>
- *</tr>
- *<tr>
- *<td>@ref TCP_NODELAY</td><td>int</td><td>1</td><td>RW</td>
- *</tr>
- *<tr>
- *<td>@ref TCP_FINRCVD</td><td>int</td><td>0</td><td>R</td>
- *</tr>
- *<tr>
- *<td>@ref TCP_URGRCVD</td><td>int</td><td>0</td><td>R</td>
- *</tr>
- *<tr>
- *<td>@ref TCP_KEEPIDLE</td><td>int</td><td>7200</td><td>RW</td>
- *</tr>
- *<tr>
- *<td>@ref TCP_KEEPINTVL</td><td>int</td><td>75</td><td>RW</td>
- *</tr>
- *<tr>
- *<td>@ref TCP_KEEPCNT</td><td>int</td><td>8</td><td>RW</td>
- *</tr>
- *</table>
- ******************************************************************************/
- typedef enum
- {
- TCP_MSS = (0x01), /**< @brief This option defines the maximum size of
- * the input segments (MSS). @n
- * The TCP Maximum Segment Size (MSS) defines the maximum amount
- * of data that a host is willing to accept in a single TCP segment.@n
- * This Maximum Segment Size (MSS) announcement is sent from the
- * data receiver to the data sender and says "I can accept TCP segments
- * up to size X". The size (X) may be larger or smaller than the
- * default.@n
- * The MSS counts only data octets in the segment, it does not count the
- * TCP header or the IP header.@n
- * The default value is defined by the @ref FNET_CFG_SOCKET_TCP_MSS
- * user-configuration option. @n
- * This option can be set to:
- * - @c 0 = The selection of the MSS is
- * automatic and is based on the MTU of the outgoing
- * interface minus 40 (does not include
- * the 20 byte IP header and the 20 byte TCP header).@n
- * It is done to assist in avoiding of IP fragmentation
- * at the endpoints of the TCP connection.
- * - Non-zero value (up to 64K) = The TCP segment could be as large as 64K
- * (the maximum IP datagram size), but it could be fragmented
- * at the IP layer in order to be transmitted
- * across the network to the receiving host.
- */
- #if FNET_CFG_TCP_URGENT || defined(__DOXYGEN__)
- TCP_BSD = (0x02), /**< @brief If this option is set to @c 1, the BSD interpretation of
- * the urgent pointer is used. In this case the
- * urgent pointer of the TCP segment points to
- * the next byte following after the urgent byte.
- * Most of the TCP implementations use this
- * interpretation by default.@n
- * If this option is set to @c 0, the interpretation of
- * the TCP specification is used. In this case the
- * urgent pointer of the TCP segment points
- * to the urgent byte. @n
- * This option is avalable only if
- * @ref FNET_CFG_TCP_URGENT is set to @c 1.
- */
- #endif
- TCP_NODELAY = (0x04), /**< @brief If this option is set to @c 1, the Nagle algorithm
- * is disabled (and vice versa). @n
- * The Nagle algorithm is effective in reducing the number
- * of small packets sent by the host by essentially buffering
- * send data, if there is unacknowledged data already "in flight",
- * or until a full-size packet can be sent.@n
- * But for some applications this algorithm can impede
- * performance, especially for a bulky data transfer.
- */
- TCP_FINRCVD = (0x08), /**< @brief This option is set when the final (FIN) segment arrives. @n
- * This option indicates that another side will not send any data
- * in the current connection.@n
- * This is the read-only option.
- */
- #if FNET_CFG_TCP_URGENT || defined(__DOXYGEN__)
- TCP_URGRCVD = (0x10), /**< @brief This option is set when the urgent byte arrives, and
- * reset when this byte is read.@n
- * This option can be set only if the @ref SO_OOBINLINE option is set to @c 0.@n
- * This is the read-only option. @n
- * This option is avalable only if
- * @ref FNET_CFG_TCP_URGENT is set to @c 1.
- */
- #endif
- TCP_KEEPIDLE = (0x20), /**< @brief When the @ref SO_KEEPALIVE option is enabled, TCP probes a connection that
- * has been idle for some amount of time. The default value for this idle
- * period is @c 7200 seconds (2 hours). The @ref TCP_KEEPIDLE option can be used to affect this
- * value for a given socket, and specifies the number of seconds of idle
- * time between keepalive probes.
- */
- TCP_KEEPINTVL = (0x40), /**< @brief When the @ref SO_KEEPALIVE option is enabled, TCP probes a connection that
- * has been idle for some amount of time. If the remote system does not
- * respond to a keepalive probe, TCP retransmits the probe after some
- * amount of time. The default value for this retransmit interval is @c 75
- * seconds. The @ref TCP_KEEPINTVL option can be used to affect this value for
- * a given socket, and specifies the number of seconds to wait before
- * retransmitting a keepalive probe.
- */
- TCP_KEEPCNT = (0x80) /**< @brief When the @ref SO_KEEPALIVE option is enabled, TCP probes a connection that
- * has been idle for some amount of time. If the remote system does not
- * respond to a keepalive probe, TCP retransmits the probe a certain
- * number of times before a connection is considered to be broken. The
- * default value for this keepalive probe retransmit limit is @c 8. The
- * @ref TCP_KEEPCNT option can be used to affect this value for a given socket,
- * and specifies the maximum number of keepalive probes to be sent.
- */
- } fnet_tcp_options_t;
-
- /**************************************************************************/ /*!
- * @brief IPv4 level (@ref IPPROTO_IP) options for the @ref setsockopt() and
- * the @ref getsockopt().
- *
- * <table>
- *<caption>Socket IPPROTO_IP level options</caption>
- *<tr class="fnet_td_grey">
- *<th ALIGN=CENTER>Option</th><th ALIGN=CENTER>Option Type</th><th ALIGN=CENTER>
- * Default Value</th><th ALIGN=CENTER>Read/Write</th>
- *</tr>
- *<tr>
- *<td>@ref IP_TOS</td><td>int</td><td>0</td><td>RW</td>
- *</tr>
- *<tr>
- *<td>@ref IP_TTL</td><td>int</td><td>64</td><td>RW</td>
- *</tr>
- *<tr>
- *<td>@ref IP_MULTICAST_TTL</td><td>int</td><td>1</td><td>RW</td>
- *</tr>
- *<tr>
- *<td>@ref IP_ADD_MEMBERSHIP</td><td>@ref ip_mreq</td><td>N/A</td><td>W</td>
- *</tr>
- *<tr>
- *<td>@ref IP_DROP_MEMBERSHIP</td><td>@ref ip_mreq</td><td>N/A</td><td>W</td>
- *</tr>
- *</table>
- ******************************************************************************/
- typedef enum
- {
- IP_TOS = (3), /**< @brief This option defines the IPv4 TOS
- * (type-of-service) field for outgoing datagrams.
- */
- IP_TTL = (4) /**< @brief This option defines the IPv4 TTL
- * (time-to-live) vlaue for outgoing datagrams.
- */
- #if FNET_CFG_MULTICAST || defined(__DOXYGEN__)
- ,
- IP_MULTICAST_TTL = (6), /**< @brief This option allows to change IPv4 "time to live" (TTL)
- * value for outgoing multicast datagrams.
- * Otherwise, multicast datagrams are sent with a default value of 1,
- * to prevent them to be forwarded beyond the local network.@n
- * This option is available only if @ref FNET_CFG_MULTICAST is set to @c 1.
- */
- IP_ADD_MEMBERSHIP = (7), /**< @brief Join the socket to the IPv4 multicast group on
- * the specified interface. It tells the system to receive packets on
- * the network whose destination is the group address (but not its own).
- * It is valid only for the SOCK_DGRAM (UDP) sockets.@n
- * This option is available only if @ref FNET_CFG_MULTICAST is set to @c 1.
- */
- IP_DROP_MEMBERSHIP = (8) /**< @brief Drops membership to a IPv4 multicast group and interface.@n
- * This option is available only if @ref FNET_CFG_MULTICAST is set to @c 1.
- */
- #endif /* FNET_CFG_MULTICAST */
- } fnet_ip_options_t;
-
- /**************************************************************************/ /*!
- * @brief IPv6 level (@ref IPPROTO_IPV6) options (RFC3493) for the @ref setsockopt()
- * and the @ref getsockopt().
- *
- * <table>
- *<caption>Socket IPPROTO_IPV6 level options</caption>
- *<tr class="fnet_td_grey">
- *<th ALIGN=CENTER>Option</th><th ALIGN=CENTER>Option Type</th><th ALIGN=CENTER>
- * Default Value</th><th ALIGN=CENTER>Read/Write</th>
- *</tr>
- *<tr>
- *<td>@ref IPV6_UNICAST_HOPS</td><td>int</td><td>0 (64)</td><td>RW</td>
- *</tr>
- *<tr>
- *<td>@ref IPV6_MULTICAST_HOPS</td><td>int</td><td>1</td><td>RW</td>
- *</tr>
- *<tr>
- *<td>@ref IPV6_JOIN_GROUP</td><td>@ref ipv6_mreq</td><td>N/A</td><td>W</td>
- *</tr>
- *<tr>
- *<td>@ref IPV6_LEAVE_GROUP</td><td>@ref ipv6_mreq</td><td>N/A</td><td>W</td>
- *</tr>
- *</table>
- ******************************************************************************/
- typedef enum
- {
- IPV6_UNICAST_HOPS = (4) /**< @brief This option defines hop limit used
- * for outgoing unicast IPv6 packets. @n
- * Its value can be from 0 till 255.@n
- * By default the option is set to 0. It means that the hop limit is defined
- * by local IPv6 router, otherwise it equals to 64.
- */
- ,IPV6_MULTICAST_HOPS = (5) /**< @brief Set the hop limit to use for outgoing multicast IPv6 packets.@n
- * If IPV6_MULTICAST_HOPS is not set, the default is 1.
- */
- ,IPV6_JOIN_GROUP = (6) /**< @brief (RFC3493) Join a multicast group on a specified local interface.@n
- * It is valid only for the SOCK_DGRAM (UDP) sockets.
- */
- ,IPV6_LEAVE_GROUP = (7) /**< @brief (RFC3493) Leave a multicast group on a specified interface.@n
- * It is valid only for the SOCK_DGRAM (UDP) sockets.
- */
-
- } fnet_ip6_options_t;
-
- /**************************************************************************/ /*!
- * @brief This structure is used for the @ref SO_LINGER option.
- ******************************************************************************/
- struct linger
- {
- unsigned short l_onoff; /**< @brief Determines, whether the option will be
- * turned on @c 1, or off @c 0.
- */
- unsigned short l_linger; /**< @brief Specifies the amount of time (in seconds)
- * to wait when the connection is closed and unsent data
- * is discarded.
- * If @c l_onoff is @c 0, the @c l_linger value is ignored
- * and the stack continues to try to send the data as usually.
- */
- };
-
- /**************************************************************************/ /*!
- * @brief Socket descriptor.
- ******************************************************************************/
- typedef int SOCKET;
-
- #define SOCKET_INVALID (FNET_ERR) /**< @brief Invalid socket. @n
- * This is the return value of the @ref
- * socket() and @ref accept() functions
- * if an error occurs.
- */
- #define SOCKET_ERROR (FNET_ERR) /**< @brief Socket error.@n
- * This is the return value of
- * the socket API functions if an error occurs.
- */
-
- /**************************************************************************/ /*!
- * @brief The flags parameters for receiving and sending functions
- * @ref recv(), @ref recvfrom(), @ref send(), and @ref sendto().
- *
- * The optional flag specifies the way, in which the call is made.
- * It can be constructed by using the bitwise OR.
- ******************************************************************************/
- typedef enum
- {
- #if FNET_CFG_TCP_URGENT || defined(__DOXYGEN__)
- MSG_OOB = (0x1U), /**< @brief Process out-of-band
- * data instead of regular data. @n
- * This option is avalable only if
- * @ref FNET_CFG_TCP_URGENT is set to @c 1.
- */
- #endif /* FNET_CFG_TCP_URGENT */
- MSG_PEEK = (0x2U), /**< @brief Receive a copy of the
- * data without consuming it.
- */
- MSG_DONTROUTE = (0x4U) /**< @brief Send without using
- * routing tables.
- */
- } fnet_flags_t;
-
- /**************************************************************************/ /*!
- * @brief The flags used by @ref shutdown().
- *
- * They describe what types of socket operation will no longer be allowed.
- ******************************************************************************/
- typedef enum
- {
- SD_READ = (0x1U), /**< @brief Data receiving is disabled.
- */
- SD_WRITE = (0x2U), /**< @brief Data sending is disabled.
- */
- SD_BOTH = (SD_READ | SD_WRITE) /**< @brief Both receiving and
- * sending are disabled.
- */
- } fnet_sd_flags_t;
-
-
- /***************************************************************************/ /*!
- *
- * @brief Creates a socket.
- *
- *
- * @param family Address family that the socket will use, defined
- * by the @ref fnet_address_family_t.
- *
- * @param type Type specification for the new socket, defined by @ref
- * fnet_socket_type_t. It can be @ref SOCK_STREAM (TCP) or
- * @ref SOCK_DGRAM (UDP).
- *
- * @param protocol Protocol to be used with the socket that is specific to
- * the indicated address family. This stack supports
- * @ref IPPROTO_TCP and @ref IPPROTO_UDP.@n
- * This parameter is optional, and can be set to zero, as
- * the @c type already defines the proper protocol.
- *
- * @return This function returns:
- * - Socket descriptor referencing the new socket, if no error occurs.
- * - @ref SOCKET_INVALID if an error occurs. @n
- * The specific error code can be retrieved using the @ref fnet_error_get().
- *
- * @see closesocket()
- *
- ******************************************************************************
- *
- * This function creates a socket and returns its descriptor.@n
- * The @ref socket() function causes a socket descriptor and any related
- * resources to be allocated and bound to a specific transport-service
- * provider that supports the requested combination of address family,
- * socket type, and protocol parameters.@n
- * @n
- * After a socket is created:
- * - Connection-oriented sockets, such as the @ref SOCK_STREAM, provide
- * full-duplex connections. Before any data can be sent or received,
- * it must be in a connected state . A connection to
- * another socket is established with the @ref connect() call.
- * Once connected, the data can be transferred using the @ref send() and the @ref
- * recv() calls. When a session has been completed, the @ref closesocket()
- * must be performed.
- * - Connectionless, message-oriented sockets, such as the @ref SOCK_DGRAM, allow
- * sending and receiving of datagrams to and from arbitrary peers using
- * the @ref sendto() and the @ref recvfrom(). If such a socket is connected
- * to a specific peer, datagrams can be sent to that peer using the
- * @ref send(), and can be received only from this peer using the @ref recv().
- *
- ******************************************************************************/
- SOCKET socket( fnet_address_family_t family, fnet_socket_type_t type, int protocol );
-
- /***************************************************************************/ /*!
- *
- * @brief Assigns a local address to a socket.
- *
- *
- * @param s Descriptor, identifying a socket to bind.
- *
- * @param name The address to be assigned to the socket, from the @ref
- * sockaddr structure.
- *
- * @param namelen The length of the @c name parameter.
- * Normally @c namelen is set to @c sizeof(name).
- *
- * @return This function returns:
- * - @ref FNET_OK if no error occurs.
- * - @ref SOCKET_ERROR if an error occurs. @n
- * The specific error code can be retrieved using the @ref fnet_error_get().
- *
- * @see socket()
- *
- ******************************************************************************
- *
- * This function associates a local address with the socket.@n
- * The @ref bind() function is used on an unconnected socket before
- * subsequent calls to the @ref connect() or the @ref listen() functions.
- * It is used to bind to either connection-oriented (stream) or connectionless
- * (datagram) sockets.@n
- * Within the @ref sockaddr structure, the address may be the address assigned
- * to a network interface on the host or the @ref INADDR_ANY.
- * Using the @ref INADDR_ANY causes the stack to use the default network
- * interface address. Using a port number of 0 causes the service provider
- * to assign a unique port to the socket with a value between 1024 and 5000.
- *
- ******************************************************************************/
- int bind( SOCKET s, const struct sockaddr *name, unsigned int namelen );
-
- /***************************************************************************/ /*!
- *
- * @brief Places the socket into a state, where it is listening for
- * an incoming connection.
- *
- *
- * @param s Descriptor identifying a socket that will be
- * used for listening.
- *
- * @param backlog Maximum length of the queue of pending connections.
- *
- *
- * @return This function returns:
- * - @ref FNET_OK if no error occurs.
- * - @ref SOCKET_ERROR if an error occurs. @n
- * The specific error code can be retrieved using the @ref fnet_error_get().
- *
- * @see socket(), bind(), accept()
- *
- ******************************************************************************
- *
- * Only connection-oriented sockets (@ref SOCK_STREAM) are used with the
- * @ref listen().@n
- * The socket is put into passive mode, where the incoming connection
- * requests are acknowledged and queued pending acceptance by the listening socket.
- * The @ref listen() function is typically used by servers that can have
- * more than one connection request at a time. @n
- * An application can call @ref listen() more than once on the same socket.
- * If there are more pending connections than the new backlog value,
- * the excess pending connections will be reset and dropped.
- *
- ******************************************************************************/
- int listen( SOCKET s, int backlog );
-
- /***************************************************************************/ /*!
- *
- * @brief Accepts a connection on the specified socket.
- *
- *
- * @param s Descriptor, identifying an unconnected socket.
- *
- * @param addr Optional pointer to a buffer that receives the address
- * of the remote host at the other end of the connection.
- *
- * @param addrlen Optional pointer to an integer that contains the
- * length of the @c addr parameter.
- *
- *
- * @return This function returns:
- * - Socket descriptor referencing the new socket, if no error occurs.
- * - @ref SOCKET_INVALID if an error occurs. @n
- * The specific error code can be retrieved using @ref fnet_error_get().
- *
- * @see socket(), bind()
- *
- ******************************************************************************
- *
- * The function extracts the first connection in the queue of pending
- * connections on the listening socket @c s, and returns the new socket descriptor.@n
- * The newly-created socket is the socket that will handle the actual
- * connection and has the same properties as the socket @c s.
- * The original socket remains open and listens for new connection requests.
- * If no pending connections are present in the queue of the socket,
- * the @ref accept() returns an error and the specific error code is set to
- * @ref FNET_ERR_AGAIN.@n
- * The parameter @c addr is a result parameter that is filled in with the
- * address of the remote host. The @c addrlen should initially contain the
- * amount of space pointed to by the @c addr; on return it will contain the
- * actual length of the address returned (in bytes).@n
- * The @ref accept() function is used only with connection-oriented socket
- * types (@ref SOCK_STREAM).@n
- * If @c addr and/or @c addrlen are equal to @c 0, then no information
- * about the remote address of the accepted socket is returned.
- *
- ******************************************************************************/
- SOCKET accept( SOCKET s, struct sockaddr *addr, unsigned int *addrlen );
-
- /***************************************************************************/ /*!
- *
- * @brief Establishes a connection with the specified socket.
- *
- *
- * @param s Descriptor identifying an unconnected socket.
- *
- * @param name Address (name) of the socket, with which the connection
- * should be established.
- *
- * @param namelen Length of the @c name.
- *
- *
- * @return This function returns:
- * - @ref FNET_OK if no error occurs.
- * - @ref SOCKET_ERROR if an error occurs. @n
- * The specific error code can be retrieved using the @ref fnet_error_get().
- *
- * @see socket(), bind()
- *
- ******************************************************************************
- *
- * For connection-oriented sockets (@ref SOCK_STREAM), this function activates
- * an active connection with the foreign host.
- *
- * When the socket call completes successfully, the socket is ready to send
- * and receive data. Any attempt to reconnect the active connection will fail
- * with the error code @ref FNET_ERR_ISCONN. For connection-oriented
- * sockets, it is often not possible to complete the connection
- * immediately. Until the connection attempt
- * completes on a socket, all subsequent calls to @ref connect()
- * on the same socket will fail with the error code @ref FNET_ERR_INPROGRESS,
- * or succeed with @ref FNET_ERR_ISCONN when the connection completes successfully.
- * Use the @ref getsockopt() function to determine the completion of the
- * connection request by checking the @ref SO_STATE to see if the socket is
- * connected (@ref SS_CONNECTED), is still connecting (@ref SS_CONNECTING)
- * or the connection has failed (@ref SS_UNCONNECTED). @n
- * @n
- * For a connectionless socket (@ref SOCK_DGRAM), the operation performed
- * by @ref connect() is merely to establish a default destination address
- * that can be used on subsequent @ref send() and @ref recv() calls.
- * Any datagrams received from an address other than the destination address
- * specified will be discarded. The default destination can be changed by…
Large files files are truncated, but you can click here to view the full file