This module includes functions that control UDP communication.

Summary

Enumerations
otNetifIdentifier{
  OT_NETIF_UNSPECIFIED = 0,
  OT_NETIF_THREAD_HOST,
  OT_NETIF_THREAD_INTERNAL,
  OT_NETIF_BACKBONE
} 		enum

Defines the OpenThread network interface identifiers.

Typedefs
otNetifIdentifier typedef

Defines the OpenThread network interface identifiers.

otUdpHandler)(void *aContext, const otMessage *aMessage, const otMessageInfo *aMessageInfo) typedef

bool(*

Represents a callback to handle a received UDP message.

otUdpReceive)(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.

otUdpReceiver typedef

struct otUdpReceiver

Represents a UDP receiver.

otUdpSocket typedef

struct otUdpSocket

Represents a UDP socket.

Functions
otUdpAddReceiver(otInstance *aInstance, otUdpReceiver *aUdpReceiver)

Adds a UDP receiver.

otUdpBind(otInstance *aInstance, otUdpSocket *aSocket, const otSockAddr *aSockName, otNetifIdentifier aNetif)

Bind a UDP/IPv6 socket.

otUdpClose(otInstance *aInstance, otUdpSocket *aSocket)

Close a UDP/IPv6 socket.

otUdpConnect(otInstance *aInstance, otUdpSocket *aSocket, const otSockAddr *aSockName)

Connect a UDP/IPv6 socket.

otUdpGetSockets(otInstance *aInstance)

Gets the head of linked list of UDP Sockets.

otUdpIsOpen(otInstance *aInstance, const otUdpSocket *aSocket)

bool

Check if a UDP socket is open.

otUdpNewMessage(otInstance *aInstance, const otMessageSettings *aSettings)

Allocate a new message buffer for sending a UDP message.

otUdpOpen(otInstance *aInstance, otUdpSocket *aSocket, otUdpReceive aCallback, void *aContext)

Open a UDP/IPv6 socket.

otUdpRemoveReceiver(otInstance *aInstance, otUdpReceiver *aUdpReceiver)

Removes a UDP receiver.

otUdpSend(otInstance *aInstance, otUdpSocket *aSocket, otMessage *aMessage, const otMessageInfo *aMessageInfo)

Send a UDP/IPv6 message.

otUdpSendDatagram(otInstance *aInstance, otMessage *aMessage, otMessageInfo *aMessageInfo)

Sends a UDP message without socket.

Structs
otUdpReceiver

Represents a UDP receiver.

otUdpSocket

Represents a UDP socket.

Enumerations

otNetifIdentifier

 otNetifIdentifier

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 otUdpAddReceiver()) 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.

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.

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.

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.

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.

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.

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.

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.

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.

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

otUdpOpen

otError otUdpOpen(
  otInstance *aInstance,
  otUdpSocket *aSocket,
  otUdpReceive aCallback,
  void *aContext
)

Open a UDP/IPv6 socket.

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.

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.
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.

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. For more information, or to contribute to our documentation, refer to Resources.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates. The OPENTHREAD and related marks are trademarks of the Thread Group and are used under license.

Last updated 2026-02-05 UTC.