UDP Sockets
[Socket API]

Collaboration diagram for UDP Sockets:

---

Detailed Description

Application interface for UDP sockets.

UDP server and client applications typically use this order of API calls

• NutUdpCreateSocket()
• NutUdpSendTo(), NutUdpReceiveFrom()
• NutUdpDestroySocket()

Assigning a stream to a UDP socket is not supported. Applications must use NutUdpSendTo() and NutUdpReceiveFrom().

For historical reasons, Nut/Net buffers only the last incoming UDP datagram for a specific port by default. Any previously received datagram will be discarded, if it hasn't been passed to the application in the meantime. Most applications will run fine with this. But it will fail for example, if more than one response is expected on a previously broadcasted request. This problem can be solved by calling NutUdpSetSockOpt() to specify a receive buffer size.

 #include <sys/socket.h>

 ...

 UDPSOCKET *sock;
 u_short udp_bufsiz = 1024;

 ...

 sock = NutUdpCreateSocket(20191);
 NutUdpSetSockOpt(sock, SO_RCVBUF, &udp_bufsiz, sizeof(udp_bufsiz));

Nut/Net supports connectionless UDP sockets only. A Berkley like bind call is not available.

Todo:

There is no similar call like NutTcpError() available for UDP.

Functions
UDPSOCKET *	NutUdpCreateSocket (u_short port)
	Create a UDP socket.
int	NutUdpSendTo (UDPSOCKET *sock, u_long addr, u_short port, void *data, u_short len)
	Send a UDP datagram.
int	NutUdpReceiveFrom (UDPSOCKET *sock, u_long *addr, u_short *port, void *data, u_short size, u_long timeout)
	Receive a UDP datagram.
int	NutUdpDestroySocket (UDPSOCKET *sock)
	Close UDP socket.
UDPSOCKET *	NutUdpFindSocket (u_short port)
	Find a matching socket.
int	NutUdpSetSockOpt (UDPSOCKET *sock, int optname, CONST void *optval, int optlen)
	Set value of a UDP socket option.
int	NutUdpGetSockOpt (UDPSOCKET *sock, int optname, void *optval, int optlen)
	Get a UDP socket option value.
Variables
UDPSOCKET *	udpSocketList

---

Function Documentation

UDPSOCKET* NutUdpCreateSocket (  u_short  port  )

Create a UDP socket. Parameters: port  Server applications provide the local port number with this parameter. Client applications should pass zero. Returns: Socket descriptor of the newly created UDP socket or 0 if there is not enough memory left.

int NutUdpSendTo (  UDPSOCKET *  sock, u_long  addr, u_short  port, void *  data, u_short  len )

Send a UDP datagram. Parameters: sock  Socket descriptor. This pointer must have been retrieved by calling NutUdpCreateSocket(). addr  IP address of the remote host in network byte order. port  Remote port number in host byte order. data  Pointer to a buffer containing the data to send. len  Number of bytes to be sent. Returns: 0 on success, -1 otherwise.

int NutUdpReceiveFrom (  UDPSOCKET *  sock, u_long *  addr, u_short *  port, void *  data, u_short  size, u_long  timeout )

Receive a UDP datagram. Parameters: sock  Socket descriptor. This pointer must have been retrieved by calling NutUdpCreateSocket(). addr  IP address of the remote host in network byte order. port  Remote port number in host byte order. data  Pointer to the buffer that receives the data. size  Size of the buffer that receives the data. timeout  Maximum number of milliseconds to wait. Returns: The number of bytes received, if successful. The return value -1 indicates an error. On timeout 0 is returned. Note: Timeout is limited to the granularity of the system timer.

int NutUdpDestroySocket (  UDPSOCKET *  sock  )

Close UDP socket. The memory occupied by the socket is immediately released after calling this function. The application must not use the socket after this call. Parameters: sock  Socket descriptor. This pointer must have been retrieved by calling NutUdpCreateSocket(). Returns: 0 on success, -1 otherwise.

UDPSOCKET* NutUdpFindSocket (  u_short  port  )

Find a matching socket. Loop through all sockets and find a matching one. Note: Applications typically do not need to call this function. Parameters: port  Local port number. Returns: Socket descriptor.

int NutUdpSetSockOpt (  UDPSOCKET *  sock, int  optname, CONST void *  optval, int  optlen )

Set value of a UDP socket option. The following values can be set: SO_RCVBUF Socket input buffer size (u_short). Parameters: sock  Socket descriptor. This pointer must have been retrieved by calling NutUdpCreateSocket(). optname  Option to set. optval  Pointer to the value. optlen  Length of the value. Returns: 0 on success, -1 otherwise.

int NutUdpGetSockOpt (  UDPSOCKET *  sock, int  optname, void *  optval, int  optlen )

Get a UDP socket option value. The following values can be set: SO_RCVBUF Socket input buffer size (u_short). Parameters: sock  Socket descriptor. This pointer must have been retrieved by calling NutUdpCreateSocket(). optname  Option to get. optval  Points to a buffer receiving the value. optlen  Length of the value buffer. Returns: 0 on success, -1 otherwise.

---

Variable Documentation

UDPSOCKET* udpSocketList

Global linked list of all UDP sockets.

---