Message

This module includes functions that manipulate OpenThread message buffers.

Summary

Enumerations
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.
otMessagePriority	typedef enum otMessagePriority Defines the OpenThread message priority levels.
otMessageQueueInfo	typedef struct otMessageQueueInfo Represents information about a message queue.
otMessageSettings	typedef struct otMessageSettings Represents a message settings.

Functions
otMessageAppend(otMessage *aMessage, const void *aBuf, uint16_t aLength)	otError 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.
otMessageGetLength(const otMessage *aMessage)	uint16_t Get the message length in bytes.
otMessageGetOffset(const otMessage *aMessage)	uint16_t Get the message offset in bytes.
otMessageGetRss(const otMessage *aMessage)	int8_t Returns the average RSS (received signal strength) associated with the message.
otMessageIsLinkSecurityEnabled(const otMessage *aMessage)	bool Indicates whether or not link security is enabled for the message.
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)	otMessage * Returns a pointer to the message at the head of the queue.
otMessageQueueGetNext(otMessageQueue *aQueue, const otMessage *aMessage)	otMessage * 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.
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)	otError Set the message length in bytes.
otMessageSetOffset(otMessage *aMessage, uint16_t aOffset)	void Set the message offset in bytes.
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.

Enumerations

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.

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.

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.

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

otMessageGetRss

int8_t otMessageGetRss(
  const otMessage *aMessage
)

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

Details
Returns	The average RSS value (in dBm) or OT_RADIO_RSSI_INVALID if no average RSS is available.

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.

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

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

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

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.