PageRenderTime 47ms CodeModel.GetById 16ms RepoModel.GetById 0ms app.codeStats 0ms

/platform/FNET/fnet_stack/stack/fnet_socket.h

https://gitlab.com/fuggles/ucos
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 
    

  1. /**************************************************************************

    2. 

  2. * 

    3. 

  3. * Copyright 2011-2015 by Andrey Butok. FNET Community.

    4. 

  4. * Copyright 2008-2010 by Andrey Butok. Freescale Semiconductor, Inc.

    5. 

  5. * Copyright 2003 by Andrey Butok. Motorola SPS.

    6. 

  6. *

    7. 

  7. ***************************************************************************

    8. 

  8. * This program is free software: you can redistribute it and/or modify

    9. 

  9. * it under the terms of the GNU Lesser General Public License Version 3 

    10. 

  10. * or later (the "LGPL").

    11. 

  11. *

    12. 

  12. * As a special exception, the copyright holders of the FNET project give you

    13. 

  13. * permission to link the FNET sources with independent modules to produce an

    14. 

  14. * executable, regardless of the license terms of these independent modules,

    15. 

  15. * and to copy and distribute the resulting executable under terms of your 

    16. 

  16. * choice, provided that you also meet, for each linked independent module,

    17. 

  17. * the terms and conditions of the license of that module.

    18. 

  18. * An independent module is a module which is not derived from or based 

    19. 

  19. * on this library. 

    20. 

  20. * If you modify the FNET sources, you may extend this exception 

    21. 

  21. * to your version of the FNET sources, but you are not obligated 

    22. 

  22. * to do so. If you do not wish to do so, delete this

    23. 

  23. * exception statement from your version.

    24. 

  24. *

    25. 

  25. * This program is distributed in the hope that it will be useful,

    26. 

  26. * but WITHOUT ANY WARRANTY; without even the implied warranty of

    27. 

  27. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

    28. 

  28. *

    29. 

  29. * You should have received a copy of the GNU General Public License

    30. 

  30. * and the GNU Lesser General Public License along with this program.

    31. 

  31. * If not, see <http://www.gnu.org/licenses/>.

    32. 

  32. *

    33. 

  33. **********************************************************************/ /*!

    34. 

  34. *

    35. 

  35. * @file fnet_socket.h

    36. 

  36. *

    37. 

  37. * @author Andrey Butok

    38. 

  38. *

    39. 

  39. * @brief Socket API.

    40. 

  40. *

    41. 

  41. ***************************************************************************/

    42. 

  42. 

    43. 

  43. #ifndef _FNET_SOCKET_H_

    44. 

  44. 

    45. 

  45. #define _FNET_SOCKET_H_

    46. 

  46. 

    47. 

  47. #include "fnet_ip.h"

    48. 

  48. #include "fnet_ip6.h"

    49. 

  49. 

    50. 

  50. /*! @addtogroup fnet_socket 

    51. 

  51. * The Socket Application Program Interface (API) defines the way, in which the 

    52. 

  52. * application program interacts with the TCP/IP stack. It has the 

    53. 

  53. * BSD-like, non-blocking socket interface that makes porting of existing network applications 

    54. 

  54. * to the FNET more convenient.@n

    55. 

  55. * @n

    56. 

  56. * The following table summarizes the supported socket API functions:

    57. 

  57. * <table>

    58. 

  58. * <caption>Socket functions</caption>

    59. 

  59. * <tr class="fnet_td_grey">

    60. 

  60. * <th ALIGN=CENTER>Category</th><th ALIGN=CENTER>Routine</th>

    61. 

  61. * <th ALIGN=CENTER>Meaning</th><th ALIGN=CENTER>Server</th>

    62. 

  62. * <th ALIGN=CENTER>Client</th><th ALIGN=CENTER>@ref SOCK_STREAM</th>

    63. 

  63. * <th ALIGN=CENTER>@ref SOCK_DGRAM</th>

    64. 

  64. * </tr>

    65. 

  65. * <tr>

    66. 

  66. * <td>setup</td><td>@ref socket()</td><td>Creates a new unnamed socket within 

    67. 

  67. * a specified communication domain family.</td><td>X</td><td>X</td><td>X</td>

    68. 

  68. * <td>X</td>

    69. 

  69. * </tr>

    70. 

  70. * <tr>

    71. 

  71. * <td>setup</td><td>@ref bind()</td><td>Assigns a local address to 

    72. 

  72. * a socket.</td><td>X</td><td>X</td><td>X</td><td>X</td>

    73. 

  73. * </tr>

    74. 

  74. * <tr>

    75. 

  75. * <td>server</td><td>@ref listen()</td><td> Prepares a socket to accept 

    76. 

  76. * the incoming connections.</td><td>X</td><td>@n</td><td>X</td><td>@n</td>

    77. 

  77. * </tr>

    78. 

  78. * <tr>

    79. 

  79. * <td>server</td><td>@ref accept()</td><td>Accepts the connections.</td>

    80. 

  80. * <td>X</td><td>@n</td><td>X</td><td>@n</td>

    81. 

  81. * </tr>

    82. 

  82. * <tr>

    83. 

  83. * <td>client</td><td>@ref connect()</td><td> Establishes a connection to 

    84. 

  84. * a foreign socket.</td><td>@n</td><td>X</td><td>X</td><td>X</td>

    85. 

  85. * </tr>

    86. 

  86. * <tr>

    87. 

  87. * <td>input</td><td>@ref recv()</td><td>Receives the data.</td><td>X</td>

    88. 

  88. * <td>X</td><td>X</td><td>X</td>

    89. 

  89. * </tr>

    90. 

  90. * <tr>

    91. 

  91. * <td>input</td><td>@ref recvfrom()</td><td>Receives the data and address of 

    92. 

  92. * the sender.</td><td>X</td><td>X</td><td>@n</td><td>X</td>

    93. 

  93. * </tr>

    94. 

  94. * <tr>

    95. 

  95. * <td>output</td><td>@ref send()</td><td>Sends the data.</td><td>X</td>

    96. 

  96. * <td>X</td><td>X</td><td>X</td>

    97. 

  97. * </tr>

    98. 

  98. * <tr>

    99. 

  99. * <td>output</td><td>@ref sendto()</td><td>Sends the data to a specified 

    100. 

  100. * address.</td><td>X</td><td>X</td><td>@n</td><td>X</td>

    101. 

  101. * </tr>

    102. 

  102. * <tr>

    103. 

  103. * <td>termination</td><td>@ref shutdown()</td><td>Terminates a connection 

    104. 

  104. * in one or both directions.</td><td>X</td><td>X</td><td>X</td><td>X</td>

    105. 

  105. * </tr>

    106. 

  106. * <tr>

    107. 

  107. * <td>termination</td><td>@ref closesocket()</td><td>Terminates a connection 

    108. 

  108. * and releases the socket.</td><td>X</td><td>X</td><td>X</td><td>X</td>

    109. 

  109. * </tr>

    110. 

  110. * <tr>

    111. 

  111. * <td>administration</td><td>@ref setsockopt()</td><td>Sets socket or protocol 

    112. 

  112. * options.</td><td>X</td><td>X</td><td>X</td><td>X</td>

    113. 

  113. * </tr>

    114. 

  114. * <tr>

    115. 

  115. * <td>administration</td><td>@ref getsockopt()</td><td>Gets socket or protocol 

    116. 

  116. * options.</td><td>X</td><td>X</td><td>X</td><td>X</td>

    117. 

  117. * </tr>

    118. 

  118. * <tr>

    119. 

  119. * <td>administration</td><td>@ref getsockname()</td><td>Gets a local address 

    120. 

  120. * assigned to a socket.</td><td>X</td><td>X</td><td>X</td><td>X</td>

    121. 

  121. * </tr>

    122. 

  122. * <tr>

    123. 

  123. * <td>administration</td><td>@ref getpeername()</td><td>Gets a foreign address 

    124. 

  124. * assigned to a socket.</td><td>X</td><td>X</td><td>X</td><td>X</td>

    125. 

  125. * </tr>

    126. 

  126. * </table>

    127. 

  127. * Configuration parameters:

    128. 

  128. * - @ref FNET_CFG_SOCKET_MAX  

    129. 

  129. * - @ref FNET_CFG_SOCKET_TCP_TX_BUF_SIZE

    130. 

  130. * - @ref FNET_CFG_SOCKET_TCP_RX_BUF_SIZE  

    131. 

  131. * - @ref FNET_CFG_SOCKET_UDP_TX_BUF_SIZE 

    132. 

  132. * - @ref FNET_CFG_SOCKET_UDP_RX_BUF_SIZE

    133. 

  133. * - @ref FNET_CFG_SOCKET_TCP_MSS 

    134. 

  134. * - @ref FNET_CFG_RAW

    135. 

  135. */

    136. 

  136. /*! @{ */

    137. 

  137. 

    138. 

  138. 

    139. 

  139. /* Special addresses */

    140. 

  140. 

    141. 

  141. /**************************************************************************/ /*!

    142. 

  142.  * @brief It means to use any network interface.

    143. 

  143.  ******************************************************************************/

    144. 

  144. #define INADDR_ANY       (unsigned long)(0x00000000U)

    145. 

  145. 

    146. 

  146. /**************************************************************************/ /*!

    147. 

  147.  * @brief  Broadcast address. @n

    148. 

  148.  * It can be used to send the broadcast UDP datagrams over an IP network.

    149. 

  149.  ******************************************************************************/

    150. 

  150. #define INADDR_BROADCAST (unsigned long)(0xffffffffU)

    151. 

  151. 

    152. 

  152. /**************************************************************************/ /*!

    153. 

  153.  * @brief Address family type.

    154. 

  154.  * @see AF_UNSPEC, AF_INET, AF_INET6, AF_SUPPORTED 

    155. 

  155.  ******************************************************************************/

    156. 

  156. typedef unsigned short fnet_address_family_t;

    157. 

  157. 

    158. 

  158. /**************************************************************************/ /*!

    159. 

  159.  * @brief Unspecified address family.

    160. 

  160.  ******************************************************************************/

    161. 

  161. #define AF_UNSPEC   (0U) 

    162. 

  162. /**************************************************************************/ /*!

    163. 

  163.  * @brief IPv4 address family.

    164. 

  164.  ******************************************************************************/                        

    165. 

  165. #define AF_INET     (1U) 

    166. 

  166. /**************************************************************************/ /*!

    167. 

  167.  * @brief IPv6 address family.

    168. 

  168.  ******************************************************************************/                         

    169. 

  169. #define AF_INET6    (2U) 

    170. 

  170. /**************************************************************************/ /*!

    171. 

  171.  * @brief Bitmask of supported address families.

    172. 

  172.  * @showinitializer 

    173. 

  173.  ******************************************************************************/ 

    174. 

  174. #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)))

    175. 

  175.     

    176. 

  176. 

    177. 

  177. /* Size of sa_data[]*/

    178. 

  178. #if FNET_CFG_IP6

    179. 

  179.     #define FNET_SA_DATA_SIZE   (20U) /* To cover sockaddr_in and sockaddr_in6. */

    180. 

  180. #else /* IPv4 */

    181. 

  181.    #define FNET_SA_DATA_SIZE    (4U)

    182. 

  182. #endif

    183. 

  183. 

    184. 

  184. /**************************************************************************/ /*!

    185. 

  185.  * @def     FNET_IP_ADDR_STR_SIZE

    186. 

  186.  * @brief   Size of the string buffer that will contain 

    187. 

  187.  *          null-terminated ASCII string of an IP address. It depends on

    188. 

  188.  *          if disabled or enabled IPv6.

    189. 

  189.  * @see fnet_inet_ntoa, fnet_inet_ntop

    190. 

  190.  * @showinitializer 

    191. 

  191.  ******************************************************************************/

    192. 

  192. #if FNET_CFG_IP6 

    193. 

  193.     #define FNET_IP_ADDR_STR_SIZE       FNET_IP6_ADDR_STR_SIZE

    194. 

  194. #else /* IPv4 */

    195. 

  195.     #define FNET_IP_ADDR_STR_SIZE       FNET_IP4_ADDR_STR_SIZE

    196. 

  196. #endif

    197. 

  197. 

    198. 

  198. /**************************************************************************/ /*!

    199. 

  199.  * @brief Socket address structure.

    200. 

  200.  *

    201. 

  201.  * @see sockaddr_in, sockaddr_in6

    202. 

  202.  *

    203. 

  203.  * The original goal of the @ref sockaddr structure is to support multiple 

    204. 

  204.  * protocols. For the TCP/IP stack @c sa_data, it contains a destination address 

    205. 

  205.  * and port number for a socket.

    206. 

  206.  ******************************************************************************/

    207. 

  207. struct sockaddr

    208. 

  208. {

    209. 

  209.     fnet_address_family_t sa_family;/**< @brief Address family. Specifies the 

    210. 

  210.                              * address family, to which the address belongs. @n

    211. 

  211.                              * It is defined by @ref fnet_address_family_t. 

    212. 

  212.                              */

    213. 

  213.     unsigned short sa_port; /**< @brief 16-bit port number used to 

    214. 

  214.                              * demultiplex the transport-level messages

    215. 

  215.                              * (in network byte order). 

    216. 

  216.                              */                             

    217. 

  217.     char sa_data[FNET_SA_DATA_SIZE];/**< @brief Address value. For the TCP/IP stack, 

    218. 

  218.                              * it contains the destination address and port 

    219. 

  219.                              * number for a socket.

    220. 

  220.                              */

    221. 

  221. };

    222. 

  222. 

    223. 

  223. /**************************************************************************/ /*!

    224. 

  224.  * @brief IPv4 address structure.

    225. 

  225.  *

    226. 

  226.  * @see sockaddr_in

    227. 

  227.  *

    228. 

  228.  * Actually, it represents an IPv4 address (in network endian).

    229. 

  229.  ******************************************************************************/

    230. 

  230. struct in_addr

    231. 

  231. {

    232. 

  232.     fnet_ip4_addr_t s_addr; /**< @brief 32-bit IPv4 address (in network byte order). 

    233. 

  233.                             */

    234. 

  234. };

    235. 

  235. 

    236. 

  236. /**************************************************************************/ /*!

    237. 

  237.  * @brief IPv4 Socket address structure.

    238. 

  238.  *

    239. 

  239.  * @see sockaddr

    240. 

  240.  *

    241. 

  241.  * To make manipulation of the @ref sockaddr structure easier, the TCP/IPv4 stack 

    242. 

  242.  * also defines the equivalent structure @ref sockaddr_in 

    243. 

  243.  * ("in" means "Internet").

    244. 

  244.  ******************************************************************************/

    245. 

  245. struct sockaddr_in

    246. 

  246. {

    247. 

  247.     fnet_address_family_t sin_family;   /**< @brief Specifies the address family. @n 

    248. 

  248.                                  * It must ne set to @ref AF_INET.  

    249. 

  249.                                  */

    250. 

  250.     unsigned short sin_port;    /**< @brief 16-bit port number used to 

    251. 

  251.                                  * demultiplex the transport-level messages

    252. 

  252.                                  * (in network byte order). 

    253. 

  253.                                  */

    254. 

  254.     struct in_addr sin_addr;    /**< @brief 32-bit internet address. 

    255. 

  255.                                  */

    256. 

  256. };

    257. 

  257. 

    258. 

  258. 

    259. 

  259. /************************************************************************

    260. 

  260. *                           IPv6

    261. 

  261. *************************************************************************/

    262. 

  262. 

    263. 

  263. 

    264. 

  264. /**************************************************************************/ /*!

    265. 

  265.  * @brief IPv6 address structure.

    266. 

  266.  *

    267. 

  267.  * @see sockaddr_in6

    268. 

  268.  *

    269. 

  269.  * Actually, it represents an IPv6 address.

    270. 

  270.  ******************************************************************************/

    271. 

  271. struct in6_addr

    272. 

  272. {

    273. 

  273.     fnet_ip6_addr_t s6_addr;        /**< @brief 128-bit IPv6 address.*/

    274. 

  274. };

    275. 

  275. 

    276. 

  276. /**************************************************************************/ /*!

    277. 

  277.  * @brief IPv6 Socket address structure.

    278. 

  278.  *

    279. 

  279.  * @see sockaddr

    280. 

  280.  *

    281. 

  281.  * To make manipulation of the @ref sockaddr structure easier, the TCP/IPv6 stack 

    282. 

  282.  * also defines the equivalent structure @ref sockaddr_in6 

    283. 

  283.  * ("in" means "Internet").

    284. 

  284.  ******************************************************************************/

    285. 

  285. struct sockaddr_in6

    286. 

  286. {

    287. 

  287.     fnet_address_family_t  sin6_family; /**< @brief Specifies the address family. @n 

    288. 

  288.                                          * It must ne set to @ref AF_INET6.  

    289. 

  289.                                          */

    290. 

  290.     unsigned short  sin6_port;          /**< @brief 16-bit port number used to 

    291. 

  291.                                          * demultiplex the transport-level messages

    292. 

  292.                                          * (in network byte order). 

    293. 

  293.                                          */

    294. 

  294.     struct in6_addr sin6_addr;          /**< @brief 128-bit IPv6 internet address. 

    295. 

  295.                                          */

    296. 

  296.     unsigned long   sin6_scope_id;      /**< @brief Scope zone index, defining network interface.

    297. 

  297.                                          */                                      

    298. 

  298. };

    299. 

  299. 

    300. 

  300. /**************************************************************************/ /*!

    301. 

  301.  * @brief IPv4 multicast group information.

    302. 

  302.  *

    303. 

  303.  * The structure is used with the @ref IP_ADD_MEMBERSHIP and 

    304. 

  304.  * @ref IP_DROP_MEMBERSHIP socket options. 

    305. 

  305.  *

    306. 

  306.  * @see IP_ADD_MEMBERSHIP, IP_DROP_MEMBERSHIP

    307. 

  307.  *

    308. 

  308.  ******************************************************************************/

    309. 

  309. struct ip_mreq

    310. 

  310. {

    311. 

  311.     struct in_addr imr_multiaddr;   /**< @brief IPv4 multicast address of group. */

    312. 

  312.     struct in_addr imr_interface;   /**< @brief Local IPv4 address of interface on which 

    313. 

  313.                                      * the multicast group should be joined or dropped.@n

    314. 

  314.                                      * If this member specifies an IPv4 address of 0.0.0.0 

    315. 

  315.                                      * or @ref INADDR_ANY, 

    316. 

  316.                                      * the default interface is used. */

    317. 

  317. };

    318. 

  318. 

    319. 

  319. /**************************************************************************/ /*!

    320. 

  320.  * @brief IPv6 multicast group information.

    321. 

  321.  *

    322. 

  322.  * The structure is used with the @ref IPV6_JOIN_GROUP and 

    323. 

  323.  * @ref IPV6_LEAVE_GROUP socket options. 

    324. 

  324.  *

    325. 

  325.  * @see IPV6_JOIN_GROUP, IPV6_LEAVE_GROUP

    326. 

  326.  *

    327. 

  327.  ******************************************************************************/

    328. 

  328. struct ipv6_mreq

    329. 

  329. {

    330. 

  330.     struct in6_addr ipv6imr_multiaddr;  /**< @brief IPv6 multicast address of group. */

    331. 

  331.     unsigned int    ipv6imr_interface;  /**< @brief Interface index. It equals to the scope zone index, defining network interface.@n

    332. 

  332.                                          * If this member is zero, the default interface is used. */

    333. 

  333. };

    334. 

  334. 

    335. 

  335. /**************************************************************************/ /*!

    336. 

  336.  * @brief Socket types.

    337. 

  337.  ******************************************************************************/

    338. 

  338. typedef enum

    339. 

  339. {

    340. 

  340.     SOCK_UNSPEC = (0U),  /**< @brief Unspecified socket type. 

    341. 

  341.                          */

    342. 

  342.     SOCK_STREAM = (1U),  /**< @brief Stream socket.@n

    343. 

  343.                          * Provides reliable, two-way, connection-based 

    344. 

  344.                          * byte stream. It corresponds to the TCP protocol    

    345. 

  345.                          */

    346. 

  346.     SOCK_DGRAM  = (2U),  /**< @brief Datagram socket.@n

    347. 

  347.                          * Provides unreliable, connectionless datagrams. 

    348. 

  348.                          * It corresponds to the UDP protocol. 

    349. 

  349.                          */

    350. 

  350.     SOCK_RAW    = (3U)   /**< @brief Raw socket.@n

    351. 

  351.                          * Raw sockets allow an application to have direct access to 

    352. 

  352.                          * lower-level communication protocols. 

    353. 

  353.                          * Raw sockets are intended to take advantage of some protocol feature 

    354. 

  354.                          * that is not directly accessible through a normal interface, 

    355. 

  355.                          * or to build new protocols on top of existing low-level protocols.@n

    356. 

  356.                          * It can be enabled by the @ref FNET_CFG_RAW option.

    357. 

  357.                          */

    358. 

  358. } fnet_socket_type_t;

    359. 

  359. 

    360. 

  360. /**************************************************************************/ /*!

    361. 

  361.  * @brief Socket state.

    362. 

  362.  ******************************************************************************/

    363. 

  363. typedef enum

    364. 

  364. {

    365. 

  365.     SS_UNCONNECTED = (0),   /**< @brief Not connected to any socket. 

    366. 

  366.                              */

    367. 

  367.     SS_CONNECTING  = (1),   /**< @brief In process of connecting. 

    368. 

  368.                              */

    369. 

  369.     SS_CONNECTED   = (2),   /**< @brief Connected to a socket. 

    370. 

  370.                              */

    371. 

  371.     SS_LISTENING   = (3)    /**< @brief In listening state. 

    372. 

  372.                              */

    373. 

  373. } fnet_socket_state_t;

    374. 

  374. 

    375. 

  375. /**************************************************************************/ /*!

    376. 

  376.  * @brief Protocol numbers and Level numbers for the @ref setsockopt() 

    377. 

  377.  * and the @ref getsockopt().

    378. 

  378.  ******************************************************************************/

    379. 

  379. typedef enum

    380. 

  380. {

    381. 

  381.     IPPROTO_IP      = (0), /**< @brief IPv4 options level number 

    382. 

  382.                             *   for @ref getsockopt() and @ref setsockopt().

    383. 

  383.                             */

    384. 

  384.     IPPROTO_ICMP    = (1), /**< @brief ICMPv4 protocol number.

    385. 

  385.                             */

    386. 

  386.     IPPROTO_IGMP    = (2), /**< @brief IGMP protocol number.

    387. 

  387.                             */                            

    388. 

  388.     IPPROTO_TCP     = (6), /**< @brief TCP protocol number; TCP options level number

    389. 

  389.                             *   for @ref getsockopt() and @ref setsockopt().

    390. 

  390.                             */

    391. 

  391.     IPPROTO_UDP     = (17),/**< @brief UDP protocol number.

    392. 

  392.                             */

    393. 

  393.     IPPROTO_IPV6    = (41), /**< @brief IPv6 options level number 

    394. 

  394.                             *    for @ref getsockopt() and @ref setsockopt().

    395. 

  395.                             */                            

    396. 

  396.     IPPROTO_ICMPV6  = (58),/**< @brief ICMPv6 protocol number.

    397. 

  397.                             */                         

    398. 

  398.     SOL_SOCKET      = (255255)  /**< @brief Socket options level number for 

    399. 

  399.                                  * @ref getsockopt() and @ref setsockopt().

    400. 

  400.                                  */

    401. 

  401. } fnet_protocol_t;

    402. 

  402. 

    403. 

  403. /**************************************************************************/ /*!

    404. 

  404.  * @brief Socket level (@ref SOL_SOCKET) options for the @ref setsockopt() and the @ref getsockopt().

    405. 

  405.  *

    406. 

  406.  * <table>

    407. 

  407.  *<caption>Socket SOL_SOCKET level options</caption>

    408. 

  408.  *<tr class="fnet_td_grey">

    409. 

  409.  *<th ALIGN=CENTER>Option</th><th ALIGN=CENTER>Option Type</th><th ALIGN=CENTER>

    410. 

  410.  * Default Value</th><th ALIGN=CENTER>Read/Write</th>

    411. 

  411.  *</tr>

    412. 

  412.  *<tr>

    413. 

  413.  *<td>@ref SO_ACCEPTCONN</td><td>int</td><td>0</td><td>R</td>

    414. 

  414.  *</tr>

    415. 

  415.  *<tr>

    416. 

  416.  *<td>@ref SO_KEEPALIVE</td><td>int</td><td>1</td><td>RW</td>

    417. 

  417.  *</tr>

    418. 

  418.  *<tr>

    419. 

  419.  *<td>@ref SO_DONTROUTE</td><td>int</td><td>0</td><td>RW</td>

    420. 

  420.  *</tr>

    421. 

  421.  *<tr>

    422. 

  422.  *<td>@ref SO_LINGER</td><td>struct @ref linger</td><td>{0,0}</td><td>RW</td>

    423. 

  423.  *</tr>

    424. 

  424.  *<tr>

    425. 

  425.  *<td>@ref SO_OOBINLINE</td><td>int</td><td>0</td><td>RW</td>

    426. 

  426.  *</tr>

    427. 

  427.  *<tr>

    428. 

  428.  *<td>@ref SO_SNDBUF</td><td>unsigned long</td>

    429. 

  429.  *<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>

    430. 

  430.  *</tr>

    431. 

  431.  *<tr>

    432. 

  432.  *<td>@ref SO_RCVBUF</td><td>unsigned long</td>

    433. 

  433.  *<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>

    434. 

  434.  *</tr>

    435. 

  435.  *<tr>

    436. 

  436.  *<td>@ref SO_STATE</td><td>@ref fnet_socket_state_t</td><td>@ref SS_UNCONNECTED</td><td>R</td>

    437. 

  437.  *</tr>

    438. 

  438.  *<tr>

    439. 

  439.  *<td>@ref SO_ERROR</td><td>@ref fnet_error_t</td><td>@ref FNET_ERR_OK</td><td>R</td>

    440. 

  440.  *</tr>

    441. 

  441.  *<tr>

    442. 

  442.  *<td>@ref SO_TYPE</td><td>@ref fnet_socket_type_t</td><td>@ref SOCK_DGRAM for 

    443. 

  443.  * UDP @n @ref SOCK_STREAM for TCP</td><td>R</td>

    444. 

  444.  *</tr>

    445. 

  445.  *<tr>

    446. 

  446.  *<td>@ref SO_RCVNUM</td><td>unsigned long</td><td>0</td><td>R</td>

    447. 

  447.  *</tr>

    448. 

  448.  *<tr>

    449. 

  449.  *<td>@ref SO_SNDNUM</td><td>unsigned long</td><td>0</td><td>R</td>

    450. 

  450.  *</tr>

    451. 

  451.  *</table>

    452. 

  452.  ******************************************************************************/

    453. 

  453. typedef enum

    454. 

  454. {

    455. 

  455.     SO_ACCEPTCONN = (1), /**< @brief Returns @c 1 if a socket is in 

    456. 

  456.                                *   listening mode and returns @c 0 when vice versa. 

    457. 

  457.                                *   This is the read-only option and it is 

    458. 

  458.                                *   valid only for connection-oriented protocols (TCP). 

    459. 

  459.                                */

    460. 

  460.     SO_KEEPALIVE  = (2), /**< @brief This option enables keep-alive probes 

    461. 

  461.                                *   for a socket connection. These probes are used 

    462. 

  462.                                *   to maintain a TCP connection and regularly 

    463. 

  463.                                *   test the connection to ensure that it's 

    464. 

  464.                                *   still available. It is only valid for 

    465. 

  465.                                *   connection-oriented protocols (TCP). 

    466. 

  466.                                */

    467. 

  467.     SO_DONTROUTE  = (4), /**< @brief This option enables bypassing of a routing algorithm.

    468. 

  468.                                *   It means that the network interface tries to send a datagram without

    469. 

  469.                                *   a gateway. 

    470. 

  470.                                */

    471. 

  471.     SO_LINGER     = (8), /**< @brief This option controls the action 

    472. 

  472.                                *   taken when unsent data is present, and 

    473. 

  473.                                *   @ref closesocket() is called. This option 

    474. 

  474.                                *   is defined by the @ref linger structure. 

    475. 

  475.                                */

    476. 

  476. #if FNET_CFG_TCP_URGENT || defined(__DOXYGEN__)

    477. 

  477.     SO_OOBINLINE  = (10), /**< @brief This option specifies that out-of-band (OOB) 

    478. 

  478.                                *   data will be received in line with regular data.

    479. 

  479.                                *   It is valid only for the TCP protocol. @n

    480. 

  480.                                *   This option is avalable only if 

    481. 

  481.                                *   @ref FNET_CFG_TCP_URGENT is set to @c 1. 

    482. 

  482.                                */

    483. 

  483. #endif /* FNET_CFG_TCP_URGENT */

    484. 

  484.     SO_SNDBUF     = (1001), /**< @brief This option defines the maximum per-socket 

    485. 

  485.                                *   buffer size for output data.

    486. 

  486.                                */

    487. 

  487.     SO_RCVBUF     = (1002), /**< @brief This option defines the maximum per-socket 

    488. 

  488.                                *   buffer size for input data.

    489. 

  489.                                */

    490. 

  490.     SO_STATE      = (1003), /**< @brief This option defines the current state of the socket.@n

    491. 

  491.                                *   This is the read-only option and it is defined by the @ref fnet_socket_state_t type.

    492. 

  492.                                */

    493. 

  493.     SO_ERROR      = (1006), /**< @brief This option returns a per-socket-based error code.@n

    494. 

  494.                                *   The error code is defined by the @ref fnet_error_t type.@n

    495. 

  495.                                *   After the error value has been read in the @ref getsockopt function, it is cleared.

    496. 

  496.                                *   But a successful call using the socket routines does not clear 

    497. 

  497.                                *   the socket-based error.

    498. 

  498.                                */

    499. 

  499.     SO_TYPE       = (1007), /**< @brief This option defines the type of the socket.

    500. 

  500.                                *   This is a read-only option and it is defined by the @ref fnet_socket_type_t type.

    501. 

  501.                                */

    502. 

  502.     SO_RCVNUM     = (1008), /**< @brief This option is used to determine the amount of data 

    503. 

  503.                                *   pending in the socket-input buffer.@n

    504. 

  504.                                *   This is a read-only option.

    505. 

  505.                                */

    506. 

  506.     SO_SNDNUM     = (1009)  /**< @brief This option is used to determine the amount of data 

    507. 

  507.                                *   in the socket output buffer. @n

    508. 

  508.                                *   This is a read-only option.

    509. 

  509.                                */

    510. 

  510. } fnet_socket_options_t;

    511. 

  511. 

    512. 

  512. 

    513. 

  513. /**************************************************************************/ /*!

    514. 

  514.  * @brief TCP level (@ref IPPROTO_TCP) options for the @ref setsockopt() 

    515. 

  515.  * and the @ref getsockopt().

    516. 

  516.  *

    517. 

  517.  * <table>

    518. 

  518.  *<caption>Socket IPPROTO_TCP level options</caption>

    519. 

  519.  *<tr class="fnet_td_grey">

    520. 

  520.  *<th ALIGN=CENTER>Option</th><th ALIGN=CENTER>Option Type</th><th ALIGN=CENTER>

    521. 

  521.  * Default Value</th><th ALIGN=CENTER>Read/Write</th>

    522. 

  522.  *</tr>

    523. 

  523.  *<tr>

    524. 

  524.  *<td>@ref TCP_MSS</td><td>unsigned short</td><td>536</td><td>RW</td>

    525. 

  525.  *</tr>

    526. 

  526.  *<tr>

    527. 

  527.  *<td>@ref TCP_BSD</td><td>int</td><td>1</td><td>RW</td>

    528. 

  528.  *</tr>

    529. 

  529.  *<tr>

    530. 

  530.  *<td>@ref TCP_NODELAY</td><td>int</td><td>1</td><td>RW</td>

    531. 

  531.  *</tr>

    532. 

  532.  *<tr>

    533. 

  533.  *<td>@ref TCP_FINRCVD</td><td>int</td><td>0</td><td>R</td>

    534. 

  534.  *</tr>

    535. 

  535.  *<tr>

    536. 

  536.  *<td>@ref TCP_URGRCVD</td><td>int</td><td>0</td><td>R</td>

    537. 

  537.  *</tr>

    538. 

  538.  *<tr>

    539. 

  539.  *<td>@ref TCP_KEEPIDLE</td><td>int</td><td>7200</td><td>RW</td>

    540. 

  540.  *</tr>

    541. 

  541.  *<tr>

    542. 

  542.  *<td>@ref TCP_KEEPINTVL</td><td>int</td><td>75</td><td>RW</td>

    543. 

  543.  *</tr> 

    544. 

  544.  *<tr>

    545. 

  545.  *<td>@ref TCP_KEEPCNT</td><td>int</td><td>8</td><td>RW</td>

    546. 

  546.  *</tr>  

    547. 

  547.  *</table>

    548. 

  548.  ******************************************************************************/

    549. 

  549. typedef enum

    550. 

  550. {

    551. 

  551.     TCP_MSS     = (0x01),   /**< @brief This option defines the maximum size of 

    552. 

  552.                              *   the input segments (MSS). @n

    553. 

  553.                              * The TCP Maximum Segment Size (MSS) defines the maximum amount 

    554. 

  554.                              * of data that a host is willing to accept in a single TCP segment.@n

    555. 

  555.                              * This Maximum Segment Size (MSS) announcement is sent from the

    556. 

  556.                              * data receiver to the data sender and says "I can accept TCP segments

    557. 

  557.                              * up to size X". The size (X) may be larger or smaller than the

    558. 

  558.                              * default.@n

    559. 

  559.                              * The MSS counts only data octets in the segment, it does not count the

    560. 

  560.                              * TCP header or the IP header.@n

    561. 

  561.                              * The default value is defined by the @ref FNET_CFG_SOCKET_TCP_MSS 

    562. 

  562.                              * user-configuration option. @n

    563. 

  563.                              * This option can be set to:

    564. 

  564.                              *     - @c 0 = The selection of the MSS is 

    565. 

  565.                              *              automatic and is based on the MTU of the outgoing 

    566. 

  566.                              *              interface minus 40 (does not include 

    567. 

  567.                              *              the 20 byte IP header and the 20 byte TCP header).@n

    568. 

  568.                              *              It is done to assist in avoiding of IP fragmentation 

    569. 

  569.                              *              at the endpoints of the TCP connection.

    570. 

  570.                              *     - Non-zero value (up to 64K) = The TCP segment could be as large as 64K 

    571. 

  571.                              *              (the maximum IP datagram size), but it could be fragmented 

    572. 

  572.                              *              at the IP layer in order to be transmitted 

    573. 

  573.                              *              across the network to the receiving host.

    574. 

  574.                              */

    575. 

  575. #if FNET_CFG_TCP_URGENT || defined(__DOXYGEN__)

    576. 

  576.     TCP_BSD     = (0x02),   /**< @brief If this option is set to @c 1, the BSD interpretation of 

    577. 

  577.                              *   the urgent pointer is used. In this case the 

    578. 

  578.                              *   urgent pointer of the TCP segment points to 

    579. 

  579.                              *   the next byte following after the urgent byte. 

    580. 

  580.                              *   Most of the TCP implementations use this 

    581. 

  581.                              *   interpretation by default.@n 

    582. 

  582.                              *   If this option is set to @c 0, the interpretation of

    583. 

  583.                              *   the TCP specification is used. In this case the 

    584. 

  584.                              *   urgent pointer of the TCP segment points 

    585. 

  585.                              *   to the urgent byte. @n

    586. 

  586.                              *   This option is avalable only if 

    587. 

  587.                              *   @ref FNET_CFG_TCP_URGENT is set to @c 1.

    588. 

  588.                              */

    589. 

  589. #endif

    590. 

  590.     TCP_NODELAY = (0x04),   /**< @brief If this option is set to @c 1, the Nagle algorithm 

    591. 

  591.                              *   is disabled (and vice versa). @n

    592. 

  592.                              *   The Nagle algorithm is effective in reducing the number 

    593. 

  593.                              *   of small packets sent by the host by essentially buffering 

    594. 

  594.                              *   send data, if there is unacknowledged data already "in flight", 

    595. 

  595.                              *   or until a full-size packet can be sent.@n

    596. 

  596.                              *   But for some applications this algorithm can impede 

    597. 

  597.                              *   performance, especially for a bulky data transfer.

    598. 

  598.                              */

    599. 

  599.     TCP_FINRCVD = (0x08),   /**< @brief This option is set when the final (FIN) segment arrives. @n 

    600. 

  600.                              *   This option indicates that another side will not send any data 

    601. 

  601.                              *   in the current connection.@n

    602. 

  602.                              *   This is the read-only option.

    603. 

  603.                              */

    604. 

  604. #if FNET_CFG_TCP_URGENT || defined(__DOXYGEN__)

    605. 

  605.     TCP_URGRCVD = (0x10),   /**< @brief This option is set when the urgent byte arrives, and 

    606. 

  606.                              *   reset when this byte is read.@n

    607. 

  607.                              *   This option can be set only if the @ref SO_OOBINLINE option is set to @c 0.@n

    608. 

  608.                              *   This is the read-only option. @n 

    609. 

  609.                              *   This option is avalable only if 

    610. 

  610.                              *   @ref FNET_CFG_TCP_URGENT is set to @c 1.                             

    611. 

  611.                              */

    612. 

  612. #endif

    613. 

  613.     TCP_KEEPIDLE = (0x20),  /**< @brief When the @ref SO_KEEPALIVE option is enabled, TCP probes a connection that

    614. 

  614.                              *   has been idle for some amount of time.  The default value for this idle

    615. 

  615.                              *   period is @c 7200 seconds (2 hours).  The @ref TCP_KEEPIDLE option can be used to affect this

    616. 

  616.                              *   value for a given socket, and specifies the number of seconds of idle

    617. 

  617.                              *   time between keepalive probes.   

    618. 

  618.                              */                           

    619. 

  619.     TCP_KEEPINTVL = (0x40), /**< @brief When the @ref SO_KEEPALIVE option is enabled, TCP probes a connection that

    620. 

  620.                              *   has been idle for some amount of time.  If the remote system does not

    621. 

  621.                              *   respond to a keepalive probe, TCP retransmits the probe after some

    622. 

  622.                              *   amount of time.  The default value for this retransmit interval is @c 75

    623. 

  623.                              *   seconds. The @ref TCP_KEEPINTVL option can be used to affect this value for

    624. 

  624.                              *   a given socket, and specifies the number of seconds to wait before

    625. 

  625.                              *   retransmitting a keepalive probe.  

    626. 

  626.                              */                           

    627. 

  627.     TCP_KEEPCNT = (0x80)    /**< @brief When the @ref SO_KEEPALIVE option is enabled, TCP probes a connection that

    628. 

  628.                              *   has been idle for some amount of time.  If the remote system does not

    629. 

  629.                              *   respond to a keepalive probe, TCP retransmits the probe a certain

    630. 

  630.                              *   number of times before a connection is considered to be broken.  The

    631. 

  631.                              *   default value for this keepalive probe retransmit limit is @c 8.  The

    632. 

  632.                              *   @ref TCP_KEEPCNT option can be used to affect this value for a given socket,

    633. 

  633.                              *   and specifies the maximum number of keepalive probes to be sent.

    634. 

  634.                              */                            

    635. 

  635. } fnet_tcp_options_t;

    636. 

  636. 

    637. 

  637. /**************************************************************************/ /*!

    638. 

  638.  * @brief IPv4 level (@ref IPPROTO_IP) options for the @ref setsockopt() and 

    639. 

  639.  * the @ref getsockopt().

    640. 

  640.  *

    641. 

  641.  * <table>

    642. 

  642.  *<caption>Socket IPPROTO_IP level options</caption>

    643. 

  643.  *<tr class="fnet_td_grey">

    644. 

  644.  *<th ALIGN=CENTER>Option</th><th ALIGN=CENTER>Option Type</th><th ALIGN=CENTER>

    645. 

  645.  * Default Value</th><th ALIGN=CENTER>Read/Write</th>

    646. 

  646.  *</tr>

    647. 

  647.  *<tr>

    648. 

  648.  *<td>@ref IP_TOS</td><td>int</td><td>0</td><td>RW</td>

    649. 

  649.  *</tr>

    650. 

  650.  *<tr>

    651. 

  651.  *<td>@ref IP_TTL</td><td>int</td><td>64</td><td>RW</td>

    652. 

  652.  *</tr>

    653. 

  653.  *<tr>

    654. 

  654.  *<td>@ref IP_MULTICAST_TTL</td><td>int</td><td>1</td><td>RW</td>

    655. 

  655.  *</tr>

    656. 

  656.  *<tr> 

    657. 

  657.  *<td>@ref IP_ADD_MEMBERSHIP</td><td>@ref ip_mreq</td><td>N/A</td><td>W</td>

    658. 

  658.  *</tr> 

    659. 

  659.  *<tr>  

    660. 

  660.  *<td>@ref IP_DROP_MEMBERSHIP</td><td>@ref ip_mreq</td><td>N/A</td><td>W</td>

    661. 

  661.  *</tr> 

    662. 

  662.  *</table>

    663. 

  663.  ******************************************************************************/

    664. 

  664. typedef enum

    665. 

  665. {

    666. 

  666.     IP_TOS      = (3), /**< @brief  This option defines the IPv4 TOS 

    667. 

  667.                         *   (type-of-service) field for outgoing datagrams.

    668. 

  668.                         */

    669. 

  669.     IP_TTL      = (4)  /**< @brief  This option defines the IPv4 TTL 

    670. 

  670.                         *   (time-to-live) vlaue for outgoing datagrams.

    671. 

  671.                         */

    672. 

  672. #if FNET_CFG_MULTICAST || defined(__DOXYGEN__)

    673. 

  673.     ,

    674. 

  674.     IP_MULTICAST_TTL = (6),     /**< @brief This option allows to change IPv4 "time to live" (TTL) 

    675. 

  675.                                  * value for outgoing multicast datagrams. 

    676. 

  676.                                  * Otherwise, multicast datagrams are sent with a default value of 1, 

    677. 

  677.                                  * to prevent them to be forwarded beyond the local network.@n

    678. 

  678.                                  * This option is available only if @ref FNET_CFG_MULTICAST is set to @c 1.

    679. 

  679.                                  */ 

    680. 

  680.     IP_ADD_MEMBERSHIP = (7),    /**< @brief  Join the socket to the IPv4 multicast group on 

    681. 

  681.                                  * the specified interface. It tells the system to receive packets on 

    682. 

  682.                                  * the network whose destination is the group address (but not its own).

    683. 

  683.                                  * It is valid only for the SOCK_DGRAM (UDP) sockets.@n

    684. 

  684.                                  * This option is available only if @ref FNET_CFG_MULTICAST is set to @c 1.

    685. 

  685.                                  */

    686. 

  686.     IP_DROP_MEMBERSHIP = (8)    /**< @brief  Drops membership to a IPv4 multicast group and interface.@n

    687. 

  687.                                  * This option is available only if @ref FNET_CFG_MULTICAST is set to @c 1.

    688. 

  688.                                  */

    689. 

  689. #endif /* FNET_CFG_MULTICAST */

    690. 

  690. } fnet_ip_options_t;

    691. 

  691. 

    692. 

  692. /**************************************************************************/ /*!

    693. 

  693.  * @brief IPv6 level (@ref IPPROTO_IPV6) options (RFC3493) for the @ref setsockopt() 

    694. 

  694.  * and the @ref getsockopt().

    695. 

  695.  *

    696. 

  696.  * <table>

    697. 

  697.  *<caption>Socket IPPROTO_IPV6 level options</caption>

    698. 

  698.  *<tr class="fnet_td_grey">

    699. 

  699.  *<th ALIGN=CENTER>Option</th><th ALIGN=CENTER>Option Type</th><th ALIGN=CENTER>

    700. 

  700.  * Default Value</th><th ALIGN=CENTER>Read/Write</th>

    701. 

  701.  *</tr>

    702. 

  702.  *<tr>

    703. 

  703.  *<td>@ref IPV6_UNICAST_HOPS</td><td>int</td><td>0 (64)</td><td>RW</td>

    704. 

  704.  *</tr>

    705. 

  705.  *<tr>

    706. 

  706.  *<td>@ref IPV6_MULTICAST_HOPS</td><td>int</td><td>1</td><td>RW</td>

    707. 

  707.  *</tr>

    708. 

  708.  *<tr> 

    709. 

  709.  *<td>@ref IPV6_JOIN_GROUP</td><td>@ref ipv6_mreq</td><td>N/A</td><td>W</td>

    710. 

  710.  *</tr> 

    711. 

  711.  *<tr> 

    712. 

  712.  *<td>@ref IPV6_LEAVE_GROUP</td><td>@ref ipv6_mreq</td><td>N/A</td><td>W</td>

    713. 

  713.  *</tr> 

    714. 

  714.  *</table>

    715. 

  715.  ******************************************************************************/

    716. 

  716. typedef enum

    717. 

  717. {

    718. 

  718.     IPV6_UNICAST_HOPS = (4)     /**< @brief  This option defines hop limit used 

    719. 

  719.                                 * for outgoing unicast IPv6 packets. @n

    720. 

  720.                                 * Its value can be from 0 till 255.@n

    721. 

  721.                                 * By default the option is set to 0. It means that the hop limit is defined 

    722. 

  722.                                 * by local IPv6 router, otherwise it equals to 64. 

    723. 

  723.                                 */

    724. 

  724.     ,IPV6_MULTICAST_HOPS = (5)  /**< @brief Set the hop limit to use for outgoing multicast IPv6 packets.@n

    725. 

  725.                                 * If IPV6_MULTICAST_HOPS is not set, the default is 1.

    726. 

  726.                                 */ 

    727. 

  727.     ,IPV6_JOIN_GROUP  = (6)     /**< @brief (RFC3493) Join a multicast group on a specified local interface.@n

    728. 

  728.                                 *  It is valid only for the SOCK_DGRAM (UDP) sockets.

    729. 

  729.                                 */ 

    730. 

  730.     ,IPV6_LEAVE_GROUP = (7)     /**< @brief (RFC3493)  Leave a multicast group on a specified interface.@n

    731. 

  731.                                 *  It is valid only for the SOCK_DGRAM (UDP) sockets.

    732. 

  732.                                 */ 

    733. 

  733.  

    734. 

  734. } fnet_ip6_options_t;

    735. 

  735. 

    736. 

  736. /**************************************************************************/ /*!

    737. 

  737.  * @brief This structure is used for the @ref SO_LINGER option.

    738. 

  738.  ******************************************************************************/

    739. 

  739. struct linger

    740. 

  740. {

    741. 

  741.     unsigned short l_onoff;  /**< @brief Determines, whether the option will be 

    742. 

  742.                               *   turned on @c 1, or off @c 0.

    743. 

  743.                               */

    744. 

  744.     unsigned short l_linger; /**< @brief Specifies the amount of time (in seconds) 

    745. 

  745.                               *   to wait when the connection is closed and unsent data 

    746. 

  746.                               *   is discarded. 

    747. 

  747.                               *   If @c l_onoff is @c 0, the @c l_linger value is ignored

    748. 

  748.                               *   and the stack continues to try to send the data as usually.

    749. 

  749.                               */

    750. 

  750. };

    751. 

  751. 

    752. 

  752. /**************************************************************************/ /*!

    753. 

  753.  * @brief Socket descriptor.

    754. 

  754.  ******************************************************************************/

    755. 

  755. typedef int SOCKET;

    756. 

  756. 

    757. 

  757. #define SOCKET_INVALID  (FNET_ERR) /**< @brief Invalid socket. @n

    758. 

  758.                                     *   This is the return value of the @ref 

    759. 

  759.                                     *   socket() and @ref accept() functions

    760. 

  760.                                     *   if an error occurs.

    761. 

  761.                                     */

    762. 

  762. #define SOCKET_ERROR    (FNET_ERR) /**< @brief Socket error.@n

    763. 

  763.                                     *   This is the return value of 

    764. 

  764.                                     *   the socket API functions if an error occurs.

    765. 

  765.                                     */

    766. 

  766. 

    767. 

  767. /**************************************************************************/ /*!

    768. 

  768.  * @brief The flags parameters for receiving and sending functions 

    769. 

  769.  * @ref recv(), @ref recvfrom(), @ref send(), and @ref sendto().

    770. 

  770.  *

    771. 

  771.  * The optional flag specifies the way, in which the call is made. 

    772. 

  772.  * It can be constructed by using the bitwise OR.

    773. 

  773.  ******************************************************************************/

    774. 

  774. typedef enum

    775. 

  775. {

    776. 

  776. #if FNET_CFG_TCP_URGENT || defined(__DOXYGEN__)

    777. 

  777.     MSG_OOB       = (0x1U),  /**< @brief Process out-of-band 

    778. 

  778.                              * data instead of regular data. @n 

    779. 

  779.                              *   This option is avalable only if 

    780. 

  780.                              *   @ref FNET_CFG_TCP_URGENT is set to @c 1. 

    781. 

  781.                              */

    782. 

  782. #endif /* FNET_CFG_TCP_URGENT */

    783. 

  783.     MSG_PEEK      = (0x2U),  /**< @brief Receive a copy of the 

    784. 

  784.                              * data without consuming it.

    785. 

  785.                              */

    786. 

  786.     MSG_DONTROUTE = (0x4U)   /**< @brief Send without using 

    787. 

  787.                              * routing tables.

    788. 

  788.                              */

    789. 

  789. } fnet_flags_t;

    790. 

  790. 

    791. 

  791. /**************************************************************************/ /*!

    792. 

  792.  * @brief The flags used by @ref shutdown().

    793. 

  793.  *

    794. 

  794.  * They describe what types of socket operation will no longer be allowed.

    795. 

  795.  ******************************************************************************/

    796. 

  796. typedef enum

    797. 

  797. {

    798. 

  798.     SD_READ  = (0x1U), /**< @brief Data receiving is disabled.

    799. 

  799.                        */

    800. 

  800.     SD_WRITE = (0x2U), /**< @brief Data sending is disabled.

    801. 

  801.                        */

    802. 

  802.     SD_BOTH  = (SD_READ | SD_WRITE) /**< @brief Both receiving and 

    803. 

  803.                                      * sending are disabled.

    804. 

  804.                                      */

    805. 

  805. } fnet_sd_flags_t;

    806. 

  806. 

    807. 

  807. 

    808. 

  808. /***************************************************************************/ /*!

    809. 

  809.  *

    810. 

  810.  * @brief    Creates a socket. 

    811. 

  811.  *

    812. 

  812.  *

    813. 

  813.  * @param family   Address family that the socket will use, defined 

    814. 

  814.  *                 by the @ref fnet_address_family_t.

    815. 

  815.  *

    816. 

  816.  * @param type     Type specification for the new socket, defined by @ref

    817. 

  817.  *                 fnet_socket_type_t. It can be @ref SOCK_STREAM (TCP) or

    818. 

  818.  *                 @ref SOCK_DGRAM (UDP).

    819. 

  819.  *

    820. 

  820.  * @param protocol Protocol to be used with the socket that is specific to 

    821. 

  821.  *                 the indicated address family. This stack supports 

    822. 

  822.  *                 @ref IPPROTO_TCP and @ref IPPROTO_UDP.@n

    823. 

  823.  *                 This parameter is optional, and can be set to zero, as 

    824. 

  824.  *                 the @c type already defines the proper protocol.

    825. 

  825.  *

    826. 

  826.  * @return This function returns:

    827. 

  827.  *   - Socket descriptor referencing the new socket, if no error occurs.

    828. 

  828.  *   - @ref SOCKET_INVALID if an error occurs. @n 

    829. 

  829.  *     The specific error code can be retrieved using the @ref fnet_error_get().

    830. 

  830.  *

    831. 

  831.  * @see closesocket()

    832. 

  832.  *

    833. 

  833.  ******************************************************************************

    834. 

  834.  *

    835. 

  835.  * This function creates a socket and returns its descriptor.@n

    836. 

  836.  * The @ref socket() function causes a socket descriptor and any related 

    837. 

  837.  * resources to be allocated and bound to a specific transport-service 

    838. 

  838.  * provider that supports the requested combination of address family,

    839. 

  839.  * socket type, and protocol parameters.@n

    840. 

  840.  * @n

    841. 

  841.  * After a socket is created:

    842. 

  842.  * - Connection-oriented sockets, such as the @ref SOCK_STREAM, provide 

    843. 

  843.  *   full-duplex connections. Before any data can be sent or received,

    844. 

  844.  *   it must be in a connected state . A connection to 

    845. 

  845.  *   another socket is established with the @ref connect() call. 

    846. 

  846.  *   Once connected, the data can be transferred using the @ref send() and  the @ref 

    847. 

  847.  *   recv() calls. When a session has been completed, the @ref closesocket() 

    848. 

  848.  *   must be performed.

    849. 

  849.  * - Connectionless, message-oriented sockets, such as the @ref SOCK_DGRAM, allow 

    850. 

  850.  *   sending and receiving of datagrams to and from arbitrary peers using 

    851. 

  851.  *   the @ref sendto() and the @ref recvfrom(). If such a socket is connected 

    852. 

  852.  *   to a specific peer, datagrams can be sent to that peer using the 

    853. 

  853.  *   @ref send(), and can be received only from this peer using the @ref recv().

    854. 

  854.  *

    855. 

  855.  ******************************************************************************/

    856. 

  856. SOCKET socket( fnet_address_family_t family, fnet_socket_type_t type, int protocol );

    857. 

  857. 

    858. 

  858. /***************************************************************************/ /*!

    859. 

  859.  *

    860. 

  860.  * @brief    Assigns a local address to a socket.

    861. 

  861.  *

    862. 

  862.  *

    863. 

  863.  * @param s       Descriptor, identifying a socket to bind.

    864. 

  864.  *

    865. 

  865.  * @param name    The address to be assigned to the socket, from the @ref 

    866. 

  866.  *                sockaddr structure.

    867. 

  867.  *

    868. 

  868.  * @param namelen The length of the @c name parameter. 

    869. 

  869.  *                Normally @c namelen is set to @c sizeof(name).

    870. 

  870.  *

    871. 

  871.  * @return This function returns:

    872. 

  872.  *   - @ref FNET_OK if no error occurs.

    873. 

  873.  *   - @ref SOCKET_ERROR if an error occurs. @n 

    874. 

  874.  *     The specific error code can be retrieved using the @ref fnet_error_get().

    875. 

  875.  *

    876. 

  876.  * @see socket()

    877. 

  877.  *

    878. 

  878.  ******************************************************************************

    879. 

  879.  *

    880. 

  880.  * This function associates a local address with the socket.@n

    881. 

  881.  * The @ref bind() function is used on an unconnected socket before 

    882. 

  882.  * subsequent calls to the @ref connect() or the @ref listen() functions. 

    883. 

  883.  * It is used to bind to either connection-oriented (stream) or connectionless 

    884. 

  884.  * (datagram) sockets.@n

    885. 

  885.  * Within the @ref sockaddr structure, the address may be the address assigned 

    886. 

  886.  * to a network interface on the host or the @ref INADDR_ANY. 

    887. 

  887.  * Using the @ref INADDR_ANY causes the stack to use the default network 

    888. 

  888.  * interface address. Using a port number of 0 causes the service provider 

    889. 

  889.  * to assign a unique port to the socket with a value between 1024 and 5000.

    890. 

  890.  *

    891. 

  891.  ******************************************************************************/

    892. 

  892. int bind( SOCKET s, const struct sockaddr *name, unsigned int namelen );

    893. 

  893. 

    894. 

  894. /***************************************************************************/ /*!

    895. 

  895.  *

    896. 

  896.  * @brief    Places the socket into a state, where it is listening for 

    897. 

  897.  *           an incoming connection.

    898. 

  898.  *

    899. 

  899.  *

    900. 

  900.  * @param s          Descriptor identifying a socket that will be 

    901. 

  901.  *                   used for listening.

    902. 

  902.  *

    903. 

  903.  * @param backlog    Maximum length of the queue of pending connections.

    904. 

  904.  *

    905. 

  905.  *

    906. 

  906.  * @return This function returns:

    907. 

  907.  *   - @ref FNET_OK if no error occurs.

    908. 

  908.  *   - @ref SOCKET_ERROR if an error occurs. @n 

    909. 

  909.  *     The specific error code can be retrieved using the @ref fnet_error_get().

    910. 

  910.  *

    911. 

  911.  * @see socket(), bind(), accept()

    912. 

  912.  *

    913. 

  913.  ******************************************************************************

    914. 

  914.  *

    915. 

  915.  * Only connection-oriented sockets (@ref SOCK_STREAM) are used with the

    916. 

  916.  * @ref listen().@n

    917. 

  917.  * The socket is put into passive mode, where the incoming connection 

    918. 

  918.  * requests are acknowledged and queued pending acceptance by the listening socket.

    919. 

  919.  * The @ref listen() function is typically used by servers that can have 

    920. 

  920.  * more than one connection request at a time. @n 

    921. 

  921.  * An application can call @ref listen() more than once on the same socket. 

    922. 

  922.  * If there are more pending connections than the new backlog value,

    923. 

  923.  * the excess pending connections will be reset and dropped.

    924. 

  924.  *

    925. 

  925.  ******************************************************************************/

    926. 

  926. int listen( SOCKET s, int backlog );

    927. 

  927. 

    928. 

  928. /***************************************************************************/ /*!

    929. 

  929.  *

    930. 

  930.  * @brief    Accepts a connection on the specified socket.

    931. 

  931.  *

    932. 

  932.  *

    933. 

  933.  * @param s          Descriptor, identifying an unconnected socket.

    934. 

  934.  *

    935. 

  935.  * @param addr       Optional pointer to a buffer that receives the address 

    936. 

  936.  *                   of the remote host at the other end of the connection.

    937. 

  937.  *

    938. 

  938.  * @param addrlen    Optional pointer to an integer that contains the 

    939. 

  939.  *                   length of the @c addr parameter.

    940. 

  940.  *

    941. 

  941.  *

    942. 

  942.  * @return This function returns:

    943. 

  943.  *   - Socket descriptor referencing the new socket, if no error occurs.

    944. 

  944.  *   - @ref SOCKET_INVALID if an error occurs. @n 

    945. 

  945.  *     The specific error code can be retrieved using @ref fnet_error_get().

    946. 

  946.  *

    947. 

  947.  * @see socket(), bind()

    948. 

  948.  *

    949. 

  949.  ******************************************************************************

    950. 

  950.  *

    951. 

  951.  * The function extracts the first connection in the queue of pending 

    952. 

  952.  * connections on the listening socket @c s, and returns the new socket descriptor.@n

    953. 

  953.  * The newly-created socket is the socket that will handle the actual 

    954. 

  954.  * connection and has the same properties as the socket @c s. 

    955. 

  955.  * The original socket remains open and listens for new connection requests.

    956. 

  956.  * If no pending connections are present in the queue of the socket, 

    957. 

  957.  * the @ref accept() returns an error and the specific error code is set to 

    958. 

  958.  * @ref FNET_ERR_AGAIN.@n 

    959. 

  959.  * The parameter @c addr is a result parameter that is filled in with the 

    960. 

  960.  * address of the remote host. The @c addrlen should initially contain the 

    961. 

  961.  * amount of space pointed to by the @c addr; on return it will contain the 

    962. 

  962.  * actual length of the address returned (in bytes).@n

    963. 

  963.  * The @ref accept() function is used only with connection-oriented socket 

    964. 

  964.  * types (@ref SOCK_STREAM).@n

    965. 

  965.  * If @c addr and/or @c addrlen are equal to @c 0, then no information

    966. 

  966.  * about the remote address of the accepted socket is returned.

    967. 

  967.  *

    968. 

  968.  ******************************************************************************/

    969. 

  969. SOCKET accept( SOCKET s, struct sockaddr *addr, unsigned int *addrlen );

    970. 

  970. 

    971. 

  971. /***************************************************************************/ /*!

    972. 

  972.  *

    973. 

  973.  * @brief    Establishes a connection with the specified socket.

    974. 

  974.  *

    975. 

  975.  *

    976. 

  976.  * @param s          Descriptor identifying an unconnected socket.

    977. 

  977.  *

    978. 

  978.  * @param name       Address (name) of the socket, with which the connection 

    979. 

  979.  *                   should be established.

    980. 

  980.  *

    981. 

  981.  * @param namelen    Length of the @c name.

    982. 

  982.  *

    983. 

  983.  *

    984. 

  984.  * @return This function returns:

    985. 

  985.  *   - @ref FNET_OK if no error occurs.

    986. 

  986.  *   - @ref SOCKET_ERROR if an error occurs. @n 

    987. 

  987.  *     The specific error code can be retrieved using the @ref fnet_error_get().

    988. 

  988.  *

    989. 

  989.  * @see socket(), bind()

    990. 

  990.  *

    991. 

  991.  ******************************************************************************

    992. 

  992.  *

    993. 

  993.  * For connection-oriented sockets (@ref SOCK_STREAM), this function activates 

    994. 

  994.  * an active connection with the foreign host. 

    995. 

  995.  * 

    996. 

  996.  * When the socket call completes successfully, the socket is ready to send 

    997. 

  997.  * and receive data. Any attempt to reconnect the active connection will fail 

    998. 

  998.  * with the error code @ref FNET_ERR_ISCONN. For connection-oriented 

    999. 

  999.  * sockets, it is often not possible to complete the connection 

    1000. 

  1000.  * immediately. Until the connection attempt 

    1001. 

  1001.  * completes on a socket, all subsequent calls to @ref connect() 

    1002. 

  1002.  * on the same socket will fail with the error code @ref FNET_ERR_INPROGRESS, 

    1003. 

  1003.  * or succeed with @ref FNET_ERR_ISCONN when the connection completes successfully.

    1004. 

  1004.  * Use the @ref getsockopt() function to determine the completion of the 

    1005. 

  1005.  * connection request by checking the @ref SO_STATE to see if the socket is 

    1006. 

  1006.  * connected (@ref SS_CONNECTED), is still connecting (@ref SS_CONNECTING) 

    1007. 

  1007.  * or the connection has failed (@ref SS_UNCONNECTED). @n

    1008. 

  1008.  * @n

    1009. 

  1009.  * For a connectionless socket (@ref SOCK_DGRAM), the operation performed 

    1010. 

  1010.  * by @ref connect() is merely to establish a default destination address 

    1011. 

  1011.  * that can be used on subsequent @ref send() and @ref recv() calls. 

    1012. 

  1012.  * Any datagrams received from an address other than the destination address 

    1013. 

  1013.  * specified will be discarded. The default destination can be changed by 

    1014. 

  1014.  * simply calling the @ref connect() again, even if the socket is connected already.

    1015. 

  1015.  * Any datagrams queued for receipt are discarded from the previous 

    1016. 

  1016.  * @ref connect(). For connectionless sockets, the @c name can indicate any 

    1017. 

  1017.  * valid address, including a broadcast address.@n

    1018. 

  1018.  * @n

    1019. 

  1019.  * If the socket @c s is unbound, unique values are assigned to the local 

    1020. 

  1020.  * association by the stack, and the socket is marked as bound.

    1021. 

  1021.  *

    1022. 

  1022.  ******************************************************************************/

    1023. 

  1023. int connect( SOCKET s, struct sockaddr *name, unsigned int namelen );

    1024. 

  1024. 

    1025. 

  1025. /***************************************************************************/ /*!

    1026. 

  1026.  *

    1027. 

  1027.  * @brief    Receives the data from a connected socket.

    1028. 

  1028.  *

    1029. 

  1029.  *

    1030. 

  1030.  * @param s      Descriptor identifying a connected socket.

    1031. 

  1031.  *

    1032. 

  1032.  * @param buf    Buffer for the incoming data.

    1033. 

  1033.  *

    1034. 

  1034.  * @param len    Length of the @c buf.

    1035. 

  1035.  *

    1036. 

  1036.  * @param flags  Optional flag specifying the way, in which the call is made. 

    1037. 

  1037.  *               It can be constructed by using the bitwise OR operator with

    1038. 

  1038.  *               any of the values defined by the @ref fnet_flags_t.

    1039. 

  1039.  *

    1040. 

  1040.  *

    1041. 

  1041.  * @return This function returns:

    1042. 

  1042.  *   - The number of bytes received, if no error occurs. 

    1043. 

  1043.  *     The return value is set to zero, if there

    1044. 

  1044.  *     is no input data.

    1045. 

  1045.  *   - @ref SOCKET_ERROR if an error occurs. @n 

    1046. 

  1046.  *     The specific error code can be retrieved using the @ref fnet_error_get().

    1047. 

  1047.  *

    1048. 

  1048.  * @see connect(), recvfrom()

    1049. 

  1049.  *

    1050. 

  1050.  ******************************************************************************

    1051. 

  1051.  *

    1052. 

  1052.  * For connection-oriented sockets (@ref SOCK_STREAM), calling the @ref recv() 

    1053. 

  1053.  * will return as much information as is currently available up to the size 

    1054. 

  1054.  * of the buffer supplied.@n

    1055. 

  1055.  * @n

    1056. 

  1056.  * For connectionless sockets (@ref SOCK_DGRAM), the data is extracted from the 

    1057. 

  1057.  * first enqueued datagram (message), whose destination address is specified 

    1058. 

  1058.  * by the @ref connect() function.

    1059. 

  1059.  * If the datagram is larger than the supplied buffer, the buffer is filled

    1060. 

  1060.  * with the first part of the datagram, and the @ref recv() generates the error 

    1061. 

  1061.  * @ref FNET_ERR_MSGSIZE and the excess data is lost.@n

    1062. 

  1062.  * @n

    1063. 

  1063.  * The @c flags parameter can be used to influence the behavior of the function

    1064. 

  1064.  * invocation beyond the options specified for the associated socket. 

    1065. 

  1065.  *

    1066. 

  1066.  ******************************************************************************/

    1067. 

  1067. int recv( SOCKET s, char *buf, unsigned int len, unsigned int flags );

    1068. 

  1068. 

    1069. 

  1069. /***************************************************************************/ /*!

    1070. 

  1070.  *

    1071. 

  1071.  * @brief    Receives the data and captures the address, from which the data 

    1072. 

  1072.  *           was sent.

    1073. 

  1073.  *

    1074. 

  1074.  *

    1075. 

  1075.  * @param s      Descriptor, identifying a bound socket.

    1076. 

  1076.  *

    1077. 

  1077.  * @param buf    Buffer for the incoming data.

    1078. 

  1078.  *

    1079. 

  1079.  * @param len    Length of the @c buf.

    1080. 

  1080.  *

    1081. 

  1081.  * @param flags  Optional flag specifying the way in which the call is made. 

    1082. 

  1082.  *               It can be constructed by using the bitwise OR operator with

    1083. 

  1083.  *               any of the values defined by the @ref fnet_flags_t.

    1084. 

  1084.  *

    1085. 

  1085.  * @param from       Optional pointer to a buffer that will hold the 

    1086. 

  1086.  *                   source address upon return.

    1087. 

  1087.  *

    1088. 

  1088.  * @param fromlen    Optional pointer to the size of the @c from buffer.

    1089. 

  1089.  *

    1090. 

  1090.  *

    1091. 

  1091.  * @return This function returns:

    1092. 

  1092.  *   - The number of bytes received, if no error occurs. 

    1093. 

  1093.  *     The return value is set to zero, if the socket is nonblocking and there

    1094. 

  1094.  *     is no input data.

    1095. 

  1095.  *   - @ref SOCKET_ERROR if an error occurs. @n 

    1096. 

  1096.  *     The specific error code can be retrieved using the @ref fnet_error_get().

    1097. 

  1097.  *

    1098. 

  1098.  * @see bind(), recv()

    1099. 

  1099.  *

    1100. 

  1100.  ******************************************************************************

    1101. 

  1101.  *

    1102. 

  1102.  * For connection-oriented sockets (@ref SOCK_STREAM), calling the @ref recvfrom() 

    1103. 

  1103.  * will return as much information as is currently available up to the size of

    1104. 

  1104.  * the buffer supplied. The @ref recvfrom() call is rarely used for 

    1105. 

  1105.  * stream sockets, because the routine provides the peer-socket information,

    1106. 

  1106.  * and stream sockets are tied to a specific peer.@n

    1107. 

  1107.  * @n

    1108. 

  1108.  * For connectionless sockets (@ref SOCK_DGRAM), the data is extracted from the 

    1109. 

  1109.  * first enqueued datagram.

    1110. 

  1110.  * If the datagram is larger than the buffer supplied, the buffer is filled 

    1111. 

  1111.  * with the first part of the datagram, and the @ref recvfrom() generates the 

    1112. 

  1112.  * error @ref FNET_ERR_MSGSIZE and the excess data is lost.@n

    1113. 

  1113.  * @n

    1114. 

  1114.  * If the @c from parameter is non-zero, the network address of the peer 

    1115. 

  1115.  * that sent the data is copied to the corresponding @ref sockaddr structure. 

    1116. 

  1116.  * The value pointed to by @c fromlen is initialized to the size of this 

    1117. 

  1117.  * structure and is modified on return, to indicate the actual size of 

    1118. 

  1118.  * the address stored in the @ref sockaddr structure.@n

    1119. 

  1119.  * @n

    1120. 

  1120.  * The flags parameter can be used to influence the behavior of the function 

    1121. 

  1121.  * invocation beyond the options specified for the associated socket.

    1122. 

  1122.  *

    1123. 

  1123.  ******************************************************************************/

    1124. 

  1124. int recvfrom( SOCKET s, char *buf, unsigned int len, unsigned int flags, struct sockaddr *from, unsigned int *fromlen );

    1125. 

  1125. 

    1126. 

  1126. /***************************************************************************/ /*!

    1127. 

  1127.  *

    1128. 

  1128.  * @brief    Sends the data on a connected socket.

    1129. 

  1129.  *

    1130. 

  1130.  *

    1131. 

  1131.  * @param s      Descriptor, identifying a connected socket.

    1132. 

  1132.  *

    1133. 

  1133.  * @param buf    Buffer containing the data to be transmitted.

    1134. 

  1134.  *

    1135. 

  1135.  * @param len    Length of the data in @c buf.

    1136. 

  1136.  *

    1137. 

  1137.  * @param flags  Optional flag specifying the way in which the call is made. 

    1138. 

  1138.  *               It can be constructed by using the bitwise OR operator with

    1139. 

  1139.  *               any of the values defined by the @ref fnet_flags_t.

    1140. 

  1140.  *

    1141. 

  1141.  *

    1142. 

  1142.  * @return This function returns:

    1143. 

  1143.  *   - The total number of bytes sent, if no error occurs. 

    1144. 

  1144.  *     It can be less than the number indicated by @c len.

    1145. 

  1145.  *   - @ref SOCKET_ERROR if an error occurs. @n 

    1146. 

  1146.  *     The specific error code can be retrieved using the @ref fnet_error_get().

    1147. 

  1147.  *

    1148. 

  1148.  * @see connect(), sendto()

    1149. 

  1149.  *

    1150. 

  1150.  ******************************************************************************

    1151. 

  1151.  *

    1152. 

  1152.  * For stream-oriented sockets (@ref SOCK_STREAM), the number of 

    1153. 

  1153.  * actually sent bytes can be between @c 1 and the requested length, depending on 

    1154. 

  1154.  * buffer availability on both client and server machines.@n

    1155. 

  1155.  * @n

    1156. 

  1156.  * For message-oriented sockets (@ref SOCK_DGRAM), care must be taken not to  

    1157. 

  1157.  * exceed the maximum datagram size, which can be obtained by using the @ref 

    1158. 

  1158.  * getsockopt() to retrieve the value of the socket option @ref SO_SNDBUF. 

    1159. 

  1159.  * If the data is too long to pass atomically through the underlying 

    1160. 

  1160.  * datagram protocol, the error @ref FNET_ERR_MSGSIZE is returned 

    1161. 

  1161.  * and no data is transmitted.@n

    1162. 

  1162.  * Calling the @ref send() with a zero @c len parameter is permissible. 

    1163. 

  1163.  * In such cases, the @ref send() will return zero as a valid value, and 

    1164. 

  1164.  * for message-oriented sockets (@ref SOCK_DGRAM) a zero-length transport 

    1165. 

  1165.  * datagram is sent.@n

    1166. 

  1166.  * @n

    1167. 

  1167.  * The @c flags parameter can be used to influence the behavior of the function

    1168. 

  1168.  * invocation beyond the options specified for the associated socket. 

    1169. 

  1169.  *

    1170. 

  1170.  ******************************************************************************/

    1171. 

  1171. int send( SOCKET s, char *buf, unsigned int len, unsigned int flags );

    1172. 

  1172. 

    1173. 

  1173. /***************************************************************************/ /*!

    1174. 

  1174.  *

    1175. 

  1175.  * @brief    Sends the data to a specific destination.

    1176. 

  1176.  *

    1177. 

  1177.  *

    1178. 

  1178.  * @param s      Descriptor, identifying a socket.

    1179. 

  1179.  *

    1180. 

  1180.  * @param buf    Buffer containing the data to be transmitted.

    1181. 

  1181.  *

    1182. 

  1182.  * @param len    Length of the data in @c buf.

    1183. 

  1183.  *

    1184. 

  1184.  * @param flags  Optional flag specifying the way, in which the call is made. 

    1185. 

  1185.  *               It can be constructed by using the bitwise OR operator with

    1186. 

  1186.  *               any of the values defined by the @ref fnet_flags_t.

    1187. 

  1187.  *

    1188. 

  1188.  * @param to     Pointer to the address of the target socket.

    1189. 

  1189.  *

    1190. 

  1190.  * @param tolen  Size of the address in @c to.

    1191. 

  1191.  *

    1192. 

  1192.  *

    1193. 

  1193.  * @return This function returns:

    1194. 

  1194.  *   - The total number of bytes sent, if no error occurs. 

    1195. 

  1195.  *     It can be lesser than the number indicated by @c len.

    1196. 

  1196.  *   - @ref SOCKET_ERROR if an error occurs. @n 

    1197. 

  1197.  *     The specific error code can be retrieved using the @ref fnet_error_get().

    1198. 

  1198.  *

    1199. 

  1199.  * @see connect(), send()

    1200. 

  1200.  *

    1201. 

  1201.  ******************************************************************************

    1202. 

  1202.  *

    1203. 

  1203.  * For nonb-locking stream-oriented sockets (@ref SOCK_STREAM), the number of 

    1204. 

  1204.  * actually sent bytes can be between @c 1 and the requested length, depending on 

    1205. 

  1205.  * buffer availability on both client and server machines.@n

    1206. 

  1206.  * @n

    1207. 

  1207.  * For message-oriented sockets (@ref SOCK_DGRAM), care must be taken not not 

    1208. 

  1208.  * exceed the maximum datagram size, which can be obtained by using the @ref 

    1209. 

  1209.  * getsockopt() to retrieve the value of the socket option @ref SO_SNDBUF. 

    1210. 

  1210.  * If the data is too long to pass atomically through the underlying 

    1211. 

  1211.  * datagram protocol, the error @ref FNET_ERR_MSGSIZE is returned 

    1212. 

  1212.  * and no data is transmitted.@n

    1213. 

  1213.  * Calling @ref sendto() with a zero @c len parameter is permissible. 

    1214. 

  1214.  * In such cases, the @ref sendto() will return zero as a valid value, and 

    1215. 

  1215.  * for message-oriented sockets (@ref SOCK_DGRAM), a zero-length transport 

    1216. 

  1216.  * datagram is sent.@n

    1217. 

  1217.  * @n

    1218. 

  1218.  * The @ref sendto() function is normally used on a connectionless socket 

    1219. 

  1219.  * (@ref SOCK_DGRAM) to send a datagram to a specific peer socket identified 

    1220. 

  1220.  * by the @c to parameter. Even if the connectionless socket has been previously 

    1221. 

  1221.  * connected to a specific address, the @c to parameter overrides the 

    1222. 

  1222.  * destination address for that particular datagram only.@n 

    1223. 

  1223.  * On a connection-oriented socket (@ref SOCK_STREAM), the @c to and @c tolen 

    1224. 

  1224.  * parameters are ignored, making the @ref sendto() equivalent to @ref send().@n

    1225. 

  1225.  * @n

    1226. 

  1226.  * The @c flags parameter can be used to influence the behavior of the function

    1227. 

  1227.  * invocation beyond the options specified for the associated socket. 

    1228. 

  1228.  *

    1229. 

  1229.  ******************************************************************************/

    1230. 

  1230. int sendto( SOCKET s, char *buf, unsigned int len, int flags, const struct sockaddr *to, unsigned int tolen );

    1231. 

  1231. 

    1232. 

  1232. /***************************************************************************/ /*!

    1233. 

  1233.  *

    1234. 

  1234.  * @brief    Terminates the connection in one or both directions.

    1235. 

  1235.  *

    1236. 

  1236.  *

    1237. 

  1237.  * @param s      Descriptor, identifying a socket.

    1238. 

  1238.  *

    1239. 

  1239.  * @param how    Flag that describes what types of operation will no longer 

    1240. 

  1240.  *               be allowed, it's defined by the @ref fnet_sd_flags_t.

    1241. 

  1241.  *

    1242. 

  1242.  *

    1243. 

  1243.  * @return This function returns:

    1244. 

  1244.  *   - @ref FNET_OK if no error occurs.

    1245. 

  1245.  *   - @ref SOCKET_ERROR if an error occurs. @n 

    1246. 

  1246.  *     The specific error code can be retrieved using the @ref fnet_error_get().

    1247. 

  1247.  *

    1248. 

  1248.  * @see closesocket()

    1249. 

  1249.  *

    1250. 

  1250.  ******************************************************************************

    1251. 

  1251.  *

    1252. 

  1252.  * This function is used on all types of sockets to disable reception, 

    1253. 

  1253.  * transmission, or both.@n

    1254. 

  1254.  * If the @c how parameter is @ref SD_READ, subsequent calls to the @ref recv()

    1255. 

  1255.  * function on the socket will be unallowed. If the @c how parameter is 

    1256. 

  1256.  * @ref SD_WRITE, subsequent calls to the @ref send() function are unallowed. 

    1257. 

  1257.  * Setting the @c how to the @ref SD_BOTH disables both sends and receives as 

    1258. 

  1258.  * described above.@n

    1259. 

  1259.  * The @ref shutdown() function does not close the socket. Any resources 

    1260. 

  1260.  * attached to the socket will not be freed until the @ref closesocket() is invoked.

    1261. 

  1261.  *

    1262. 

  1262.  ******************************************************************************/

    1263. 

  1263. int shutdown( SOCKET s, unsigned int how );

    1264. 

  1264. 

    1265. 

  1265. /***************************************************************************/ /*!

    1266. 

  1266.  *

    1267. 

  1267.  * @brief    Closes an existing socket.

    1268. 

  1268.  *

    1269. 

  1269.  *

    1270. 

  1270.  * @param s      Descriptor, identifying a socket to close.

    1271. 

  1271.  *

    1272. 

  1272.  *

    1273. 

  1273.  * @return This function returns:

    1274. 

  1274.  *   - @ref FNET_OK if no error occurs.

    1275. 

  1275.  *   - @ref SOCKET_ERROR if an error occurs. @n 

    1276. 

  1276.  *     The specific error code can be retrieved using the @ref fnet_error_get().

    1277. 

  1277.  *

    1278. 

  1278.  * @see socket()

    1279. 

  1279.  *

    1280. 

  1280.  ******************************************************************************

    1281. 

  1281.  *

    1282. 

  1282.  * This function releases the socket descriptor @c s, so that further 

    1283. 

  1283.  * references to @c s fail with the error @ref FNET_ERR_BAD_DESC.@n

    1284. 

  1284.  * An application should always have a matching call to the @ref closesocket() for 

    1285. 

  1285.  * each successful call to the @ref socket() to return any socket resources to

    1286. 

  1286.  * the system.@n

    1287. 

  1287.  * @n

    1288. 

  1288.  * For the @ref SOCK_STREAM sockets, the @ref SO_LINGER option controls the action 

    1289. 

  1289.  * of the closing, when unsent data is present on the socket and the @ref 

    1290. 

  1290.  * closesocket() function is performed. This option has effect on 

    1291. 

  1291.  * TCP sockets only. To enable or disable the @ref SO_LINGER option, the application 

    1292. 

  1292.  * should use the @ref linger structure. This structure includes the 

    1293. 

  1293.  * @c l_onoff and the @c l_linger fields. If the @c l_onoff has a non-zero value, 

    1294. 

  1294.  * then the @ref SO_LINGER is enabled. Otherwise, the @ref SO_LINGER option is 

    1295. 

  1295.  * disabled. The @c l_linger field includes the timeout in seconds.

    1296. 

  1296.  * If the @ref SO_LINGER option is not used 

    1297. 

  1297.  * , the remaining data of the output buffer can be sent after the execution 

    1298. 

  1298.  * of the @ref closesocket() in the background.@n

    1299. 

  1299.  * If a timeout expires and unsent data is present, the hard reset occurs and

    1300. 

  1300.  * unsent data will be deleted.@n

    1301. 

  1301.  * If the @ref SO_LINGER option is used with a zero timeout interval, the 

    1302. 

  1302.  * hard reset occurs immediately and unsent data will be deleted.

    1303. 

  1303.  *

    1304. 

  1304.  ******************************************************************************/

    1305. 

  1305. int closesocket( SOCKET s );

    1306. 

  1306. 

    1307. 

  1307. /***************************************************************************/ /*!

    1308. 

  1308.  *

    1309. 

  1309.  * @brief    Sets a socket option.

    1310. 

  1310.  *

    1311. 

  1311.  *

    1312. 

  1312.  * @param s          Descriptor identifying a socket.

    1313. 

  1313.  *

    1314. 

  1314.  * @param level      Level, at which the option is defined.

    1315. 

  1315.  *                   The supported levels are @ref SOL_SOCKET, 

    1316. 

  1316.  *                   @ref IPPROTO_IP, @ref IPPROTO_IPV6 or @ref IPPROTO_TCP.

    1317. 

  1317.  *

    1318. 

  1318.  * @param optname    Socket option for which the value is to be set.

    1319. 

  1319.  *                   - for the @ref SOL_SOCKET level the options are defined by 

    1320. 

  1320.  *                     @ref fnet_socket_options_t.

    1321. 

  1321.  *                   - for the @ref IPPROTO_IP level the options are defined by 

    1322. 

  1322.  *                     @ref fnet_ip_options_t.

    1323. 

  1323.  *                   - for the @ref IPPROTO_IPV6 level the options are defined by 

    1324. 

  1324.  *                     @ref fnet_ip6_options_t.

    1325. 

  1325.  *                   - for the @ref IPPROTO_TCP level the options are defined by 

    1326. 

  1326.  *                     @ref fnet_tcp_options_t.

    1327. 

  1327.  *

    1328. 

  1328.  * @param optval     Pointer to a buffer, in which the value for the requested 

    1329. 

  1329.  *                   option is supplied.

    1330. 

  1330.  *

    1331. 

  1331.  * @param optlen     Size of the @c optval buffer.

    1332. 

  1332.  *

    1333. 

  1333.  *

    1334. 

  1334.  * @return This function returns:

    1335. 

  1335.  *   - @ref FNET_OK if no error occurs.

    1336. 

  1336.  *   - @ref SOCKET_ERROR if an error occurs. @n 

    1337. 

  1337.  *     The specific error code can be retrieved using the @ref fnet_error_get().

    1338. 

  1338.  *

    1339. 

  1339.  * @see getsockopt()

    1340. 

  1340.  *

    1341. 

  1341.  ******************************************************************************

    1342. 

  1342.  *

    1343. 

  1343.  * This function sets the current value for a socket option associated with the 

    1344. 

  1344.  * specified socket.@n

    1345. 

  1345.  * The various socket options are described by the @ref fnet_socket_options_t, 

    1346. 

  1346.  * @ref fnet_ip_options_t, and @ref fnet_tcp_options_t.

    1347. 

  1347.  *

    1348. 

  1348.  ******************************************************************************/

    1349. 

  1349. int setsockopt( SOCKET s, int level, int optname, char *optval, unsigned int optlen );

    1350. 

  1350. 

    1351. 

  1351. /***************************************************************************/ /*!

    1352. 

  1352.  *

    1353. 

  1353.  * @brief    Gets a socket option.

    1354. 

  1354.  *

    1355. 

  1355.  *

    1356. 

  1356.  * @param s          Descriptor identifying a socket.

    1357. 

  1357.  *

    1358. 

  1358.  * @param level      Level, at which the option is defined.

    1359. 

  1359.  *                   The supported levels are the @ref SOL_SOCKET, 

    1360. 

  1360.  *                   @ref IPPROTO_IP, @ref IPPROTO_IPV6 or @ref IPPROTO_TCP.

    1361. 

  1361.  *

    1362. 

  1362.  * @param optname    Socket option, for which the value is to be retrievied.

    1363. 

  1363.  *                   - for the @ref SOL_SOCKET level the options are defined by 

    1364. 

  1364.  *                     @ref fnet_socket_options_t.

    1365. 

  1365.  *                   - for the @ref IPPROTO_IP level the options are defined by 

    1366. 

  1366.  *                     @ref fnet_ip_options_t.

    1367. 

  1367.  *                   - for the @ref IPPROTO_IPV6 level the options are defined by 

    1368. 

  1368.  *                     @ref fnet_ip6_options_t. 

    1369. 

  1369.  *                   - for the @ref IPPROTO_TCP level the options are defined by 

    1370. 

  1370.  *                     @ref fnet_tcp_options_t.

    1371. 

  1371.  *

    1372. 

  1372.  * @param optval     Pointer to a buffer in which the value for the requested 

    1373. 

  1373.  *                   option has to be returned.

    1374. 

  1374.  *

    1375. 

  1375.  * @param optlen     Pointer to the size of the @c optval buffer.

    1376. 

  1376.  *

    1377. 

  1377.  *

    1378. 

  1378.  * @return This function returns:

    1379. 

  1379.  *   - @ref FNET_OK if no error occurs.

    1380. 

  1380.  *   - @ref SOCKET_ERROR if an error occurs. @n 

    1381. 

  1381.  *     The specific error code can be retrieved using the @ref fnet_error_get().

    1382. 

  1382.  *

    1383. 

  1383.  * @see setsockopt()

    1384. 

  1384.  *

    1385. 

  1385.  ******************************************************************************

    1386. 

  1386.  *

    1387. 

  1387.  * This function retrieves the current value for a socket option associated 

    1388. 

  1388.  * with the socket @c s, and stores the result in the @c optval.@n

    1389. 

  1389.  * The various socket options are described by the @ref fnet_socket_options_t, 

    1390. 

  1390.  * @ref fnet_ip_options_t, and @ref fnet_tcp_options_t.

    1391. 

  1391.  *

    1392. 

  1392.  ******************************************************************************/

    1393. 

  1393. int getsockopt( SOCKET s, int level, int optname, char *optval, unsigned int *optlen );

    1394. 

  1394. 

    1395. 

  1395. /***************************************************************************/ /*!

    1396. 

  1396.  *

    1397. 

  1397.  * @brief    Retrieves the name of a peer connected to a socket.

    1398. 

  1398.  *

    1399. 

  1399.  *

    1400. 

  1400.  * @param s          Descriptor identifying a connected socket.

    1401. 

  1401.  *

    1402. 

  1402.  * @param name       Structure that receives the name (address) of the peer.

    1403. 

  1403.  *

    1404. 

  1404.  * @param namelen    Pointer to the size of the @c name structure.

    1405. 

  1405.  *

    1406. 

  1406.  *

    1407. 

  1407.  * @return This function returns:

    1408. 

  1408.  *   - @ref FNET_OK if no error occurs.

    1409. 

  1409.  *   - @ref SOCKET_ERROR if an error occurs. @n 

    1410. 

  1410.  *     The specific error code can be retrieved using the @ref fnet_error_get().

    1411. 

  1411.  *

    1412. 

  1412.  * @see getsockname()

    1413. 

  1413.  *

    1414. 

  1414.  ******************************************************************************

    1415. 

  1415.  *

    1416. 

  1416.  * This function retrieves the name of the peer connected to the socket @c s 

    1417. 

  1417.  * and stores it in the @ref sockaddr structure identified by @c name.@n

    1418. 

  1418.  * The @ref getpeername() function can be used only with a connected socket.

    1419. 

  1419.  * For datagram sockets, only the name of a peer specified in a previous 

    1420. 

  1420.  * @ref connect() call will be returned - any name specified by a previous 

    1421. 

  1421.  * @ref sendto() call will not be returned by the @ref getpeername().

    1422. 

  1422.  *

    1423. 

  1423.  ******************************************************************************/

    1424. 

  1424. int getpeername( SOCKET s, struct sockaddr *name, unsigned int *namelen );

    1425. 

  1425. 

    1426. 

  1426. /***************************************************************************/ /*!

    1427. 

  1427.  *

    1428. 

  1428.  * @brief    Retrieves the current name for the specified socket.

    1429. 

  1429.  *

    1430. 

  1430.  *

    1431. 

  1431.  * @param s          Descriptor identifying a socket.

    1432. 

  1432.  *

    1433. 

  1433.  * @param name       Structure that receives the name (address) of the 

    1434. 

  1434.  *                   socket @c s.

    1435. 

  1435.  *

    1436. 

  1436.  * @param namelen    Pointer to the size of the @c name structure.

    1437. 

  1437.  *

    1438. 

  1438.  *

    1439. 

  1439.  * @return This function returns:

    1440. 

  1440.  *   - @ref FNET_OK if no error occurs.

    1441. 

  1441.  *   - @ref SOCKET_ERROR if an error occurs. @n 

    1442. 

  1442.  *     The specific error code can be retrieved using the @ref fnet_error_get().

    1443. 

  1443.  *

    1444. 

  1444.  * @see getpeername()

    1445. 

  1445.  *

    1446. 

  1446.  ******************************************************************************

    1447. 

  1447.  *

    1448. 

  1448.  * This function retrieves the current name for the specified socket @c s

    1449. 

  1449.  * and stores it in the @c name.@n

    1450. 

  1450.  * It is used on a bound or connected socket. 

    1451. 

  1451.  *

    1452. 

  1452.  ******************************************************************************/

    1453. 

  1453. int getsockname( SOCKET s, struct sockaddr *name, unsigned int *namelen );

    1454. 

  1454. 

    1455. 

  1455. /***************************************************************************/ /*!

    1456. 

  1456.  *

    1457. 

  1457.  * @brief    Compares socket addresses.

    1458. 

  1458.  *

    1459. 

  1459.  * @param addr1     First socket address to be compared.

    1460. 

  1460.  *

    1461. 

  1461.  * @param addr2     Second socket address to be compared.

    1462. 

  1462.  *

    1463. 

  1463.  * @return This function returns:

    1464. 

  1464.  *   - @ref FNET_TRUE if addresses are equal.

    1465. 

  1465.  *   - @ref FNET_FALSE if addresses are not equal. 

    1466. 

  1466.  *

    1467. 

  1467.  ******************************************************************************

    1468. 

  1468.  *

    1469. 

  1469.  * This function compares specified socket addresses, depending on address family. @n

    1470. 

  1470.  * Port number and Scope Id do not take part in process of comparison.

    1471. 

  1471.  *

    1472. 

  1472.  ******************************************************************************/

    1473. 

  1473. int fnet_socket_addr_are_equal(const struct sockaddr *addr1, const struct sockaddr *addr2);

    1474. 

  1474. 

    1475. 

  1475. /***************************************************************************/ /*!

    1476. 

  1476.  *

    1477. 

  1477.  * @brief    Determines, if socket address is unspecified.

    1478. 

  1478.  *

    1479. 

  1479.  * @param addr  Socket address.

    1480. 

  1480.  *

    1481. 

  1481.  * @return       This function returns:

    1482. 

  1482.  *   - @c FNET_TRUE if the address is unspecified.

    1483. 

  1483.  *   - @c FNET_FALSE if the address is specified.

    1484. 

  1484.  *

    1485. 

  1485.  ******************************************************************************

    1486. 

  1486.  *

    1487. 

  1487.  * This function determines if the socket address is unspecified 

    1488. 

  1488.  *  (IP address is set to all zeros) or not.

    1489. 

  1489.  *

    1490. 

  1490.  ******************************************************************************/

    1491. 

  1491. int fnet_socket_addr_is_unspecified(const struct sockaddr *addr);

    1492. 

  1492. 

    1493. 

  1493. /***************************************************************************/ /*!

    1494. 

  1494.  *

    1495. 

  1495.  * @brief    Determines, if socket address is multicast.

    1496. 

  1496.  *

    1497. 

  1497.  * @param addr  Socket address.

    1498. 

  1498.  *

    1499. 

  1499.  * @return       This function returns:

    1500. 

  1500.  *   - @c FNET_TRUE if the address is multicast.

    1501. 

  1501.  *   - @c FNET_FALSE if the address is not multicast.

    1502. 

  1502.  *

    1503. 

  1503.  ******************************************************************************

    1504. 

  1504.  *

    1505. 

  1505.  * This function determines if the socket address is multicast or not.

    1506. 

  1506.  *

    1507. 

  1507.  ******************************************************************************/

    1508. 

  1508. int fnet_socket_addr_is_multicast(const struct sockaddr *addr);

    1509. 

  1509. 

    1510. 

  1510. /*! @} */

    1511. 

  1511. 

    1512. 

  1512. #endif /* _FNET_SOCKET_H_ */

    1513. 

  1513.