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

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.


Data Structures

struct  udp_socket
 UDP socket information structure. More...

Typedefs

typedef struct udp_socket UDPSOCKET
 UDP socket type.

Functions

UDPSOCKETNutUdpCreateSocket (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.
UDPSOCKETNutUdpFindSocket (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.

Variables

UDPSOCKETudpSocketList


Typedef Documentation

typedef struct udp_socket UDPSOCKET

UDP socket type.

Definition at line 154 of file sock_var.h.


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.

Definition at line 178 of file udpsock.c.

References htons, IPPROTO_UDP, NutHeapAllocClear(), NutRegisterIpHandler(), NutUdpInput(), udp_socket::so_local_port, and udp_socket::so_next.

Referenced by DiscoveryResponder(), NutDhcpClient(), NutDnsGetResource(), NutSNTPGetTime(), NutWinsNameQuery(), and openlog().

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.

Definition at line 222 of file udpsock.c.

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

Referenced by DiscoveryResponder(), NutDnsGetResource(), NutSNTPGetTime(), NutWinsNameQuery(), SnmpAgent(), vsyslog(), and vsyslog_P().

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 -1 indicates an error. On timeout 0 is returned.
Note:
Timeout is limited to the granularity of the system timer.

Definition at line 256 of file udpsock.c.

References htons, ip::ip_src, memcpy(), _NETBUF::nb_ap, _NETBUF::nb_next, _NETBUF::nb_nw, _NETBUF::nb_tp, NutEventWait(), NutNetBufFree(), 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(), NutSNTPGetTime(), NutWinsNameQuery(), and SnmpAgent().

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.

Definition at line 301 of file udpsock.c.

References _NETBUF::nb_next, NutHeapFree(), NutNetBufFree(), udp_socket::so_next, and udp_socket::so_rx_nb.

Referenced by closelog(), NutDhcpClient(), NutDnsGetResource(), and NutSNTPGetTime().

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.

Definition at line 341 of file udpsock.c.

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:

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.

Definition at line 369 of file udpsock.c.

References SO_RCVBUF, and udp_socket::so_rx_bsz.

Referenced by DiscoveryResponder(), 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:

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.

Definition at line 406 of file udpsock.c.

References SO_RCVBUF, and udp_socket::so_rx_bsz.


Variable Documentation

Global linked list of all UDP sockets.

Definition at line 163 of file udpsock.c.


© 2000-2007 by egnite Software GmbH - visit http://www.ethernut.de/