socket.h
Go to the documentation of this file.
1 /**
2  * @file socket.h
3  * @brief Socket API
4  *
5  * @section License
6  *
7  * Copyright (C) 2010-2018 Oryx Embedded SARL. All rights reserved.
8  *
9  * This file is part of CycloneTCP Open.
10  *
11  * This program is free software; you can redistribute it and/or
12  * modify it under the terms of the GNU General Public License
13  * as published by the Free Software Foundation; either version 2
14  * of the License, or (at your option) any later version.
15  *
16  * This program is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19  * GNU General Public License for more details.
20  *
21  * You should have received a copy of the GNU General Public License
22  * along with this program; if not, write to the Free Software Foundation,
23  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
24  *
25  * @author Oryx Embedded SARL (www.oryx-embedded.com)
26  * @version 1.9.0
27  **/
28 
29 #ifndef _SOCKET_H
30 #define _SOCKET_H
31 
32 //Forward declaration of Socket structure
33 struct _Socket;
34 #define Socket struct _Socket
35 
36 //Dependencies
37 #include "core/net.h"
38 #include "core/ip.h"
39 #include "core/tcp.h"
40 
41 //Number of sockets that can be opened simultaneously
42 #ifndef SOCKET_MAX_COUNT
43  #define SOCKET_MAX_COUNT 16
44 #elif (SOCKET_MAX_COUNT < 1)
45  #error SOCKET_MAX_COUNT parameter is not valid
46 #endif
47 
48 //Dynamic port range (lower limit)
49 #ifndef SOCKET_EPHEMERAL_PORT_MIN
50  #define SOCKET_EPHEMERAL_PORT_MIN 49152
51 #elif (SOCKET_EPHEMERAL_PORT_MIN < 1024)
52  #error SOCKET_EPHEMERAL_PORT_MIN parameter is not valid
53 #endif
54 
55 //Dynamic port range (upper limit)
56 #ifndef SOCKET_EPHEMERAL_PORT_MAX
57  #define SOCKET_EPHEMERAL_PORT_MAX 65535
58 #elif (SOCKET_EPHEMERAL_PORT_MAX <= SOCKET_EPHEMERAL_PORT_MIN || SOCKET_EPHEMERAL_PORT_MAX > 65535)
59  #error SOCKET_EPHEMERAL_PORT_MAX parameter is not valid
60 #endif
61 
62 //C++ guard
63 #ifdef __cplusplus
64  extern "C" {
65 #endif
66 
67 
68 /**
69  * @brief Socket types
70  **/
71 
72 typedef enum
73 {
79 } SocketType;
80 
81 
82 /**
83  * @brief IP protocols
84  **/
85 
86 typedef enum
87 {
94 
95 
96 /**
97  * @brief Ethernet protocols
98  **/
99 
100 typedef enum
101 {
107 
108 
109 /**
110  * @brief Flags used by I/O functions
111  **/
112 
113 typedef enum
114 {
124 } SocketFlags;
125 
126 
127 //The SOCKET_FLAG_BREAK macro causes the I/O functions to stop reading
128 //data whenever the specified break character is encountered
129 #define SOCKET_FLAG_BREAK(c) (SOCKET_FLAG_BREAK_CHAR | LSB(c))
130 
131 
132 /**
133  * @brief Flags used by shutdown function
134  **/
135 
136 typedef enum
137 {
142 
143 
144 /**
145  * @brief Socket events
146  **/
147 
148 typedef enum
149 {
161 } SocketEvent;
162 
163 
164 /**
165  * @brief Host types
166  **/
167 
168 typedef enum
169 {
173 } HostType;
174 
175 
176 /**
177  * @brief Name resolution protocols
178  **/
179 
180 typedef enum
181 {
188 
189 
190 /**
191  * @brief Receive queue item
192  **/
193 
194 typedef struct _SocketQueueItem
195 {
198  uint16_t srcPort;
201  size_t offset;
203 
204 
205 /**
206  * @brief Structure describing a socket
207  **/
208 
209 struct _Socket
210 {
216  uint16_t localPort;
218  uint16_t remotePort;
220  uint8_t ttl;
226 
227 //TCP specific variables
228 #if (TCP_SUPPORT == ENABLED)
229  TcpState state; ///<Current state of the TCP finite state machine
230  bool_t ownedFlag; ///<The user is the owner of the TCP socket
231  bool_t closedFlag; ///<The connection has been closed properly
232  bool_t resetFlag; ///<The connection has been reset
233 
234  uint16_t smss; ///<Sender maximum segment size
235  uint16_t rmss; ///<Receiver maximum segment size
236  uint32_t iss; ///<Initial send sequence number
237  uint32_t irs; ///<Initial receive sequence number
238 
239  uint32_t sndUna; ///<Data that have been sent but not yet acknowledged
240  uint32_t sndNxt; ///<Sequence number of the next byte to be sent
241  uint16_t sndUser; ///<Amount of data buffered but not yet sent
242  uint16_t sndWnd; ///<Size of the send window
243  uint16_t maxSndWnd; ///<Maximum send window it has seen so far on the connection
244  uint32_t sndWl1; ///<Segment sequence number used for last window update
245  uint32_t sndWl2; ///<Segment acknowledgment number used for last window update
246 
247  uint32_t rcvNxt; ///<Receive next sequence number
248  uint16_t rcvUser; ///<Number of data received but not yet consumed
249  uint16_t rcvWnd; ///<Receive window
250 
251  bool_t rttBusy; ///<RTT measurement is being performed
252  uint32_t rttSeqNum; ///<Sequence number identifying a TCP segment
253  systime_t rttStartTime; ///<Round-trip start time
254  systime_t srtt; ///<Smoothed round-trip time
255  systime_t rttvar; ///<Round-trip time variation
256  systime_t rto; ///<Retransmission timeout
257 
258 #if (TCP_CONGEST_CONTROL_SUPPORT == ENABLED)
259  TcpCongestState congestState; ///<Congestion state
260  uint16_t cwnd; ///<Congestion window
261  uint16_t ssthresh; ///<Slow start threshold
262  uint_t dupAckCount; ///<Number of consecutive duplicate ACKs
263  uint_t n; ///<Number of bytes acknowledged during the whole round-trip
264  uint32_t recover; ///<NewReno modification to TCP's fast recovery algorithm
265 #endif
266 
267  TcpTxBuffer txBuffer; ///<Send buffer
268  size_t txBufferSize; ///<Size of the send buffer
269  TcpRxBuffer rxBuffer; ///<Receive buffer
270  size_t rxBufferSize; ///<Size of the receive buffer
271 
272  TcpQueueItem *retransmitQueue; ///<Retransmission queue
273  TcpTimer retransmitTimer; ///<Retransmission timer
274  uint_t retransmitCount; ///<Number of retransmissions
275 
276  TcpSynQueueItem *synQueue; ///<SYN queue for listening sockets
277  uint_t synQueueSize; ///<Maximum number of pending connections for listening sockets
278 
279  uint_t wndProbeCount; ///<Zero window probe counter
280  systime_t wndProbeInterval; ///<Interval between successive probes
281 
282  TcpTimer persistTimer; ///<Persist timer
283  TcpTimer overrideTimer; ///<Override timer
284  TcpTimer finWait2Timer; ///<FIN-WAIT-2 timer
285  TcpTimer timeWaitTimer; ///<2MSL timer
286 
287  bool_t sackPermitted; ///<SACK Permitted option received
288  TcpSackBlock sackBlock[TCP_MAX_SACK_BLOCKS]; ///<List of non-contiguous blocks that have been received
289  uint_t sackBlockCount; ///<Number of non-contiguous blocks that have been received
290 #endif
291 
292 //UDP specific variables
293 #if (UDP_SUPPORT == ENABLED || RAW_SOCKET_SUPPORT == ENABLED)
295 #endif
296 };
297 
298 
299 /**
300  * @brief Structure describing socket events
301  **/
302 
303 typedef struct
304 {
305  Socket *socket; ///<Handle to a socket to monitor
306  uint_t eventMask; ///<Requested events
307  uint_t eventFlags; ///<Returned events
309 
310 
311 //Global variables
313 
314 //Socket related functions
315 error_t socketInit(void);
316 
318 
322 
324 error_t socketBind(Socket *socket, const IpAddr *localIpAddr, uint16_t localPort);
325 error_t socketConnect(Socket *socket, const IpAddr *remoteIpAddr, uint16_t remotePort);
327 Socket *socketAccept(Socket *socket, IpAddr *clientIpAddr, uint16_t *clientPort);
328 
329 error_t socketSend(Socket *socket, const void *data,
330  size_t length, size_t *written, uint_t flags);
331 
333  const void *data, size_t length, size_t *written, uint_t flags);
334 
336  size_t size, size_t *received, uint_t flags);
337 
339  void *data, size_t size, size_t *received, uint_t flags);
340 
342  IpAddr *destIpAddr, void *data, size_t size, size_t *received, uint_t flags);
343 
344 error_t socketGetLocalAddr(Socket *socket, IpAddr *localIpAddr, uint16_t *localPort);
345 error_t socketGetRemoteAddr(Socket *socket, IpAddr *remoteIpAddr, uint16_t *remotePort);
346 
348 void socketClose(Socket *socket);
349 
350 error_t socketPoll(SocketEventDesc *eventDesc, uint_t size, OsEvent *extEvent, systime_t timeout);
354 
356  const char_t *name, IpAddr *ipAddr, uint_t flags);
357 
358 //C++ guard
359 #ifdef __cplusplus
360  }
361 #endif
362 
363 #endif
IpAddr srcIpAddr
Definition: socket.h:197
SYN queue item.
Definition: tcp.h:370
TcpState
TCP FSM states.
Definition: tcp.h:229
uint32_t systime_t
Definition: compiler_port.h:44
error_t socketGetRemoteAddr(Socket *socket, IpAddr *remoteIpAddr, uint16_t *remotePort)
Retrieve the address of the peer to which a socket is connected.
Definition: socket.c:730
Socket * socketAccept(Socket *socket, IpAddr *clientIpAddr, uint16_t *clientPort)
Permit an incoming connection attempt on a socket.
Definition: socket.c:457
error_t socketBind(Socket *socket, const IpAddr *localIpAddr, uint16_t localPort)
Associate a local address with a socket.
Definition: socket.c:331
uint16_t destPort
Definition: tcp.h:301
char char_t
Definition: compiler_port.h:41
uint8_t flags
Definition: tcp.h:312
Socket * socket
Handle to a socket to monitor.
Definition: socket.h:305
TcpTimer persistTimer
Persist timer.
Definition: socket.h:282
uint32_t iss
Initial send sequence number.
Definition: socket.h:236
error_t socketReceiveEx(Socket *socket, IpAddr *srcIpAddr, uint16_t *srcPort, IpAddr *destIpAddr, void *data, size_t size, size_t *received, uint_t flags)
Receive a datagram.
Definition: socket.c:625
error_t socketUnregisterEvents(Socket *socket)
Unsubscribe previously registered events.
Definition: socket.c:990
error_t socketBindToInterface(Socket *socket, NetInterface *interface)
Bind a socket to a particular network interface.
Definition: socket.c:309
TCP/IP stack core.
TcpTxBuffer txBuffer
Send buffer.
Definition: socket.h:267
uint_t synQueueSize
Maximum number of pending connections for listening sockets.
Definition: socket.h:277
uint32_t sndWl1
Segment sequence number used for last window update.
Definition: socket.h:244
uint16_t sndWnd
Size of the send window.
Definition: socket.h:242
uint_t dupAckCount
Number of consecutive duplicate ACKs.
Definition: socket.h:262
bool_t sackPermitted
SACK Permitted option received.
Definition: socket.h:287
error_t socketConnect(Socket *socket, const IpAddr *remoteIpAddr, uint16_t remotePort)
Establish a connection to a specified socket.
Definition: socket.c:357
uint32_t sndUna
Data that have been sent but not yet acknowledged.
Definition: socket.h:239
error_t socketReceiveFrom(Socket *socket, IpAddr *srcIpAddr, uint16_t *srcPort, void *data, size_t size, size_t *received, uint_t flags)
Receive a datagram from a connectionless socket.
Definition: socket.c:604
bool_t closedFlag
The connection has been closed properly.
Definition: socket.h:231
error_t socketGetEvents(Socket *socket, uint_t *eventFlags)
Retrieve event flags for a specified socket.
Definition: socket.c:1016
TcpSynQueueItem * synQueue
SYN queue for listening sockets.
Definition: socket.h:276
NetInterface * interface
Definition: socket.h:214
size_t offset
Definition: socket.h:201
IP network address.
Definition: ip.h:57
IPv4 and IPv6 common routines.
bool_t rttBusy
RTT measurement is being performed.
Definition: socket.h:251
SACK block.
Definition: tcp.h:386
TcpQueueItem * retransmitQueue
Retransmission queue.
Definition: socket.h:272
size_t rxBufferSize
Size of the receive buffer.
Definition: socket.h:270
uint_t retransmitCount
Number of retransmissions.
Definition: socket.h:274
TcpState state
Current state of the TCP finite state machine.
Definition: socket.h:229
error_t socketListen(Socket *socket, uint_t backlog)
Place a socket in the listening state.
Definition: socket.c:420
char_t type
error_t socketSend(Socket *socket, const void *data, size_t length, size_t *written, uint_t flags)
Send data to a connected socket.
Definition: socket.c:490
uint32_t rttSeqNum
Sequence number identifying a TCP segment.
Definition: socket.h:252
#define SOCKET_MAX_COUNT
Definition: socket.h:43
SocketType
Socket types.
Definition: socket.h:72
uint_t eventFlags
Returned events.
Definition: socket.h:307
bool_t ownedFlag
The user is the owner of the TCP socket.
Definition: socket.h:230
Event object.
systime_t wndProbeInterval
Interval between successive probes.
Definition: socket.h:280
error_t socketReceive(Socket *socket, void *data, size_t size, size_t *received, uint_t flags)
Receive data from a connected socket.
Definition: socket.c:584
int_t socket(int_t family, int_t type, int_t protocol)
Create a socket that is bound to a specific transport service provider.
Definition: bsd_socket.c:106
void socketClose(Socket *socket)
Close an existing socket.
Definition: socket.c:797
uint8_t ipAddr[4]
Definition: mib_common.h:185
#define TCP_MAX_SACK_BLOCKS
Definition: tcp.h:206
TcpSackBlock sackBlock[TCP_MAX_SACK_BLOCKS]
List of non-contiguous blocks that have been received.
Definition: socket.h:288
uint32_t sndNxt
Sequence number of the next byte to be sent.
Definition: socket.h:240
struct _SocketQueueItem SocketQueueItem
Receive queue item.
#define Socket
Definition: socket.h:34
systime_t timeout
Definition: socket.h:219
Socket socketTable[SOCKET_MAX_COUNT]
Definition: socket.c:46
uint_t n
Number of bytes acknowledged during the whole round-trip.
Definition: socket.h:263
IpAddr destIpAddr
Definition: socket.h:199
uint_t eventMask
Requested events.
Definition: socket.h:306
struct _SocketQueueItem * next
Definition: socket.h:196
signed int int_t
Definition: compiler_port.h:42
HostType
Host types.
Definition: socket.h:168
systime_t rttStartTime
Round-trip start time.
Definition: socket.h:253
char_t name[]
IpAddr remoteIpAddr
Definition: socket.h:217
uint_t protocol
Definition: socket.h:213
error_t socketPoll(SocketEventDesc *eventDesc, uint_t size, OsEvent *extEvent, systime_t timeout)
Wait for one of a set of sockets to become ready to perform I/O.
Definition: socket.c:857
SocketIpProtocol
IP protocols.
Definition: socket.h:86
SocketFlags
Flags used by I/O functions.
Definition: socket.h:113
uint16_t sndUser
Amount of data buffered but not yet sent.
Definition: socket.h:241
systime_t rttvar
Round-trip time variation.
Definition: socket.h:255
uint32_t sndWl2
Segment acknowledgment number used for last window update.
Definition: socket.h:245
SocketEthProtocol
Ethernet protocols.
Definition: socket.h:100
uint_t sackBlockCount
Number of non-contiguous blocks that have been received.
Definition: socket.h:289
Structure describing a buffer that spans multiple chunks.
Definition: net_mem.h:86
uint16_t maxSndWnd
Maximum send window it has seen so far on the connection.
Definition: socket.h:243
systime_t srtt
Smoothed round-trip time.
Definition: socket.h:254
int_t errnoCode
Definition: socket.h:221
Structure describing socket events.
Definition: socket.h:303
Ipv4Addr srcIpAddr
Definition: ipcp.h:75
NetBuffer * buffer
Definition: socket.h:200
error_t getHostByName(NetInterface *interface, const char_t *name, IpAddr *ipAddr, uint_t flags)
Resolve a host name into an IP address.
Definition: socket.c:1049
uint16_t cwnd
Congestion window.
Definition: socket.h:260
SocketQueueItem * receiveQueue
Definition: socket.h:294
Receive queue item.
Definition: socket.h:194
TcpTimer retransmitTimer
Retransmission timer.
Definition: socket.h:273
uint16_t srcPort
Definition: tcp.h:300
uint32_t recover
NewReno modification to TCP&#39;s fast recovery algorithm.
Definition: socket.h:264
error_t
Error codes.
Definition: error.h:40
TCP timer.
Definition: tcp.h:344
TcpCongestState
TCP congestion states.
Definition: tcp.h:249
uint32_t rcvNxt
Receive next sequence number.
Definition: socket.h:247
Ipv4Addr destIpAddr
Definition: ipcp.h:76
error_t socketSetTimeout(Socket *socket, systime_t timeout)
Set timeout value for blocking operations.
Definition: socket.c:216
SocketShutdownFlags
Flags used by shutdown function.
Definition: socket.h:136
unsigned int uint_t
Definition: compiler_port.h:43
uint32_t irs
Initial receive sequence number.
Definition: socket.h:237
TcpTimer timeWaitTimer
2MSL timer
Definition: socket.h:285
uint_t type
Definition: socket.h:212
uint8_t data[]
Definition: dtls_misc.h:167
#define NetInterface
Definition: net.h:34
error_t socketInit(void)
Socket related initialization.
Definition: socket.c:54
uint16_t rcvWnd
Receive window.
Definition: socket.h:249
OsEvent * userEvent
Definition: socket.h:225
uint8_t ttl
Definition: socket.h:220
TcpCongestState congestState
Congestion state.
Definition: socket.h:259
TcpRxBuffer rxBuffer
Receive buffer.
Definition: socket.h:269
TcpTimer overrideTimer
Override timer.
Definition: socket.h:283
uint16_t remotePort
Definition: socket.h:218
uint_t wndProbeCount
Zero window probe counter.
Definition: socket.h:279
error_t socketSendTo(Socket *socket, const IpAddr *destIpAddr, uint16_t destPort, const void *data, size_t length, size_t *written, uint_t flags)
Send a datagram to a specific destination.
Definition: socket.c:511
TcpTimer finWait2Timer
FIN-WAIT-2 timer.
Definition: socket.h:284
Structure describing a socket.
Definition: socket.h:209
uint_t descriptor
Definition: socket.h:211
OsEvent event
Definition: socket.h:222
size_t txBufferSize
Size of the send buffer.
Definition: socket.h:268
uint16_t srcPort
Definition: socket.h:198
uint16_t localPort
Definition: socket.h:216
Receive buffer.
Definition: tcp.h:409
Transmit buffer.
Definition: tcp.h:397
uint16_t rcvUser
Number of data received but not yet consumed.
Definition: socket.h:248
uint_t eventFlags
Definition: socket.h:224
Socket * socketOpen(uint_t type, uint_t protocol)
Create a socket (UDP or TCP)
Definition: socket.c:92
error_t socketRegisterEvents(Socket *socket, OsEvent *event, uint_t eventMask)
Subscribe to the specified socket events.
Definition: socket.c:936
uint16_t rmss
Receiver maximum segment size.
Definition: socket.h:235
error_t socketSetTxBufferSize(Socket *socket, size_t size)
Specify the size of the send buffer.
Definition: socket.c:241
bool_t resetFlag
The connection has been reset.
Definition: socket.h:232
uint8_t protocol
uint16_t smss
Sender maximum segment size.
Definition: socket.h:234
systime_t rto
Retransmission timeout.
Definition: socket.h:256
HostnameResolver
Name resolution protocols.
Definition: socket.h:180
Retransmission queue item.
Definition: tcp.h:356
error_t socketGetLocalAddr(Socket *socket, IpAddr *localIpAddr, uint16_t *localPort)
Retrieve the local address for a given socket.
Definition: socket.c:703
uint8_t length
Definition: dtls_misc.h:140
TCP (Transmission Control Protocol)
error_t socketShutdown(Socket *socket, uint_t how)
Disable reception, transmission, or both.
Definition: socket.c:760
uint16_t ssthresh
Slow start threshold.
Definition: socket.h:261
error_t socketSetRxBufferSize(Socket *socket, size_t size)
Specify the size of the receive buffer.
Definition: socket.c:275
IpAddr localIpAddr
Definition: socket.h:215
int bool_t
Definition: compiler_port.h:47
SocketEvent
Socket events.
Definition: socket.h:148
uint_t eventMask
Definition: socket.h:223