[coap] rename low-level Send() to Transmit() in CoapBase (#12635)

This commit renames the low-level `Send()` method in `CoapBase` to
`Transmit()` to clearly differentiate it from the higher-level message
construction and scheduling logic of `SendMessage()`. The `Sender`
function pointer type and member have also been renamed to
`Transmitter` and `mTransmitter`, respectively, to align with the new
terminology.

Using `Transmit()` clearly communicates the action of handing off a
fully prepared CoAP datagram to the underlying transport layer for
transmission, resolving the naming ambiguity with `SendMessage()`.
This establishes a symmetric "Transmit/Receive" boundary between the
CoAP layer and the transport layer.

src/core/coap/coap.cpp

@@ -118,12 +118,12 @@ void Msg::UpdateMessageId(uint16_t aMessageId)
 //---------------------------------------------------------------------------------------------------------------------
 // CoapBase
 
-CoapBase::CoapBase(Instance &aInstance, Sender aSender)
+CoapBase::CoapBase(Instance &aInstance, Transmitter aTransmitter)
     : InstanceLocator(aInstance)
     , mPendingRequests(aInstance, *this)
     , mResponseCache(aInstance)
     , mResourceHandler(nullptr)
-    , mSender(aSender)
+    , mTransmitter(aTransmitter)
     , mMessageId(Random::NonCrypto::GetUint16())
 #if OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE
     , mLastResponse(nullptr)
@@ -228,20 +228,20 @@ exit:
     return aMessage;
 }
 
-Error CoapBase::Send(ot::Message &aMessage, const Ip6::MessageInfo &aMessageInfo)
+Error CoapBase::Transmit(Message &aMessage, const Ip6::MessageInfo &aMessageInfo)
 {
     Error error;
 
 #if OPENTHREAD_CONFIG_OTNS_ENABLE
-    Get<Utils::Otns>().EmitCoapSend(AsCoapMessage(&aMessage), aMessageInfo);
+    Get<Utils::Otns>().EmitCoapSend(aMessage, aMessageInfo);
 #endif
 
-    error = mSender(*this, aMessage, aMessageInfo);
+    error = mTransmitter(*this, aMessage, aMessageInfo);
 
 #if OPENTHREAD_CONFIG_OTNS_ENABLE
     if (error != kErrorNone)
     {
-        Get<Utils::Otns>().EmitCoapSendFailure(error, AsCoapMessage(&aMessage), aMessageInfo);
+        Get<Utils::Otns>().EmitCoapSendFailure(error, aMessage, aMessageInfo);
     }
 #endif
     return error;
@@ -309,7 +309,7 @@ Error CoapBase::SendMessage(Message                &aMessage,
         SuccessOrExit(error = mPendingRequests.AddClone(txMsg.mMessage, copyLength, request));
     }
 
-    SuccessOrExit(error = Send(txMsg.mMessage, txMsg.mMessageInfo));
+    SuccessOrExit(error = Transmit(txMsg.mMessage, txMsg.mMessageInfo));
 
 exit:
 
@@ -439,7 +439,7 @@ Error CoapBase::SendEmptyMessage(Type aType, const Msg &aRxMsg)
     VerifyOrExit((message = NewMessage()) != nullptr, error = kErrorNoBufs);
 
     SuccessOrExit(error = message->Init(aType, kCodeEmpty, aRxMsg.GetMessageId()));
-    SuccessOrExit(error = Send(*message, aRxMsg.mMessageInfo));
+    SuccessOrExit(error = Transmit(*message, aRxMsg.mMessageInfo));
 
 exit:
     FreeMessageOnError(message, error);
@@ -1668,7 +1668,7 @@ void CoapBase::PendingRequests::RetransmitRequest(const Request &aRequest)
 
     aRequest.mMetadata.CopyInfoTo(messageInfo);
 
-    SuccessOrExit(error = mCoapBase.Send(*clone, messageInfo));
+    SuccessOrExit(error = mCoapBase.Transmit(*clone, messageInfo));
 
 exit:
     FreeMessageOnError(clone, error);
@@ -1781,7 +1781,7 @@ Error CoapBase::ResponseCache::SendCachedResponse(const Msg &aRxMsg, CoapBase &a
     response = AsCoapMessagePtr(match->Clone(match->GetLength() - sizeof(ResponseMetadata)));
     VerifyOrExit(response != nullptr, error = kErrorNoBufs);
 
-    error = aCoapBase.Send(*response, aRxMsg.mMessageInfo);
+    error = aCoapBase.Transmit(*response, aRxMsg.mMessageInfo);
 
 exit:
     FreeMessageOnError(response, error);
@@ -2013,7 +2013,7 @@ Resource::Resource(Uri aUri, RequestHandler aHandler, void *aContext)
 // Coap
 
 Coap::Coap(Instance &aInstance)
-    : CoapBase(aInstance, &Coap::Send)
+    : CoapBase(aInstance, Coap::Transmit)
     , mSocket(aInstance, *this)
 {
 }
@@ -2057,12 +2057,12 @@ void Coap::HandleUdpReceive(ot::Message &aMessage, const Ip6::MessageInfo &aMess
     Receive(AsCoapMessage(&aMessage), aMessageInfo);
 }
 
-Error Coap::Send(CoapBase &aCoapBase, ot::Message &aMessage, const Ip6::MessageInfo &aMessageInfo)
+Error Coap::Transmit(CoapBase &aCoapBase, ot::Message &aMessage, const Ip6::MessageInfo &aMessageInfo)
 {
-    return static_cast<Coap &>(aCoapBase).Send(aMessage, aMessageInfo);
+    return static_cast<Coap &>(aCoapBase).Transmit(aMessage, aMessageInfo);
 }
 
-Error Coap::Send(ot::Message &aMessage, const Ip6::MessageInfo &aMessageInfo)
+Error Coap::Transmit(ot::Message &aMessage, const Ip6::MessageInfo &aMessageInfo)
 {
     return mSocket.IsBound() ? mSocket.SendTo(aMessage, aMessageInfo) : kErrorInvalidState;
 }

src/core/coap/coap.hpp

@@ -759,31 +759,31 @@ protected:
     typedef bool (*ResourceHandler)(CoapBase &aCoapBase, const char *aUriPath, Msg &aRxMsg);
 
     /**
-     * Pointer is called to send a CoAP message.
+     * Represents a function reference used to pass a prepared CoAP message to the transport layer for transmission.
      *
      * @param[in]  aCoapBase     A reference to the CoAP agent.
-     * @param[in]  aMessage      A reference to the message to send.
+     * @param[in]  aMessage      A reference to the message to transmit.
      * @param[in]  aMessageInfo  A reference to the message info associated with @p aMessage.
      *
      * @retval kErrorNone    Successfully sent CoAP message.
      * @retval kErrorNoBufs  Failed to allocate retransmission data.
      */
-    typedef Error (*Sender)(CoapBase &aCoapBase, ot::Message &aMessage, const Ip6::MessageInfo &aMessageInfo);
+    typedef Error (&Transmitter)(CoapBase &aCoapBase, ot::Message &aMessage, const Ip6::MessageInfo &aMessageInfo);
 
     /**
-     * Initializes the object.
+     * Initializes the `CoapBase` object.
      *
-     * @param[in]  aInstance        A reference to the OpenThread instance.
+     * @param[in]  aInstance       The OpenThread instance.
-     * @param[in]  aSender          A function pointer to send CoAP message, which SHOULD be a static
+     * @param[in]  aTransmitter    A `Transmitter` function reference used to pass a CoAP message to the transport
-     *                              member method of a descendant of this class.
+     *                             layer for transmission.
      */
-    CoapBase(Instance &aInstance, Sender aSender);
+    CoapBase(Instance &aInstance, Transmitter aTransmitter);
 
     /**
-     * Receives a CoAP message.
+     * Receives a CoAP message from the transport layer.
      *
-     * @param[in]  aMessage      A reference to the received message.
+     * @param[in]  aMessage      The received message.
-     * @param[in]  aMessageInfo  A reference to the message info associated with @p aMessage.
+     * @param[in]  aMessageInfo  The message info associated with @p aMessage.
      */
     void Receive(ot::Message &aMessage, const Ip6::MessageInfo &aMessageInfo);
 
@@ -958,7 +958,7 @@ private:
                          const TxParameters     *aTxParameters,
                          const SendCallbacks    &aCallbacks);
     Error    SendEmptyMessage(Type aType, const Msg &aRxMsg);
-    Error    Send(ot::Message &aMessage, const Ip6::MessageInfo &aMessageInfo);
+    Error    Transmit(Message &aMessage, const Ip6::MessageInfo &aMessageInfo);
 
 #if OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE
 
@@ -991,7 +991,7 @@ private:
     Callback<RequestHandler>   mDefaultHandler;
     Callback<ResponseFallback> mResponseFallback;
     ResourceHandler            mResourceHandler;
-    Sender                     mSender;
+    Transmitter                mTransmitter;
     uint16_t                   mMessageId;
 #if OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE
     LinkedList<ResourceBlockWise> mBlockWiseResources;
@@ -1039,8 +1039,8 @@ protected:
     CoapSocket mSocket;
 
 private:
-    static Error Send(CoapBase &aCoapBase, ot::Message &aMessage, const Ip6::MessageInfo &aMessageInfo);
+    static Error Transmit(CoapBase &aCoapBase, ot::Message &aMessage, const Ip6::MessageInfo &aMessageInfo);
-    Error        Send(ot::Message &aMessage, const Ip6::MessageInfo &aMessageInfo);
+    Error        Transmit(ot::Message &aMessage, const Ip6::MessageInfo &aMessageInfo);
 };
 
 #if OPENTHREAD_CONFIG_COAP_API_ENABLE

src/core/coap/coap_secure.cpp

@@ -43,7 +43,7 @@ namespace Coap {
 RegisterLogModule("CoapSecure");
 
 SecureSession::SecureSession(Instance &aInstance, Dtls::Transport &aDtlsTransport)
-    : CoapBase(aInstance, Transmit)
+    : CoapBase(aInstance, SecureSession::Transmit)
     , Dtls::Session(aDtlsTransport)
     , mTransmitTask(aInstance, HandleTransmitTask, this)
 {