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 struct EMBENET_UDP_SocketDescriptor EMBENET_UDP_SocketDescriptor |
Convenience alias for EMBENET_UDP_SocketDescriptor that SHALL be used in user's code
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.
[in] | socket | descriptor of the socket that received the data |
[in] | sourceAddress | IPv6 address of the sender |
[in] | sourcePort | source port number that was used in the sender to send the data |
[in] | data | pointer to memory region that holds the received data |
[in] | dataSize | size of the received data (in number of bytes) |
enum EMBENET_UDP_Traffic |
Possible types of an UDP socket that describe what is the socket's listening IPv6 address.
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] | socket | pointer to a valid socket descriptor structure |
EMBENET_Result EMBENET_UDP_UnregisterSocket | ( | EMBENET_UDP_SocketDescriptor * | socket | ) |
Unregisters socket from interface.
[in] | socket | pointer to valid socket descriptor instance |
EMBENET_RESULT_OK | if socket was successfully unregistered |
EMBENET_RESULT_UDP_SOCKET_UNREGISTERED | if the given socket has not been registered |
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] | socket | pointer to valid socket descriptor instance |
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.
[in] | socket | pointer to valid socket descriptor instance from which the data will be sent |
[in] | destinationAddress | IPv6 destination address |
[in] | destinationPort | UDP destination port number |
[in] | data | pointer to memory address storing UDP payload data |
[in] | dataSize | size of data in bytes (see EMBENET_UDP_GetMaxDataSize) |
EMBENET_RESULT_OK | if datagram was scheduled properly for sending |
EMBENET_RESULT_INVALID_ARGUMENT | if at least one of the input arguments was invalid |
EMBENET_RESULT_UDP_MAX_DATA_SIZE_EXCEEDED | if the size of the data to be sent is too large (see EMBENET_UDP_GetMaxDataSize) |
EMBENET_RESULT_UDP_PACKET_QUEUE_FULL | if there is not enough space to buffer the data to send |
EMBENET_RESULT_UDP_SOCKET_UNREGISTERED | if the given socket has not been registered |
Any question or remarks? Just write us a message!
Feel free to get in touch