DNS-SD (mDNS)
This module includes the platform abstraction for DNS-SD (e.g., mDNS) on the infrastructure network.
Summary
The DNS-SD platform APIs are used only when OPENTHREAD_CONFIG_PLATFORM_DNSSD_ENABLE
is enabled.
Enumerations |
|
---|---|
otPlatDnssdState{
|
enum Represents the state of the DNS-SD platform. |
Typedefs |
|
---|---|
otPlatDnssdHost
|
typedefstruct otPlatDnssdHost
Represents a DNS-SD host. |
otPlatDnssdKey
|
typedefstruct otPlatDnssdKey
Represents a DNS-SD key record. |
otPlatDnssdRegisterCallback)(otInstance *aInstance, otPlatDnssdRequestId aRequestId, otError aError)
|
typedefvoid(*
Represents the callback function used when registering/unregistering a host or service. |
otPlatDnssdRequestId
|
typedefuint32_t
Represents a request ID for registering/unregistering a service or host. |
otPlatDnssdService
|
typedefstruct otPlatDnssdService
Represents a DNS-SD service. |
otPlatDnssdState
|
typedefenum otPlatDnssdState
Represents the state of the DNS-SD platform. |
Functions |
|
---|---|
otPlatDnssdGetState(otInstance *aInstance)
|
Gets the current state of the DNS-SD module.
|
otPlatDnssdRegisterHost(otInstance *aInstance, const otPlatDnssdHost *aHost, otPlatDnssdRequestId aRequestId, otPlatDnssdRegisterCallback aCallback)
|
void
Registers or updates a host on the infrastructure network's DNS-SD module.
|
otPlatDnssdRegisterKey(otInstance *aInstance, const otPlatDnssdKey *aKey, otPlatDnssdRequestId aRequestId, otPlatDnssdRegisterCallback aCallback)
|
void
Registers or updates a key record on the infrastructure network's DNS-SD module.
|
otPlatDnssdRegisterService(otInstance *aInstance, const otPlatDnssdService *aService, otPlatDnssdRequestId aRequestId, otPlatDnssdRegisterCallback aCallback)
|
void
Registers or updates a service on the infrastructure network's DNS-SD module.
|
otPlatDnssdStateHandleStateChange(otInstance *aInstance)
|
void
Callback to notify state changes of the DNS-SD platform.
|
otPlatDnssdUnregisterHost(otInstance *aInstance, const otPlatDnssdHost *aHost, otPlatDnssdRequestId aRequestId, otPlatDnssdRegisterCallback aCallback)
|
void
Unregisters a host on the infrastructure network's DNS-SD module.
|
otPlatDnssdUnregisterKey(otInstance *aInstance, const otPlatDnssdKey *aKey, otPlatDnssdRequestId aRequestId, otPlatDnssdRegisterCallback aCallback)
|
void
Unregisters a key record on the infrastructure network's DNS-SD module.
|
otPlatDnssdUnregisterService(otInstance *aInstance, const otPlatDnssdService *aService, otPlatDnssdRequestId aRequestId, otPlatDnssdRegisterCallback aCallback)
|
void
Unregisters a service on the infrastructure network's DNS-SD module.
|
Structs |
|
---|---|
otPlatDnssdHost |
Represents a DNS-SD host. |
otPlatDnssdKey |
Represents a DNS-SD key record. |
otPlatDnssdService |
Represents a DNS-SD service. |
Enumerations
otPlatDnssdState
otPlatDnssdState
Typedefs
otPlatDnssdHost
struct otPlatDnssdHost otPlatDnssdHost
Represents a DNS-SD host.
See otPlatDnssdRegisterHost()
, otPlatDnssdUnregisterHost()
for more details about fields in each case.
otPlatDnssdKey
struct otPlatDnssdKey otPlatDnssdKey
Represents a DNS-SD key record.
See otPlatDnssdRegisterKey()
, otPlatDnssdUnregisterKey()
for more details about fields in each case.
otPlatDnssdRegisterCallback
void(* otPlatDnssdRegisterCallback)(otInstance *aInstance, otPlatDnssdRequestId aRequestId, otError aError)
Represents the callback function used when registering/unregistering a host or service.
See otPlatDnssdRegisterService()
, otPlatDnssdUnregisterService()
, otPlatDnssdRegisterHost()
, and otPlatDnssdUnregisterHost()
for more details about when to invoke the callback and the aError
values that can be returned in each case.
Details | |||||||
---|---|---|---|---|---|---|---|
Parameters |
|
otPlatDnssdRequestId
uint32_t otPlatDnssdRequestId
Represents a request ID for registering/unregistering a service or host.
otPlatDnssdService
struct otPlatDnssdService otPlatDnssdService
Represents a DNS-SD service.
See otPlatDnssdRegisterService()
, otPlatDnssdUnregisterService()
for more details about fields in each case.
otPlatDnssdState
enum otPlatDnssdState otPlatDnssdState
Represents the state of the DNS-SD platform.
Functions
otPlatDnssdGetState
otPlatDnssdState otPlatDnssdGetState( otInstance *aInstance )
Gets the current state of the DNS-SD module.
The platform MUST notify the OpenThread stack whenever its state gets changed by invoking otPlatDnssdStateHandleStateChange()
.
Details | |||
---|---|---|---|
Parameters |
|
||
Returns |
The current state of the DNS-SD module.
|
otPlatDnssdRegisterHost
void otPlatDnssdRegisterHost( otInstance *aInstance, const otPlatDnssdHost *aHost, otPlatDnssdRequestId aRequestId, otPlatDnssdRegisterCallback aCallback )
Registers or updates a host on the infrastructure network's DNS-SD module.
The aHost
and all its contained information (strings and arrays) are only valid during this call. The platform MUST save a copy of the information if it wants to retain the information after returning from this function.
The fields in aHost
follow these rules:
- The
mHostName
field specifies the host name to register. It is never NULL. - The
mAddresses
field is an array of IPv6 addresses to register with the host.mAddressesLength
field provides the number of entries inmAddresses
array. The platform implementation MUST not filter or remove any of addresses in the list. The OpenThread stack will already ensure that the given addresses are externally reachable. For example, when registering host from an SRP registration, link-local or mesh-local addresses associated with the host which are intended for use within Thread mesh are not included inmAddresses
array passed to this API. ThemAddresses
array can be empty with zeromAddressesLength
. In such a case, the platform MUST stop advertising any addresses for this host name on the infrastructure DNS-SD. - The
mTtl
field specifies the TTL if non-zero. If zero, the platform can choose the TTL to use. - The
mInfraIfIndex
field, if non-zero, specifies the infrastructure network interface index to use for this request. If zero, the platform implementation can decided the interface.
Regarding the invocation of the aCallback
and the reuse of the aRequestId
, this function follows the same rules as described in otPlatDnssdRegisterService()
.
The OpenThread stack will not register the same host (with no changes) that was registered successfully earlier. Therefore, the platform implementation does not need to check for duplicate/same host and can assume that calls to this function are either registering a new entry or changing some parameter in a previously registered item. As a result, these changes always need to be synced on the infrastructure DNS-SD module.
Details | |||||||||
---|---|---|---|---|---|---|---|---|---|
Parameters |
|
otPlatDnssdRegisterKey
void otPlatDnssdRegisterKey( otInstance *aInstance, const otPlatDnssdKey *aKey, otPlatDnssdRequestId aRequestId, otPlatDnssdRegisterCallback aCallback )
Registers or updates a key record on the infrastructure network's DNS-SD module.
The aKey
and all its contained information (strings and arrays) are only valid during this call. The platform MUST save a copy of the information if it wants to retain the information after returning from this function.
The fields in aKey
follow these rules:
- If the key is associated with a host,
mName
field specifies the host name andmServiceType
will be NULL. - If the key is associated with a service,
mName
field specifies the service instance label andmServiceType
field specifies the service type. In this case the DNS name for key record is{mName}.{mServiceTye}
. - The
mKeyData
field contains the key record's data withmKeyDataLength
as its length in byes. It is never NULL. - The
mClass
fields specifies the resource record class to use when registering key record. - The
mTtl
field specifies the TTL if non-zero. If zero, the platform can choose the TTL to use. - The
mInfraIfIndex
field, if non-zero, specifies the infrastructure network interface index to use for this request. If zero, the platform implementation can decided the interface.
Regarding the invocation of the aCallback
and the reuse of the aRequestId
, this function follows the same rules as described in otPlatDnssdRegisterService()
.
The OpenThread stack will not register the same key (with no changes) that was registered successfully earlier. Therefore, the platform implementation does not need to check for duplicate/same name and can assume that calls to this function are either registering a new key or changing the key data in a previously registered one. As a result, these changes always need to be synced on the infrastructure DNS-SD module.
Details | |||||||||
---|---|---|---|---|---|---|---|---|---|
Parameters |
|
otPlatDnssdRegisterService
void otPlatDnssdRegisterService( otInstance *aInstance, const otPlatDnssdService *aService, otPlatDnssdRequestId aRequestId, otPlatDnssdRegisterCallback aCallback )
Registers or updates a service on the infrastructure network's DNS-SD module.
The aService
and all its contained information (strings and buffers) are only valid during this call. The platform MUST save a copy of the information if it wants to retain the information after returning from this function.
The fields in aService
follow these rules:
- The
mServiceInstance
andmServiceType
fields specify the service instance label and service type name, respectively. They are never NULL. - The
mHostName
field specifies the host name of the service if it is not NULL. Otherwise, if it is NULL, it indicates that this service is for the device itself and leaves the host name selection to DNS-SD platform. - The
mSubTypeLabels
is an array of strings representing sub-types associated with the service. It can be NULL if there are no sub-types. Otherwise, the array length is specified bymSubTypeLabelsLength
. - The
mTxtData
andmTxtDataLength
fields specify the encoded TXT data. - The
mPort
,mWeight
, andmPriority
fields specify the service's parameters (as specified in DNS SRV record). - The
mTtl
field specifies the TTL if non-zero. If zero, the platform can choose the TTL to use. - The
mInfraIfIndex
field, if non-zero, specifies the infrastructure network interface index to use for this request. If zero, the platform implementation can decided the interface.
When the mHostName
field in aService
is not NULL (indicating that this registration is on behalf of another host), the OpenThread stack will ensure that otPlatDnssdRegisterHost()
is also called for the same host before any service registration requests for the same host.
Once the registration request is finished, either successfully or failed, the platform reports the outcome by invoking the aCallback
and passing the same aRequestId
in the callback. The aCallback
function pointer can be NULL, which indicates that the OpenThread stack does not need to be notified of the outcome of the request. If the outcome is determined, the platform implementation may invoke the aCallback
before returning from this function. The OpenThread stack will ensure to handle such a situation.
On success, the aCallback
MUST be called (if non-NULL) with OT_ERROR_NONE
as the aError
input parameter. If the registration causes a name conflict on DNS-SD domain (the service instance name is already claimed by another host), the OT_ERROR_DUPLICATED
error MUST be used. The platform implementation can use other OT_ERROR
types for other types of errors.
The platform implementation MUST not assume that the aRequestId
used in subsequent requests will be different. OpenThread may reuse the same request ID again for a different request.
The OpenThread stack will not register the same service (with no changes) that was registered successfully earlier. Therefore, the platform implementation does not need to check for duplicate/same service and can assume that calls to this function are either registering a new entry or changing some parameter in a previously registered item. As a result, these changes always need to be synced on the infrastructure DNS-SD module.
The OpenThread stack does not require the platform implementation to always invoke the aCallback
function. The OpenThread stack has its own mechanism to time out an aged request with no response. This relaxes the requirement for platform implementations.
Details | |||||||||
---|---|---|---|---|---|---|---|---|---|
Parameters |
|
otPlatDnssdStateHandleStateChange
void otPlatDnssdStateHandleStateChange( otInstance *aInstance )
Callback to notify state changes of the DNS-SD platform.
The OpenThread stack will call otPlatDnssdGetState()
(from this callback or later) to get the new state. The platform MUST therefore ensure that the returned state from otPlatDnssdGetState()
is updated before calling this.
Details | |||
---|---|---|---|
Parameters |
|
otPlatDnssdUnregisterHost
void otPlatDnssdUnregisterHost( otInstance *aInstance, const otPlatDnssdHost *aHost, otPlatDnssdRequestId aRequestId, otPlatDnssdRegisterCallback aCallback )
Unregisters a host on the infrastructure network's DNS-SD module.
The aHost
and all its contained information (strings and arrays) are only valid during this call. The platform MUST save a copy of the information if it wants to retain the information after returning from this function.
The fields in aHost
follow these rules:
- The
mHostName
field specifies the host name to unregister. It is never NULL. - The
mInfraIfIndex
field, if non-zero, specifies the infrastructure network interface index to use for this request. If zero, the platform implementation can decided the interface. - The rest of the fields in
aHost
structure MUST be ignored inotPlatDnssdUnregisterHost()
call and may be set to zero by the OpenThread stack.
Regarding the invocation of the aCallback
and the reuse of the aRequestId
, this function follows the same rules as described in otPlatDnssdRegisterService()
.
The OpenThread stack may request the unregistration of a host that was not previously registered, and the platform implementation MUST handle this case. In such a case, the platform can use either OT_ERROR_NOT_FOUND
to indicate that there was no such registration, or OT_ERROR_NONE
when invoking the aCallback
function. OpenThread stack will handle either case correctly.
When unregistering a host, the OpenThread stack will also unregister any previously registered services associated with the same host (by calling otPlatDnssdUnregisterService()
). However, the platform implementation MAY assume that unregistering a host also unregisters all its associated services.
Details | |||||||||
---|---|---|---|---|---|---|---|---|---|
Parameters |
|
otPlatDnssdUnregisterKey
void otPlatDnssdUnregisterKey( otInstance *aInstance, const otPlatDnssdKey *aKey, otPlatDnssdRequestId aRequestId, otPlatDnssdRegisterCallback aCallback )
Unregisters a key record on the infrastructure network's DNS-SD module.
The aKey
and all its contained information (strings and arrays) are only valid during this call. The platform MUST save a copy of the information if it wants to retain the information after returning from this function.
The fields in aKey
follow these rules:
- If the key is associated with a host,
mName
field specifies the host name andmServiceType
will be NULL. - If the key is associated with a service,
mName
field specifies the service instance label andmServiceType
field specifies the service type. In this case the DNS name for key record is{mName}.{mServiceTye}
. - The
mInfraIfIndex
field, if non-zero, specifies the infrastructure network interface index to use for this request. If zero, the platform implementation can decided the interface. - The rest of the fields in
aKey
structure MUST be ignored inotPlatDnssdUnregisterKey()
call and may be set to zero by the OpenThread stack.
Regarding the invocation of the aCallback
and the reuse of the aRequestId
, this function follows the same rules as described in otPlatDnssdRegisterService()
.
The OpenThread stack may request the unregistration of a key that was not previously registered, and the platform implementation MUST handle this case. In such a case, the platform can use either OT_ERROR_NOT_FOUND
to indicate that there was no such registration, or OT_ERROR_NONE
when invoking the aCallback
function. the OpenThread stack will handle either case correctly.
Details | |||||||||
---|---|---|---|---|---|---|---|---|---|
Parameters |
|
otPlatDnssdUnregisterService
void otPlatDnssdUnregisterService( otInstance *aInstance, const otPlatDnssdService *aService, otPlatDnssdRequestId aRequestId, otPlatDnssdRegisterCallback aCallback )
Unregisters a service on the infrastructure network's DNS-SD module.
The aService
and all its contained information (strings and buffers) are only valid during this call. The platform MUST save a copy of the information if it wants to retain the information after returning from this function.
The fields in aService
follow these rules:
- The
mServiceInstance
andmServiceType
fields specify the service instance label and service type name, respectively. They are never NULL. - The
mHostName
field specifies the host name of the service if it is not NULL. Otherwise, if it is NULL, it indicates that this service is for the device itself and leaves the host name selection to DNS-SD platform. - The
mInfraIfIndex
field, if non-zero, specifies the infrastructure network interface index to use for this request. If zero, the platform implementation can decided the interface. - The rest of the fields in
aService
structure MUST be ignored inotPlatDnssdUnregisterService()
call and may be set to zero by the OpenThread stack.
Regarding the invocation of the aCallback
and the reuse of the aRequestId
, this function follows the same rules as described in otPlatDnssdRegisterService()
.
The OpenThread stack may request the unregistration of a service that was not previously registered, and the platform implementation MUST handle this case. In such a case, the platform can use either OT_ERROR_NOT_FOUND
to indicate that there was no such registration, or OT_ERROR_NONE
when invoking the aCallback
function. The OpenThread stack will handle either case correctly.
Details | |||||||||
---|---|---|---|---|---|---|---|---|---|
Parameters |
|
Resources
OpenThread API Reference topics originate from the source code, available on GitHub. For more information, or to contribute to our documentation, refer to Resources.