espressif/openthread
1
0
Fork 0
mirror of https://github.com/espressif/openthread.git synced 2026-08-02 00:57:47 +00:00
Code Issues Packages Projects Releases Wiki Activity

[dnssd] correct DNS upstream query cancellation documentation (#12210)

Browse Source 
This commit clarifies the expected platform behavior for handling a
DNS upstream query cancellation.

The previous documentation was inconsistent. The documentation of
`otPlatDnsStartUpstreamQuery()` incorrectly stated that the platform
must not call `otPlatDnsUpstreamQueryDone()` on a cancelled
transaction, while the opposite was mentioned in
`otPlatDnsCancelUpstreamQuery()`.

This is now corrected to state that the platform MUST always invoke
the `otPlatDnsUpstreamQueryDone()` callback for every
`otPlatDnsStartUpstreamQuery()`, even if the query is cancelled using
`otPlatDnsCancelUpstreamQuery()`.
This commit is contained in:
Abtin Keshavarzian
2025-12-15 14:53:53 -08:00
committed by GitHub
parent 47f041790d
commit 47f557a822
2 changed files with 6 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
include/openthread/instance.h
+1 -1
View File
@@ -52,7 +52,7 @@ extern "C" {
*
* @note This number versions both OpenThread platform and user APIs.
*/
#define OPENTHREAD_API_VERSION (560)
#define OPENTHREAD_API_VERSION (561)
/**
* @addtogroup api-instance
include/openthread/platform/dns.h
+5 -5
View File
@@ -80,9 +80,9 @@ bool otPlatDnsIsUpstreamQueryAvailable(otInstance *aInstance);
*
* - In success case (and errors represented by DNS protocol messages), the platform is expected to call
* `otPlatDnsUpstreamQueryDone`.
* - The OpenThread core may cancel a (possibly timeout) query transaction by calling
* `otPlatDnsCancelUpstreamQuery`, the platform must not call `otPlatDnsUpstreamQueryDone` on a
* cancelled transaction.
* - The OpenThread core may cancel a query transaction (possibly due to a timeout) by invoking
* `otPlatDnsCancelUpstreamQuery()`. The platform MUST still call `otPlatDnsUpstreamQueryDone()` on a
* cancelled transaction to release the transaction.
*
* @param[in] aInstance The OpenThread instance structure.
* @param[in] aTxn A pointer to the opaque DNS query transaction object.
@@ -93,7 +93,7 @@ void otPlatDnsStartUpstreamQuery(otInstance *aInstance, otPlatDnsUpstreamQuery *
/**
* Cancels a transaction of upstream query.
*
* The platform must call `otPlatDnsUpstreamQueryDone` to release the resources.
* The platform MUST call `otPlatDnsUpstreamQueryDone()` to release the transaction.
*
* @param[in] aInstance The OpenThread instance structure.
* @param[in] aTxn A pointer to the opaque DNS query transaction object.
@@ -103,7 +103,7 @@ void otPlatDnsCancelUpstreamQuery(otInstance *aInstance, otPlatDnsUpstreamQuery
/**
* The platform calls this function to finish DNS query.
*
* The transaction will be released, so the platform must not call on the same transaction twice. This function passes
* The transaction will be released, so the platform MUST NOT call on the same transaction twice. This function passes
* the ownership of `aResponse` to OpenThread stack.
*
* Platform can pass NULL to close a transaction without a response.