Message

This module includes functions that manipulate OpenThread message buffers.

Summary

Enumerations
otMessageOrigin{
  OT_MESSAGE_ORIGIN_THREAD_NETIF = 0,
  OT_MESSAGE_ORIGIN_HOST_TRUSTED = 1,
  OT_MESSAGE_ORIGIN_HOST_UNTRUSTED = 2
} 		enum
Defines the OpenThread message origins.
otMessagePriority{
  OT_MESSAGE_PRIORITY_LOW = 0,
  OT_MESSAGE_PRIORITY_NORMAL = 1,
  OT_MESSAGE_PRIORITY_HIGH = 2
} 		enum
Defines the OpenThread message priority levels.

Typedefs
otBufferInfo typedef
struct otBufferInfo
Represents the message buffer information for different queues used by OpenThread stack.
otMessage typedef
struct otMessage
An opaque representation of an OpenThread message buffer.
otMessageOrigin typedef
Defines the OpenThread message origins.
otMessagePriority typedef
Defines the OpenThread message priority levels.
otMessageQueueInfo typedef
Represents information about a message queue.
otMessageSettings typedef
Represents a message settings.
otMessageTxCallback)(const otMessage *aMessage, otError aError, void *aContext) typedef
void(*
Represents the callback function pointer to notify the transmission outcome (success or failure) of a message.
otThreadLinkInfo typedef
Represents link-specific information for messages received from the Thread radio.

Functions
otMessageAppend(otMessage *aMessage, const void *aBuf, uint16_t aLength)
Append bytes to a message.
otMessageFree(otMessage *aMessage)
void
Free an allocated message buffer.
otMessageGetBufferInfo(otInstance *aInstance, otBufferInfo *aBufferInfo)
void
Get the Message Buffer information.
otMessageGetInstance(const otMessage *aMessage)
Gets the otInstance associated with a given message.
otMessageGetLength(const otMessage *aMessage)
uint16_t
Get the message length in bytes.
otMessageGetOffset(const otMessage *aMessage)
uint16_t
Get the message offset in bytes.
otMessageGetOrigin(const otMessage *aMessage)
Gets the message origin.
otMessageGetRss(const otMessage *aMessage)
int8_t
Returns the average RSS (received signal strength) associated with the message.
otMessageGetThreadLinkInfo(const otMessage *aMessage, otThreadLinkInfo *aLinkInfo)
Retrieves the link-specific information for a message received over Thread radio.
otMessageIsLinkSecurityEnabled(const otMessage *aMessage)
bool
Indicates whether or not link security is enabled for the message.
otMessageIsLoopbackToHostAllowed(const otMessage *aMessage)
bool
Indicates whether or not the message is allowed to be looped back to host.
otMessageIsMulticastLoopEnabled(otMessage *aMessage)
bool
Indicates whether the given message may be looped back in a case of a multicast destination address.
otMessageQueueDequeue(otMessageQueue *aQueue, otMessage *aMessage)
void
Removes a message from the given message queue.
otMessageQueueEnqueue(otMessageQueue *aQueue, otMessage *aMessage)
void
Adds a message to the end of the given message queue.
otMessageQueueEnqueueAtHead(otMessageQueue *aQueue, otMessage *aMessage)
void
Adds a message at the head/front of the given message queue.
otMessageQueueGetHead(otMessageQueue *aQueue)
Returns a pointer to the message at the head of the queue.
otMessageQueueGetNext(otMessageQueue *aQueue, const otMessage *aMessage)
Returns a pointer to the next message in the queue by iterating forward (from head to tail).
otMessageQueueInit(otMessageQueue *aQueue)
void
Initialize the message queue.
otMessageRead(const otMessage *aMessage, uint16_t aOffset, void *aBuf, uint16_t aLength)
uint16_t
Read bytes from a message.
otMessageRegisterTxCallback(otMessage *aMessage, otMessageTxCallback aCallback, void *aContext)
void
Registers a callback to be notified of a message's transmission outcome.
otMessageResetBufferInfo(otInstance *aInstance)
void
Reset the Message Buffer information counter tracking the maximum number buffers in use at the same time.
otMessageSetDirectTransmission(otMessage *aMessage, bool aEnabled)
void
Sets/forces the message to be forwarded using direct transmission.
otMessageSetLength(otMessage *aMessage, uint16_t aLength)
Set the message length in bytes.
otMessageSetLoopbackToHostAllowed(otMessage *aMessage, bool aAllowLoopbackToHost)
void
Sets whether or not the message is allowed to be looped back to host.
otMessageSetMulticastLoopEnabled(otMessage *aMessage, bool aEnabled)
void
Controls whether the given message may be looped back in a case of a multicast destination address.
otMessageSetOffset(otMessage *aMessage, uint16_t aOffset)
void
Set the message offset in bytes.
otMessageSetOrigin(otMessage *aMessage, otMessageOrigin aOrigin)
void
Sets the message origin.
otMessageWrite(otMessage *aMessage, uint16_t aOffset, const void *aBuf, uint16_t aLength)
int
Write bytes to a message.

Structs
otBufferInfo

Represents the message buffer information for different queues used by OpenThread stack.

otMessageQueue

Represents an OpenThread message queue.

otMessageQueueInfo

Represents information about a message queue.

otMessageSettings

Represents a message settings.

otThreadLinkInfo

Represents link-specific information for messages received from the Thread radio.

Enumerations

otMessageOrigin

 otMessageOrigin

Defines the OpenThread message origins.

Properties
OT_MESSAGE_ORIGIN_HOST_TRUSTED

Message from a trusted source on host.

OT_MESSAGE_ORIGIN_HOST_UNTRUSTED

Message from an untrusted source on host.

OT_MESSAGE_ORIGIN_THREAD_NETIF

Message from Thread Netif.

otMessagePriority

 otMessagePriority

Defines the OpenThread message priority levels.

Properties
OT_MESSAGE_PRIORITY_HIGH

High priority level.

OT_MESSAGE_PRIORITY_LOW

Low priority level.

OT_MESSAGE_PRIORITY_NORMAL

Normal priority level.

Typedefs

otBufferInfo

struct otBufferInfo otBufferInfo

Represents the message buffer information for different queues used by OpenThread stack.

otMessage

struct otMessage otMessage

An opaque representation of an OpenThread message buffer.

otMessageOrigin

enum otMessageOrigin otMessageOrigin

Defines the OpenThread message origins.

otMessagePriority

enum otMessagePriority otMessagePriority

Defines the OpenThread message priority levels.

otMessageQueueInfo

struct otMessageQueueInfo otMessageQueueInfo

Represents information about a message queue.

otMessageSettings

struct otMessageSettings otMessageSettings

Represents a message settings.

otMessageTxCallback

void(* otMessageTxCallback)(const otMessage *aMessage, otError aError, void *aContext)

Represents the callback function pointer to notify the transmission outcome (success or failure) of a message.

The error indicates the transmission status of the IPv6 message from this device to an immediate neighbor (one-hop transmission). It doesn't indicate that the message is received by its final intended destination (multi-hop away).

For a unicast IPv6 message, an OT_ERROR_NONE error indicates that the message (all its corresponding fragment frames if the message is larger and requires fragmentation) was successfully delivered to the immediate neighbor, and a MAC layer acknowledgment was received for all fragments. This is reported regardless of whether the message is sent using direct TX or indirect TX (to a sleepy child using CSL or data poll triggered TX).

For a multicast message, an OT_ERROR_NONE status indicates that the message (all its fragment frames) was successfully broadcast. Note that no MAC-level acknowledgment is required for broadcast frame TX.

The OpenThread stack may alter the content of the message as it is prepared for transmission (e.g., IPv6 headers may be prepended, or additional metadata appended at the end). So, the content of aMessage when this callback is invoked may differ from its original content (e.g., when it was given as input in otIp6Send() for transmission).

Details
Parameters
[in] aMessage
A pointer to the message.
[in] aError
The TX error when sending the message.
[in] aContext
A pointer to the user-provided context when the callback was registered.

otThreadLinkInfo

struct otThreadLinkInfo otThreadLinkInfo

Represents link-specific information for messages received from the Thread radio.

Functions

otMessageAppend

otError otMessageAppend(
  otMessage *aMessage,
  const void *aBuf,
  uint16_t aLength
)

Append bytes to a message.

Details
Parameters
[in] aMessage
A pointer to a message buffer.
[in] aBuf
A pointer to the data to append.
[in] aLength
Number of bytes to append.
Return Values
OT_ERROR_NONE
Successfully appended to the message
OT_ERROR_NO_BUFS
No available buffers to grow the message.
See also:
otMessageFree
otMessageGetLength
otMessageSetLength
otMessageGetOffset
otMessageSetOffset
otMessageRead
otMessageWrite

otMessageFree

void otMessageFree(
  otMessage *aMessage
)

Free an allocated message buffer.

Details
Parameters
[in] aMessage
A pointer to a message buffer.
See also:
otMessageAppend
otMessageGetLength
otMessageSetLength
otMessageGetOffset
otMessageSetOffset
otMessageRead
otMessageWrite

otMessageGetBufferInfo

void otMessageGetBufferInfo(
  otInstance *aInstance,
  otBufferInfo *aBufferInfo
)

Get the Message Buffer information.

Details
Parameters
[in] aInstance
A pointer to the OpenThread instance.
[out] aBufferInfo
A pointer where the message buffer information is written.

otMessageGetInstance

otInstance * otMessageGetInstance(
  const otMessage *aMessage
)

Gets the otInstance associated with a given message.

Details
Parameters
[in] aMessage
A message.
Returns
The otInstance associated with aMessage.

otMessageGetLength

uint16_t otMessageGetLength(
  const otMessage *aMessage
)

Get the message length in bytes.

Details
Parameters
[in] aMessage
A pointer to a message buffer.
Returns
The message length in bytes.
See also:
otMessageFree
otMessageAppend
otMessageSetLength
otMessageGetOffset
otMessageSetOffset
otMessageRead
otMessageWrite
otMessageSetLength

otMessageGetOffset

uint16_t otMessageGetOffset(
  const otMessage *aMessage
)

Get the message offset in bytes.

Details
Parameters
[in] aMessage
A pointer to a message buffer.
Returns
The message offset value.
See also:
otMessageFree
otMessageAppend
otMessageGetLength
otMessageSetLength
otMessageSetOffset
otMessageRead
otMessageWrite

otMessageGetOrigin

otMessageOrigin otMessageGetOrigin(
  const otMessage *aMessage
)

Gets the message origin.

Details
Parameters
[in] aMessage
A pointer to a message buffer.
Returns
The message origin.

otMessageGetRss

int8_t otMessageGetRss(
  const otMessage *aMessage
)

Returns the average RSS (received signal strength) associated with the message.

Details
Parameters
[in] aMessage
A pointer to a message buffer.
Returns
The average RSS value (in dBm) or OT_RADIO_RSSI_INVALID if no average RSS is available.

otMessageGetThreadLinkInfo

otError otMessageGetThreadLinkInfo(
  const otMessage *aMessage,
  otThreadLinkInfo *aLinkInfo
)

Retrieves the link-specific information for a message received over Thread radio.

Details
Parameters
[in] aMessage
The message from which to retrieve otThreadLinkInfo. [out] aLinkInfo A pointer to an otThreadLinkInfo to populate.
Return Values
OT_ERROR_NONE
Successfully retrieved the link info, aLinkInfo is updated.
OT_ERROR_NOT_FOUND
Message origin is not OT_MESSAGE_ORIGIN_THREAD_NETIF.

otMessageIsLinkSecurityEnabled

bool otMessageIsLinkSecurityEnabled(
  const otMessage *aMessage
)

Indicates whether or not link security is enabled for the message.

Details
Parameters
[in] aMessage
A pointer to a message buffer.
Return Values
TRUE
If link security is enabled.
FALSE
If link security is not enabled.

otMessageIsLoopbackToHostAllowed

bool otMessageIsLoopbackToHostAllowed(
  const otMessage *aMessage
)

Indicates whether or not the message is allowed to be looped back to host.

Details
Parameters
[in] aMessage
A pointer to a message buffer.
Return Values
TRUE
If the message is allowed to be looped back to host.
FALSE
If the message is not allowed to be looped back to host.

otMessageIsMulticastLoopEnabled

bool otMessageIsMulticastLoopEnabled(
  otMessage *aMessage
)

Indicates whether the given message may be looped back in a case of a multicast destination address.

If aMessage is used along with an otMessageInfo, the mMulticastLoop field from otMessageInfo structure takes precedence and will be used instead of the the value set on aMessage.

This API is mainly intended for use along with otIp6Send() which expects an already prepared IPv6 message.

Details
Parameters
[in] aMessage
A pointer to the message.

otMessageQueueDequeue

void otMessageQueueDequeue(
  otMessageQueue *aQueue,
  otMessage *aMessage
)

Removes a message from the given message queue.

Details
Parameters
[in] aQueue
A pointer to the message queue.
[in] aMessage
The message to remove.

otMessageQueueEnqueue

void otMessageQueueEnqueue(
  otMessageQueue *aQueue,
  otMessage *aMessage
)

Adds a message to the end of the given message queue.

Details
Parameters
[in] aQueue
A pointer to the message queue.
[in] aMessage
The message to add.

otMessageQueueEnqueueAtHead

void otMessageQueueEnqueueAtHead(
  otMessageQueue *aQueue,
  otMessage *aMessage
)

Adds a message at the head/front of the given message queue.

Details
Parameters
[in] aQueue
A pointer to the message queue.
[in] aMessage
The message to add.

otMessageQueueGetHead

otMessage * otMessageQueueGetHead(
  otMessageQueue *aQueue
)

Returns a pointer to the message at the head of the queue.

Details
Parameters
[in] aQueue
A pointer to a message queue.
Returns
A pointer to the message at the head of queue or NULL if queue is empty.

otMessageQueueGetNext

otMessage * otMessageQueueGetNext(
  otMessageQueue *aQueue,
  const otMessage *aMessage
)

Returns a pointer to the next message in the queue by iterating forward (from head to tail).

Details
Parameters
[in] aQueue
A pointer to a message queue.
[in] aMessage
A pointer to current message buffer.
Returns
A pointer to the next message in the queue after aMessage or NULL if aMessage is the tail of queue. NULL is returned ifaMessageis not in the queueaQueue`.

otMessageQueueInit

void otMessageQueueInit(
  otMessageQueue *aQueue
)

Initialize the message queue.

MUST be called once and only once for a otMessageQueue instance before any other otMessageQueue functions. The behavior is undefined if other queue APIs are used with an otMessageQueue before it being initialized or if it is initialized more than once.

Details
Parameters
[in] aQueue
A pointer to a message queue.

otMessageRead

uint16_t otMessageRead(
  const otMessage *aMessage,
  uint16_t aOffset,
  void *aBuf,
  uint16_t aLength
)

Read bytes from a message.

Details
Parameters
[in] aMessage
A pointer to a message buffer.
[in] aOffset
An offset in bytes.
[in] aBuf
A pointer to a buffer that message bytes are read to.
[in] aLength
Number of bytes to read.
Returns
The number of bytes read.
See also:
otMessageFree
otMessageAppend
otMessageGetLength
otMessageSetLength
otMessageGetOffset
otMessageSetOffset
otMessageWrite

otMessageRegisterTxCallback

void otMessageRegisterTxCallback(
  otMessage *aMessage,
  otMessageTxCallback aCallback,
  void *aContext
)

Registers a callback to be notified of a message's transmission outcome.

Calling this function again for the same message will replace any previously registered callback.

If the message is never actually sent (e.g., it's not passed to otIp6Send() or other send APIs), the callback will still be invoked when the message is freed. In this case, OT_ERROR_DROP will be passed as the error.

Details
Parameters
[in] aMessage
The message to register the callback with.
[in] aCallback
The TX callback.
[in] aContext
A pointer to a user-provided arbitrary context for the callback.

otMessageResetBufferInfo

void otMessageResetBufferInfo(
  otInstance *aInstance
)

Reset the Message Buffer information counter tracking the maximum number buffers in use at the same time.

This resets mMaxUsedBuffers in otBufferInfo.

Details
Parameters
[in] aInstance
A pointer to the OpenThread instance.

otMessageSetDirectTransmission

void otMessageSetDirectTransmission(
  otMessage *aMessage,
  bool aEnabled
)

Sets/forces the message to be forwarded using direct transmission.

Default setting for a new message is false.

Details
Parameters
[in] aMessage
A pointer to a message buffer.
[in] aEnabled
If true, the message is forced to use direct transmission. If false, the message follows the normal procedure.

otMessageSetLength

otError otMessageSetLength(
  otMessage *aMessage,
  uint16_t aLength
)

Set the message length in bytes.

Details
Parameters
[in] aMessage
A pointer to a message buffer.
[in] aLength
A length in bytes.
Return Values
OT_ERROR_NONE
Successfully set the message length.
OT_ERROR_NO_BUFS
No available buffers to grow the message.
See also:
otMessageFree
otMessageAppend
otMessageGetLength
otMessageGetOffset
otMessageSetOffset
otMessageRead
otMessageWrite

otMessageSetLoopbackToHostAllowed

void otMessageSetLoopbackToHostAllowed(
  otMessage *aMessage,
  bool aAllowLoopbackToHost
)

Sets whether or not the message is allowed to be looped back to host.

Details
Parameters
[in] aMessage
A pointer to a message buffer.
[in] aAllowLoopbackToHost
Whether to allow the message to be looped back to host.

otMessageSetMulticastLoopEnabled

void otMessageSetMulticastLoopEnabled(
  otMessage *aMessage,
  bool aEnabled
)

Controls whether the given message may be looped back in a case of a multicast destination address.

Details
Parameters
[in] aMessage
A pointer to the message.
[in] aEnabled
The configuration value.

otMessageSetOffset

void otMessageSetOffset(
  otMessage *aMessage,
  uint16_t aOffset
)

Set the message offset in bytes.

Details
Parameters
[in] aMessage
A pointer to a message buffer.
[in] aOffset
An offset in bytes.
See also:
otMessageFree
otMessageAppend
otMessageGetLength
otMessageSetLength
otMessageGetOffset
otMessageRead
otMessageWrite

otMessageSetOrigin

void otMessageSetOrigin(
  otMessage *aMessage,
  otMessageOrigin aOrigin
)

Sets the message origin.

Details
Parameters
[in] aMessage
A pointer to a message buffer.
[in] aOrigin
The message origin.

otMessageWrite

int otMessageWrite(
  otMessage *aMessage,
  uint16_t aOffset,
  const void *aBuf,
  uint16_t aLength
)

Write bytes to a message.

Details
Parameters
[in] aMessage
A pointer to a message buffer.
[in] aOffset
An offset in bytes.
[in] aBuf
A pointer to a buffer that message bytes are written from.
[in] aLength
Number of bytes to write.
Returns
The number of bytes written.
See also:
otMessageFree
otMessageAppend
otMessageGetLength
otMessageSetLength
otMessageGetOffset
otMessageSetOffset
otMessageRead

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.