Detailed Description

This page documents the embeNET UDP C API. The API consists of the following parts:

Socket management
EMBENET_UDP_RegisterSocket Registers an UDP socket.
EMBENET_UDP_UnregisterSocket Unregisters an UDP socket.
Sending data
EMBENET_UDP_GetMaxDataSize Gets the maximum amount of data that can be sent in a single UDP datagram.
EMBENET_UDP_Send Sends a single UDP datagram through a registered UDP socket.

To get more information on how to use this API refer to: Using UDP sockets

Data Structures

struct  EMBENET_UDP_SocketDescriptor
 Structure describing an UDP Socket. More...

Typedef Documentation

◆ EMBENET_UDP_SocketDescriptor

Convenience alias for EMBENET_UDP_SocketDescriptor that SHALL be used in user's code

◆ EMBENET_UDP_RxDataHandler

typedef void(* EMBENET_UDP_RxDataHandler) (EMBENET_UDP_SocketDescriptor const *socket, EMBENET_IPV6 const *sourceAddress, uint16_t sourcePort, void const *data, size_t dataSize)

Data reception handler that is called every time some data on a certain registered port is received.

During socket registration (see EMBENET_UDP_RegisterSocket) the user is expected to pass the callback function that will be called each time a UDP datagram is received through this socket. This typedef defines the format of such function.

This handler callback is called in non-privileged mode. It is called from a thread or main loop and not from an interrupt service routine.
[in]socketdescriptor of the socket that received the data
[in]sourceAddressIPv6 address of the sender
[in]sourcePortsource port number that was used in the sender to send the data
[in]datapointer to memory region that holds the received data
[in]dataSizesize of the received data (in number of bytes)

Enumeration Type Documentation


Possible types of an UDP socket that describe what is the socket's listening IPv6 address.


The socket only listens on node's unicast address.


The socket only listens on multicast address of given group.


The socket listens both on nodes unicast address or any matching multicast address - equivalent to IPv6 [::].

Function Documentation

◆ EMBENET_UDP_RegisterSocket()

EMBENET_Result EMBENET_UDP_RegisterSocket ( EMBENET_UDP_SocketDescriptor socket)

Registers a new UDP socket.

This function is used to register a new UDP socket, thus enabling data reception on the resulting address/port combination.

[in]socketpointer to a valid socket descriptor structure
The provided socket descriptor instance MUST be valid and accessible until EMBENET_UDP_UnregisterSocket. In particular, the descriptor SHALL NOT have automatic storage duration.
The user MAY register socket with EMBENET_UDP_SOCKET_TYPE_MULTICAST==socketType and group not joined by the node. The user will not receive messages on this socket until the node joines the required group
EMBENET_RESULT_OK if socket was properly registered, or error status when the registration failed

◆ EMBENET_UDP_UnregisterSocket()

EMBENET_Result EMBENET_UDP_UnregisterSocket ( EMBENET_UDP_SocketDescriptor socket)

Unregisters socket from interface.

[in]socketpointer to valid socket descriptor instance
Return values
EMBENET_RESULT_OKif socket was successfully unregistered
EMBENET_RESULT_UDP_SOCKET_UNREGISTEREDif the given socket has not been registered

◆ EMBENET_UDP_GetMaxDataSize()

size_t EMBENET_UDP_GetMaxDataSize ( EMBENET_UDP_SocketDescriptor const *  socket)

Gets the maximum size of a single UDP payload size.

This function returns the maximum size of data that can be sent in a single UDP datagram. This is the maximum allowed size of the data to be sent by a call to EMBENET_UDP_Send

[in]socketpointer to valid socket descriptor instance
maximum size of data that can be sent in a single UDP datagram (in number of bytes)


EMBENET_Result EMBENET_UDP_Send ( EMBENET_UDP_SocketDescriptor const *  socket,
EMBENET_IPV6 const *  destinationAddress,
uint16_t  destinationPort,
const void *  data,
size_t  dataSize 

Sends UDP datagram from the given socket.

This function schedules an UDP datagram to be sent.

An UDP datagram can be sent only from a registered port.
The source address of the resulting IPv6 Packet will always resolve to Node's UNICAST address
[in]socketpointer to valid socket descriptor instance from which the data will be sent
[in]destinationAddressIPv6 destination address
[in]destinationPortUDP destination port number
[in]datapointer to memory address storing UDP payload data
[in]dataSizesize of data in bytes (see EMBENET_UDP_GetMaxDataSize)
Return values
EMBENET_RESULT_OKif datagram was scheduled properly for sending
EMBENET_RESULT_INVALID_ARGUMENTif at least one of the input arguments was invalid
EMBENET_RESULT_UDP_MAX_DATA_SIZE_EXCEEDEDif the size of the data to be sent is too large (see EMBENET_UDP_GetMaxDataSize)
EMBENET_RESULT_UDP_PACKET_QUEUE_FULLif there is not enough space to buffer the data to send
EMBENET_RESULT_UDP_SOCKET_UNREGISTEREDif the given socket has not been registered
Go to Top