]> git.sur5r.net Git - freertos/blob - FreeRTOS-Plus/Source/FreeRTOS-Plus-TCP/include/FreeRTOS_Sockets.h
commit 9f316c246baafa15c542a5aea81a94f26e3d6507
[freertos] / FreeRTOS-Plus / Source / FreeRTOS-Plus-TCP / include / FreeRTOS_Sockets.h
1 /*
2  * FreeRTOS+TCP V2.2.0
3  * Copyright (C) 2017 Amazon.com, Inc. or its affiliates.  All Rights Reserved.
4  *
5  * Permission is hereby granted, free of charge, to any person obtaining a copy of
6  * this software and associated documentation files (the "Software"), to deal in
7  * the Software without restriction, including without limitation the rights to
8  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
9  * the Software, and to permit persons to whom the Software is furnished to do so,
10  * subject to the following conditions:
11  *
12  * The above copyright notice and this permission notice shall be included in all
13  * copies or substantial portions of the Software.
14  *
15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
17  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
18  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
19  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
20  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
21  *
22  * http://aws.amazon.com/freertos
23  * http://www.FreeRTOS.org
24  */
25
26 #ifndef FREERTOS_SOCKETS_H
27 #define FREERTOS_SOCKETS_H
28
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
32
33 /* Standard includes. */
34 #include <string.h>
35
36 /* Application level configuration options. */
37 #include "FreeRTOSIPConfig.h"
38
39 #ifndef FREERTOS_IP_CONFIG_H
40         #error FreeRTOSIPConfig.h has not been included yet
41 #endif
42
43 /* Event bit definitions are required by the select functions. */
44 #include "event_groups.h"
45
46 #ifndef INC_FREERTOS_H
47         #error FreeRTOS.h must be included before FreeRTOS_Sockets.h.
48 #endif
49
50 #ifndef INC_TASK_H
51         #ifndef TASK_H /* For compatibility with older FreeRTOS versions. */
52                 #error The FreeRTOS header file task.h must be included before FreeRTOS_Sockets.h.
53         #endif
54 #endif
55
56 /* Assigned to an Socket_t variable when the socket is not valid, probably
57 because it could not be created. */
58 #define FREERTOS_INVALID_SOCKET ( ( Socket_t ) ~0U )
59
60 /* API function error values.  As errno is supported, the FreeRTOS sockets
61 functions return error codes rather than just a pass or fail indication. */
62 /* HT: Extended the number of error codes, gave them positive values and if possible
63 the corresponding found in errno.h
64 In case of an error, API's will still return negative numbers, e.g.
65   return -pdFREERTOS_ERRNO_EWOULDBLOCK;
66 in case an operation would block */
67
68 /* The following defines are obsolete, please use -pdFREERTOS_ERRNO_Exxx */
69
70 #define FREERTOS_SOCKET_ERROR   ( -1 )
71 #define FREERTOS_EWOULDBLOCK    ( - pdFREERTOS_ERRNO_EWOULDBLOCK )
72 #define FREERTOS_EINVAL                 ( - pdFREERTOS_ERRNO_EINVAL )
73 #define FREERTOS_EADDRNOTAVAIL  ( - pdFREERTOS_ERRNO_EADDRNOTAVAIL )
74 #define FREERTOS_EADDRINUSE             ( - pdFREERTOS_ERRNO_EADDRINUSE )
75 #define FREERTOS_ENOBUFS                ( - pdFREERTOS_ERRNO_ENOBUFS )
76 #define FREERTOS_ENOPROTOOPT    ( - pdFREERTOS_ERRNO_ENOPROTOOPT )
77 #define FREERTOS_ECLOSED                ( - pdFREERTOS_ERRNO_ENOTCONN )
78
79 /* Values for the parameters to FreeRTOS_socket(), inline with the Berkeley
80 standard.  See the documentation of FreeRTOS_socket() for more information. */
81 #define FREERTOS_AF_INET                ( 2 )
82 #define FREERTOS_AF_INET6               ( 10 )
83 #define FREERTOS_SOCK_DGRAM             ( 2 )
84 #define FREERTOS_IPPROTO_UDP    ( 17 )
85
86 #define FREERTOS_SOCK_STREAM    ( 1 )
87 #define FREERTOS_IPPROTO_TCP    ( 6 )
88 /* IP packet of type "Any local network"
89  * can be used in stead of TCP for testing with sockets in raw mode
90  */
91 #define FREERTOS_IPPROTO_USR_LAN  ( 63 )
92
93 /* A bit value that can be passed into the FreeRTOS_sendto() function as part of
94 the flags parameter.  Setting the FREERTOS_ZERO_COPY in the flags parameter
95 indicates that the zero copy interface is being used.  See the documentation for
96 FreeRTOS_sockets() for more information. */
97 #define FREERTOS_ZERO_COPY              ( 1 )
98
99 /* Values that can be passed in the option name parameter of calls to
100 FreeRTOS_setsockopt(). */
101 #define FREERTOS_SO_RCVTIMEO                    ( 0 )           /* Used to set the receive time out. */
102 #define FREERTOS_SO_SNDTIMEO                    ( 1 )           /* Used to set the send time out. */
103 #define FREERTOS_SO_UDPCKSUM_OUT                ( 2 )           /* Used to turn the use of the UDP checksum by a socket on or off.  This also doubles as part of an 8-bit bitwise socket option. */
104 #if( ipconfigSOCKET_HAS_USER_SEMAPHORE == 1 )
105         #define FREERTOS_SO_SET_SEMAPHORE       ( 3 )           /* Used to set a user's semaphore */
106 #endif
107 #define FREERTOS_SO_SNDBUF                              ( 4 )           /* Set the size of the send buffer (TCP only) */
108 #define FREERTOS_SO_RCVBUF                              ( 5 )           /* Set the size of the receive buffer (TCP only) */
109
110 #if ipconfigUSE_CALLBACKS == 1
111         #define FREERTOS_SO_TCP_CONN_HANDLER    ( 6 )           /* Install a callback for (dis) connection events. Supply pointer to 'F_TCP_UDP_Handler_t' (see below) */
112         #define FREERTOS_SO_TCP_RECV_HANDLER    ( 7 )           /* Install a callback for receiving TCP data. Supply pointer to 'F_TCP_UDP_Handler_t' (see below) */
113         #define FREERTOS_SO_TCP_SENT_HANDLER    ( 8 )           /* Install a callback for sending TCP data. Supply pointer to 'F_TCP_UDP_Handler_t' (see below) */
114         #define FREERTOS_SO_UDP_RECV_HANDLER    ( 9 )           /* Install a callback for receiving UDP data. Supply pointer to 'F_TCP_UDP_Handler_t' (see below) */
115         #define FREERTOS_SO_UDP_SENT_HANDLER    ( 10 )          /* Install a callback for sending UDP data. Supply pointer to 'F_TCP_UDP_Handler_t' (see below) */
116 #endif /* ipconfigUSE_CALLBACKS */
117
118 #define FREERTOS_SO_REUSE_LISTEN_SOCKET ( 11 )          /* When a listening socket gets connected, do not create a new one but re-use it */
119 #define FREERTOS_SO_CLOSE_AFTER_SEND    ( 12 )          /* As soon as the last byte has been transmitted, finalise the connection */
120 #define FREERTOS_SO_WIN_PROPERTIES              ( 13 )          /* Set all buffer and window properties in one call, parameter is pointer to WinProperties_t */
121 #define FREERTOS_SO_SET_FULL_SIZE               ( 14 )          /* Refuse to send packets smaller than MSS  */
122
123 #define FREERTOS_SO_STOP_RX                             ( 15 )          /* Temporarily hold up reception, used by streaming client */
124
125 #if( ipconfigUDP_MAX_RX_PACKETS > 0 )
126         #define FREERTOS_SO_UDP_MAX_RX_PACKETS  ( 16 )          /* This option helps to limit the maximum number of packets a UDP socket will buffer */
127 #endif
128
129 #if( ipconfigSOCKET_HAS_USER_WAKE_CALLBACK == 1 )
130         #define FREERTOS_SO_WAKEUP_CALLBACK     ( 17 )
131 #endif
132
133 #define FREERTOS_SO_SET_LOW_HIGH_WATER  ( 18 )
134
135 #define FREERTOS_NOT_LAST_IN_FRAGMENTED_PACKET  ( 0x80 )  /* For internal use only, but also part of an 8-bit bitwise value. */
136 #define FREERTOS_FRAGMENTED_PACKET                              ( 0x40 )  /* For internal use only, but also part of an 8-bit bitwise value. */
137
138 /* Values for flag for FreeRTOS_shutdown(). */
139 #define FREERTOS_SHUT_RD                                ( 0 )           /* Not really at this moment, just for compatibility of the interface */
140 #define FREERTOS_SHUT_WR                                ( 1 )
141 #define FREERTOS_SHUT_RDWR                              ( 2 )
142
143 /* Values for flag for FreeRTOS_recv(). */
144 #define FREERTOS_MSG_OOB                                ( 2 )           /* process out-of-band data */
145 #define FREERTOS_MSG_PEEK                               ( 4 )           /* peek at incoming message */
146 #define FREERTOS_MSG_DONTROUTE                  ( 8 )           /* send without using routing tables */
147 #define FREERTOS_MSG_DONTWAIT                   ( 16 )          /* Can be used with recvfrom(), sendto(), recv(), and send(). */
148
149 typedef struct xWIN_PROPS {
150         /* Properties of the Tx buffer and Tx window */
151         int32_t lTxBufSize;     /* Unit: bytes */
152         int32_t lTxWinSize;     /* Unit: MSS */
153
154         /* Properties of the Rx buffer and Rx window */
155         int32_t lRxBufSize;     /* Unit: bytes */
156         int32_t lRxWinSize;     /* Unit: MSS */
157 } WinProperties_t;
158
159 typedef struct xLOW_HIGH_WATER {
160         /* Structure to pass for the 'FREERTOS_SO_SET_LOW_HIGH_WATER' option */
161         size_t uxLittleSpace;   /* Send a STOP when buffer space drops below X bytes */
162         size_t uxEnoughSpace;   /* Send a GO when buffer space grows above X bytes */
163 } LowHighWater_t;
164
165 /* For compatibility with the expected Berkeley sockets naming. */
166 #define socklen_t uint32_t
167
168 /* For this limited implementation, only two members are required in the
169 Berkeley style sockaddr structure. */
170 struct freertos_sockaddr
171 {
172         /* _HT_ On 32- and 64-bit architectures, the addition of the two uint8_t
173         fields doesn't make the structure bigger, due to alignment.
174         The fields are inserted as a preparation for IPv6. */
175
176         /* sin_len and sin_family not used in the IPv4-only release. */
177         uint8_t sin_len;                /* length of this structure. */
178         uint8_t sin_family;             /* FREERTOS_AF_INET. */
179         uint16_t sin_port;
180         uint32_t sin_addr;
181 };
182
183 #if ipconfigBYTE_ORDER == pdFREERTOS_LITTLE_ENDIAN
184
185         #define FreeRTOS_inet_addr_quick( ucOctet0, ucOctet1, ucOctet2, ucOctet3 )                              \
186                                                                                 ( ( ( ( uint32_t ) ( ucOctet3 ) ) << 24UL ) |           \
187                                                                                 ( ( ( uint32_t ) ( ucOctet2 ) ) << 16UL ) |                     \
188                                                                                 ( ( ( uint32_t ) ( ucOctet1 ) ) <<  8UL ) |                     \
189                                                                                 ( ( uint32_t ) ( ucOctet0 ) ) )
190
191         #define FreeRTOS_inet_ntoa( ulIPAddress, pucBuffer )                                                                    \
192                                                                 sprintf( ( char * ) ( pucBuffer ), "%u.%u.%u.%u",                       \
193                                                                         ( ( unsigned ) ( ( ulIPAddress ) & 0xffUL ) ),                  \
194                                                                         ( ( unsigned ) ( ( ( ulIPAddress ) >> 8 ) & 0xffUL ) ), \
195                                                                         ( ( unsigned ) ( ( ( ulIPAddress ) >> 16 ) & 0xffUL ) ),\
196                                                                         ( ( unsigned ) ( ( ulIPAddress ) >> 24 ) ) )
197
198 #else /* ipconfigBYTE_ORDER */
199
200         #define FreeRTOS_inet_addr_quick( ucOctet0, ucOctet1, ucOctet2, ucOctet3 )                              \
201                                                                                 ( ( ( ( uint32_t ) ( ucOctet0 ) ) << 24UL ) |           \
202                                                                                 ( ( ( uint32_t ) ( ucOctet1 ) ) << 16UL ) |                     \
203                                                                                 ( ( ( uint32_t ) ( ucOctet2 ) ) <<  8UL ) |                     \
204                                                                                 ( ( uint32_t ) ( ucOctet3 ) ) )
205
206         #define FreeRTOS_inet_ntoa( ulIPAddress, pucBuffer )                                                                    \
207                                                                 sprintf( ( char * ) ( pucBuffer ), "%u.%u.%u.%u",                       \
208                                                                         ( ( unsigned ) ( ( ulIPAddress ) >> 24 ) ),                             \
209                                                                         ( ( unsigned ) ( ( ( ulIPAddress ) >> 16 ) & 0xffUL ) ),\
210                                                                         ( ( unsigned ) ( ( ( ulIPAddress ) >> 8 ) & 0xffUL ) ), \
211                                                                         ( ( unsigned ) ( ( ulIPAddress ) & 0xffUL ) ) )
212
213 #endif /* ipconfigBYTE_ORDER */
214
215 /* The socket type itself. */
216 struct xSOCKET;
217 typedef struct xSOCKET *Socket_t;
218
219 /* The SocketSet_t type is the equivalent to the fd_set type used by the
220 Berkeley API. */
221 struct xSOCKET_SET;
222 typedef struct xSOCKET_SET *SocketSet_t;
223
224 /**
225  * FULL, UP-TO-DATE AND MAINTAINED REFERENCE DOCUMENTATION FOR ALL THESE
226  * FUNCTIONS IS AVAILABLE ON THE FOLLOWING URL:
227  * http://www.FreeRTOS.org/FreeRTOS-Plus/FreeRTOS_Plus_TCP/FreeRTOS_TCP_API_Functions.html
228  */
229 Socket_t FreeRTOS_socket( BaseType_t xDomain, BaseType_t xType, BaseType_t xProtocol );
230 int32_t FreeRTOS_recvfrom( Socket_t xSocket, void *pvBuffer, size_t xBufferLength, BaseType_t xFlags, struct freertos_sockaddr *pxSourceAddress, socklen_t *pxSourceAddressLength );
231 int32_t FreeRTOS_sendto( Socket_t xSocket, const void *pvBuffer, size_t xTotalDataLength, BaseType_t xFlags, const struct freertos_sockaddr *pxDestinationAddress, socklen_t xDestinationAddressLength );
232 BaseType_t FreeRTOS_bind( Socket_t xSocket, struct freertos_sockaddr *pxAddress, socklen_t xAddressLength );
233
234 /* function to get the local address and IP port */
235 size_t FreeRTOS_GetLocalAddress( Socket_t xSocket, struct freertos_sockaddr *pxAddress );
236
237 /* Made available when ipconfigETHERNET_DRIVER_FILTERS_PACKETS is set to 1. */
238 BaseType_t xPortHasUDPSocket( uint16_t usPortNr );
239
240 #if ipconfigUSE_TCP == 1
241
242 BaseType_t FreeRTOS_connect( Socket_t xClientSocket, struct freertos_sockaddr *pxAddress, socklen_t xAddressLength );
243 BaseType_t FreeRTOS_listen( Socket_t xSocket, BaseType_t xBacklog );
244 BaseType_t FreeRTOS_recv( Socket_t xSocket, void *pvBuffer, size_t xBufferLength, BaseType_t xFlags );
245 BaseType_t FreeRTOS_send( Socket_t xSocket, const void *pvBuffer, size_t uxDataLength, BaseType_t xFlags );
246 Socket_t FreeRTOS_accept( Socket_t xServerSocket, struct freertos_sockaddr *pxAddress, socklen_t *pxAddressLength );
247 BaseType_t FreeRTOS_shutdown (Socket_t xSocket, BaseType_t xHow);
248
249 #if( ipconfigSUPPORT_SIGNALS != 0 )
250         /* Send a signal to the task which is waiting for a given socket. */
251         BaseType_t FreeRTOS_SignalSocket( Socket_t xSocket );
252
253         /* Send a signal to the task which reads from this socket (FromISR
254         version). */
255         BaseType_t FreeRTOS_SignalSocketFromISR( Socket_t xSocket, BaseType_t *pxHigherPriorityTaskWoken );
256 #endif /* ipconfigSUPPORT_SIGNALS */
257
258 /* Return the remote address and IP port. */
259 BaseType_t FreeRTOS_GetRemoteAddress( Socket_t xSocket, struct freertos_sockaddr *pxAddress );
260
261 /* returns pdTRUE if TCP socket is connected */
262 BaseType_t FreeRTOS_issocketconnected( Socket_t xSocket );
263
264 /* returns the actual size of MSS being used */
265 BaseType_t FreeRTOS_mss( Socket_t xSocket );
266
267 /* for internal use only: return the connection status */
268 BaseType_t FreeRTOS_connstatus( Socket_t xSocket );
269
270 /* Returns the number of bytes that may be added to txStream */
271 BaseType_t FreeRTOS_maywrite( Socket_t xSocket );
272
273 /*
274  * Two helper functions, mostly for testing
275  * rx_size returns the number of bytes available in the Rx buffer
276  * tx_space returns the free space in the Tx buffer
277  */
278 BaseType_t FreeRTOS_rx_size( Socket_t xSocket );
279 BaseType_t FreeRTOS_tx_space( Socket_t xSocket );
280 BaseType_t FreeRTOS_tx_size( Socket_t xSocket );
281
282 /* Returns the number of outstanding bytes in txStream. */
283 /* The function FreeRTOS_outstanding() was already implemented
284 FreeRTOS_tx_size(). */
285 #define FreeRTOS_outstanding( xSocket ) FreeRTOS_tx_size( xSocket )
286
287 /* Returns the number of bytes in the socket's rxStream. */
288 /* The function FreeRTOS_recvcount() was already implemented
289 FreeRTOS_rx_size(). */
290 #define FreeRTOS_recvcount( xSocket )   FreeRTOS_rx_size( xSocket )
291
292 /*
293  * For advanced applications only:
294  * Get a direct pointer to the circular transmit buffer.
295  * '*pxLength' will contain the number of bytes that may be written.
296  */
297 uint8_t *FreeRTOS_get_tx_head( Socket_t xSocket, BaseType_t *pxLength );
298
299 #endif /* ipconfigUSE_TCP */
300
301 /*
302  * Connect / disconnect handler for a TCP socket
303  * For example:
304  *              static void vMyConnectHandler (Socket_t xSocket, BaseType_t ulConnected)
305  *              {
306  *              }
307  *              F_TCP_UDP_Handler_t xHnd = { vMyConnectHandler };
308  *              FreeRTOS_setsockopt( sock, 0, FREERTOS_SO_TCP_CONN_HANDLER, ( void * ) &xHnd, sizeof( xHnd ) );
309  */
310
311 typedef void (* FOnConnected_t )( Socket_t /* xSocket */, BaseType_t /* ulConnected */ );
312
313 /*
314  * Reception handler for a TCP socket
315  * A user-proved function will be called on reception of a message
316  * If the handler returns a positive number, the messages will not be stored
317  * For example:
318  *              static BaseType_t xOnTCPReceive( Socket_t xSocket, void * pData, size_t xLength )
319  *              {
320  *                      // handle the message
321  *                      return 1;
322  *              }
323  *              F_TCP_UDP_Handler_t xHand = { xOnTCPReceive };
324  *              FreeRTOS_setsockopt( sock, 0, FREERTOS_SO_TCP_RECV_HANDLER, ( void * ) &xHand, sizeof( xHand ) );
325  */
326 typedef BaseType_t (* FOnTCPReceive_t )( Socket_t /* xSocket */, void * /* pData */, size_t /* xLength */ );
327 typedef void (* FOnTCPSent_t )( Socket_t /* xSocket */, size_t /* xLength */ );
328
329 /*
330  * Reception handler for a UDP socket
331  * A user-proved function will be called on reception of a message
332  * If the handler returns a positive number, the messages will not be stored
333  */
334 typedef BaseType_t (* FOnUDPReceive_t ) (Socket_t /* xSocket */, void * /* pData */, size_t /* xLength */,
335         const struct freertos_sockaddr * /* pxFrom */, const struct freertos_sockaddr * /* pxDest */ );
336 typedef void (* FOnUDPSent_t )( Socket_t /* xSocket */, size_t /* xLength */ );
337
338
339 typedef union xTCP_UDP_HANDLER
340 {
341         FOnConnected_t  pxOnTCPConnected;       /* FREERTOS_SO_TCP_CONN_HANDLER */
342         FOnTCPReceive_t pxOnTCPReceive;         /* FREERTOS_SO_TCP_RECV_HANDLER */
343         FOnTCPSent_t    pxOnTCPSent;            /* FREERTOS_SO_TCP_SENT_HANDLER */
344         FOnUDPReceive_t pxOnUDPReceive;         /* FREERTOS_SO_UDP_RECV_HANDLER */
345         FOnUDPSent_t    pxOnUDPSent;            /* FREERTOS_SO_UDP_SENT_HANDLER */
346 } F_TCP_UDP_Handler_t;
347
348 BaseType_t FreeRTOS_setsockopt( Socket_t xSocket, int32_t lLevel, int32_t lOptionName, const void *pvOptionValue, size_t xOptionLength );
349 BaseType_t FreeRTOS_closesocket( Socket_t xSocket );
350 uint32_t FreeRTOS_gethostbyname( const char *pcHostName );
351 uint32_t FreeRTOS_inet_addr( const char * pcIPAddress );
352
353 /*
354  * For the web server: borrow the circular Rx buffer for inspection
355  * HTML driver wants to see if a sequence of 13/10/13/10 is available
356  */
357 const struct xSTREAM_BUFFER *FreeRTOS_get_rx_buf( Socket_t xSocket );
358
359 void FreeRTOS_netstat( void );
360
361 #if ipconfigSUPPORT_SELECT_FUNCTION == 1
362
363         /* For FD_SET and FD_CLR, a combination of the following bits can be used: */
364
365         typedef enum eSELECT_EVENT {
366                 eSELECT_READ    = 0x0001,
367                 eSELECT_WRITE   = 0x0002,
368                 eSELECT_EXCEPT  = 0x0004,
369                 eSELECT_INTR    = 0x0008,
370                 eSELECT_ALL             = 0x000F,
371                 /* Reserved for internal use: */
372                 eSELECT_CALL_IP = 0x0010,
373                 /* end */
374         } eSelectEvent_t;
375
376         SocketSet_t FreeRTOS_CreateSocketSet( void );
377         void FreeRTOS_DeleteSocketSet( SocketSet_t xSocketSet );
378         void FreeRTOS_FD_SET( Socket_t xSocket, SocketSet_t xSocketSet, EventBits_t xBitsToSet );
379         void FreeRTOS_FD_CLR( Socket_t xSocket, SocketSet_t xSocketSet, EventBits_t xBitsToClear );
380         EventBits_t FreeRTOS_FD_ISSET( Socket_t xSocket, SocketSet_t xSocketSet );
381         BaseType_t FreeRTOS_select( SocketSet_t xSocketSet, TickType_t xBlockTimeTicks );
382
383 #endif /* ipconfigSUPPORT_SELECT_FUNCTION */
384
385 #ifdef __cplusplus
386 } // extern "C"
387 #endif
388
389 #endif /* FREERTOS_SOCKETS_H */
390
391
392
393
394
395
396
397
398
399
400
401
402