UDP protocol support
[Protocol stack]

---

Detailed Description

Implementation of the UDP protocol.

To receive UDP packets, a socket has to be allocated using udp_socket_alloc() and bound to a local port with udp_bind_local(). For each packet received, the socket callback function gets called.

For being able to send UDP packets, an additional call to udp_bind_remote() is needed. Binding a socket to a remote host has two consequences:

1. Incoming packets on this socket are forwarded only if they match the remote binding.
2. Transmitted packets are sent to the remote host and port of the remote binding.

Files
file	udp.c
	UDP implementation (license: GPLv2).
file	udp.h
	UDP header (license: GPLv2).
Modules
	UDP configuration
Defines
#define	udp_socket_valid(socket)
	Checks if the given number is a valid socket identifier.
#define	udp_get_buffer()
	Retrieves a pointer to the UDP transmit buffer.
#define	udp_get_buffer_size()
	Retrieves the maximum payload size of the transmit buffer.
Functions
void	udp_init ()
	Initializes the UDP layer.
bool	udp_handle_packet (const uint8_t *ip_remote, const struct udp_header *packet, uint16_t packet_len)
	Forwards incoming packets to the appropriate UDP socket.
int	udp_socket_alloc (udp_callback callback)
	Allocates a new UDP socket.
bool	udp_socket_free (int socket)
	Deallocates an UDP socket and makes it available for future allocations.
bool	udp_bind_local (int socket, uint16_t port_local)
	Bind an UDP socket to a local port.
bool	udp_bind_remote (int socket, const uint8_t *ip_remote, uint16_t port_remote)
	Bind an UDP socket to a remote port and optionally to a remote host.
bool	udp_unbind_remote (int socket)
	Remove the remote binding of an UDP socket.
bool	udp_send (int socket, uint16_t data_len)
	Send an UDP packet from the transmit buffer to a remote host.

---

Define Documentation

#define udp_socket_valid

(

socket

)

Checks if the given number is a valid socket identifier.

Parameters:

[in]

socket

The socket identifier to check.

Returns:

TRUE if the argument is a valid socket number, FALSE otherwise.

 

#define udp_get_buffer

(

)

Retrieves a pointer to the UDP transmit buffer.

For sending UDP packets, write your data to the buffer returned by this function and call udp_send_packet() afterwards.

Returns:

A pointer pointing to the beginning of the transmit buffer.

 

#define udp_get_buffer_size

(

)

Retrieves the maximum payload size of the transmit buffer.

You may not send more bytes per UDP packet than returned by this function.

Returns:

The maximum payload size per UDP packet.

---

Function Documentation

void udp_init

(

)

Initializes the UDP layer.

This function has to be called once on startup.

bool udp_handle_packet	(	const uint8_t *	ip_remote,
		const struct udp_header *	packet,
		uint16_t	packet_len
	)

Forwards incoming packets to the appropriate UDP socket.

Note:

This function is used internally and should not be explicitly called by applications.

Returns:

true if a matching socket was found, false if the packet was discarded.

int udp_socket_alloc

(

udp_callback

callback

)

Allocates a new UDP socket.

Each socket has an attached callback function which gets called for every packet which arrives on the socket.

A socket is identified by a non-negative integer. Use udp_socket_valid() to check if the returned socket is valid.

Parameters:

[in]

callback

Pointer to the callback function which gets attached to the new socket.

Returns:

The non-negative socket identifier on success, -1 on failure.

bool udp_socket_free

(

int

socket

)

Deallocates an UDP socket and makes it available for future allocations.

After freeing the socket, it can no longer be used.

Parameters:

[in]

socket

The identifier of the socket which is to be deallocated.

Returns:

true if the socket has been deallocated, false on failure.

bool udp_bind_local	(	int	socket,
		uint16_t	port_local
	)

Bind an UDP socket to a local port.

Specifies which port the incoming packet must be addressed to in order to be received by the socket.

Parameters:

[in]	socket	The identifier of the socket which is to be locally bound.
[in]	port_local	The port which should be bound to the socket.

Returns:

true if the binding could be established, false otherwise.

bool udp_bind_remote	(	int	socket,
		const uint8_t *	ip_remote,
		uint16_t	port_remote
	)

Bind an UDP socket to a remote port and optionally to a remote host.

Binding an UDP socket to a remote host and/or port has two consequences:

1. All packets sent via this socket are sent to this remote host.
2. Incoming packets are only forwarded to the application if their source ip and/or port matches the values the socket is bound to.

A remote ip of NULL means "broadcast"/"accept all".

Parameters:

[in]	socket	The identifier of the socket which is to be remotely bound.
[in]	ip_remote	The remote IP address of the host to which to bind the socket, or NULL.
[in]	port_remote	The remote port to which to bind the socket.

Returns:

true if the binding could be established, false otherwise.

bool udp_unbind_remote

(

int

socket

)

Remove the remote binding of an UDP socket.

Note that after the socket has been remotely unbound, it receives packets from any remote host which are sent to the socket's local port.

Parameters:

[in]

socket

The identifier of the socket which is to be remotely unbound.

Returns:

true if the binding could be removed, false otherwise.

bool udp_send	(	int	socket,
		uint16_t	data_len
	)

Send an UDP packet from the transmit buffer to a remote host.

Note that before using this function, the socket must have been locally and remotely bound via udp_socket_bind_local() and udp_socket_bind_remote().

Parameters:

[in]	socket	The identifier of the socket via which to send the packet.
[in]	data_len	The payload length of the packet.

Returns:

true if the packet was successfully sent, false on failure.