DNS - Platform#

This module includes the platform abstraction for sending recursive DNS query to upstream DNS servers.

Typedefs#

typedef struct otPlatDnsUpstreamQuery

otPlatDnsUpstreamQuery

This opaque type represents an upstream DNS query transaction.

Functions#

bool

otPlatDnsIsUpstreamQueryAvailable(otInstance *aInstance)

Indicates whether upstream DNS query functionality is available on the platform.

void

otPlatDnsStartUpstreamQuery(otInstance *aInstance, otPlatDnsUpstreamQuery *aTxn, const otMessage *aQuery)

Starts an upstream query transaction.

void

otPlatDnsCancelUpstreamQuery(otInstance *aInstance, otPlatDnsUpstreamQuery *aTxn)

Cancels a transaction of upstream query.

void

otPlatDnsUpstreamQueryDone(otInstance *aInstance, otPlatDnsUpstreamQuery *aTxn, otMessage *aResponse)

The platform calls this function to finish DNS query.

Typedef Documentation#

otPlatDnsUpstreamQuery#

typedef struct otPlatDnsUpstreamQuery otPlatDnsUpstreamQuery

This opaque type represents an upstream DNS query transaction.

Function Documentation#

otPlatDnsIsUpstreamQueryAvailable#

bool otPlatDnsIsUpstreamQueryAvailable (otInstance * aInstance)

Indicates whether upstream DNS query functionality is available on the platform.

Parameters

Type	Direction	Argument Name	Description
otInstance *	[in]	aInstance	The OpenThread instance.

This function allows the platform to inform the OpenThread stack if no upstream DNS server is available.

This function is used to optimize query handling. If this function returns false (e.g., no upstream DNS server is currently available), one can avoid attempting an upstream resolution (which would likely time out) and instead immediately send an appropriate negative response (e.g., SERVFAIL) to the DNS client.

otPlatDnsStartUpstreamQuery#

void otPlatDnsStartUpstreamQuery (otInstance * aInstance, otPlatDnsUpstreamQuery * aTxn, const otMessage * aQuery)

Starts an upstream query transaction.

Parameters

Type	Direction	Argument Name	Description
otInstance *	[in]	aInstance	The OpenThread instance structure.
otPlatDnsUpstreamQuery *	[in]	aTxn	A pointer to the opaque DNS query transaction object.
const otMessage *	[in]	aQuery	A message buffer of the DNS payload that should be sent to upstream DNS server.

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.

otPlatDnsCancelUpstreamQuery#

void otPlatDnsCancelUpstreamQuery (otInstance * aInstance, otPlatDnsUpstreamQuery * aTxn)

Cancels a transaction of upstream query.

Parameters

Type	Direction	Argument Name	Description
otInstance *	[in]	aInstance	The OpenThread instance structure.
otPlatDnsUpstreamQuery *	[in]	aTxn	A pointer to the opaque DNS query transaction object.

The platform must call otPlatDnsUpstreamQueryDone to release the resources.

otPlatDnsUpstreamQueryDone#

void otPlatDnsUpstreamQueryDone (otInstance * aInstance, otPlatDnsUpstreamQuery * aTxn, otMessage * aResponse)

The platform calls this function to finish DNS query.

Parameters

Type	Direction	Argument Name	Description
otInstance *	[in]	aInstance	The OpenThread instance structure.
otPlatDnsUpstreamQuery *	[in]	aTxn	A pointer to the opaque DNS query transaction object.
otMessage *	[in]	aResponse	A message buffer of the DNS response payload or NULL to close a transaction without a response.

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.