Message#

This module includes functions that manipulate OpenThread message buffers.

Modules#

otMessageSettings

otThreadLinkInfo

otMessageQueue

otMessageQueueInfo

otBufferInfo

Enumerations#

enum
OT_MESSAGE_PRIORITY_LOW = 0
OT_MESSAGE_PRIORITY_NORMAL = 1
OT_MESSAGE_PRIORITY_HIGH = 2
}

Defines the OpenThread message priority levels.

enum
OT_MESSAGE_ORIGIN_THREAD_NETIF = 0
OT_MESSAGE_ORIGIN_HOST_TRUSTED = 1
OT_MESSAGE_ORIGIN_HOST_UNTRUSTED = 2
}

Defines the OpenThread message origins.

Typedefs#

typedef struct otMessage

An opaque representation of an OpenThread message buffer.

typedef enum otMessagePriority

Defines the OpenThread message priority levels.

typedef enum otMessageOrigin

Defines the OpenThread message origins.

typedef struct otMessageSettings

Represents a message settings.

typedef struct otThreadLinkInfo

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

typedef struct otMessageQueueInfo

Represents information about a message queue.

typedef struct otBufferInfo

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

Functions#

void
otMessageFree(otMessage *aMessage)

Free an allocated message buffer.

uint16_t
otMessageGetLength(const otMessage *aMessage)

Get the message length in bytes.

otMessageSetLength(otMessage *aMessage, uint16_t aLength)

Set the message length in bytes.

uint16_t
otMessageGetOffset(const otMessage *aMessage)

Get the message offset in bytes.

void
otMessageSetOffset(otMessage *aMessage, uint16_t aOffset)

Set the message offset in bytes.

bool
otMessageIsLinkSecurityEnabled(const otMessage *aMessage)

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

bool
otMessageIsLoopbackToHostAllowed(const otMessage *aMessage)

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

void
otMessageSetLoopbackToHostAllowed(otMessage *aMessage, bool aAllowLoopbackToHost)

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

bool
otMessageIsMulticastLoopEnabled(otMessage *aMessage)

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

void
otMessageSetMulticastLoopEnabled(otMessage *aMessage, bool aEnabled)

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

otMessageGetOrigin(const otMessage *aMessage)

Gets the message origin.

void
otMessageSetOrigin(otMessage *aMessage, otMessageOrigin aOrigin)

Sets the message origin.

void
otMessageSetDirectTransmission(otMessage *aMessage, bool aEnabled)

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

int8_t
otMessageGetRss(const otMessage *aMessage)

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.

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

Append bytes to a message.

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

Read bytes from a message.

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

Write bytes to a message.

void
otMessageQueueInit(otMessageQueue *aQueue)

Initialize the message queue.

void
otMessageQueueEnqueue(otMessageQueue *aQueue, otMessage *aMessage)

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

void
otMessageQueueEnqueueAtHead(otMessageQueue *aQueue, otMessage *aMessage)

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

void
otMessageQueueDequeue(otMessageQueue *aQueue, otMessage *aMessage)

Removes a message from 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).

void
otMessageGetBufferInfo(otInstance *aInstance, otBufferInfo *aBufferInfo)

Get the Message Buffer information.

void
otMessageResetBufferInfo(otInstance *aInstance)

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

Enumeration Documentation#

otMessagePriority#

otMessagePriority

Defines the OpenThread message priority levels.

Enumerator
OT_MESSAGE_PRIORITY_LOW

Low priority level.

OT_MESSAGE_PRIORITY_NORMAL

Normal priority level.

OT_MESSAGE_PRIORITY_HIGH

High priority level.


Definition at line 65 of file include/openthread/message.h

otMessageOrigin#

otMessageOrigin

Defines the OpenThread message origins.

Enumerator
OT_MESSAGE_ORIGIN_THREAD_NETIF

Message from Thread Netif.

OT_MESSAGE_ORIGIN_HOST_TRUSTED

Message from a trusted source on host.

OT_MESSAGE_ORIGIN_HOST_UNTRUSTED

Message from an untrusted source on host.


Definition at line 76 of file include/openthread/message.h

Typedef Documentation#

otMessage#

typedef struct otMessage otMessage

An opaque representation of an OpenThread message buffer.


Definition at line 59 of file include/openthread/message.h

otMessagePriority#

typedef enum otMessagePriority otMessagePriority

Defines the OpenThread message priority levels.


Definition at line 70 of file include/openthread/message.h

otMessageOrigin#

typedef enum otMessageOrigin otMessageOrigin

Defines the OpenThread message origins.


Definition at line 81 of file include/openthread/message.h

otMessageSettings#

typedef struct otMessageSettings otMessageSettings

Represents a message settings.


Definition at line 91 of file include/openthread/message.h

otThreadLinkInfo#

typedef struct otThreadLinkInfo otThreadLinkInfo

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


Definition at line 112 of file include/openthread/message.h

otMessageQueueInfo#

typedef struct otMessageQueueInfo otMessageQueueInfo

Represents information about a message queue.


Definition at line 389 of file include/openthread/message.h

otBufferInfo#

typedef struct otBufferInfo otBufferInfo

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


Definition at line 415 of file include/openthread/message.h

Function Documentation#

otMessageFree#

void otMessageFree (otMessage * aMessage)

Free an allocated message buffer.

Parameters
[in]aMessage

A pointer to a message buffer.

See Also


Definition at line 128 of file include/openthread/message.h

otMessageGetLength#

uint16_t otMessageGetLength (const otMessage * aMessage)

Get the message length in bytes.

Parameters
[in]aMessage

A pointer to a message buffer.

Returns

  • The message length in bytes.

See Also


Definition at line 147 of file include/openthread/message.h

otMessageSetLength#

otError otMessageSetLength (otMessage * aMessage, uint16_t aLength)

Set the message length in bytes.

Parameters
[in]aMessage

A pointer to a message buffer.

[in]aLength

A length in bytes.

See Also


Definition at line 167 of file include/openthread/message.h

otMessageGetOffset#

uint16_t otMessageGetOffset (const otMessage * aMessage)

Get the message offset in bytes.

Parameters
[in]aMessage

A pointer to a message buffer.

Returns

  • The message offset value.

See Also


Definition at line 185 of file include/openthread/message.h

otMessageSetOffset#

void otMessageSetOffset (otMessage * aMessage, uint16_t aOffset)

Set the message offset in bytes.

Parameters
[in]aMessage

A pointer to a message buffer.

[in]aOffset

An offset in bytes.

See Also


Definition at line 202 of file include/openthread/message.h

otMessageIsLinkSecurityEnabled#

bool otMessageIsLinkSecurityEnabled (const otMessage * aMessage)

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

Parameters
[in]aMessage

A pointer to a message buffer.


Definition at line 213 of file include/openthread/message.h

otMessageIsLoopbackToHostAllowed#

bool otMessageIsLoopbackToHostAllowed (const otMessage * aMessage)

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

Parameters
[in]aMessage

A pointer to a message buffer.


Definition at line 224 of file include/openthread/message.h

otMessageSetLoopbackToHostAllowed#

void otMessageSetLoopbackToHostAllowed (otMessage * aMessage, bool aAllowLoopbackToHost)

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

Parameters
[in]aMessage

A pointer to a message buffer.

[in]aAllowLoopbackToHost

Whether to allow the message to be looped back to host.


Definition at line 233 of file include/openthread/message.h

otMessageIsMulticastLoopEnabled#

bool otMessageIsMulticastLoopEnabled (otMessage * aMessage)

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

Parameters
[in]aMessage

A pointer to the message.

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.


Definition at line 246 of file include/openthread/message.h

otMessageSetMulticastLoopEnabled#

void otMessageSetMulticastLoopEnabled (otMessage * aMessage, bool aEnabled)

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

Parameters
[in]aMessage

A pointer to the message.

[in]aEnabled

The configuration value.


Definition at line 255 of file include/openthread/message.h

otMessageGetOrigin#

otMessageOrigin otMessageGetOrigin (const otMessage * aMessage)

Gets the message origin.

Parameters
[in]aMessage

A pointer to a message buffer.

Returns

  • The message origin.


Definition at line 265 of file include/openthread/message.h

otMessageSetOrigin#

void otMessageSetOrigin (otMessage * aMessage, otMessageOrigin aOrigin)

Sets the message origin.

Parameters
[in]aMessage

A pointer to a message buffer.

[in]aOrigin

The message origin.


Definition at line 274 of file include/openthread/message.h

otMessageSetDirectTransmission#

void otMessageSetDirectTransmission (otMessage * aMessage, bool aEnabled)

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

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.

Default setting for a new message is false.


Definition at line 285 of file include/openthread/message.h

otMessageGetRss#

int8_t otMessageGetRss (const otMessage * aMessage)

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

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.


Definition at line 295 of file include/openthread/message.h

otMessageGetThreadLinkInfo#

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

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

Parameters
[in]aMessage

The message from which to retrieve otThreadLinkInfo. @pram[out] aLinkInfo A pointer to an otThreadLinkInfo to populate.

N/AaLinkInfo

Definition at line 307 of file include/openthread/message.h

otMessageAppend#

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

Append bytes to a message.

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.

See Also


Definition at line 328 of file include/openthread/message.h

otMessageRead#

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

Read bytes from a message.

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


Definition at line 349 of file include/openthread/message.h

otMessageWrite#

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

Write bytes to a message.

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


Definition at line 370 of file include/openthread/message.h

otMessageQueueInit#

void otMessageQueueInit (otMessageQueue * aQueue)

Initialize the message queue.

Parameters
[in]aQueue

A pointer to a 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.


Definition at line 427 of file include/openthread/message.h

otMessageQueueEnqueue#

void otMessageQueueEnqueue (otMessageQueue * aQueue, otMessage * aMessage)

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

Parameters
[in]aQueue

A pointer to the message queue.

[in]aMessage

The message to add.


Definition at line 436 of file include/openthread/message.h

otMessageQueueEnqueueAtHead#

void otMessageQueueEnqueueAtHead (otMessageQueue * aQueue, otMessage * aMessage)

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

Parameters
[in]aQueue

A pointer to the message queue.

[in]aMessage

The message to add.


Definition at line 445 of file include/openthread/message.h

otMessageQueueDequeue#

void otMessageQueueDequeue (otMessageQueue * aQueue, otMessage * aMessage)

Removes a message from the given message queue.

Parameters
[in]aQueue

A pointer to the message queue.

[in]aMessage

The message to remove.


Definition at line 454 of file include/openthread/message.h

otMessageQueueGetHead#

otMessage * otMessageQueueGetHead (otMessageQueue * aQueue)

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

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.


Definition at line 464 of file include/openthread/message.h

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

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


Definition at line 476 of file include/openthread/message.h

otMessageGetBufferInfo#

void otMessageGetBufferInfo (otInstance * aInstance, otBufferInfo * aBufferInfo)

Get the Message Buffer information.

Parameters
[in]aInstance

A pointer to the OpenThread instance.

[out]aBufferInfo

A pointer where the message buffer information is written.


Definition at line 485 of file include/openthread/message.h

otMessageResetBufferInfo#

void otMessageResetBufferInfo (otInstance * aInstance)

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

Parameters
[in]aInstance

A pointer to the OpenThread instance.

This resets mMaxUsedBuffers in otBufferInfo.


Definition at line 495 of file include/openthread/message.h