From b838d67954782a4009b292dc34ce99ba303a3fb7 Mon Sep 17 00:00:00 2001 From: Abtin Keshavarzian Date: Thu, 8 Jan 2026 11:14:30 -0800 Subject: [PATCH] [coap] clean up `coap.h` header and API definitions (#12259) This commit improves the structure and readability of the CoAP public API header(`coap.h`) and its implementation (`coap_api.cpp`). - Reorganizes function and type declarations in `coap.h` and their corresponding definitions in `coap_api.cpp` into logical groups to improve clarity. For example, group all block-wise transfer APIs together. There is no change to the API documentation. - Moves the definitions of several `static inline` functions (e.g., `otCoapSendRequest`, `otCoapSendResponse`, and block-wise transfer variants) from `coap.h` to `coap_api.cpp`. - Updates `otCoapOptionContentFormat` enum comments to use the `///<` style for better consistency and alignment. --- include/openthread/coap.h | 611 ++++++++++++++-------------------- include/openthread/instance.h | 2 +- src/core/api/coap_api.cpp | 134 +++++--- 3 files changed, 336 insertions(+), 411 deletions(-) diff --git a/include/openthread/coap.h b/include/openthread/coap.h index 1f7748a86..f4eb8122e 100644 --- a/include/openthread/coap.h +++ b/include/openthread/coap.h @@ -36,7 +36,6 @@ #define OPENTHREAD_COAP_H_ #include -#include #include #include @@ -175,141 +174,33 @@ typedef struct otCoapOptionIterator */ typedef enum otCoapOptionContentFormat { - /** - * text/plain; charset=utf-8: [RFC2046][RFC3676][RFC5147] - */ - OT_COAP_OPTION_CONTENT_FORMAT_TEXT_PLAIN = 0, - - /** - * application/cose; cose-type="cose-encrypt0": [RFC8152] - */ - OT_COAP_OPTION_CONTENT_FORMAT_COSE_ENCRYPT0 = 16, - - /** - * application/cose; cose-type="cose-mac0": [RFC8152] - */ - OT_COAP_OPTION_CONTENT_FORMAT_COSE_MAC0 = 17, - - /** - * application/cose; cose-type="cose-sign1": [RFC8152] - */ - OT_COAP_OPTION_CONTENT_FORMAT_COSE_SIGN1 = 18, - - /** - * application/link-format: [RFC6690] - */ - OT_COAP_OPTION_CONTENT_FORMAT_LINK_FORMAT = 40, - - /** - * application/xml: [RFC3023] - */ - OT_COAP_OPTION_CONTENT_FORMAT_XML = 41, - - /** - * application/octet-stream: [RFC2045][RFC2046] - */ - OT_COAP_OPTION_CONTENT_FORMAT_OCTET_STREAM = 42, - - /** - * application/exi: - * ["Efficient XML Interchange (EXI) Format 1.0 (Second Edition)", February 2014] - */ - OT_COAP_OPTION_CONTENT_FORMAT_EXI = 47, - - /** - * application/json: [RFC7159] - */ - OT_COAP_OPTION_CONTENT_FORMAT_JSON = 50, - - /** - * application/json-patch+json: [RFC6902] - */ - OT_COAP_OPTION_CONTENT_FORMAT_JSON_PATCH_JSON = 51, - - /** - * application/merge-patch+json: [RFC7396] - */ - OT_COAP_OPTION_CONTENT_FORMAT_MERGE_PATCH_JSON = 52, - - /** - * application/cbor: [RFC7049] - */ - OT_COAP_OPTION_CONTENT_FORMAT_CBOR = 60, - - /** - * application/cwt: [RFC8392] - */ - OT_COAP_OPTION_CONTENT_FORMAT_CWT = 61, - - /** - * application/cose; cose-type="cose-encrypt": [RFC8152] - */ - OT_COAP_OPTION_CONTENT_FORMAT_COSE_ENCRYPT = 96, - - /** - * application/cose; cose-type="cose-mac": [RFC8152] - */ - OT_COAP_OPTION_CONTENT_FORMAT_COSE_MAC = 97, - - /** - * application/cose; cose-type="cose-sign": [RFC8152] - */ - OT_COAP_OPTION_CONTENT_FORMAT_COSE_SIGN = 98, - - /** - * application/cose-key: [RFC8152] - */ - OT_COAP_OPTION_CONTENT_FORMAT_COSE_KEY = 101, - - /** - * application/cose-key-set: [RFC8152] - */ - OT_COAP_OPTION_CONTENT_FORMAT_COSE_KEY_SET = 102, - - /** - * application/senml+json: [RFC8428] - */ - OT_COAP_OPTION_CONTENT_FORMAT_SENML_JSON = 110, - - /** - * application/sensml+json: [RFC8428] - */ - OT_COAP_OPTION_CONTENT_FORMAT_SENSML_JSON = 111, - - /** - * application/senml+cbor: [RFC8428] - */ - OT_COAP_OPTION_CONTENT_FORMAT_SENML_CBOR = 112, - - /** - * application/sensml+cbor: [RFC8428] - */ - OT_COAP_OPTION_CONTENT_FORMAT_SENSML_CBOR = 113, - - /** - * application/senml-exi: [RFC8428] - */ - OT_COAP_OPTION_CONTENT_FORMAT_SENML_EXI = 114, - - /** - * application/sensml-exi: [RFC8428] - */ - OT_COAP_OPTION_CONTENT_FORMAT_SENSML_EXI = 115, - - /** - * application/coap-group+json: [RFC7390] - */ - OT_COAP_OPTION_CONTENT_FORMAT_COAP_GROUP_JSON = 256, - - /** - * application/senml+xml: [RFC8428] - */ - OT_COAP_OPTION_CONTENT_FORMAT_SENML_XML = 310, - - /** - * application/sensml+xml: [RFC8428] - */ - OT_COAP_OPTION_CONTENT_FORMAT_SENSML_XML = 311 + OT_COAP_OPTION_CONTENT_FORMAT_TEXT_PLAIN = 0, ///< txt/plain; charset=utf-8: [RFC2046][RFC3676][RFC5147] + OT_COAP_OPTION_CONTENT_FORMAT_COSE_ENCRYPT0 = 16, ///< application/cose; cose-type="cose-encrypt0": [RFC8152] + OT_COAP_OPTION_CONTENT_FORMAT_COSE_MAC0 = 17, ///< application/cose; cose-type="cose-mac0": [RFC8152] + OT_COAP_OPTION_CONTENT_FORMAT_COSE_SIGN1 = 18, ///< application/cose; cose-type="cose-sign1": [RFC8152] + OT_COAP_OPTION_CONTENT_FORMAT_LINK_FORMAT = 40, ///< application/link-format: [RFC6690] + OT_COAP_OPTION_CONTENT_FORMAT_XML = 41, ///< application/xml: [RFC3023] + OT_COAP_OPTION_CONTENT_FORMAT_OCTET_STREAM = 42, ///< application/octet-stream: [RFC2045][RFC2046] + OT_COAP_OPTION_CONTENT_FORMAT_EXI = 47, ///< application/exi: ["Efficient XML Interchange (EXI)"] + OT_COAP_OPTION_CONTENT_FORMAT_JSON = 50, ///< application/json: [RFC7159] + OT_COAP_OPTION_CONTENT_FORMAT_JSON_PATCH_JSON = 51, ///< application/json-patch+json: [RFC6902] + OT_COAP_OPTION_CONTENT_FORMAT_MERGE_PATCH_JSON = 52, ///< application/merge-patch+json: [RFC7396] + OT_COAP_OPTION_CONTENT_FORMAT_CBOR = 60, ///< application/cbor: [RFC7049] + OT_COAP_OPTION_CONTENT_FORMAT_CWT = 61, ///< application/cwt: [RFC8392] + OT_COAP_OPTION_CONTENT_FORMAT_COSE_ENCRYPT = 96, ///< application/cose; cose-type="cose-encrypt": [RFC8152] + OT_COAP_OPTION_CONTENT_FORMAT_COSE_MAC = 97, ///< application/cose; cose-type="cose-mac": [RFC8152] + OT_COAP_OPTION_CONTENT_FORMAT_COSE_SIGN = 98, ///< application/cose; cose-type="cose-sign": [RFC8152] + OT_COAP_OPTION_CONTENT_FORMAT_COSE_KEY = 101, ///< application/cose-key: [RFC8152] + OT_COAP_OPTION_CONTENT_FORMAT_COSE_KEY_SET = 102, ///< application/cose-key-set: [RFC8152] + OT_COAP_OPTION_CONTENT_FORMAT_SENML_JSON = 110, ///< application/senml+json: [RFC8428] + OT_COAP_OPTION_CONTENT_FORMAT_SENSML_JSON = 111, ///< application/sensml+json: [RFC8428] + OT_COAP_OPTION_CONTENT_FORMAT_SENML_CBOR = 112, ///< application/senml+cbor: [RFC8428] + OT_COAP_OPTION_CONTENT_FORMAT_SENSML_CBOR = 113, ///< application/sensml+cbor: [RFC8428] + OT_COAP_OPTION_CONTENT_FORMAT_SENML_EXI = 114, ///< application/senml-exi: [RFC8428] + OT_COAP_OPTION_CONTENT_FORMAT_SENSML_EXI = 115, ///< application/sensml-exi: [RFC8428] + OT_COAP_OPTION_CONTENT_FORMAT_COAP_GROUP_JSON = 256, ///< application/coap-group+json: [RFC7390] + OT_COAP_OPTION_CONTENT_FORMAT_SENML_XML = 310, ///< application/senml+xml: [RFC8428] + OT_COAP_OPTION_CONTENT_FORMAT_SENSML_XML = 311 ///< application/sensml+xml: [RFC8428] } otCoapOptionContentFormat; /** @@ -364,56 +255,6 @@ typedef void (*otCoapRequestHandler)(void *aContext, otMessage *aMessage, const */ typedef bool (*otCoapResponseFallback)(void *aContext, otMessage *aMessage, const otMessageInfo *aMessageInfo); -/** - * Pointer is called when a CoAP message with a block-wise transfer option is received. - * - * Is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE configuration - * is enabled. - * - * @param[in] aContext A pointer to application-specific context. - * @param[in] aBlock A pointer to the block segment. - * @param[in] aPosition The position of @p aBlock in a sequence in bytes. - * @param[in] aBlockLength The length of the block segment in bytes. - * @param[in] aMore Flag if more block segments are following. - * @param[in] aTotalLength The total length in bytes of the transferred information (indicated by a Size1 or Size2 - * option). - * - * @retval OT_ERROR_NONE Block segment was stored successfully. - * @retval OT_ERROR_NO_BUFS No more memory to store blocks. - * @retval OT_ERROR_NO_FRAME_RECEIVED Block segment missing. - */ -typedef otError (*otCoapBlockwiseReceiveHook)(void *aContext, - const uint8_t *aBlock, - uint32_t aPosition, - uint16_t aBlockLength, - bool aMore, - uint32_t aTotalLength); - -/** - * Pointer is called before the next block in a block-wise transfer is sent. - * - * Is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE configuration - * is enabled. - * - * @param[in] aContext A pointer to application-specific context. - * @param[in,out] aBlock A pointer to where the block segment can be written to. - * @param[in] aPosition The position in a sequence from which to obtain the block segment. - * @param[in,out] aBlockLength On entry, the maximum block segment length in bytes. - * @param[out] aMore A pointer to the flag if more block segments will follow. - * - * @warning By changing the value of aBlockLength, the block size of the whole exchange is - * renegotiated. It is recommended to do this after the first block has been received as - * later changes could cause problems with other CoAP implementations. - * - * @retval OT_ERROR_NONE No error occurred. - * @retval OT_ERROR_INVALID_ARGS Block at @p aPosition does not exist. - */ -typedef otError (*otCoapBlockwiseTransmitHook)(void *aContext, - uint8_t *aBlock, - uint32_t aPosition, - uint16_t *aBlockLength, - bool *aMore); - /** * Represents a CoAP resource. */ @@ -425,29 +266,6 @@ typedef struct otCoapResource struct otCoapResource *mNext; ///< The next CoAP resource in the list } otCoapResource; -/** - * Represents a CoAP resource with block-wise transfer. - */ -typedef struct otCoapBlockwiseResource -{ - const char *mUriPath; ///< The URI Path string - otCoapRequestHandler mHandler; ///< The callback for handling a received request - - /** The callback for handling incoming block-wise transfer. - * This callback is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE - * configuration is enabled. - */ - otCoapBlockwiseReceiveHook mReceiveHook; - - /** The callback for handling outgoing block-wise transfer. - * This callback is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE - * configuration is enabled. - */ - otCoapBlockwiseTransmitHook mTransmitHook; - void *mContext; ///< Application-specific context - struct otCoapBlockwiseResource *mNext; ///< The next CoAP resource in the list -} otCoapBlockwiseResource; - /** * Represents the CoAP transmission parameters. * @@ -481,6 +299,9 @@ typedef struct otCoapTxParameters uint8_t mMaxRetransmit; } otCoapTxParameters; +//---------------------------------------------------------------------------------------------------------------------- +// `otCoapMessage*` APIs - Constructing or parsing a CoAP message. + /** * Initializes the CoAP header. * @@ -756,13 +577,16 @@ uint8_t otCoapMessageGetTokenLength(const otMessage *aMessage); */ const uint8_t *otCoapMessageGetToken(const otMessage *aMessage); +//--------------------------------------------------------------------------------------------------------------------- +// `otCoapOptionIterator*` APIs - Iterating over CoAP Options in a CoAP message. + /** - * Initialises an iterator for the options in the given message. + * Initializes an iterator for the options in the given message. * * @param[in,out] aIterator A pointer to the CoAP message option iterator. * @param[in] aMessage A pointer to the CoAP message. * - * @retval OT_ERROR_NONE Successfully initialised. + * @retval OT_ERROR_NONE Successfully initialized. * @retval OT_ERROR_PARSE Message state is inconsistent. */ otError otCoapOptionIteratorInit(otCoapOptionIterator *aIterator, const otMessage *aMessage); @@ -831,6 +655,9 @@ otError otCoapOptionIteratorGetOptionUintValue(otCoapOptionIterator *aIterator, */ otError otCoapOptionIteratorGetOptionValue(otCoapOptionIterator *aIterator, void *aValue); +//--------------------------------------------------------------------------------------------------------------------- +// `otCoap*` APIs - Send and receive + /** * Creates a new CoAP message. * @@ -872,6 +699,206 @@ otError otCoapSendRequestWithParameters(otInstance *aInstance, void *aContext, const otCoapTxParameters *aTxParameters); +/** + * Sends a CoAP request. + * + * If a response for a request is expected, respective function and context information should be provided. + * If no response is expected, these arguments should be NULL pointers. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * @param[in] aMessage A pointer to the message to send. + * @param[in] aMessageInfo A pointer to the message info associated with @p aMessage. + * @param[in] aHandler A function pointer that shall be called on response reception or timeout. + * @param[in] aContext A pointer to arbitrary context information. May be NULL if not used. + * + * @retval OT_ERROR_NONE Successfully sent CoAP message. + * @retval OT_ERROR_NO_BUFS Failed to allocate retransmission data. + */ +otError otCoapSendRequest(otInstance *aInstance, + otMessage *aMessage, + const otMessageInfo *aMessageInfo, + otCoapResponseHandler aHandler, + void *aContext); +/** + * Starts the CoAP server. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * @param[in] aPort The local UDP port to bind to. + * + * @retval OT_ERROR_NONE Successfully started the CoAP server. + * @retval OT_ERROR_FAILED Failed to start the CoAP server. + */ +otError otCoapStart(otInstance *aInstance, uint16_t aPort); + +/** + * Stops the CoAP server. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * + * @retval OT_ERROR_NONE Successfully stopped the CoAP server. + */ +otError otCoapStop(otInstance *aInstance); + +/** + * Adds a resource to the CoAP server. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * @param[in] aResource A pointer to the resource. + */ +void otCoapAddResource(otInstance *aInstance, otCoapResource *aResource); + +/** + * Removes a resource from the CoAP server. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * @param[in] aResource A pointer to the resource. + */ +void otCoapRemoveResource(otInstance *aInstance, otCoapResource *aResource); + +/** + * Sets the default handler for unhandled CoAP requests. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * @param[in] aHandler A function pointer that shall be called when an unhandled request arrives. + * @param[in] aContext A pointer to arbitrary context information. May be NULL if not used. + */ +void otCoapSetDefaultHandler(otInstance *aInstance, otCoapRequestHandler aHandler, void *aContext); + +/** + * Sets a fallback handler for CoAP responses not matching any active/pending request. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * @param[in] aHandler A function pointer that shall be called as a fallback for responses without matching + * active/pending CoAP requests. + * @param[in] aContext A pointer to arbitrary context information. May be NULL if not used. + */ +void otCoapSetResponseFallback(otInstance *aInstance, otCoapResponseFallback aHandler, void *aContext); + +/** + * Sends a CoAP response from the server with custom transmission parameters. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * @param[in] aMessage A pointer to the CoAP response to send. + * @param[in] aMessageInfo A pointer to the message info associated with @p aMessage. + * @param[in] aTxParameters A pointer to transmission parameters for this response. Use NULL for defaults. + * + * @retval OT_ERROR_NONE Successfully enqueued the CoAP response message. + * @retval OT_ERROR_NO_BUFS Insufficient buffers available to send the CoAP response. + * @retval OT_ERROR_INVALID_ARGS Invalid arguments are given. + */ +otError otCoapSendResponseWithParameters(otInstance *aInstance, + otMessage *aMessage, + const otMessageInfo *aMessageInfo, + const otCoapTxParameters *aTxParameters); + +/** + * Sends a CoAP response from the server. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * @param[in] aMessage A pointer to the CoAP response to send. + * @param[in] aMessageInfo A pointer to the message info associated with @p aMessage. + * + * @retval OT_ERROR_NONE Successfully enqueued the CoAP response message. + * @retval OT_ERROR_NO_BUFS Insufficient buffers available to send the CoAP response. + */ +otError otCoapSendResponse(otInstance *aInstance, otMessage *aMessage, const otMessageInfo *aMessageInfo); + +//---------------------------------------------------------------------------------------------------------------------- +// Block-wise transfer (requires `OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE`). + +/** + * Pointer is called when a CoAP message with a block-wise transfer option is received. + * + * Is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE configuration + * is enabled. + * + * @param[in] aContext A pointer to application-specific context. + * @param[in] aBlock A pointer to the block segment. + * @param[in] aPosition The position of @p aBlock in a sequence in bytes. + * @param[in] aBlockLength The length of the block segment in bytes. + * @param[in] aMore Flag if more block segments are following. + * @param[in] aTotalLength The total length in bytes of the transferred information (indicated by a Size1 or Size2 + * option). + * + * @retval OT_ERROR_NONE Block segment was stored successfully. + * @retval OT_ERROR_NO_BUFS No more memory to store blocks. + * @retval OT_ERROR_NO_FRAME_RECEIVED Block segment missing. + */ +typedef otError (*otCoapBlockwiseReceiveHook)(void *aContext, + const uint8_t *aBlock, + uint32_t aPosition, + uint16_t aBlockLength, + bool aMore, + uint32_t aTotalLength); + +/** + * Pointer is called before the next block in a block-wise transfer is sent. + * + * Is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE configuration + * is enabled. + * + * @param[in] aContext A pointer to application-specific context. + * @param[in,out] aBlock A pointer to where the block segment can be written to. + * @param[in] aPosition The position in a sequence from which to obtain the block segment. + * @param[in,out] aBlockLength On entry, the maximum block segment length in bytes. + * @param[out] aMore A pointer to the flag if more block segments will follow. + * + * @warning By changing the value of aBlockLength, the block size of the whole exchange is + * renegotiated. It is recommended to do this after the first block has been received as + * later changes could cause problems with other CoAP implementations. + * + * @retval OT_ERROR_NONE No error occurred. + * @retval OT_ERROR_INVALID_ARGS Block at @p aPosition does not exist. + */ +typedef otError (*otCoapBlockwiseTransmitHook)(void *aContext, + uint8_t *aBlock, + uint32_t aPosition, + uint16_t *aBlockLength, + bool *aMore); + +/** + * Represents a CoAP resource with block-wise transfer. + */ +typedef struct otCoapBlockwiseResource +{ + const char *mUriPath; ///< The URI Path string + otCoapRequestHandler mHandler; ///< The callback for handling a received request + + /** The callback for handling incoming block-wise transfer. + * This callback is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE + * configuration is enabled. + */ + otCoapBlockwiseReceiveHook mReceiveHook; + + /** The callback for handling outgoing block-wise transfer. + * This callback is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE + * configuration is enabled. + */ + otCoapBlockwiseTransmitHook mTransmitHook; + void *mContext; ///< Application-specific context + struct otCoapBlockwiseResource *mNext; ///< The next CoAP resource in the list +} otCoapBlockwiseResource; + +/** + * Adds a block-wise resource to the CoAP server. + * + * Requires `OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE`. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * @param[in] aResource A pointer to the resource. + */ +void otCoapAddBlockWiseResource(otInstance *aInstance, otCoapBlockwiseResource *aResource); + +/** + * Removes a block-wise resource from the CoAP server. + * + * Requires `OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE`. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * @param[in] aResource A pointer to the resource. + */ +void otCoapRemoveBlockWiseResource(otInstance *aInstance, otCoapBlockwiseResource *aResource); + /** * Sends a CoAP request block-wise with custom transmission parameters. * @@ -925,131 +952,13 @@ otError otCoapSendRequestBlockWiseWithParameters(otInstance *aIn * @retval OT_ERROR_NONE Successfully sent CoAP message. * @retval OT_ERROR_NO_BUFS Failed to allocate retransmission data. */ -static inline otError otCoapSendRequestBlockWise(otInstance *aInstance, - otMessage *aMessage, - const otMessageInfo *aMessageInfo, - otCoapResponseHandler aHandler, - void *aContext, - otCoapBlockwiseTransmitHook aTransmitHook, - otCoapBlockwiseReceiveHook aReceiveHook) -{ - // NOLINTNEXTLINE(modernize-use-nullptr) - return otCoapSendRequestBlockWiseWithParameters(aInstance, aMessage, aMessageInfo, aHandler, aContext, NULL, - aTransmitHook, aReceiveHook); -} - -/** - * Sends a CoAP request. - * - * If a response for a request is expected, respective function and context information should be provided. - * If no response is expected, these arguments should be NULL pointers. - * - * @param[in] aInstance A pointer to an OpenThread instance. - * @param[in] aMessage A pointer to the message to send. - * @param[in] aMessageInfo A pointer to the message info associated with @p aMessage. - * @param[in] aHandler A function pointer that shall be called on response reception or timeout. - * @param[in] aContext A pointer to arbitrary context information. May be NULL if not used. - * - * @retval OT_ERROR_NONE Successfully sent CoAP message. - * @retval OT_ERROR_NO_BUFS Failed to allocate retransmission data. - */ -static inline otError otCoapSendRequest(otInstance *aInstance, - otMessage *aMessage, - const otMessageInfo *aMessageInfo, - otCoapResponseHandler aHandler, - void *aContext) -{ - // NOLINTNEXTLINE(modernize-use-nullptr) - return otCoapSendRequestWithParameters(aInstance, aMessage, aMessageInfo, aHandler, aContext, NULL); -} - -/** - * Starts the CoAP server. - * - * @param[in] aInstance A pointer to an OpenThread instance. - * @param[in] aPort The local UDP port to bind to. - * - * @retval OT_ERROR_NONE Successfully started the CoAP server. - * @retval OT_ERROR_FAILED Failed to start the CoAP server. - */ -otError otCoapStart(otInstance *aInstance, uint16_t aPort); - -/** - * Stops the CoAP server. - * - * @param[in] aInstance A pointer to an OpenThread instance. - * - * @retval OT_ERROR_NONE Successfully stopped the CoAP server. - */ -otError otCoapStop(otInstance *aInstance); - -/** - * Adds a resource to the CoAP server. - * - * @param[in] aInstance A pointer to an OpenThread instance. - * @param[in] aResource A pointer to the resource. - */ -void otCoapAddResource(otInstance *aInstance, otCoapResource *aResource); - -/** - * Removes a resource from the CoAP server. - * - * @param[in] aInstance A pointer to an OpenThread instance. - * @param[in] aResource A pointer to the resource. - */ -void otCoapRemoveResource(otInstance *aInstance, otCoapResource *aResource); - -/** - * Adds a block-wise resource to the CoAP server. - * - * @param[in] aInstance A pointer to an OpenThread instance. - * @param[in] aResource A pointer to the resource. - */ -void otCoapAddBlockWiseResource(otInstance *aInstance, otCoapBlockwiseResource *aResource); - -/** - * Removes a block-wise resource from the CoAP server. - * - * @param[in] aInstance A pointer to an OpenThread instance. - * @param[in] aResource A pointer to the resource. - */ -void otCoapRemoveBlockWiseResource(otInstance *aInstance, otCoapBlockwiseResource *aResource); - -/** - * Sets the default handler for unhandled CoAP requests. - * - * @param[in] aInstance A pointer to an OpenThread instance. - * @param[in] aHandler A function pointer that shall be called when an unhandled request arrives. - * @param[in] aContext A pointer to arbitrary context information. May be NULL if not used. - */ -void otCoapSetDefaultHandler(otInstance *aInstance, otCoapRequestHandler aHandler, void *aContext); - -/** - * Sets a fallback handler for CoAP responses not matching any active/pending request. - * - * @param[in] aInstance A pointer to an OpenThread instance. - * @param[in] aHandler A function pointer that shall be called as a fallback for responses without matching - * active/pending CoAP requests. - * @param[in] aContext A pointer to arbitrary context information. May be NULL if not used. - */ -void otCoapSetResponseFallback(otInstance *aInstance, otCoapResponseFallback aHandler, void *aContext); - -/** - * Sends a CoAP response from the server with custom transmission parameters. - * - * @param[in] aInstance A pointer to an OpenThread instance. - * @param[in] aMessage A pointer to the CoAP response to send. - * @param[in] aMessageInfo A pointer to the message info associated with @p aMessage. - * @param[in] aTxParameters A pointer to transmission parameters for this response. Use NULL for defaults. - * - * @retval OT_ERROR_NONE Successfully enqueued the CoAP response message. - * @retval OT_ERROR_NO_BUFS Insufficient buffers available to send the CoAP response. - * @retval OT_ERROR_INVALID_ARGS Invalid arguments are given. - */ -otError otCoapSendResponseWithParameters(otInstance *aInstance, - otMessage *aMessage, - const otMessageInfo *aMessageInfo, - const otCoapTxParameters *aTxParameters); +otError otCoapSendRequestBlockWise(otInstance *aInstance, + otMessage *aMessage, + const otMessageInfo *aMessageInfo, + otCoapResponseHandler aHandler, + void *aContext, + otCoapBlockwiseTransmitHook aTransmitHook, + otCoapBlockwiseReceiveHook aReceiveHook); /** * Sends a CoAP response block-wise from the server with custom transmission parameters. @@ -1090,31 +999,11 @@ otError otCoapSendResponseBlockWiseWithParameters(otInstance *aI * @retval OT_ERROR_NONE Successfully enqueued the CoAP response message. * @retval OT_ERROR_NO_BUFS Insufficient buffers available to send the CoAP response. */ -static inline otError otCoapSendResponseBlockWise(otInstance *aInstance, - otMessage *aMessage, - const otMessageInfo *aMessageInfo, - void *aContext, - otCoapBlockwiseTransmitHook aTransmitHook) -{ - // NOLINTNEXTLINE(modernize-use-nullptr) - return otCoapSendResponseBlockWiseWithParameters(aInstance, aMessage, aMessageInfo, NULL, aContext, aTransmitHook); -} - -/** - * Sends a CoAP response from the server. - * - * @param[in] aInstance A pointer to an OpenThread instance. - * @param[in] aMessage A pointer to the CoAP response to send. - * @param[in] aMessageInfo A pointer to the message info associated with @p aMessage. - * - * @retval OT_ERROR_NONE Successfully enqueued the CoAP response message. - * @retval OT_ERROR_NO_BUFS Insufficient buffers available to send the CoAP response. - */ -static inline otError otCoapSendResponse(otInstance *aInstance, otMessage *aMessage, const otMessageInfo *aMessageInfo) -{ - // NOLINTNEXTLINE(modernize-use-nullptr) - return otCoapSendResponseWithParameters(aInstance, aMessage, aMessageInfo, NULL); -} +otError otCoapSendResponseBlockWise(otInstance *aInstance, + otMessage *aMessage, + const otMessageInfo *aMessageInfo, + void *aContext, + otCoapBlockwiseTransmitHook aTransmitHook); /** * @} diff --git a/include/openthread/instance.h b/include/openthread/instance.h index 4aeee1947..12170deb2 100644 --- a/include/openthread/instance.h +++ b/include/openthread/instance.h @@ -52,7 +52,7 @@ extern "C" { * * @note This number versions both OpenThread platform and user APIs. */ -#define OPENTHREAD_API_VERSION (567) +#define OPENTHREAD_API_VERSION (568) /** * @addtogroup api-instance diff --git a/src/core/api/coap_api.cpp b/src/core/api/coap_api.cpp index 2b76c9edc..4a210125d 100644 --- a/src/core/api/coap_api.cpp +++ b/src/core/api/coap_api.cpp @@ -208,29 +208,6 @@ otError otCoapOptionIteratorGetOptionValue(otCoapOptionIterator *aIterator, void return AsCoreType(aIterator).ReadOptionValue(aValue); } -#if OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE -otError otCoapSendRequestBlockWiseWithParameters(otInstance *aInstance, - otMessage *aMessage, - const otMessageInfo *aMessageInfo, - otCoapResponseHandler aHandler, - void *aContext, - const otCoapTxParameters *aTxParameters, - otCoapBlockwiseTransmitHook aTransmitHook, - otCoapBlockwiseReceiveHook aReceiveHook) -{ - Error error; - - VerifyOrExit(!AsCoreType(aMessage).IsOriginThreadNetif(), error = kErrorInvalidArgs); - - error = AsCoreType(aInstance).Get().SendMessage( - AsCoapMessage(aMessage), AsCoreType(aMessageInfo), AsCoreTypePtr(aTxParameters), aHandler, aContext, - aTransmitHook, aReceiveHook); - -exit: - return error; -} -#endif // OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE - otError otCoapSendRequestWithParameters(otInstance *aInstance, otMessage *aMessage, const otMessageInfo *aMessageInfo, @@ -249,6 +226,15 @@ exit: return error; } +otError otCoapSendRequest(otInstance *aInstance, + otMessage *aMessage, + const otMessageInfo *aMessageInfo, + otCoapResponseHandler aHandler, + void *aContext) +{ + return otCoapSendRequestWithParameters(aInstance, aMessage, aMessageInfo, aHandler, aContext, nullptr); +} + otError otCoapStart(otInstance *aInstance, uint16_t aPort) { return AsCoreType(aInstance).Get().Start(aPort); @@ -256,18 +242,6 @@ otError otCoapStart(otInstance *aInstance, uint16_t aPort) otError otCoapStop(otInstance *aInstance) { return AsCoreType(aInstance).Get().Stop(); } -#if OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE -void otCoapAddBlockWiseResource(otInstance *aInstance, otCoapBlockwiseResource *aResource) -{ - AsCoreType(aInstance).Get().AddBlockWiseResource(AsCoreType(aResource)); -} - -void otCoapRemoveBlockWiseResource(otInstance *aInstance, otCoapBlockwiseResource *aResource) -{ - AsCoreType(aInstance).Get().RemoveBlockWiseResource(AsCoreType(aResource)); -} -#endif - void otCoapAddResource(otInstance *aInstance, otCoapResource *aResource) { AsCoreType(aInstance).Get().AddResource(AsCoreType(aResource)); @@ -288,7 +262,74 @@ void otCoapSetResponseFallback(otInstance *aInstance, otCoapResponseFallback aHa AsCoreType(aInstance).Get().SetResponseFallback(aHandler, aContext); } +otError otCoapSendResponseWithParameters(otInstance *aInstance, + otMessage *aMessage, + const otMessageInfo *aMessageInfo, + const otCoapTxParameters *aTxParameters) +{ + otError error; + + VerifyOrExit(!AsCoreType(aMessage).IsOriginThreadNetif(), error = kErrorInvalidArgs); + + error = AsCoreType(aInstance).Get().SendMessage( + AsCoapMessage(aMessage), AsCoreType(aMessageInfo), AsCoreTypePtr(aTxParameters), nullptr, nullptr); + +exit: + return error; +} + +otError otCoapSendResponse(otInstance *aInstance, otMessage *aMessage, const otMessageInfo *aMessageInfo) +{ + return otCoapSendResponseWithParameters(aInstance, aMessage, aMessageInfo, nullptr); +} + +//--------------------------------------------------------------------------------------------------------------------- + #if OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE + +void otCoapAddBlockWiseResource(otInstance *aInstance, otCoapBlockwiseResource *aResource) +{ + AsCoreType(aInstance).Get().AddBlockWiseResource(AsCoreType(aResource)); +} + +void otCoapRemoveBlockWiseResource(otInstance *aInstance, otCoapBlockwiseResource *aResource) +{ + AsCoreType(aInstance).Get().RemoveBlockWiseResource(AsCoreType(aResource)); +} + +otError otCoapSendRequestBlockWiseWithParameters(otInstance *aInstance, + otMessage *aMessage, + const otMessageInfo *aMessageInfo, + otCoapResponseHandler aHandler, + void *aContext, + const otCoapTxParameters *aTxParameters, + otCoapBlockwiseTransmitHook aTransmitHook, + otCoapBlockwiseReceiveHook aReceiveHook) +{ + Error error; + + VerifyOrExit(!AsCoreType(aMessage).IsOriginThreadNetif(), error = kErrorInvalidArgs); + + error = AsCoreType(aInstance).Get().SendMessage( + AsCoapMessage(aMessage), AsCoreType(aMessageInfo), AsCoreTypePtr(aTxParameters), aHandler, aContext, + aTransmitHook, aReceiveHook); + +exit: + return error; +} + +otError otCoapSendRequestBlockWise(otInstance *aInstance, + otMessage *aMessage, + const otMessageInfo *aMessageInfo, + otCoapResponseHandler aHandler, + void *aContext, + otCoapBlockwiseTransmitHook aTransmitHook, + otCoapBlockwiseReceiveHook aReceiveHook) +{ + return otCoapSendRequestBlockWiseWithParameters(aInstance, aMessage, aMessageInfo, aHandler, aContext, nullptr, + aTransmitHook, aReceiveHook); +} + otError otCoapSendResponseBlockWiseWithParameters(otInstance *aInstance, otMessage *aMessage, const otMessageInfo *aMessageInfo, @@ -306,22 +347,17 @@ otError otCoapSendResponseBlockWiseWithParameters(otInstance *aI exit: return error; } -#endif -otError otCoapSendResponseWithParameters(otInstance *aInstance, - otMessage *aMessage, - const otMessageInfo *aMessageInfo, - const otCoapTxParameters *aTxParameters) +otError otCoapSendResponseBlockWise(otInstance *aInstance, + otMessage *aMessage, + const otMessageInfo *aMessageInfo, + void *aContext, + otCoapBlockwiseTransmitHook aTransmitHook) { - otError error; - - VerifyOrExit(!AsCoreType(aMessage).IsOriginThreadNetif(), error = kErrorInvalidArgs); - - error = AsCoreType(aInstance).Get().SendMessage( - AsCoapMessage(aMessage), AsCoreType(aMessageInfo), AsCoreTypePtr(aTxParameters), nullptr, nullptr); - -exit: - return error; + return otCoapSendResponseBlockWiseWithParameters(aInstance, aMessage, aMessageInfo, nullptr, aContext, + aTransmitHook); } +#endif // OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE + #endif // OPENTHREAD_CONFIG_COAP_API_ENABLE