Collaboration diagram for * TCP Sockets:
![]() |
TCP clients typically use this order of API calls
This is quite similar to the traditional Berkley TCP Socket API used on desktop PCs.
The order of API calls for TCP servers is
Note, that this differs slightly from the Berkley API, where the initial socket is bound to a port and an additional socket is created when a connection is accepted. Nut/Net doesn't provide a bind call.
Most Nut/OS applications make use of the ability to assign a TCP socket to a stream and replace the somewhat primitive functions NutTcpSend() and NutTcpReceive() with stdio calls like fprintf() or fscanf().
#include <stdio.h> #include <sys/socket.h> ... TCPSOCKET *sock; FILE *stream; ... stream = _fdopen((int) sock, "r+b"); fprintf(stream, "Hello peer\r\n");
Remember, that Nut/OS streams are opened in text mode by default. Thus, we explicitly specify binary mode for the stream.
The application programmer can modify some default values of the TCP stack by calling NutTcpSetSockOpt(). This could be useful to fine tune the stack for maximum performance at minimum resource usage.
In addition you may call NutTcpSetSockOpt() to set a receive timeout in order to detect broken connections. That's often required, because TCP relies on a gracefully closed connection on the remote side. If the remote crashes or if the physical connection breaks, then NutTcpReceive() will never return unless a receive timeout value had been set. At least this is true for Nut/Net, which currently doesn't support the SO_KEEPALIVE option.
#include <sys/socket.h> ... UDPSOCKET *sock; u_long tmo = 3000; int rc; char buff[128]; ... NutTcpSetSockOpt(sock, SO_RCVTIMEO, &tmo, sizeof(tmo)); ... rc = NutTcpReceive(sock, buff, sizeof(buf)); if (rc == 0) { /* * A timeout occured. We will now perform an application specific * action to check wether our remote is still alive. */ ... }
Note again the difference to the Berkley API, where select() is used to determine receive timeouts.
Most socket API calls return -1 in case of a failure. The function NutTcpError() can be used to query a more specific error code.
#include <stdio.h> #include <sys/socket.h> ... TCPSOCKET *sock; u_long ip = inet_addr("192.168.1.100"); u_short port = 20191; int tcperr; ... if (NutTcpConnect(sock, ip, port)) { tcperr = NutTcpError(sock); printf("TCP Error: "); switch(tcperr) { case EHOSTUNREACH: printf("No route to %s\n", inet_ntoa(ip)); break; default: printf("%d\n", tcperr); break; } }
Data Structures | |
struct | tcp_socket |
TCP socket information structure. More... | |
Defines | |
#define | SO_FIN |
Socket transmit flag. | |
#define | SO_SYN |
Socket transmit flag. | |
#define | SO_FORCE |
Socket transmit flag. | |
#define | SO_ACK |
Socket transmit flag. | |
Functions | |
void | NutTcpDiscardBuffers (TCPSOCKET *sock) |
void | NutTcpDestroySocket (TCPSOCKET *sock) |
Destroy a previously allocated socket. | |
TCPSOCKET * | NutTcpFindSocket (u_short lport, u_short rport, u_long raddr) |
Find a matching socket. | |
TCPSOCKET * | NutTcpCreateSocket (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 virtual socket 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 | |
typedef *struct tcp_socket | TCPSOCKET |
TCP socket type. | |
*TCPSOCKET * | tcpSocketList |
|
Socket transmit flag. Send ACK. |
|
Socket transmit flag. Send FIN after all data has been transmitted. |
|
Socket transmit flag. Force sending ACK. |
|
Socket transmit flag. Send SYN first. |
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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().
|
|
Write to device.Driver control function. Used by the virtual device driver to modify or query device specific settings.
|
|
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.
|
|
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.
|
|
Return specific code of the last error. Possible error codes (net/errno.h) are:
|
|
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.
|
|
Get a TCP socket option value. The following values can be set:
|
|
Receive data on a connected TCP socket.
|
|
Send data on a connected TCP socket.
|
|
Set value of a TCP socket option. The following values can be set:
|
|
Global linked list of all TCP sockets. |