DNS-SD (mDNS)#

otPlatDnssdState#

otPlatDnssdState

Represents the state of the DNS-SD platform.

otPlatDnssdState#

typedef enum otPlatDnssdState otPlatDnssdState

Represents the state of the DNS-SD platform.

otPlatDnssdRequestId#

typedef uint32_t otPlatDnssdRequestId

Represents a request ID for registering/unregistering a service or host.

otPlatDnssdRegisterCallback#

typedef void(* otPlatDnssdRegisterCallback) (otInstance *aInstance, otPlatDnssdRequestId aRequestId, otError aError) )(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.

otPlatDnssdService#

typedef struct otPlatDnssdService otPlatDnssdService

Represents a DNS-SD service.

See otPlatDnssdRegisterService(), otPlatDnssdUnregisterService() for more details about fields in each case.

otPlatDnssdHost#

typedef struct otPlatDnssdHost otPlatDnssdHost

Represents a DNS-SD host.

See otPlatDnssdRegisterHost(), otPlatDnssdUnregisterHost() for more details about fields in each case.

otPlatDnssdKey#

typedef struct otPlatDnssdKey otPlatDnssdKey

Represents a DNS-SD key record.

See otPlatDnssdRegisterKey(), otPlatDnssdUnregisterKey() for more details about fields in each case.

otPlatDnssdBrowseResult#

typedef struct otPlatDnssdBrowseResult otPlatDnssdBrowseResult

Represents a browse result.

otPlatDnssdBrowseCallback#

typedef void(* otPlatDnssdBrowseCallback) (otInstance *aInstance, const otPlatDnssdBrowseResult *aResult) )(otInstance *aInstance, const otPlatDnssdBrowseResult *aResult)

Represents the callback function used to report a browse result.

otPlatDnssdBrowser#

typedef struct otPlatDnssdBrowser otPlatDnssdBrowser

Represents a service browser.

otPlatDnssdSrvResult#

typedef struct otPlatDnssdSrvResult otPlatDnssdSrvResult

Represents an SRV resolver result.

otPlatDnssdSrvCallback#

typedef void(* otPlatDnssdSrvCallback) (otInstance *aInstance, const otPlatDnssdSrvResult *aResult) )(otInstance *aInstance, const otPlatDnssdSrvResult *aResult)

Represents the callback function used to report an SRV resolve result.

otPlatDnssdSrvResolver#

typedef struct otPlatDnssdSrvResolver otPlatDnssdSrvResolver

Represents an SRV service resolver.

otPlatDnssdTxtResult#

typedef struct otPlatDnssdTxtResult otPlatDnssdTxtResult

Represents a TXT resolver result.

otPlatDnssdTxtCallback#

typedef void(* otPlatDnssdTxtCallback) (otInstance *aInstance, const otPlatDnssdTxtResult *aResult) )(otInstance *aInstance, const otPlatDnssdTxtResult *aResult)

Represents the callback function used to report a TXT resolve result.

otPlatDnssdTxtResolver#

typedef struct otPlatDnssdTxtResolver otPlatDnssdTxtResolver

Represents a TXT service resolver.

otPlatDnssdAddressAndTtl#

typedef struct otPlatDnssdAddressAndTtl otPlatDnssdAddressAndTtl

Represents a discovered host address and its TTL.

otPlatDnssdAddressResult#

typedef struct otPlatDnssdAddressResult otPlatDnssdAddressResult

Represents address resolver result.

otPlatDnssdAddressCallback#

typedef void(* otPlatDnssdAddressCallback) (otInstance *aInstance, const otPlatDnssdAddressResult *aResult) )(otInstance *aInstance, const otPlatDnssdAddressResult *aResult)

Represents the callback function use to report a IPv6/IPv4 address resolve result.

otPlatDnssdAddressResolver#

typedef struct otPlatDnssdAddressResolver otPlatDnssdAddressResolver

Represents an address resolver.

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.

When the platform signals a state change to OT_PLAT_DNSSD_STOPPED using this callback, all active browsers and resolvers are considered to be stopped, and any previously registered host, service, key entries as removed.

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().

Returns

• The current state of the DNS-SD module.

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 and mServiceType 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 by mSubTypeLabelsLength.

• The mTxtData and mTxtDataLength fields specify the encoded TXT data.

• The mPort, mWeight, and mPriority 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.

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 and mServiceType 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 in otPlatDnssdUnregisterService() 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.

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 in mAddresses 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 in mAddresses array passed to this API. The mAddresses array can be empty with zero mAddressesLength. 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.

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 in otPlatDnssdUnregisterHost() 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.

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 and mServiceType will be NULL.

• If the key is associated with a service, mName field specifies the service instance label and mServiceType 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 with mKeyDataLength 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.

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 and mServiceType will be NULL.

• If the key is associated with a service, mName field specifies the service instance label and mServiceType 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 in otPlatDnssdUnregisterKey() 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.

otPlatDnssdStartBrowser#

void otPlatDnssdStartBrowser (otInstance * aInstance, const otPlatDnssdBrowser * aBrowser)

Starts a service browser.

Initiates a continuous search for the specified mServiceType in aBrowser. For sub-type services, mSubTypeLabel specifies the sub-type, for base services, mSubTypeLabel is set to NULL.

Discovered services should be reported through the mCallback function in aBrowser. Services that have been removed are reported with a TTL value of zero. The callback may be invoked immediately with cached information (if available) and potentially before this function returns. When cached results are used, the reported TTL value should reflect the original TTL from the last received response.

Multiple browsers can be started for the same service, provided they use different callback functions.

The aBrowser and all its contained information (strings) 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.

otPlatDnssdStopBrowser#

void otPlatDnssdStopBrowser (otInstance * aInstance, const otPlatDnssdBrowser * aBrowser)

Stops a service browser.

No action is performed if no matching browser with the same service and callback is currently active.

The aBrowser and all its contained information (strings) 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.

otPlatDnssdStartSrvResolver#

void otPlatDnssdStartSrvResolver (otInstance * aInstance, const otPlatDnssdSrvResolver * aResolver)

Starts an SRV record resolver.

Initiates a continuous SRV record resolver for the specified service in aResolver.

Discovered information should be reported through the mCallback function in aResolver. When the service is removed it is reported with a TTL value of zero. In this case, mHostName may be NULL and other result fields (such as mPort) will be ignored by the OpenThread stack.

The callback may be invoked immediately with cached information (if available) and potentially before this function returns. When cached result is used, the reported TTL value should reflect the original TTL from the last received response.

Multiple resolvers can be started for the same service, provided they use different callback functions.

The aResolver and all its contained information (strings) 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.

otPlatDnssdStopSrvResolver#

void otPlatDnssdStopSrvResolver (otInstance * aInstance, const otPlatDnssdSrvResolver * aResolver)

Stops an SRV record resolver.

No action is performed if no matching resolver with the same service and callback is currently active.

The aResolver and all its contained information (strings) 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.

otPlatDnssdStartTxtResolver#

void otPlatDnssdStartTxtResolver (otInstance * aInstance, const otPlatDnssdTxtResolver * aResolver)

Starts a TXT record resolver.

Initiates a continuous TXT record resolver for the specified service in aResolver.

Discovered information should be reported through the mCallback function in aResolver. When the TXT record is removed it is reported with a TTL value of zero. In this case, mTxtData may be NULL, and other result fields (such as mTxtDataLength) will be ignored by the OpenThread stack.

The callback may be invoked immediately with cached information (if available) and potentially before this function returns. When cached result is used, the reported TTL value should reflect the original TTL from the last received response.

Multiple resolvers can be started for the same service, provided they use different callback functions.

The aResolver and all its contained information (strings) 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.

otPlatDnssdStopTxtResolver#

void otPlatDnssdStopTxtResolver (otInstance * aInstance, const otPlatDnssdTxtResolver * aResolver)

Stops a TXT record resolver.

No action is performed if no matching resolver with the same service and callback is currently active.

The aResolver and all its contained information (strings) 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.

otPlatDnssdStartIp6AddressResolver#

void otPlatDnssdStartIp6AddressResolver (otInstance * aInstance, const otPlatDnssdAddressResolver * aResolver)

Starts an IPv6 address resolver.

Initiates a continuous IPv6 address resolver for the specified host name in aResolver.

Discovered addresses should be reported through the mCallback function in aResolver. The callback should be invoked whenever addresses are added or removed, providing an updated list. If all addresses are removed, the callback should be invoked with an empty list (mAddressesLength set to zero).

The callback may be invoked immediately with cached information (if available) and potentially before this function returns. When cached result is used, the reported TTL values should reflect the original TTL from the last received response.

Multiple resolvers can be started for the same host name, provided they use different callback functions.

The aResolver and all its contained information (strings) 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.

otPlatDnssdStopIp6AddressResolver#

void otPlatDnssdStopIp6AddressResolver (otInstance * aInstance, const otPlatDnssdAddressResolver * aResolver)

Stops an IPv6 address resolver.

No action is performed if no matching resolver with the same host name and callback is currently active.

The aResolver and all its contained information (strings) 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.

otPlatDnssdStartIp4AddressResolver#

void otPlatDnssdStartIp4AddressResolver (otInstance * aInstance, const otPlatDnssdAddressResolver * aResolver)

Starts an IPv4 address resolver.

Initiates a continuous IPv4 address resolver for the specified host name in aResolver.

Discovered addresses should be reported through the mCallback function in aResolver. The IPv4 addresses are represented using the IPv4-mapped IPv6 address format in mAddresses array. The callback should be invoked whenever addresses are added or removed, providing an updated list. If all addresses are removed, the callback should be invoked with an empty list (mAddressesLength set to zero).

The callback may be invoked immediately with cached information (if available) and potentially before this function returns. When cached result is used, the reported TTL values will reflect the original TTL from the last received response.

Multiple resolvers can be started for the same host name, provided they use different callback functions.

The aResolver and all its contained information (strings) 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.

otPlatDnssdStopIp4AddressResolver#

void otPlatDnssdStopIp4AddressResolver (otInstance * aInstance, const otPlatDnssdAddressResolver * aResolver)

Stops an IPv4 address resolver.

No action is performed if no matching resolver with the same host name and callback is currently active.

The aResolver and all its contained information (strings) 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.