UDP

Types

Name	Type	Description
mira_net_udp_connection_t	struct
mira_net_udp_callback_t	void(*)(mira_net_udp_connection_t *connection, const void *data, uint16_t data_len, const mira_net_udp_callback_metadata_t *metadata, void *storage)

Structs

mira_net_udp_callback_metadata_t

Type	Name	Description
mira_net_address_t	source_address
mira_net_address_t	destination_address
uint16_t	source_port
uint16_t	destination_port

Functions

mira_net_udp_listen

mira_net_udp_connection_t* mira_net_udp_listen(
    uint16_t                 port,
    mira_net_udp_callback_t  callback,
    void*                    storage);

Listen the specified UDP port.

Parameters

Parameter	Description
port	The port number.
callback	Callback function with data.
storage	Storage pointer which is used to store optional information to be used by the callback function. E.g. it could be used as an identifier or to pass on a configuration struct.

Return

A UDP connection on the specified port.

mira_net_udp_listen_address

mira_net_udp_connection_t* mira_net_udp_listen_address(
    const mira_net_address_t*  address,
    uint16_t                   port,
    mira_net_udp_callback_t    callback,
    void*                      storage);

Listen to the specified UDP port and address.

Parameters

Parameter	Description
address	The listening link-local multicast address to bind to.
port	The port number.
callback	Callback function with data.
storage	Storage pointer which is used to store optional information to be used by the callback function. E.g. it could be used as an identifier or to pass on a configuration struct.

Return

A UDP connection on the specified port.

mira_net_udp_connect

mira_net_udp_connection_t* mira_net_udp_connect(
    const mira_net_address_t*  address,
    uint16_t                   port,
    mira_net_udp_callback_t    callback,
    void*                      storage);

Connect via UDP to the specified IP address and port.

Parameters

Parameter	Description
address	The IP address to connect to.
port	The port number to connect to. Discarded if address is NULL.
callback	UDP callback function.
storage	Storage pointer that is used to store optional information to be used by the callback function. E.g. it could be used as an identifier or to pass on a configuration struct.

Return

UDP connection.

mira_net_udp_bind

mira_net_udp_connection_t* mira_net_udp_bind(
    const mira_net_address_t*  remote_address,
    uint16_t                   remote_port,
    uint16_t                   local_port,
    mira_net_udp_callback_t    callback,
    void*                      storage);

Bind a socket and sets up a connection.

Parameters

Parameter	Description
remote_address	IP address to bind to.
remote_port	The remote port to connect to. Discarded if address is NULL.
local_port	The local port to bind the connection to.
callback	UDP callback function.
storage	Storage pointer which is used to store optional information to be used by the callback function. E.g. it could be used as an identifier or to pass on a configuration struct.

Return

The UDP Connection.

mira_net_udp_bind_address

mira_net_udp_connection_t* mira_net_udp_bind_address(
    const mira_net_address_t*  remote_address,
    const mira_net_address_t*  local_address,
    uint16_t                   remote_port,
    uint16_t                   local_port,
    mira_net_udp_callback_t    callback,
    void*                      storage);

Binds a socket to a local address and/or sets up a connection.

Parameters

Parameter	Description
remote_address	IP address to bind to.
local_address	The listening link-local multicast address to bind to.
remote_port	The remote port to connect to.
local_port	The local port to bind the connection to.
callback	UDP callback function.
storage	Storage pointer which is used to store optional information to be used by the callback function. E.g. it could be used as an identifier or to pass on a configuration struct.

Return

The UDP Connection.

mira_net_udp_close

mira_status_t mira_net_udp_close(
    mira_net_udp_connection_t*  mira_udp_connection);

Close the specified connection.

Parameters

Parameter	Description
mira_udp_connection	The UDP connection to close.

Return

MIRA_SUCCESS if successful.

MIRA_NET_ERROR_INVALID_SOCKET if socket is not free.

MIRA_ERROR_INVALID_VALUE if wrong input parameter.

mira_net_udp_multicast_group_join

mira_status_t mira_net_udp_multicast_group_join(
    mira_net_udp_connection_t*  mira_udp_connection,
    const mira_net_address_t*   multicast_address);

Join a multicast group.

Add a socket to a multicast group.

To be able to receive packets to a multicast address, a multicast group needs to be joined, and the socket needs to listen to all addresses (default) or to the multicast address (using mira_net_udp_listen_address or mira_net_udp_bind_address)

The node leaves the group when closing the socket or calling mira_net_udp_multicast_group_leave() on the same group.

If multiple sockets have joined the same group, the group will be removed when no sockets remain bound to the address.

To control latency and current consumption, the address needs to follow a certain the format: ff02::3fRR:XXXX, where RR is the rate, from 0-31, same as for mira_net_init(). XXXX is an any number.

Lower value of rate decreases latency and increases throughput, to the cost of current consumption.

Only one multicast group is allowed per socket.

Note: The address must be a link-local multicast address to bind to.

Parameters

Parameter	Description
mira_udp_connection	The UDP connection to close.
multicast_address	The address of the multicast group to join.

Return

MIRA_SUCCESS If successful.

MIRA_ERROR_INVALID_VALUE Invalid argument.

MIRA_ERROR_NO_MEMORY No space for additional multicast addresses in socket.

mira_net_udp_multicast_group_leave

mira_status_t mira_net_udp_multicast_group_leave(
    mira_net_udp_connection_t*  mira_udp_connection,
    const mira_net_address_t*   multicast_address);

Leave a multicast group.

Leave a group that previously was joined using mira_net_udp_multicast_group_join.

Parameters

Parameter	Description
mira_udp_connection	The UDP connection to close.
multicast_address	The address of the multicast group to leave.

Return

MIRA_SUCCESS If successful.

MIRA_NET_ERROR_NO_ADDRESS_SET Socket is not bound to address.

MIRA_ERROR_INVALID_VALUE Invalid argument.

mira_net_udp_send

mira_status_t mira_net_udp_send(
    mira_net_udp_connection_t*  mira_udp_connection,
    const void*                 data,
    uint16_t                    data_len);

Sends a data string over a specified UDP connection.

Note: When sending to link-local multicast addresses, expect lower delivery rates due to lack of retransmissions. Also when packet is fragmented, the delivery rates will reduced further. Recommend maximum packet size is 160 bytes.

Parameters

Parameter	Description
mira_udp_connection	The UDP connection to use for the transmission.
data	The data to be sent.
data_len	The length, in bytes, of the data to be sent.

Return

See enum definition.

Value	Description
MIRA_SUCCESS	UDP packet successfully sent.
MIRA_NET_ERROR_SEND_FAILED	Sending UDP packet failed.

mira_net_udp_send_to

mira_status_t mira_net_udp_send_to(
    mira_net_udp_connection_t*  mira_udp_connection,
    const mira_net_address_t*   address,
    uint16_t                    port,
    const void*                 data,
    uint16_t                    data_len);

Sends a data string via UDP to a specified IP address.

Note: When sending to link-local multicast addresses, expect lower delivery rates due to lack of retransmissions. Also when packet is fragmented, the delivery rates will reduced further. Recommend maximum packet size is 160 bytes.

Parameters

Parameter	Description
mira_udp_connection	The UDP connection to use for the transmission.
address	The IP address to send to, i.e. the receiver.
port	The UDP port to send to.
data	Data to send as vector.
data_len	The length of the data vector to send.

Return

See enum definition.

Value	Description
MIRA_SUCCESS	UDP packet successfully sent.
MIRA_NET_ERROR_SEND_FAILED	Sending UDP packet failed.