# UDP

# UDP

This module includes functions that control UDP communication.

## Summary

| ### Enumerations ||
|---|---|
| `https://openthread.io/reference/group/api-udp#group__api-udp_1gae0373a8b42c58d633bd4d0b23199a678{ https://openthread.io/reference/group/api-udp#group__api-udp_1ggae0373a8b42c58d633bd4d0b23199a678ab3507eaf3eb2975b4998fe1844ad0b61 = 0, https://openthread.io/reference/group/api-udp#group__api-udp_1ggae0373a8b42c58d633bd4d0b23199a678aff531dde09beeaf28974a8bc38a30593, https://openthread.io/reference/group/api-udp#group__api-udp_1ggae0373a8b42c58d633bd4d0b23199a678a62851832f619cd093e84bf14392a12bb, https://openthread.io/reference/group/api-udp#group__api-udp_1ggae0373a8b42c58d633bd4d0b23199a678ac96afc6576257b3a456500986ee8c573 }` | enumDefines the OpenThread network interface identifiers. |

| ### Typedefs ||
|---|---|
| `https://openthread.io/reference/group/api-udp#group__api-udp_1ga06e001de26fe5a9485e7c97df21fca7d` | typedef `enum https://openthread.io/reference/group/api-udp#group__api-udp_1gae0373a8b42c58d633bd4d0b23199a678` Defines the OpenThread network interface identifiers. |
| `https://openthread.io/reference/group/api-udp#group__api-udp_1ga847ee9625e4be2d38fee0d552efdd32d)(void *aContext, const otMessage *aMessage, const otMessageInfo *aMessageInfo)` | typedef `bool(*` Represents a callback to handle a received UDP message. |
| `https://openthread.io/reference/group/api-udp#group__api-udp_1ga2f9fe48646b31d5088d9c4e2492fe9ce)(void *aContext, otMessage *aMessage, const otMessageInfo *aMessageInfo)` | typedef `void(*` Callback function pointer to notify the application of a received UDP message on a UDP socket. |
| `https://openthread.io/reference/group/api-udp#group__api-udp_1gae0e5ce179221849c8109e1ec2c79b344` | typedef `struct https://openthread.io/reference/struct/ot-udp-receiver` Represents a UDP receiver. |
| `https://openthread.io/reference/group/api-udp#group__api-udp_1ga2d245018891da475518da5c375beeba7` | typedef `struct https://openthread.io/reference/struct/ot-udp-socket` Represents a UDP socket. |

| ### Functions ||
|---|---|
| `https://openthread.io/reference/group/api-udp#group__api-udp_1ga8898d1d888eabfdb24b0cb62106dcce9(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/struct/ot-udp-receiver *aUdpReceiver)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Adds a UDP receiver. |
| `https://openthread.io/reference/group/api-udp#group__api-udp_1ga98ed16fc2e4aff157aba52a2a4369176(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/struct/ot-udp-socket *aSocket, const https://openthread.io/reference/struct/ot-sock-addr *aSockName, https://openthread.io/reference/group/api-udp#group__api-udp_1gae0373a8b42c58d633bd4d0b23199a678 aNetif)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Bind a UDP/IPv6 socket. |
| `https://openthread.io/reference/group/api-udp#group__api-udp_1ga884d74daea78d18e5364bd0d54f079a7(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/struct/ot-udp-socket *aSocket)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Close a UDP/IPv6 socket. |
| `https://openthread.io/reference/group/api-udp#group__api-udp_1ga80a9566a6afeada05b9c58e4286bdf84(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/struct/ot-udp-socket *aSocket, const https://openthread.io/reference/struct/ot-sock-addr *aSockName)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Connect a UDP/IPv6 socket. |
| `https://openthread.io/reference/group/api-udp#group__api-udp_1ga68273525966cf9b04ad482d2a1942c21(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `https://openthread.io/reference/struct/ot-udp-socket *` Gets the head of linked list of UDP Sockets. |
| `https://openthread.io/reference/group/api-udp#group__api-udp_1gaceb92d8761724f2bae10b2e40c9c335e(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, const https://openthread.io/reference/struct/ot-udp-socket *aSocket)` | `bool` Check if a UDP socket is open. |
| `https://openthread.io/reference/group/api-udp#group__api-udp_1gab58e1df115551727f959616da8e6a4ca(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, const https://openthread.io/reference/struct/ot-message-settings *aSettings)` | `https://openthread.io/reference/group/api-message#group__api-message_1ga42d128a0a9ad58de0eb79673843c2955 *` Allocate a new message buffer for sending a UDP message. |
| `https://openthread.io/reference/group/api-udp#group__api-udp_1gac3df0bb2b8e2feeb44094d2702423cc2(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/struct/ot-udp-socket *aSocket, https://openthread.io/reference/group/api-udp#group__api-udp_1ga2f9fe48646b31d5088d9c4e2492fe9ce aCallback, void *aContext)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Open a UDP/IPv6 socket. |
| `https://openthread.io/reference/group/api-udp#group__api-udp_1gab65be3590610a5516beae28adf98a053(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/struct/ot-udp-receiver *aUdpReceiver)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Removes a UDP receiver. |
| `https://openthread.io/reference/group/api-udp#group__api-udp_1gad69e602fb052467ae57c199c78cb4e49(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/struct/ot-udp-socket *aSocket, https://openthread.io/reference/group/api-message#group__api-message_1ga42d128a0a9ad58de0eb79673843c2955 *aMessage, const https://openthread.io/reference/struct/ot-message-info *aMessageInfo)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Send a UDP/IPv6 message. |
| `https://openthread.io/reference/group/api-udp#group__api-udp_1ga7189dc38e0321c353562c48ad0526f83(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/group/api-message#group__api-message_1ga42d128a0a9ad58de0eb79673843c2955 *aMessage, https://openthread.io/reference/struct/ot-message-info *aMessageInfo)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Sends a UDP message without socket. |

| ### Structs ||
|---|---|
| [otUdpReceiver](https://openthread.io/reference/struct/ot-udp-receiver) | Represents a UDP receiver. |
| [otUdpSocket](https://openthread.io/reference/struct/ot-udp-socket) | Represents a UDP socket. |

## Enumerations

### otNetifIdentifier

```
 otNetifIdentifier
```
Defines the OpenThread network interface identifiers.

| Properties ||
|---|---|
| `OT_NETIF_BACKBONE` | The Backbone interface. |
| `OT_NETIF_THREAD_HOST` | The host Thread interface - allow use of platform UDP. |
| `OT_NETIF_THREAD_INTERNAL` | The internal Thread interface (within OpenThread) - do not use platform UDP. |
| `OT_NETIF_UNSPECIFIED` | Unspecified network interface. |

## Typedefs

### otNetifIdentifier

```
enum otNetifIdentifier otNetifIdentifier
```
Defines the OpenThread network interface identifiers.

### otUdpHandler

```
bool(* otUdpHandler)(void *aContext, const otMessage *aMessage, const otMessageInfo *aMessageInfo)
```
Represents a callback to handle a received UDP message.

This callback is used by a UDP receiver (see `https://openthread.io/reference/group/api-udp#group__api-udp_1ga8898d1d888eabfdb24b0cb62106dcce9`) to process an incoming UDP message.

This callback does not transfer ownership of `aMessage`. The callback implementation must not modify the message content. The message is guaranteed to be valid only within the context of the callback.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aContext` | A pointer to the application-specific context. | | `[in] aMessage` | A pointer to the received UDP message. | | `[in] aMessageInfo` | A pointer to the IPv6 message info structure. | |
| Return Values | |---|---| | `TRUE` | The message is handled by this receiver and should not be further processed. | | `FALSE` | The message is not handled by this receiver. | |

### otUdpReceive

```
void(* otUdpReceive)(void *aContext, otMessage *aMessage, const otMessageInfo *aMessageInfo)
```
Callback function pointer to notify the application of a received UDP message on a UDP socket.

This callback does not transfer ownership of `aMessage`. The callback implementation must not modify the message content. The message is guaranteed to be valid only within the context of the callback.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aContext` | A pointer to the application-specific context. | | `[in] aMessage` | A pointer to the received UDP message. | | `[in] aMessageInfo` | A pointer to the IPv6 message info structure. | |

### otUdpReceiver

```
struct otUdpReceiver otUdpReceiver
```
Represents a UDP receiver.

### otUdpSocket

```
struct otUdpSocket otUdpSocket
```
Represents a UDP socket.

## Functions

### otUdpAddReceiver

```
otError otUdpAddReceiver(
  otInstance *aInstance,
  otUdpReceiver *aUdpReceiver
)
```
Adds a UDP receiver.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aUdpReceiver` | A pointer to the UDP receiver. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | The receiver is successfully added. | | `OT_ERROR_ALREADY` | The UDP receiver was already added. | |

### otUdpBind

```
otError otUdpBind(
  otInstance *aInstance,
  otUdpSocket *aSocket,
  const otSockAddr *aSockName,
  otNetifIdentifier aNetif
)
```
Bind a UDP/IPv6 socket.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aSocket` | A pointer to a UDP socket structure. | | `[in] aSockName` | A pointer to an IPv6 socket address structure. | | `[in] aNetif` | The network interface to bind. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Bind operation was successful. | | `OT_ERROR_FAILED` | Failed to bind UDP socket. | |

### otUdpClose

```
otError otUdpClose(
  otInstance *aInstance,
  otUdpSocket *aSocket
)
```
Close a UDP/IPv6 socket.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aSocket` | A pointer to a UDP socket structure. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Successfully closed the socket. | | `OT_ERROR_FAILED` | Failed to close UDP Socket. | |

### otUdpConnect

```
otError otUdpConnect(
  otInstance *aInstance,
  otUdpSocket *aSocket,
  const otSockAddr *aSockName
)
```
Connect a UDP/IPv6 socket.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aSocket` | A pointer to a UDP socket structure. | | `[in] aSockName` | A pointer to an IPv6 socket address structure. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Connect operation was successful. | | `OT_ERROR_FAILED` | Failed to connect UDP socket. | |

### otUdpGetSockets

```
otUdpSocket * otUdpGetSockets(
  otInstance *aInstance
)
```
Gets the head of linked list of UDP Sockets.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | |
| **Returns** | A pointer to the head of UDP Socket linked list. |

### otUdpIsOpen

```
bool otUdpIsOpen(
  otInstance *aInstance,
  const otUdpSocket *aSocket
)
```
Check if a UDP socket is open.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aSocket` | A pointer to a UDP socket structure. | |
| **Returns** | Whether the UDP socket is open. |

### otUdpNewMessage

```
otMessage * otUdpNewMessage(
  otInstance *aInstance,
  const otMessageSettings *aSettings
)
```
Allocate a new message buffer for sending a UDP message.


> [!NOTE]
> **Note:** If `aSettings` is 'NULL', the link layer security is enabled and the message priority is set to OT_MESSAGE_PRIORITY_NORMAL by default.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aSettings` | A pointer to the message settings or NULL to use default settings. | |
| **Returns** | A pointer to the message buffer or NULL if no message buffers are available or parameters are invalid. |

**See also:**   
[otMessageFree](https://openthread.io/reference/group/api-message#group__api-message_1ga70291a9d11f2f2a0bff290bf8ff4ea20)   

### otUdpOpen

```
otError otUdpOpen(
  otInstance *aInstance,
  otUdpSocket *aSocket,
  otUdpReceive aCallback,
  void *aContext
)
```
Open a UDP/IPv6 socket.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aSocket` | A pointer to a UDP socket structure. | | `[in] aCallback` | A pointer to the application callback function. | | `[in] aContext` | A pointer to application-specific context. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Successfully opened the socket. | | `OT_ERROR_FAILED` | Failed to open the socket. | |

### otUdpRemoveReceiver

```
otError otUdpRemoveReceiver(
  otInstance *aInstance,
  otUdpReceiver *aUdpReceiver
)
```
Removes a UDP receiver.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aUdpReceiver` | A pointer to the UDP receiver. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | The receiver is successfully removed. | | `OT_ERROR_NOT_FOUND` | The UDP receiver was not added. | |

### otUdpSend

```
otError otUdpSend(
  otInstance *aInstance,
  otUdpSocket *aSocket,
  otMessage *aMessage,
  const otMessageInfo *aMessageInfo
)
```
Send a UDP/IPv6 message.


If the return value is OT_ERROR_NONE, OpenThread takes ownership of `aMessage`, and the caller should no longer reference `aMessage`. If the return value is not OT_ERROR_NONE, the caller retains ownership of `aMessage`, including freeing `aMessage` if the message buffer is no longer needed.

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aSocket` | A pointer to a UDP socket structure. | | `[in] aMessage` | A pointer to a message buffer. | | `[in] aMessageInfo` | A pointer to a message info structure. | |

<br />

| Details ||
|---|---|
| Return Values | |---|---| | `OT_ERROR_NONE` | The message is successfully scheduled for sending. | | `OT_ERROR_INVALID_ARGS` | Invalid arguments are given. | | `OT_ERROR_NO_BUFS` | Insufficient available buffer to add the UDP and IPv6 headers. | |

### otUdpSendDatagram

```
otError otUdpSendDatagram(
  otInstance *aInstance,
  otMessage *aMessage,
  otMessageInfo *aMessageInfo
)
```
Sends a UDP message without socket.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aMessage` | A pointer to a message without UDP header. | | `[in] aMessageInfo` | A pointer to a message info associated with `aMessage`. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Successfully enqueued the message into an output interface. | | `OT_ERROR_NO_BUFS` | Insufficient available buffer to add the IPv6 headers. | | `OT_ERROR_INVALID_ARGS` | Invalid arguments are given. | |

## Resources

OpenThread API Reference topics originate from the source code, available
on [GitHub](https://github.com/openthread/openthread/tree/main/include/openthread).
For more information, or to contribute to our documentation, refer to
[Resources](https://openthread.io/resources).