Main Page | Modules | Alphabetical List | Data Structures | File List | Data Fields | Globals | Related Pages | Examples

TCP Sockets
[Socket API]


Detailed Description

TCP sockets.


Data Structures

struct  tcp_socket
 TCP socket information structure. More...

struct  tcp_socket
 TCP socket information structure. More...


Defines

#define SO_FIN
 Send FIN after all data has been transmitted.

#define SO_SYN
 Send SYN first.

#define SO_FORCE
 Force sending ACK.

#define SO_ACK
 Send ACK.

#define TICK_RATE

Typedefs

typedef tcp_socket TCPSOCKET
 TCP socket type.


Functions

void NutTcpDiscardBuffers (TCPSOCKET *sock)
void NutTcpDestroySocket (TCPSOCKET *sock)
 Destroy a previously allocated socket.

TCPSOCKETNutTcpFindSocket (u_short lport, u_short rport, u_long raddr)
 Find a matching socket.

TCPSOCKETNutTcpCreateSocket (void)
 Create a TCP socket.

int NutTcpSetSockOpt (TCPSOCKET *sock, int optname, CONST void *optval, int optlen)
 Set value of a TCP socket option.

int NutTcpGetSockOpt (TCPSOCKET *sock, int optname, void *optval, int optlen)
 Get a TCP socket option value.

int NutTcpConnect (TCPSOCKET *sock, u_long addr, u_short port)
 Connect to a remote socket.

int NutTcpAccept (TCPSOCKET *sock, u_short port)
 Wait for incoming connect from a remote socket.

int NutTcpSend (TCPSOCKET *sock, CONST void *data, u_short len)
 Send data on a connected TCP socket.

int NutTcpReceive (TCPSOCKET *sock, void *data, u_short size)
 Receive data on a connected TCP socket.

int NutTcpCloseSocket (TCPSOCKET *sock)
 Close TCP socket.

int NutTcpError (TCPSOCKET *sock)
 Return specific code of the last error.

int NutTcpDeviceRead (TCPSOCKET *sock, void *buffer, int size)
 Read from device.

int NutTcpDeviceWrite (TCPSOCKET *sock, CONST void *buf, int size)
 Write to a socket.

int NutTcpDeviceIOCtl (TCPSOCKET *sock, int cmd, void *param)
 Write to device. Driver control function.


Variables

TCPSOCKETtcpSocketList


Function Documentation

int NutTcpAccept TCPSOCKET sock,
u_short  port
 

Wait for incoming connect from a remote socket.

The calling thread will be suspended until until an incoming connection request is received.

This function is typically used by TCP server applications.

Parameters:
sock Socket descriptor. This pointer must have been retrieved by calling NutTcpCreateSocket().
port Port number to listen to (host byte order).
Returns:
0 on success, -1 otherwise. The specific error code can be retrieved by calling NutTcpError().

int NutTcpCloseSocket TCPSOCKET sock  ) 
 

Close TCP socket.

Note, that the socket may not be immediately destroyed after calling this function. However, the application must not use the socket after this call.

Parameters:
sock Socket descriptor. This pointer must have been retrieved by calling NutTcpCreateSocket().
Returns:
0 on success, -1 otherwise.

int NutTcpConnect TCPSOCKET sock,
u_long  addr,
u_short  port
 

Connect to a remote socket.

This function tries to establish a connection to the specified remote port of the specified remote server. The calling thread will be suspended until a connection is successfully established or an error occurs.

This function is typically used by TCP client applications.

Parameters:
sock Socket descriptor. This pointer must have been retrieved by calling NutTcpCreateSocket().
addr IP address of the host to connect (network byte order).
port Port number to connect (host byte order).
Returns:
0 on success, -1 otherwise. The specific error code can be retrieved by calling NutTcpError().

TCPSOCKET* NutTcpCreateSocket void   ) 
 

Create a TCP socket.

Allocates a TCPSOCKET structure from heap memory, initializes it and returns a pointer to that structure.

The first call will also start the TCP timer, which is required by various timeout checks.

Returns:
Socket descriptor of the newly created TCP socket or 0 if there is not enough memory left.

Todo:
Avoid fixed initial sequence number.

Configurable buffer size.

Allow larger maximum segment size.

void NutTcpDestroySocket TCPSOCKET sock  ) 
 

Destroy a previously allocated socket.

Remove socket from the socket list and release occupied memory.

Applications typically do not need to call this function. It is automatically called by a timer after the socket has been closed by NutTcpCloseSocket().

Parameters:
sock Socket descriptor. This pointer must have been retrieved by calling NutTcpCreateSocket().

int NutTcpDeviceIOCtl TCPSOCKET sock,
int  cmd,
void *  param
 

Write to device. Driver control function.

Used to modify or query device specific settings.

Parameters:
sock Socket descriptor. This pointer must have been retrieved by calling NutTcpCreateSocket().

int NutTcpDeviceRead TCPSOCKET sock,
void *  buffer,
int  size
 

Read from device.

Parameters:
sock Socket descriptor. This pointer must have been retrieved by calling NutTcpCreateSocket().

int NutTcpDeviceWrite TCPSOCKET sock,
CONST void *  buf,
int  size
 

Write to a socket.

In contrast to NutTcpSend() this routine provides some buffering.

Parameters:
sock Socket descriptor. This pointer must have been retrieved by calling NutTcpCreateSocket().

int NutTcpError TCPSOCKET sock  ) 
 

Return specific code of the last error.

Possible error codes (net/errno.h) are:

  • EWOULDBLOCK: Operation would block
  • EINPROGRESS: Operation now in progress
  • EALREADY: Operation already in progress
  • ENOTSOCK: Socket operation on non-socket
  • EDESTADDRREQ: Destination address required
  • EMSGSIZE: Message too long
  • EPROTOTYPE: Protocol wrong type for socket
  • ENOPROTOOPT: Protocol not available
  • EPROTONOSUPPORT: Protocol not supported
  • ESOCKTNOSUPPORT: Socket type not supported
  • EOPNOTSUPP: Operation not supported on socket
  • EPFNOSUPPORT: Protocol family not supported
  • EAFNOSUPPORT: Address family not supported by protocol family
  • EADDRINUSE: Address already in use
  • EADDRNOTAVAIL: Can't assign requested address
  • ENETDOWN: Network is down
  • ENETUNREACH: Network is unreachable
  • ENETRESET: Network dropped connection on reset
  • ECONNABORTED: Software caused connection abort
  • ECONNRESET: Connection reset by peer
  • ENOBUFS: No buffer space available
  • EISCONN: Socket is already connected
  • ENOTCONN: Socket is not connected
  • ESHUTDOWN: Can't send after socket shutdown
  • ETOOMANYREFS: Too many references: can't splice
  • ETIMEDOUT: Connection timed out
  • ECONNREFUSED: Connection refused
  • ELOOP: Too many levels of symbolic links
  • ENAMETOOLONG: File name too long
  • EHOSTDOWN: Host is down
  • EHOSTUNREACH: No route to host
  • ENOTEMPTY: Directory not empty

Parameters:
sock Socket descriptor. This pointer must have been retrieved by calling NutTcpCreateSocket().
Note:
Applications must not call this function to retrieve the error code if NutTcpCloseSocket() or NutTcpDestroySocket() failed.

Bug:
Not all error codes are properly set right now. Some socket functions return an error without setting an error code.

TCPSOCKET* NutTcpFindSocket u_short  lport,
u_short  rport,
u_long  raddr
 

Find a matching socket.

Loop through all sockets and find a matching connection (prefered) or a listening socket.

Applications typically do not need to call this function.

Parameters:
lport Local port number.
rport Remote port number.
raddr Remote IP address in network byte order.
Returns:
Socket descriptor.

int NutTcpGetSockOpt TCPSOCKET sock,
int  optname,
void *  optval,
int  optlen
 

Get a TCP socket option value.

The following values can be set:

  • TCP_MAXSEG Maximum segment size (u_short).
  • SO_SNDTIMEO Socket send timeout (u_long).
  • SO_RCVTIMEO Socket receive timeout (u_long).
  • SO_SNDBUF Socket output buffer size (u_short).

Parameters:
sock Socket descriptor. This pointer must have been retrieved by calling NutTcpCreateSocket().
optname Option to get.
optval Points to a buffer receiving the value.
optlen Length of the value buffer.
Returns:
0 on success, -1 otherwise. The specific error code can be retrieved by calling NutTcpError().

int NutTcpReceive TCPSOCKET sock,
void *  data,
u_short  size
 

Receive data on a connected TCP socket.

Parameters:
sock Socket descriptor. This pointer must have been retrieved by calling NutTcpCreateSocket(). In addition a connection must have been established by calling NutTcpConnect or NutTcpAccept.
data Pointer to the buffer that receives the data.
size Size of the buffer.
Returns:
If successful, the number of received data bytes is returned. This may be less than the specified size of the buffer. The return value 0 indicates a timeout, while -1 is returned in case of an error or broken connection. Call NutTcpError() to determine the specific error code.

int NutTcpSend TCPSOCKET sock,
CONST void *  data,
u_short  len
 

Send data on a connected TCP socket.

Parameters:
sock Socket descriptor. This pointer must have been retrieved by calling NutTcpCreateSocket(). In addition a connection must have been established by calling NutTcpConnect or NutTcpAccept.
data Pointer to a buffer containing the data to send.
len Number of bytes to be sent.
Returns:
If successful, the number of bytes added to the socket transmit buffer. This may be less than the specified number of bytes to send. The return value -1 indicates a fatal error.

int NutTcpSetSockOpt TCPSOCKET sock,
int  optname,
CONST void *  optval,
int  optlen
 

Set value of a TCP socket option.

The following values can be set:

  • TCP_MAXSEG Maximum segment size (u_short).
  • SO_SNDTIMEO Socket send timeout (u_long).
  • SO_RCVTIMEO Socket receive timeout (u_long).
  • SO_SNDBUF Socket output buffer size (u_short).

Parameters:
sock Socket descriptor. This pointer must have been retrieved by calling NutTcpCreateSocket().
optname Option to set.
optval Pointer to the value.
optlen Length of the value.
Returns:
0 on success, -1 otherwise. The specific error code can be retrieved by calling NutTcpError().


Variable Documentation

TCPSOCKET* tcpSocketList
 

Linked list of all TCP sockets.


© 2000-2003 by egnite Software GmbH - visit http://www.ethernut.de/