Home Original page

Message  |  OpenThread

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.

otMessageClone(const otMessage *aMessage)

Creates a clone of a given 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

otMessagePriority

 otMessagePriority

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
)

otMessageClone

otMessage * otMessageClone(
  const otMessage *aMessage
)

Creates a clone of a given message.

The new message is allocated from the same message pool as aMessage. The entire message content from aMessage is copied to the new message.

The caller takes ownership of the returned message and must free it by calling otMessageFree() when it is no longer needed.

Details
Parameters
[in] aMessage

A pointer to the message to clone.
Returns

A pointer to the new message clone, or nullptr if no message buffers are available.

otMessageFree

void otMessageFree(
  otMessage *aMessage
)

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
)

otMessageGetOffset

uint16_t otMessageGetOffset(
  const otMessage *aMessage
)

otMessageGetOrigin

otMessageOrigin otMessageGetOrigin(
  const otMessage *aMessage
)

Gets the message origin.

Details
Parameters
[in] aMessage

A pointer to a message buffer.
Returns

The message origin. 

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
)

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
)

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
)

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
)

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.