UDP¶
Reserved UDP ports¶
UDP ports from 6960 to 6970 are reserved for internal Mira communications.
Ports from 49152 to 65535 are used when no port has been specified for a connection.
Types¶
mira_net_udp_connection_t¶
typedef struct mira_net_udp_connection_t mira_net_udp_connection_t;
mira_net_udp_callback_t¶
typedef void(* mira_net_udp_callback_t) (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¶
| Name | Type | Description |
|---|---|---|
source_address |
const mira_net_address_t * |
|
destination_address |
const mira_net_address_t * |
|
source_port |
uint16_t |
|
destination_port |
uint16_t |
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.
Note
Can not be called before mira_net_init.
Parameters
| Name | Description |
|---|---|
| port | The port number, zero means the system will allocate it. |
| 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. |
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.
Please see mira_net_udp_multicast_group_join() for more info about handling multicast groups.
Note
Can not be called before mira_net_init. No verification is made of the address.
Parameters
| Name | Description |
|---|---|
| address | The link-local multicast IP address to listen to, NULL means all IP addresses. |
| port | The port number, zero means the system will allocate it. |
| 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. |
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.
When address is NULL, the socket will not bind to a specific remote address and mira_net_udp_send_to has to be used to send messages.
Note
Can not be called before mira_net_init.
Parameters
| Name | Description |
|---|---|
| address | The IP address to connect to. |
| port | The remote 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. |
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.
When remote_address is NULL, the socket does not have a remote address and mira_net_udp_send_to has to be used when sending messages.
If local_port is 0, a random number within the 49152 to 65535 range will be used.
Note
Can not be called before mira_net_init.
Parameters
| Name | 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. |
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.
When remote_address is NULL, the socket does not have a remote address and mira_net_udp_send_to has to be used when sending messages.
When local_address is NULL, the socket listens to all available addresses. Please see mira_net_udp_multicast_group_join() for more info about multicast groups.
If local_port is 0, a random number within the 49152 to 65535 range will be used.
Note
Can not be called before mira_net_init. No verification is made of local_address.
Parameters
| Name | Description |
|---|---|
| remote_address | IP address to bind to. |
| local_address | IP link-local multicast IP address to listen 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. |
mira_net_udp_close¶
mira_status_t mira_net_udp_close(mira_net_udp_connection_t *mira_udp_connection);
Close the specified connection.
Parameters
| Name | Description |
|---|---|
| mira_udp_connection | The UDP connection to close. |
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, the address must be joined (with this call) and the socket must also listen to all addresses or to the multicast address (using mira_net_udp_listen_address or mira_net_udp_bind_address).
The node leaves the group when all sockets have left the group. Sockets leave the group when mira_net_udp_multicast_group_leave() is called and when they are closed.
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, no verification is done of it.
Parameters
| Name | Description |
|---|---|
| mira_udp_connection | The UDP connection to use for multicast address. |
| multicast_address | The address of the multicast group to join. |
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. Sockets will also leave the group when they are closed.
Parameters
| Name | Description |
|---|---|
| mira_udp_connection | The UDP connection to close. |
| multicast_address | The address of the multicast group to leave. |
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.
The connection must be created with a remote address and port to use this method. To specify the remote address and port when sending, use the mira_net_udp_send_to() method.
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 to avoid fragmentation is 160 bytes.
Parameters
| Name | 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. At most 800 should be used. |
Return value
| Name | 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.
To reply to a received message, use mira_net_udp_send_to() with addess and port set to the values from metadata->source_address and metadata->source_port from the receive callback.
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 to avoid fragmentation is 160 bytes.
Parameters
| Name | 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. At most 800 should be used. |
Return value
| Name | Description |
|---|---|
| MIRA_SUCCESS | UDP packet successfully sent. |
| MIRA_NET_ERROR_SEND_FAILED | Sending UDP packet failed. |