UDP

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

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