TCP Sockets
[Nut/Net APISocket API]


Detailed Description

TCP sockets.


Data Structures

struct  tcp_socket
 TCP socket information structure. More...

Defines

#define SO_ACK   0x10
 Socket transmit flag. Send ACK.
#define SO_FIN   0x01
 Socket transmit flag. Send FIN after all data has been transmitted.
#define SO_FORCE   0x08
 Socket transmit flag. Force sending ACK.
#define SO_SYN   0x02
 Socket transmit flag. Send SYN first.

Typedefs

typedef tcp_socket TCPSOCKET
 TCP socket type.

Functions

int NutTcpAccept (TCPSOCKET *sock, u_short port)
 Wait for incoming connect from a remote socket.
int NutTcpCloseSocket (TCPSOCKET *sock)
 Close TCP socket.
int NutTcpConnect (TCPSOCKET *sock, u_long addr, u_short port)
 Connect to a remote socket.
TCPSOCKETNutTcpCreateSocket (void)
 Create a TCP socket.
void NutTcpDestroySocket (TCPSOCKET *sock)
 Destroy a previously allocated socket.
int NutTcpDeviceIOCtl (TCPSOCKET *sock, int cmd, void *param)
 Write to device.Driver control function.
int NutTcpDeviceRead (TCPSOCKET *sock, void *buffer, int size)
 Read from virtual socket device.
int NutTcpDeviceWrite (TCPSOCKET *sock, CONST void *buf, int size)
 Write to a socket.
void NutTcpDiscardBuffers (TCPSOCKET *sock)
int NutTcpError (TCPSOCKET *sock)
 Return specific code of the last error.
TCPSOCKETNutTcpFindSocket (u_short lport, u_short rport, u_long raddr)
 Find a matching socket.
int NutTcpGetSockOpt (TCPSOCKET *sock, int optname, void *optval, int optlen)
 Get a TCP socket option value.
int NutTcpReceive (TCPSOCKET *sock, void *data, u_short size)
 Receive data on a connected TCP socket.
int NutTcpSend (TCPSOCKET *sock, CONST void *data, u_short len)
 Send data on a connected TCP socket.
int NutTcpSetSockOpt (TCPSOCKET *sock, int optname, CONST void *optval, int optlen)
 Set value of a TCP socket option.

Variables

TCPSOCKETtcpSocketList = 0


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 very first call will also start the TCP state machine, which is running in a separate thread.

Returns:
Socket descriptor of the newly created TCP socket or 0 if there is not enough memory left.
Todo:
Avoid fixed initial sequence number.

void NutTcpDestroySocket ( TCPSOCKET sock  ) 

Destroy a previously allocated socket.

Remove socket from the socket list and release occupied memory.

Applications must not 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 by the virtual device driver to modify or query device specific settings.

Parameters:
sock Socket descriptor. This pointer must have been retrieved by calling NutTcpCreateSocket().
cmd Requested control function. May be set to one of the following constants:
param Points to a buffer that contains any data required for the given control function or receives data from that function.
Returns:
0 on success, -1 otherwise.

int NutTcpDeviceRead ( TCPSOCKET sock,
void *  buffer,
int  size 
)

Read from virtual socket device.

TCP sockets can be used like other Nut/OS devices. This routine is part of the virtual socket device driver.

This function is called by the low level input routines of the C runtime library, using the _NUTDEVICE::dev_read entry.

Parameters:
sock Socket descriptor. This pointer must have been retrieved by calling NutTcpCreateSocket().
buffer Pointer to the buffer that receives the data.
size Maximum number of bytes to read.
Returns:
The number of bytes read, which may be less than the number of bytes specified. A return value of -1 indicates an error, while zero is returned in case of a timeout.

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

Write to a socket.

TCP sockets can be used like other Nut/OS devices. This routine is part of the virtual socket device driver.

This function is called by the low level output routines of the C runtime library, using the _NUTDEVICE::dev_write entry.

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

Parameters:
sock Socket descriptor. This pointer must have been retrieved by calling NutTcpCreateSocket().
buf Pointer to the data to be written.
size Number of bytes to write. If zero, then the output buffer will be flushed.
Returns:
The number of bytes written. A return value of -1 indicates an error.

int NutTcpError ( TCPSOCKET sock  ) 

Return specific code of the last error.

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

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.
Todo:
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 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:

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 is limited to the maximum segment size of the connection and thus may be less than the specified number of bytes to send. The return value -1 indicates a fatal error. On time out, a value of 0 is returned.

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

Set value of a TCP socket option.

The following values can be set:

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 = 0

Global linked list of all TCP sockets.


Generated on Tue Jan 23 21:12:26 2007 for BTnut System Software by doxygen 1.4.7