UDP Sockets
[Socket API]

Application interface for UDP sockets. More...

Collaboration diagram for UDP Sockets:

Data Structures

struct  UDPSOCKET
 UDP socket information structure. More...

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.

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 195 of file udpsock.c.

References calloc, htons, IPPROTO_UDP, NutRegisterIpHandler(), NutUdpInput(), and udpSocketList.

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

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

Definition at line 241 of file udpsock.c.

References ENOMEM, memcpy(), NBAF_APPLICATION, NutNetBufAlloc(), NutNetBufFree(), and NutUdpOutput().

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

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.

Definition at line 282 of file udpsock.c.

References htons, memcpy(), NutEventWait(), NutNetBufFree(), and UDPHDR::uh_sport.

Referenced by DiscoveryResponder(), NutDnsGetResource(), NutDnsGetResourceAll(), 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 339 of file udpsock.c.

References free, NutNetBufFree(), and udpSocketList.

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

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.

Definition at line 391 of file udpsock.c.

References ENOTSOCK, and ntohs.

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 425 of file udpsock.c.

References udpSocketList.

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 453 of file udpsock.c.

References SO_RCVBUF.

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:

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 490 of file udpsock.c.

References SO_RCVBUF.

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:

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.

Definition at line 530 of file udpsock.c.

References NutEventPost().


Variable Documentation

UDPSOCKET* udpSocketList

Global linked list of all UDP sockets.

Definition at line 180 of file udpsock.c.

Referenced by NutDumpSocketList(), NutUdpCreateSocket(), NutUdpDestroySocket(), and NutUdpFindSocket().


© 2000-2010 by contributors - visit http://www.ethernut.de/