[coap-message] add Coap::MessageQueue class (#4701)

This commit adds `Coap::MessageQueue` class as a subclass of generic
`ot::MessageQueue` as a queue of `Coap::Message` only. This type is
used in `coap.cpp` helping simplify the code (by removing the type
casting).

src/core/coap/coap.cpp

@@ -76,11 +76,11 @@ void CoapBase::ClearRequests(const Ip6::Address *aAddress)
 {
     Message *nextMessage;
 
-    for (Message *message = static_cast<Message *>(mPendingRequests.GetHead()); message != NULL; message = nextMessage)
+    for (Message *message = mPendingRequests.GetHead(); message != NULL; message = nextMessage)
     {
         Metadata metadata;
 
-        nextMessage = static_cast<Message *>(message->GetNext());
+        nextMessage = message->GetNextCoapMessage();
         metadata.ReadFrom(*message);
 
         if ((aAddress == NULL) || (metadata.mSourceAddress == *aAddress))
@@ -339,9 +339,9 @@ void CoapBase::HandleRetransmissionTimer(void)
     Message *        nextMessage;
     Ip6::MessageInfo messageInfo;
 
-    for (Message *message = static_cast<Message *>(mPendingRequests.GetHead()); message != NULL; message = nextMessage)
+    for (Message *message = mPendingRequests.GetHead(); message != NULL; message = nextMessage)
     {
-        nextMessage = static_cast<Message *>(message->GetNext());
+        nextMessage = message->GetNextCoapMessage();
 
         metadata.ReadFrom(*message);
 
@@ -411,9 +411,9 @@ otError CoapBase::AbortTransaction(ResponseHandler aHandler, void *aContext)
     Message *nextMessage;
     Metadata metadata;
 
-    for (Message *message = static_cast<Message *>(mPendingRequests.GetHead()); message != NULL; message = nextMessage)
+    for (Message *message = mPendingRequests.GetHead(); message != NULL; message = nextMessage)
     {
-        nextMessage = static_cast<Message *>(message->GetNext());
+        nextMessage = message->GetNextCoapMessage();
         metadata.ReadFrom(*message);
 
         if (metadata.mResponseHandler == aHandler && metadata.mResponseContext == aContext)
@@ -492,8 +492,7 @@ Message *CoapBase::FindRelatedRequest(const Message &         aResponse,
 {
     Message *message;
 
-    for (message = static_cast<Message *>(mPendingRequests.GetHead()); message != NULL;
-         message = static_cast<Message *>(message->GetNext()))
+    for (message = mPendingRequests.GetHead(); message != NULL; message = message->GetNextCoapMessage())
     {
         aMetadata.ReadFrom(*message);
 
@@ -809,8 +808,7 @@ const Message *ResponsesQueue::FindMatchedResponse(const Message &aRequest, cons
 {
     Message *message;
 
-    for (message = static_cast<Message *>(mQueue.GetHead()); message != NULL;
-         message = static_cast<Message *>(message->GetNext()))
+    for (message = mQueue.GetHead(); message != NULL; message = message->GetNextCoapMessage())
     {
         if (message->GetMessageId() == aRequest.GetMessageId())
         {
@@ -865,8 +863,7 @@ void ResponsesQueue::UpdateQueue(void)
     // `kMaxCachedResponses` remove the one with earliest dequeue
     // time.
 
-    for (Message *message = static_cast<Message *>(mQueue.GetHead()); message != NULL;
-         message          = static_cast<Message *>(message->GetNext()))
+    for (Message *message = mQueue.GetHead(); message != NULL; message = message->GetNextCoapMessage())
     {
         ResponseMetadata metadata;
 
@@ -897,7 +894,7 @@ void ResponsesQueue::DequeueAllResponses(void)
 {
     Message *message;
 
-    while ((message = static_cast<Message *>(mQueue.GetHead())) != NULL)
+    while ((message = mQueue.GetHead()) != NULL)
     {
         DequeueResponse(*message);
     }
@@ -914,11 +911,11 @@ void ResponsesQueue::HandleTimer(void)
     TimeMilli nextDequeueTime = now.GetDistantFuture();
     Message * nextMessage;
 
-    for (Message *message = static_cast<Message *>(mQueue.GetHead()); message != NULL; message = nextMessage)
+    for (Message *message = mQueue.GetHead(); message != NULL; message = nextMessage)
     {
         ResponseMetadata metadata;
 
-        nextMessage = static_cast<Message *>(message->GetNext());
+        nextMessage = message->GetNextCoapMessage();
 
         metadata.ReadFrom(*message);
 

src/core/coap/coap_message.hpp

@@ -545,6 +545,28 @@ public:
      */
     static uint16_t GetHelpDataReserved(void) { return sizeof(HelpData) + kHelpDataAlignment; }
 
+    /**
+     * This method returns a pointer to the next message after this as a `Coap::Message`.
+     *
+     * This method should be used when the message is in a `Coap::MessageQueue` (i.e., a queue containing only CoAP
+     * messages).
+     *
+     * @returns A pointer to the next message in the queue or NULL if at the end of the queue.
+     *
+     */
+    Message *GetNextCoapMessage(void) { return static_cast<Message *>(GetNext()); }
+
+    /**
+     * This method returns a pointer to the next message after this as a `Coap::Message`.
+     *
+     * This method should be used when the message is in a `Coap::MessageQueue` (i.e., a queue containing only CoAP
+     * messages).
+     *
+     * @returns A pointer to the next message in the queue or NULL if at the end of the queue.
+     *
+     */
+    const Message *GetNextCoapMessage(void) const { return static_cast<const Message *>(GetNext()); }
+
 private:
     /**
      * Protocol Constants (RFC 7252).
@@ -627,13 +649,79 @@ private:
     HelpData &GetHelpData(void) { return const_cast<HelpData &>(static_cast<const Message *>(this)->GetHelpData()); }
 };
 
+/**
+ * This class implements a CoAP message queue.
+ *
+ */
+class MessageQueue : public ot::MessageQueue
+{
+public:
+    /**
+     * This constructor initializes the message queue.
+     *
+     */
+    MessageQueue(void)
+        : ot::MessageQueue()
+    {
+    }
+
+    /**
+     * This method returns a pointer to the first message.
+     *
+     * @returns A pointer to the first message.
+     *
+     */
+    Message *GetHead(void) const { return static_cast<Message *>(ot::MessageQueue::GetHead()); }
+
+    /**
+     * This method adds a message to the end of the queue.
+     *
+     * @param[in]  aMessage  The message to add.
+     *
+     * @retval OT_ERROR_NONE     Successfully added the message to the queue.
+     * @retval OT_ERROR_ALREADY  The message is already enqueued in a queue.
+     *
+     */
+    otError Enqueue(Message &aMessage) { return Enqueue(aMessage, kQueuePositionTail); }
+
+    /**
+     * This method adds a message at a given position (head/tail) of the queue.
+     *
+     * @param[in]  aMessage  The message to add.
+     * @param[in]  aPosition The position (head or tail) where to add the message.
+     *
+     * @retval OT_ERROR_NONE     Successfully added the message to the queue.
+     * @retval OT_ERROR_ALREADY  The message is already enqueued in a queue.
+     *
+     */
+    otError Enqueue(Message &aMessage, QueuePosition aPosition)
+    {
+        return ot::MessageQueue::Enqueue(aMessage, aPosition);
+    }
+
+    /**
+     * This method removes a message from the queue.
+     *
+     * @param[in]  aMessage  The message to remove.
+     *
+     * @retval OT_ERROR_NONE       Successfully removed the message from the queue.
+     * @retval OT_ERROR_NOT_FOUND  The message is not enqueued in a queue.
+     *
+     */
+    otError Dequeue(Message &aMessage) { return ot::MessageQueue::Dequeue(aMessage); }
+};
+
+/**
+ * This class acts as an iterator for CoAP options.
+ *
+ */
 class OptionIterator : public ::otCoapOptionIterator
 {
 public:
     /**
-     * Initialise the state of the iterator to iterate over the given message.
+     * Initialize the state of the iterator to iterate over the given message.
      *
-     * @retval  OT_ERROR_NONE   Successfully initialised
+     * @retval  OT_ERROR_NONE   Successfully initialized
      * @retval  OT_ERROR_PARSE  Message state is inconsistent
      *
      */

src/core/coap/coap_secure.hpp

@@ -325,7 +325,7 @@ private:
     MeshCoP::Dtls     mDtls;
     ConnectedCallback mConnectedCallback;
     void *            mConnectedContext;
-    MessageQueue      mTransmitQueue;
+    ot::MessageQueue  mTransmitQueue;
     TaskletContext    mTransmitTask;
 };