[coap] add payload marker when block-wise transfer starts (#12381)

This commit updates `CoapBase::ProcessBlockwiseSend()` to ensure a
Payload Marker is appended before adding the first block of data.

`SendMessage()` always calls `ParseHeaderAndOptions()` with
`kRemovePayloadMarkerIfNoPayload`, which removes any existing payload
marker if the message body is empty. However, for block-wise transfers,
the payload is added later via the block-wise transmit hook in
`ProcessBlockwiseSend()`. If the marker was removed, the first
block would be appended directly after the options without a
separator, resulting in a malformed CoAP message.

This change ensures that `ProcessBlockwiseSend()` explicitly restores
or adds the payload marker before appending the block data. The
documentation for `Message::AppendPayloadMarker()` is also updated to
clarify that the method is idempotent, making no changes if a marker
is already present.

src/core/coap/coap.cpp

@@ -978,6 +978,8 @@ Error CoapBase::ProcessBlockwiseSend(Msg &aMsg, const SendCallbacks &aCallbacks)
     VerifyOrExit(blockSize <= kMaxBlockSize, error = kErrorNoBufs);
 
     SuccessOrExit(error = aCallbacks.mBlockwiseTransmitHook(aCallbacks.mContext, buf, 0, &blockSize, &moreBlocks));
+
+    SuccessOrExit(error = aMsg.mMessage.AppendPayloadMarker());
     SuccessOrExit(error = aMsg.mMessage.AppendBytes(buf, blockSize));
 
     switch (type)

src/core/coap/coap_message.hpp

@@ -818,10 +818,11 @@ public:
     /**
      * Appends a Payload Marker indicating the beginning of the payload.
      *
-     * It also sets the offset to the start of the payload.
+     * If the message already contains a Payload Marker, this method makes no changes. If it appends a Payload
+     * Marker, it also sets the message offset to the start of the payload.
      *
-     * @retval kErrorNone    Payload Marker was successfully added.
-     * @retval kErrorNoBufs  Could not grow the message to append the payload marker.
+     * @retval kErrorNone    Payload Marker was successfully added or was already present in the message.
+     * @retval kErrorNoBufs  Could not grow the message to append the Payload Marker.
      */
     Error AppendPayloadMarker(void);