Nut/OS API

This is quite similar to the traditional Berkley TCP Socket API used on desktop PCs.

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;
     }
 }

Define Documentation

#define SO_FIN 0x01

Socket transmit flag.

Send FIN after all data has been transmitted.

Function Documentation

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().

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.

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.

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). Can only be set if socket is not yet connected.
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().

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 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().

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

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

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 NutTcpDeviceWrite_P	(	TCPSOCKET *	sock,
		PGM_P	buffer,
		int	size
	)

Write to device.

This function is implemented for CPUs with Harvard Architecture only.

TCP sockets can be used like other Nut/OS devices. This routine is part of the virtual socket device driver and similar to NutTcpDeviceWrite() except that the data is located in program memory.

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

Parameters:

	sock	Socket descriptor. This pointer must have been retrieved by calling NutTcpCreateSocket().
	buffer	Pointer to the data in program space to be written.
	size	Number of bytes to write.

Warning:: Inefficient implementation. No buffering has been implemented. Thus, each call will result in a separate TCP segment.

int NutTcpDeviceIOCtl	(	TCPSOCKET *	sock,
		int	cmd,
		void *	param
	)

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: IOCTL_GETFILESIZE IOCTL_GETINBUFCOUNT IOCTL_GETOUTBUFCOUNT
	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.

TCP Sockets
[Socket API]

Detailed Description

Data Structures

Defines

Typedefs

Functions

Variables

Define Documentation

Function Documentation

Variable Documentation


Data Structures
struct	tcp_socket
	TCP socket information structure. More...
Defines
#define	SO_FIN 0x01
	Socket transmit flag.
#define	SO_SYN 0x02
	Socket transmit flag.
#define	SO_FORCE 0x08
	Socket transmit flag.
#define	SO_ACK 0x10
	Socket transmit flag.
Typedefs
typedef tcp_socket	TCPSOCKET
	TCP socket type.
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	NutTcpDeviceWrite_P (TCPSOCKET *sock, PGM_P buffer, int size)
	Write to device.
int	NutTcpDeviceIOCtl (TCPSOCKET sock, int cmd, void param)
	Driver control function.
Variables
TCPSOCKET *	tcpSocketList = 0

TCP Sockets [Socket API]

Detailed Description

Data Structures

Defines

Typedefs

Functions

Variables

Define Documentation

Function Documentation

Variable Documentation

TCP Sockets
[Socket API]