Application interface for UDP sockets. More...

Collaboration diagram for UDP Sockets:

Data Structures
struct	udp_socket
	UDP socket information structure. More...
Typedefs
typedef struct udp_socket	UDPSOCKET
	UDP socket type.
Functions
UDPSOCKET *	NutUdpCreateSocket (uint16_t port)
	Create a UDP socket.
int	NutUdpSendTo (UDPSOCKET sock, uint32_t addr, uint16_t port, void data, int len)
	Send a UDP datagram.
int	NutUdpReceiveFrom (UDPSOCKET sock, uint32_t addr, uint16_t port, void data, int size, uint32_t timeout)
	Receive a UDP datagram.
int	NutUdpDestroySocket (UDPSOCKET *sock)
	Close UDP socket.
int	NutUdpError (UDPSOCKET sock, uint32_t addr, uint16_t *port)
	Return specific code of the last error and the IP address / port of the host to which the communication failed.
UDPSOCKET *	NutUdpFindSocket (uint16_t 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.
int	NutUdpSetSocketError (UDPSOCKET *sock, uint32_t remote_addr, uint16_t remote_port, uint16_t error)
	Set a UDP socket error.
Variables
UDPSOCKET *	udpSocketList

Detailed Description

Application interface for UDP sockets.

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

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.

Typedef Documentation

typedef struct udp_socket UDPSOCKET

UDP socket type.

Function Documentation

UDPSOCKET* NutUdpCreateSocket ( uint16_t 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.

References calloc, htons, IPPROTO_UDP, NULL, NutGetMillis(), NutRegisterIpHandler(), NutUdpInput(), udp_socket::so_local_port, udp_socket::so_next, and udpSocketList.

Referenced by DiscoveryResponder(), main(), NotifyTask(), NutDhcpClient(), NutDnsGetResource(), NutDnsGetResourceAll(), NutSNTPGetTime(), NutWinsNameQuery(), openlog(), SnmpSessionOpen(), and SSDPTask().

Here is the call graph for this function:

int NutUdpSendTo	(	UDPSOCKET *	sock,
		uint32_t	addr,
		uint16_t	port,
		void *	data,
		int	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. The specific error code can be retrieved by calling NutUdpError().

References ENOMEM, memcpy(), _NETBUF::nb_ap, NBAF_APPLICATION, NutNetBufAlloc(), NutNetBufFree(), NutUdpOutput(), rc, udp_socket::so_last_error, and _NBDATA::vp.

Referenced by DiscoveryResponder(), main(), NutDnsGetResource(), NutDnsGetResourceAll(), NutSNTPGetTime(), NutWinsNameQuery(), SnmpAgent(), SnmpSessionSendPdu(), SSDPTask(), and syslog_flush().

Here is the call graph for this function:

int NutUdpReceiveFrom	(	UDPSOCKET *	sock,
		uint32_t *	addr,
		uint16_t *	port,
		void *	data,
		int	size,
		uint32_t	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 < 0 indicates an error. The specific error code can be retrieved by calling NutUdpError().

Note:: Timeout is limited to the granularity of the system timer.

References htons, ip::ip_src, memcpy(), _NETBUF::nb_ap, _NETBUF::nb_next, _NETBUF::nb_nw, _NETBUF::nb_tp, NutEventWait(), NutNetBufFree(), udp_socket::so_last_error, udp_socket::so_rx_cnt, udp_socket::so_rx_nb, udp_socket::so_rx_rdy, _NBDATA::sz, udphdr::uh_sport, and _NBDATA::vp.

Referenced by DiscoveryResponder(), NutDnsGetResource(), NutDnsGetResourceAll(), NutSNTPGetTime(), NutWinsNameQuery(), SnmpAgent(), SSDPTask(), and UDPReceiver().

Here is the call graph for this function:

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.

References free(), _NETBUF::nb_next, NutNetBufFree(), rc, udp_socket::so_next, udp_socket::so_rx_nb, and udpSocketList.

Referenced by closelog(), main(), NutDhcpClient(), NutDnsGetResource(), NutDnsGetResourceAll(), NutSNTPGetTime(), and SnmpSessionClose().

Here is the call graph for this function:

int NutUdpError	(	UDPSOCKET *	sock,
		uint32_t *	addr,
		uint16_t *	port
	)

Return specific code of the last error and the IP address / port of the host to which the communication failed.

Possible error codes are:

ENOTSOCK: Socket operation on non-socket
EMSGSIZE: Message too long
ENOPROTOOPT: Protocol not available
EOPNOTSUPP: Operation not supported on socket
ENETUNREACH: Network is unreachable
ECONNREFUSED: Connection refused
EHOSTDOWN: Host is down
EHOSTUNREACH: No route to host

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.

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

Examples:: icmp-udp/icmp-udp.c.

References ENOTSOCK, ntohs, rc, udp_socket::so_last_error, udp_socket::so_remote_addr, and udp_socket::so_remote_port.

Referenced by main(), and UDPReceiver().

UDPSOCKET* NutUdpFindSocket ( uint16_t 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.

References udp_socket::so_local_port, and udp_socket::so_next.

Referenced by NutUdpInput().

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

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.

References rc, SO_RCVBUF, and udp_socket::so_rx_bsz.

Referenced by DiscoveryResponder(), main(), NutDhcpClient(), and NutSNTPGetTime().

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

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.

References rc, SO_RCVBUF, and udp_socket::so_rx_bsz.

int NutUdpSetSocketError	(	UDPSOCKET *	sock,
		uint32_t	remote_addr,
		uint16_t	remote_port,
		uint16_t	error
	)

Set a UDP socket error.

This function should only be used together (and from) the ICMP input routine

The following values can be set:

EHOSTUNREACH Host is unreachable

Parameters:

sock	Socket descriptor. This pointer must have been retrieved by calling NutUdpCreateSocket().
remote_addr	Remote IP address in network byte order
remote_port	Remote port in network byte order
error	Error number.

Returns:: 0 on success, -1 otherwise.

References NutEventPost(), udp_socket::so_last_error, udp_socket::so_remote_addr, udp_socket::so_remote_port, and udp_socket::so_rx_rdy.

Here is the call graph for this function:

Variable Documentation

UDPSOCKET* udpSocketList

Global linked list of all UDP sockets.

Referenced by NutUdpCreateSocket(), and NutUdpDestroySocket().

Data Structures

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

Function Documentation

Variable Documentation