diff --git a/include/openthread/instance.h b/include/openthread/instance.h index 300c75e40..7b477b762 100644 --- a/include/openthread/instance.h +++ b/include/openthread/instance.h @@ -53,7 +53,7 @@ extern "C" { * @note This number versions both OpenThread platform and user APIs. * */ -#define OPENTHREAD_API_VERSION (80) +#define OPENTHREAD_API_VERSION (81) /** * @addtogroup api-instance diff --git a/include/openthread/message.h b/include/openthread/message.h index ba3527944..9c59b5212 100644 --- a/include/openthread/message.h +++ b/include/openthread/message.h @@ -53,12 +53,10 @@ extern "C" { */ /** - * This structure points to an OpenThread message buffer. + * This type is an opaque representation of an OpenThread message buffer. + * */ -typedef struct otMessage -{ - struct otMessage *mNext; ///< A pointer to the next Message buffer. -} otMessage; +typedef struct otMessage otMessage; /** * This structure represents the message buffer information. diff --git a/include/openthread/platform/messagepool.h b/include/openthread/platform/messagepool.h index 3391c4a21..6f369c721 100644 --- a/include/openthread/platform/messagepool.h +++ b/include/openthread/platform/messagepool.h @@ -53,12 +53,23 @@ extern "C" { #endif +/** + * This struct represents an OpenThread message buffer. + * + */ +typedef struct otMessageBuffer +{ + struct otMessageBuffer *mNext; ///< Pointer to the next buffer. +} otMessageBuffer; + /** * Initialize the platform implemented message pool. * + * This function is used when `OPENTHREAD_CONFIG_PLATFORM_MESSAGE_MANAGEMENT` is enabled. + * * @param[in] aInstance A pointer to the OpenThread instance. * @param[in] aMinNumFreeBuffers An uint16 containing the minimum number of free buffers desired by OpenThread. - * @param[in] aBufferSize The size in bytes of a Buffer object. + * @param[in] aBufferSize The size in bytes of a buffer object. * */ void otPlatMessagePoolInit(otInstance *aInstance, uint16_t aMinNumFreeBuffers, size_t aBufferSize); @@ -66,25 +77,33 @@ void otPlatMessagePoolInit(otInstance *aInstance, uint16_t aMinNumFreeBuffers, s /** * Allocate a buffer from the platform managed buffer pool. * + * This function is used when `OPENTHREAD_CONFIG_PLATFORM_MESSAGE_MANAGEMENT` is enabled. + * + * The returned buffer instance MUST have at least `aBufferSize` bytes (as specified in `otPlatMessagePoolInit()`). + * * @param[in] aInstance A pointer to the OpenThread instance. * - * @returns A pointer to the Buffer or NULL if no Buffers are available. + * @returns A pointer to the buffer or NULL if no buffers are available. * */ -otMessage *otPlatMessagePoolNew(otInstance *aInstance); +otMessageBuffer *otPlatMessagePoolNew(otInstance *aInstance); /** - * This function is used to free a Buffer back to the platform managed buffer pool. + * This function is used to free a buffer back to the platform managed buffer pool. + * + * This function is used when `OPENTHREAD_CONFIG_PLATFORM_MESSAGE_MANAGEMENT` is enabled. * * @param[in] aInstance A pointer to the OpenThread instance. - * @param[in] aBuffer The Buffer to free. + * @param[in] aBuffer The buffer to free. * */ -void otPlatMessagePoolFree(otInstance *aInstance, otMessage *aBuffer); +void otPlatMessagePoolFree(otInstance *aInstance, otMessageBuffer *aBuffer); /** * Get the number of free buffers. * + * This function is used when `OPENTHREAD_CONFIG_PLATFORM_MESSAGE_MANAGEMENT` is enabled. + * * @param[in] aInstance A pointer to the OpenThread instance. * * @returns The number of buffers currently free and available to OpenThread. diff --git a/src/core/common/message.hpp b/src/core/common/message.hpp index 13f46e774..65f1b1c4f 100644 --- a/src/core/common/message.hpp +++ b/src/core/common/message.hpp @@ -52,6 +52,14 @@ #include "thread/child_mask.hpp" #include "thread/link_quality.hpp" +/** + * This struct represents an opaque (and empty) type for an OpenThread message buffer. + * + */ +struct otMessage +{ +}; + namespace ot { namespace Crypto { @@ -198,9 +206,10 @@ struct MessageMetadata * This class represents a Message buffer. * */ -class Buffer : public otMessage, public LinkedListEntry +class Buffer : public otMessageBuffer, public LinkedListEntry { friend class Message; + friend class LinkedListEntry; public: /** @@ -278,7 +287,7 @@ private: enum { - kBufferDataSize = kBufferSize - sizeof(otMessage), + kBufferDataSize = kBufferSize - sizeof(otMessageBuffer), kHeadBufferDataSize = kBufferDataSize - sizeof(MessageMetadata), }; @@ -298,7 +307,7 @@ protected: * This class represents a message. * */ -class Message : public Buffer +class Message : public otMessage, public Buffer { friend class Checksum; friend class Crypto::HmacSha256;