Multicast DNS

This module includes APIs for Multicast DNS (mDNS).

Summary

The mDNS APIs are available when the mDNS support OPENTHREAD_CONFIG_MULTICAST_DNS_ENABLE is enabled and the OPENTHREAD_CONFIG_MULTICAST_DNS_PUBLIC_API_ENABLE is also enabled.

Enumerations
otMdnsEntryState{   OT_MDNS_ENTRY_STATE_PROBING,   OT_MDNS_ENTRY_STATE_REGISTERED,   OT_MDNS_ENTRY_STATE_CONFLICT,   OT_MDNS_ENTRY_STATE_REMOVING }	enum Represents a host/service/key entry state.

Typedefs
otMdnsAddressAndTtl	typedef otPlatDnssdAddressAndTtl Represents a discovered host address and its TTL.
otMdnsAddressCallback	typedef otPlatDnssdAddressCallback Represents the callback function pointer type use to report an IPv6/IPv4 address resolve result.
otMdnsAddressResolver	typedef otPlatDnssdAddressResolver Represents an address resolver.
otMdnsAddressResult	typedef otPlatDnssdAddressResult Represents address resolver result.
otMdnsBrowseCallback	typedef otPlatDnssdBrowseCallback Represents the callback function pointer type used to report a browse result.
otMdnsBrowseResult	typedef otPlatDnssdBrowseResult Represents a browse result.
otMdnsBrowser	typedef otPlatDnssdBrowser Represents a service browser.
otMdnsCacheInfo	typedef struct otMdnsCacheInfo Represents additional information about a browser/resolver and its cached results.
otMdnsConflictCallback)(otInstance *aInstance, const char *aName, const char *aServiceType)	typedef void(* Represents the callback function to report a detected name conflict after successful registration of an entry.
otMdnsEntryState	typedef enum otMdnsEntryState Represents a host/service/key entry state.
otMdnsHost	typedef otPlatDnssdHost Represents an mDNS host.
otMdnsIterator	typedef struct otMdnsIterator Represents an mDNS entry iterator.
otMdnsKey	typedef otPlatDnssdKey Represents an mDNS key record.
otMdnsRegisterCallback	typedef otPlatDnssdRegisterCallback Represents the callback function to report the outcome of a host, service, or key registration request.
otMdnsRequestId	typedef otPlatDnssdRequestId Represents a request ID (uint32_t value) for registering a host, a service, or a key service.
otMdnsService	typedef otPlatDnssdService Represents an mDNS service.
otMdnsSrvCallback	typedef otPlatDnssdSrvCallback Represents the callback function pointer type used to report an SRV resolve result.
otMdnsSrvResolver	typedef otPlatDnssdSrvResolver Represents an SRV service resolver.
otMdnsSrvResult	typedef otPlatDnssdSrvResult Represents an SRV resolver result.
otMdnsTxtCallback	typedef otPlatDnssdTxtCallback Represents the callback function pointer type used to report a TXT resolve result.
otMdnsTxtResolver	typedef otPlatDnssdTxtResolver Represents a TXT service resolver.
otMdnsTxtResult	typedef otPlatDnssdTxtResult Represents a TXT resolver result.

Functions
otMdnsAllocateIterator(otInstance *aInstance)	otMdnsIterator * Allocates a new iterator.
otMdnsFreeIterator(otInstance *aInstance, otMdnsIterator *aIterator)	void Frees a previously allocated iterator.
otMdnsGetNextBrowser(otInstance *aInstance, otMdnsIterator *aIterator, otMdnsBrowser *aBrowser, otMdnsCacheInfo *aInfo)	otError Iterates over browsers.
otMdnsGetNextHost(otInstance *aInstance, otMdnsIterator *aIterator, otMdnsHost *aHost, otMdnsEntryState *aState)	otError Iterates over registered host entries.
otMdnsGetNextIp4AddressResolver(otInstance *aInstance, otMdnsIterator *aIterator, otMdnsAddressResolver *aResolver, otMdnsCacheInfo *aInfo)	otError Iterates over IPv4 address resolvers.
otMdnsGetNextIp6AddressResolver(otInstance *aInstance, otMdnsIterator *aIterator, otMdnsAddressResolver *aResolver, otMdnsCacheInfo *aInfo)	otError Iterates over IPv6 address resolvers.
otMdnsGetNextKey(otInstance *aInstance, otMdnsIterator *aIterator, otMdnsKey *aKey, otMdnsEntryState *aState)	otError Iterates over registered key entries.
otMdnsGetNextService(otInstance *aInstance, otMdnsIterator *aIterator, otMdnsService *aService, otMdnsEntryState *aState)	otError Iterates over registered service entries.
otMdnsGetNextSrvResolver(otInstance *aInstance, otMdnsIterator *aIterator, otMdnsSrvResolver *aResolver, otMdnsCacheInfo *aInfo)	otError Iterates over SRV resolvers.
otMdnsGetNextTxtResolver(otInstance *aInstance, otMdnsIterator *aIterator, otMdnsTxtResolver *aResolver, otMdnsCacheInfo *aInfo)	otError Iterates over TXT resolvers.
otMdnsIsEnabled(otInstance *aInstance)	bool Indicates whether the mDNS module is enabled.
otMdnsIsQuestionUnicastAllowed(otInstance *aInstance)	bool Indicates whether mDNS module is allowed to send "QU" questions requesting unicast response.
otMdnsRegisterHost(otInstance *aInstance, const otMdnsHost *aHost, otMdnsRequestId aRequestId, otMdnsRegisterCallback aCallback)	otError Registers or updates a host on mDNS.
otMdnsRegisterKey(otInstance *aInstance, const otMdnsKey *aKey, otMdnsRequestId aRequestId, otMdnsRegisterCallback aCallback)	otError Registers or updates a key record on mDNS module.
otMdnsRegisterService(otInstance *aInstance, const otMdnsService *aService, otMdnsRequestId aRequestId, otMdnsRegisterCallback aCallback)	otError Registers or updates a service on mDNS.
otMdnsSetConflictCallback(otInstance *aInstance, otMdnsConflictCallback aCallback)	void Sets the post-registration conflict callback.
otMdnsSetEnabled(otInstance *aInstance, bool aEnable, uint32_t aInfraIfIndex)	otError Enables or disables the mDNS module.
otMdnsSetQuestionUnicastAllowed(otInstance *aInstance, bool aAllow)	void Sets whether the mDNS module is allowed to send questions requesting unicast responses referred to as "QU" questions.
otMdnsStartBrowser(otInstance *aInstance, const otMdnsBrowser *aBrowser)	otError Starts a service browser.
otMdnsStartIp4AddressResolver(otInstance *aInstance, const otMdnsAddressResolver *aResolver)	otError Starts an IPv4 address resolver.
otMdnsStartIp6AddressResolver(otInstance *aInstance, const otMdnsAddressResolver *aResolver)	otError Starts an IPv6 address resolver.
otMdnsStartSrvResolver(otInstance *aInstance, const otMdnsSrvResolver *aResolver)	otError Starts an SRV record resolver.
otMdnsStartTxtResolver(otInstance *aInstance, const otMdnsTxtResolver *aResolver)	otError Starts a TXT record resolver.
otMdnsStopBrowser(otInstance *aInstance, const otMdnsBrowser *aBroswer)	otError Stops a service browser.
otMdnsStopIp4AddressResolver(otInstance *aInstance, const otMdnsAddressResolver *aResolver)	otError Stops an IPv4 address resolver.
otMdnsStopIp6AddressResolver(otInstance *aInstance, const otMdnsAddressResolver *aResolver)	otError Stops an IPv6 address resolver.
otMdnsStopSrvResolver(otInstance *aInstance, const otMdnsSrvResolver *aResolver)	otError Stops an SRV record resolver.
otMdnsStopTxtResolver(otInstance *aInstance, const otMdnsTxtResolver *aResolver)	otError Stops a TXT record resolver.
otMdnsUnregisterHost(otInstance *aInstance, const otMdnsHost *aHost)	otError Unregisters a host on mDNS.
otMdnsUnregisterKey(otInstance *aInstance, const otMdnsKey *aKey)	otError Unregisters a key record on mDNS.
otMdnsUnregisterService(otInstance *aInstance, const otMdnsService *aService)	otError Unregisters a service on mDNS module.

Structs
otMdnsCacheInfo	Represents additional information about a browser/resolver and its cached results.

Enumerations

otMdnsEntryState

 otMdnsEntryState

Represents a host/service/key entry state.

Properties
OT_MDNS_ENTRY_STATE_CONFLICT	Name conflict was detected.
OT_MDNS_ENTRY_STATE_PROBING	Probing to claim the name.
OT_MDNS_ENTRY_STATE_REGISTERED	Entry is successfully registered.
OT_MDNS_ENTRY_STATE_REMOVING	Entry is being removed (sending "goodbye" announcements).

Typedefs

otMdnsAddressAndTtl

otPlatDnssdAddressAndTtl otMdnsAddressAndTtl

Represents a discovered host address and its TTL.

otMdnsAddressCallback

otPlatDnssdAddressCallback otMdnsAddressCallback

Represents the callback function pointer type use to report an IPv6/IPv4 address resolve result.

otMdnsAddressResolver

otPlatDnssdAddressResolver otMdnsAddressResolver

Represents an address resolver.

Refer to otPlatDnssdAddressResolver for documentation of member fields and otMdnsStartIp6AddressResolver() or otMdnsStartIp4AddressResolver() for how they are used.

otMdnsAddressResult

otPlatDnssdAddressResult otMdnsAddressResult

Represents address resolver result.

otMdnsBrowseCallback

otPlatDnssdBrowseCallback otMdnsBrowseCallback

Represents the callback function pointer type used to report a browse result.

otMdnsBrowseResult

otPlatDnssdBrowseResult otMdnsBrowseResult

Represents a browse result.

otMdnsBrowser

otPlatDnssdBrowser otMdnsBrowser

Represents a service browser.

Refer to otPlatDnssdBrowser for documentation of member fields and otMdnsStartBrowser() for how they are used.

otMdnsCacheInfo

struct otMdnsCacheInfo otMdnsCacheInfo

Represents additional information about a browser/resolver and its cached results.

otMdnsConflictCallback

void(* otMdnsConflictCallback)(otInstance *aInstance, const char *aName, const char *aServiceType)

Represents the callback function to report a detected name conflict after successful registration of an entry.

If a conflict is detected while registering an entry, it is reported through the provided otMdnsRegisterCallback. The otMdnsConflictCallback is used only when a name conflict is detected after an entry has been successfully registered.

A non-NULL aServiceType indicates that conflict is for a service entry. In this case aName specifies the service instance label (treated as as a single DNS label and can potentially include dot . character).

A NULL aServiceType indicates that conflict is for a host entry. In this case Name specifies the host name. It does not include the domain name.

Details
Parameters	[in] aInstance The OpenThread instance. [in] aName The host name or the service instance label. [in] aServiceType The service type (e.g., _tst._udp).

otMdnsEntryState

enum otMdnsEntryState otMdnsEntryState

Represents a host/service/key entry state.

otMdnsHost

otPlatDnssdHost otMdnsHost

Represents an mDNS host.

This type is used to register or unregister a host (otMdnsRegisterHost() and otMdnsUnregisterHost()).

See the description of each function for more details on how different fields are used in each case.

otMdnsIterator

struct otMdnsIterator otMdnsIterator

Represents an mDNS entry iterator.

otMdnsKey

otPlatDnssdKey otMdnsKey

Represents an mDNS key record.

See otMdnsRegisterKey(), otMdnsUnregisterKey() for more details about fields in each case.

otMdnsRegisterCallback

otPlatDnssdRegisterCallback otMdnsRegisterCallback

Represents the callback function to report the outcome of a host, service, or key registration request.

The outcome of a registration request is reported back by invoking this callback with one of the following aError inputs:

• OT_ERROR_NONE indicates registration was successful.
• OT_ERROR_DUPLICATED indicates a name conflict while probing, i.e., name is claimed by another mDNS responder.

See otMdnsRegisterHost(), otMdnsRegisterService(), and otMdnsRegisterKey() for more details about when the callback will be invoked.

Details
Parameters	[in] aInstance The OpenThread instance. [in] aRequestId The request ID. [in] aError Error indicating the outcome of request.

otMdnsRequestId

otPlatDnssdRequestId otMdnsRequestId

Represents a request ID (uint32_t value) for registering a host, a service, or a key service.

otMdnsService

otPlatDnssdService otMdnsService

Represents an mDNS service.

This type is used to register or unregister a service (otMdnsRegisterService() and otMdnsUnregisterService()).

See the description of each function for more details on how different fields are used in each case.

otMdnsSrvCallback

otPlatDnssdSrvCallback otMdnsSrvCallback

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

otMdnsSrvResolver

otPlatDnssdSrvResolver otMdnsSrvResolver

Represents an SRV service resolver.

Refer to otPlatDnssdSrvResolver for documentation of member fields and otMdnsStartSrvResolver() for how they are used.

otMdnsSrvResult

otPlatDnssdSrvResult otMdnsSrvResult

Represents an SRV resolver result.

otMdnsTxtCallback

otPlatDnssdTxtCallback otMdnsTxtCallback

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

otMdnsTxtResolver

otPlatDnssdTxtResolver otMdnsTxtResolver

Represents a TXT service resolver.

Refer to otPlatDnssdTxtResolver for documentation of member fields and otMdnsStartTxtResolver() for how they are used.

otMdnsTxtResult

otPlatDnssdTxtResult otMdnsTxtResult

Represents a TXT resolver result.

Functions

otMdnsAllocateIterator

otMdnsIterator * otMdnsAllocateIterator(
  otInstance *aInstance
)

Allocates a new iterator.

Requires OPENTHREAD_CONFIG_MULTICAST_DNS_ENTRY_ITERATION_API_ENABLE.

An allocated iterator must be freed by the caller using otMdnsFreeIterator().

Details
Parameters	[in] aInstance The OpenThread instance.
Returns	A pointer to the allocated iterator, or NULL if it fails to allocate.

otMdnsFreeIterator

void otMdnsFreeIterator(
  otInstance *aInstance,
  otMdnsIterator *aIterator
)

Frees a previously allocated iterator.

Requires OPENTHREAD_CONFIG_MULTICAST_DNS_ENTRY_ITERATION_API_ENABLE.

Details
Parameters	[in] aInstance The OpenThread instance. [in] aIterator The iterator to free.

otMdnsGetNextBrowser

otError otMdnsGetNextBrowser(
  otInstance *aInstance,
  otMdnsIterator *aIterator,
  otMdnsBrowser *aBrowser,
  otMdnsCacheInfo *aInfo
)

Iterates over browsers.

Requires OPENTHREAD_CONFIG_MULTICAST_DNS_ENTRY_ITERATION_API_ENABLE.

On success, aBrowser is populated with information about the next browser. The mCallback field is always set to NULL as there may be multiple active browsers with different callbacks. Other pointers within the otMdnsBrowser structure remain valid until the next call to any OpenThread stack's public or platform API/callback.

Details
Parameters	[in] aInstance The OpenThread instance. [in] aIterator Pointer to the iterator. [out] aBrowser Pointer to an otMdnsBrowser to return the information about the next browser. [out] aInfo Pointer to an otMdnsCacheInfo to return additional information.
Return Values	OT_ERROR_NONE aBrowser, aInfo, & aIterator are updated successfully. OT_ERROR_NOT_FOUND Reached the end of the list. OT_ERROR_INVALID_ARG aIterator is not valid.

otMdnsGetNextHost

otError otMdnsGetNextHost(
  otInstance *aInstance,
  otMdnsIterator *aIterator,
  otMdnsHost *aHost,
  otMdnsEntryState *aState
)

Iterates over registered host entries.

Requires OPENTHREAD_CONFIG_MULTICAST_DNS_ENTRY_ITERATION_API_ENABLE.

On success, aHost is populated with information about the next host. Pointers within the otMdnsHost structure (like mName) remain valid until the next call to any OpenThread stack's public or platform API/callback.

Details
Parameters	[in] aInstance The OpenThread instance. [in] aIterator Pointer to the iterator. [out] aHost Pointer to an otMdnsHost to return the information about the next host entry. [out] aState Pointer to an otMdnsEntryState to return the entry state.
Return Values	OT_ERROR_NONE aHost, aState, & aIterator are updated successfully. OT_ERROR_NOT_FOUND Reached the end of the list. OT_ERROR_INVALID_ARG aIterator is not valid.

otMdnsGetNextIp4AddressResolver

otError otMdnsGetNextIp4AddressResolver(
  otInstance *aInstance,
  otMdnsIterator *aIterator,
  otMdnsAddressResolver *aResolver,
  otMdnsCacheInfo *aInfo
)

Iterates over IPv4 address resolvers.

Requires OPENTHREAD_CONFIG_MULTICAST_DNS_ENTRY_ITERATION_API_ENABLE.

On success, aResolver is populated with information about the next resolver. The mCallback field is always set to NULL as there may be multiple active resolvers with different callbacks. Other pointers within the otMdnsAddressResolver structure remain valid until the next call to any OpenThread stack's public or platform API/callback.

Details
Parameters	[in] aInstance The OpenThread instance. [in] aIterator Pointer to the iterator. [out] aResolver Pointer to an otMdnsAddressResolver to return the information about the next resolver. [out] aInfo Pointer to an otMdnsCacheInfo to return additional information.
Return Values	OT_ERROR_NONE aResolver, aInfo, & aIterator are updated successfully. OT_ERROR_NOT_FOUND Reached the end of the list. OT_ERROR_INVALID_ARG aIterator is not valid.

otMdnsGetNextIp6AddressResolver

otError otMdnsGetNextIp6AddressResolver(
  otInstance *aInstance,
  otMdnsIterator *aIterator,
  otMdnsAddressResolver *aResolver,
  otMdnsCacheInfo *aInfo
)

Iterates over IPv6 address resolvers.

Requires OPENTHREAD_CONFIG_MULTICAST_DNS_ENTRY_ITERATION_API_ENABLE.

On success, aResolver is populated with information about the next resolver. The mCallback field is always set to NULL as there may be multiple active resolvers with different callbacks. Other pointers within the otMdnsAddressResolver structure remain valid until the next call to any OpenThread stack's public or platform API/callback.

Details
Parameters	[in] aInstance The OpenThread instance. [in] aIterator Pointer to the iterator. [out] aResolver Pointer to an otMdnsAddressResolver to return the information about the next resolver. [out] aInfo Pointer to an otMdnsCacheInfo to return additional information.
Return Values	OT_ERROR_NONE aResolver, aInfo, & aIterator are updated successfully. OT_ERROR_NOT_FOUND Reached the end of the list. OT_ERROR_INVALID_ARG aIterator is not valid.

otMdnsGetNextKey

otError otMdnsGetNextKey(
  otInstance *aInstance,
  otMdnsIterator *aIterator,
  otMdnsKey *aKey,
  otMdnsEntryState *aState
)

Iterates over registered key entries.

Requires OPENTHREAD_CONFIG_MULTICAST_DNS_ENTRY_ITERATION_API_ENABLE.

On success, aKey is populated with information about the next key. Pointers within the otMdnsKey structure (like mName) remain valid until the next call to any OpenThread stack's public or platform API/callback.

Details
Parameters	[in] aInstance The OpenThread instance. [in] aIterator Pointer to the iterator to use. [out] aKey Pointer to an otMdnsKey to return the information about the next key entry. [out] aState Pointer to an otMdnsEntryState to return the entry state.
Return Values	OT_ERROR_NONE aKey, aState, & aIterator are updated successfully. OT_ERROR_NOT_FOUND Reached the end of the list. OT_ERROR_INVALID_ARG Iterator is not valid.

otMdnsGetNextService

otError otMdnsGetNextService(
  otInstance *aInstance,
  otMdnsIterator *aIterator,
  otMdnsService *aService,
  otMdnsEntryState *aState
)

Iterates over registered service entries.

Requires OPENTHREAD_CONFIG_MULTICAST_DNS_ENTRY_ITERATION_API_ENABLE.

On success, aService is populated with information about the next service . Pointers within the otMdnsService structure (like mServiceType, mSubTypeLabels) remain valid until the next call to any OpenThread stack's public or platform API/callback.

Details
Parameters	[in] aInstance The OpenThread instance. [in] aIterator Pointer to the iterator to use. [out] aService Pointer to an otMdnsService to return the information about the next service entry. [out] aState Pointer to an otMdnsEntryState to return the entry state.
Return Values	OT_ERROR_NONE aService, aState, & aIterator are updated successfully. OT_ERROR_NOT_FOUND Reached the end of the list. OT_ERROR_INVALID_ARG aIterator is not valid.

otMdnsGetNextSrvResolver

otError otMdnsGetNextSrvResolver(
  otInstance *aInstance,
  otMdnsIterator *aIterator,
  otMdnsSrvResolver *aResolver,
  otMdnsCacheInfo *aInfo
)

Iterates over SRV resolvers.

Requires OPENTHREAD_CONFIG_MULTICAST_DNS_ENTRY_ITERATION_API_ENABLE.

On success, aResolver is populated with information about the next resolver. The mCallback field is always set to NULL as there may be multiple active resolvers with different callbacks. Other pointers within the otMdnsSrvResolver structure remain valid until the next call to any OpenThread stack's public or platform API/callback.

Details
Parameters	[in] aInstance The OpenThread instance. [in] aIterator Pointer to the iterator. [out] aResolver Pointer to an otMdnsSrvResolver to return the information about the next resolver. [out] aInfo Pointer to an otMdnsCacheInfo to return additional information.
Return Values	OT_ERROR_NONE aResolver, aInfo, & aIterator are updated successfully. OT_ERROR_NOT_FOUND Reached the end of the list. OT_ERROR_INVALID_ARG aIterator is not valid.

otMdnsGetNextTxtResolver

otError otMdnsGetNextTxtResolver(
  otInstance *aInstance,
  otMdnsIterator *aIterator,
  otMdnsTxtResolver *aResolver,
  otMdnsCacheInfo *aInfo
)

Iterates over TXT resolvers.

Requires OPENTHREAD_CONFIG_MULTICAST_DNS_ENTRY_ITERATION_API_ENABLE.

On success, aResolver is populated with information about the next resolver. The mCallback field is always set to NULL as there may be multiple active resolvers with different callbacks. Other pointers within the otMdnsTxtResolver structure remain valid until the next call to any OpenThread stack's public or platform API/callback.

Details
Parameters	[in] aInstance The OpenThread instance. [in] aIterator Pointer to the iterator. [out] aResolver Pointer to an otMdnsTxtResolver to return the information about the next resolver. [out] aInfo Pointer to an otMdnsCacheInfo to return additional information.
Return Values	OT_ERROR_NONE aResolver, aInfo, & aIterator are updated successfully. OT_ERROR_NOT_FOUND Reached the end of the list. OT_ERROR_INVALID_ARG aIterator is not valid.

otMdnsIsEnabled

bool otMdnsIsEnabled(
  otInstance *aInstance
)

Indicates whether the mDNS module is enabled.

Details
Parameters	[in] aInstance The OpenThread instance.
Return Values	TRUE The mDNS module is enabled FALSE The mDNS module is disabled.

otMdnsIsQuestionUnicastAllowed

bool otMdnsIsQuestionUnicastAllowed(
  otInstance *aInstance
)

Indicates whether mDNS module is allowed to send "QU" questions requesting unicast response.

Details
Return Values	TRUE The mDNS module is allowed to send "QU" questions. FALSE The mDNS module is not allowed to send "QU" questions.

otMdnsRegisterHost

otError otMdnsRegisterHost(
  otInstance *aInstance,
  const otMdnsHost *aHost,
  otMdnsRequestId aRequestId,
  otMdnsRegisterCallback aCallback
)

Registers or updates a host on mDNS.

The fields in aHost follow these rules:

• The mHostName field specifies the host name to register (e.g., "myhost"). MUST NOT contain the domain name.
• The mAddresses is array of IPv6 addresses to register with the host. mAddressesLength provides the number of entries in mAddresses array.
• The mAddresses array can be empty with zero mAddressesLength. In this case, mDNS will treat it as if host is unregistered and stops advertising any addresses for this the host name.
• The mTtl specifies the TTL if non-zero. If zero, the mDNS core will choose the default TTL of 120 seconds.
• Other fields in aHost structure are ignored in an otMdnsRegisterHost() call.

This function can be called again for the same mHostName to update a previously registered host entry, for example, to change the list of addresses of the host. In this case, the mDNS module will send "goodbye" announcements for any previously registered and now removed addresses and announce any newly added addresses.

The outcome of the registration request is reported back by invoking the provided aCallback with aRequestId as its input and one of the following aError inputs:

• OT_ERROR_NONE indicates registration was successful.
• OT_ERROR_DULICATED indicates a name conflict while probing, i.e., name is claimed by another mDNS responder.

For caller convenience, the OpenThread mDNS module guarantees that the callback will be invoked after this function returns, even in cases of immediate registration success. The aCallback can be NULL if caller does not want to be notified of the outcome.

Details
Parameters	[in] aInstance The OpenThread instance. [in] aHost Information about the host to register. [in] aRequestId The ID associated with this request. [in] aCallback The callback function pointer to report the outcome (can be NULL if not needed).
Return Values	OT_ERROR_NONE Successfully started registration. aCallback will report the outcome. OT_ERROR_INVALID_STATE mDNS module is not enabled.

otMdnsRegisterKey

otError otMdnsRegisterKey(
  otInstance *aInstance,
  const otMdnsKey *aKey,
  otMdnsRequestId aRequestId,
  otMdnsRegisterCallback aCallback
)

Registers or updates a key record on mDNS module.

The fields in aKey follow these rules:

• If the key is associated with a host entry, the mName field specifies the host name and the mServiceType MUST be NULL.
• If the key is associated with a service entry, the mName filed specifies the service instance label (always treated as a single label) and the mServiceType filed specifies the service type (e.g., "_tst._udp"). In this case the DNS name for key record is ..
• The mKeyData field contains the key record's data with mKeyDataLength as its length in byes.
• The mTtl specifies the TTL if non-zero. If zero, the mDNS module will use the default TTL of 120 seconds.
• Other fields in aKey structure are ignored in an otMdnsRegisterKey() call.

This function can be called again for the same name to updated a previously registered key entry, for example, to change the key data or TTL.

Regarding the invocation of the aCallback, this function behaves in the same way as described in otMdnsRegisterHost().

Details
Parameters	[in] aInstance The OpenThread instance. [in] aKey Information about the key record to register. [in] aRequestId The ID associated with this request. [in] aCallback The callback function pointer to report the outcome (can be NULL if not needed).
Return Values	OT_ERROR_NONE Successfully started registration. aCallback will report the outcome. OT_ERROR_INVALID_STATE mDNS module is not enabled.

otMdnsRegisterService

otError otMdnsRegisterService(
  otInstance *aInstance,
  const otMdnsService *aService,
  otMdnsRequestId aRequestId,
  otMdnsRegisterCallback aCallback
)

Registers or updates a service on mDNS.

The fields in aService follow these rules:

• The mServiceInstance specifies the service instance label. It is treated as a single DNS name label. It may contain dot . character which is allowed in a service instance label.
• The mServiceType specifies the service type (e.g., "_tst._udp"). It is treated as multiple dot . separated labels. It MUST NOT contain the domain name.
• The mHostName field specifies the host name of the service. MUST NOT contain the domain name.
• The mSubTypeLabels is an array of strings representing sub-types associated with the service. Each array entry is a sub-type label. The mSubTypeLabels can be NULL if there is no sub-type. Otherwise, the array length is specified bymSubTypeLabelsLength.
• ThemTxtDataandmTxtDataLengthspecify the encoded TXT data. ThemTxtDatacan be NULL ormTxtDataLength can be zero to specify an empty TXT data. In this case mDNS module will use a single zero byte[ 0 ]` as the TXT data.
• The mPort, mWeight, and mPriority specify the service's parameters as specified in DNS SRV record.
• The mTtl specifies the TTL if non-zero. If zero, the mDNS module will use the default TTL of 120 seconds.
• Other fields in aService structure are ignored in an otMdnsRegisterService() call.

This function can be called again for the same mServiceInstance and mServiceType to update a previously registered service entry, for example, to change the sub-types list, or update any parameter such as port, weight, priority, TTL, or host name. The mDNS module will send announcements for any changed info, e.g., will send "goodbye" announcements for any removed sub-types and announce any newly added sub-types.

Regarding the invocation of the aCallback, this function behaves in the same way as described in otMdnsRegisterHost().

Details
Parameters	[in] aInstance The OpenThread instance. [in] aService Information about the service to register. [in] aRequestId The ID associated with this request. [in] aCallback The callback function pointer to report the outcome (can be NULL if not needed).
Return Values	OT_ERROR_NONE Successfully started registration. aCallback will report the outcome. OT_ERROR_INVALID_STATE mDNS module is not enabled.

otMdnsSetConflictCallback

void otMdnsSetConflictCallback(
  otInstance *aInstance,
  otMdnsConflictCallback aCallback
)

Sets the post-registration conflict callback.

If a conflict is detected while registering an entry, it is reported through the provided otMdnsRegisterCallback. The otMdnsConflictCallback is used only when a name conflict is detected after an entry has been successfully registered.

aCallback can be set to NULL if not needed. Subsequent calls will replace any previously set callback.

Details
Parameters	[in] aInstance The OpenThread instance. [in] aCallback The conflict callback.

otMdnsSetEnabled

otError otMdnsSetEnabled(
  otInstance *aInstance,
  bool aEnable,
  uint32_t aInfraIfIndex
)

Enables or disables the mDNS module.

The mDNS module should be enabled before registration any host, service, or key entries. Disabling mDNS will immediately stop all operations and any communication (multicast or unicast tx) and remove any previously registered entries without sending any "goodbye" announcements or invoking their callback. Once disabled, all currently active browsers and resolvers are stopped.

Details
Parameters	[in] aInstance The OpenThread instance. [in] aEnable Boolean to indicate whether to enable (on TRUE) or disable (on FALSE). [in] aInfraIfIndex The network interface index for mDNS operation. Value is ignored when disabling
Return Values	OT_ERROR_NONE Enabled or disabled the mDNS module successfully. OT_ERROR_ALREADY mDNS is already enabled on an enable request or is already disabled on a disable request.

otMdnsSetQuestionUnicastAllowed

void otMdnsSetQuestionUnicastAllowed(
  otInstance *aInstance,
  bool aAllow
)

Sets whether the mDNS module is allowed to send questions requesting unicast responses referred to as "QU" questions.

The "QU" questions request unicast responses, in contrast to "QM" questions which request multicast responses.

When allowed, the first probe will be sent as a "QU" question. This API can be used to address platform limitation where platform socket cannot accept unicast response received on mDNS port (due to it being already bound).

Details
Parameters	[in] aInstance The OpenThread instance. [in] aAllow Indicates whether or not to allow "QU" questions.

otMdnsStartBrowser

otError otMdnsStartBrowser(
  otInstance *aInstance,
  const otMdnsBrowser *aBrowser
)

Starts a service browser.

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

Discovered services are 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 will reflect the original TTL from the last received response.

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

Details
Parameters	[in] aInstance The OpenThread instance. [in] aBrowser The browser to be started.
Return Values	OT_ERROR_NONE Browser started successfully. OT_ERROR_INVALID_STATE mDNS module is not enabled. OT_ERROR_ALREADY An identical browser (same service and callback) is already active.

otMdnsStartIp4AddressResolver

otError otMdnsStartIp4AddressResolver(
  otInstance *aInstance,
  const otMdnsAddressResolver *aResolver
)

Starts an IPv4 address resolver.

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

Discovered addresses are reported through the mCallback function in aResolver. The IPv4 addresses are represented using the IPv4-mapped IPv6 address format in mAddresses array. The callback is invoked whenever addresses are added or removed, providing an updated list. If all addresses are removed, the callback is invoked with an empty list (mAddresses will be NULL, and mAddressesLength will be 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.

Details
Parameters	[in] aInstance The OpenThread instance. [in] aResolver The resolver to be started.
Return Values	OT_ERROR_NONE Resolver started successfully. OT_ERROR_INVALID_STATE mDNS module is not enabled. OT_ERROR_ALREADY An identical resolver (same host and callback) is already active.

otMdnsStartIp6AddressResolver

otError otMdnsStartIp6AddressResolver(
  otInstance *aInstance,
  const otMdnsAddressResolver *aResolver
)

Starts an IPv6 address resolver.

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

Discovered addresses are reported through the mCallback function in aResolver. The callback is invoked whenever addresses are added or removed, providing an updated list. If all addresses are removed, the callback is invoked with an empty list (mAddresses will be NULL, and mAddressesLength will be 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.

Details
Parameters	[in] aInstance The OpenThread instance. [in] aResolver The resolver to be started.
Return Values	OT_ERROR_NONE Resolver started successfully. OT_ERROR_INVALID_STATE mDNS module is not enabled. OT_ERROR_ALREADY An identical resolver (same host and callback) is already active.

otMdnsStartSrvResolver

otError otMdnsStartSrvResolver(
  otInstance *aInstance,
  const otMdnsSrvResolver *aResolver
)

Starts an SRV record resolver.

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

Discovered information is 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) should be ignored.

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 will reflect the original TTL from the last received response.

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

Details
Parameters	[in] aInstance The OpenThread instance. [in] aResolver The resolver to be started.
Return Values	OT_ERROR_NONE Resolver started successfully. OT_ERROR_INVALID_STATE mDNS module is not enabled. OT_ERROR_ALREADY An identical resolver (same service and callback) is already active.

otMdnsStartTxtResolver

otError otMdnsStartTxtResolver(
  otInstance *aInstance,
  const otMdnsTxtResolver *aResolver
)

Starts a TXT record resolver.

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

Discovered information is 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) should be ignored.

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 will reflect the original TTL from the last received response.

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

Details
Parameters	[in] aInstance The OpenThread instance. [in] aResolver The resolver to be started.
Return Values	OT_ERROR_NONE Resolver started successfully. OT_ERROR_INVALID_STATE mDNS module is not enabled. OT_ERROR_ALREADY An identical resolver (same service and callback) is already active.

otMdnsStopBrowser

otError otMdnsStopBrowser(
  otInstance *aInstance,
  const otMdnsBrowser *aBroswer
)

Stops a service browser.

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

Details
Parameters	[in] aInstance The OpenThread instance. [in] aBrowser The browser to stop.
Return Values	OT_ERROR_NONE Browser stopped successfully. OT_ERROR_INVALID_STATE mDNS module is not enabled.

otMdnsStopIp4AddressResolver

otError otMdnsStopIp4AddressResolver(
  otInstance *aInstance,
  const otMdnsAddressResolver *aResolver
)

Stops an IPv4 address resolver.

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

Details
Parameters	[in] aInstance The OpenThread instance. [in] aResolver The resolver to stop.
Return Values	OT_ERROR_NONE Resolver stopped successfully. OT_ERROR_INVALID_STATE mDNS module is not enabled.

otMdnsStopIp6AddressResolver

otError otMdnsStopIp6AddressResolver(
  otInstance *aInstance,
  const otMdnsAddressResolver *aResolver
)

Stops an IPv6 address resolver.

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

Details
Parameters	[in] aInstance The OpenThread instance. [in] aResolver The resolver to stop.
Return Values	OT_ERROR_NONE Resolver stopped successfully. OT_ERROR_INVALID_STATE mDNS module is not enabled.

otMdnsStopSrvResolver

otError otMdnsStopSrvResolver(
  otInstance *aInstance,
  const otMdnsSrvResolver *aResolver
)

Stops an SRV record resolver.

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

Details
Parameters	[in] aInstance The OpenThread instance. [in] aResolver The resolver to stop.
Return Values	OT_ERROR_NONE Resolver stopped successfully. OT_ERROR_INVALID_STATE mDNS module is not enabled.

otMdnsStopTxtResolver

otError otMdnsStopTxtResolver(
  otInstance *aInstance,
  const otMdnsTxtResolver *aResolver
)

Stops a TXT record resolver.

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

Details
Parameters	[in] aInstance The OpenThread instance. [in] aResolver The resolver to stop.
Return Values	OT_ERROR_NONE Resolver stopped successfully. OT_ERROR_INVALID_STATE mDNS module is not enabled.

otMdnsUnregisterHost

otError otMdnsUnregisterHost(
  otInstance *aInstance,
  const otMdnsHost *aHost
)

Unregisters a host on mDNS.

The fields in aHost follow these rules:

• The mHostName field specifies the host name to unregister (e.g., "myhost"). MUST NOT contain the domain name.
• Other fields in aHost structure are ignored in an otMdnsUnregisterHost() call.

If there is no previously registered host with the same name, no action is performed.

If there is a previously registered host with the same name, the mDNS module will send "goodbye" announcement for all previously advertised address records.

Details
Parameters	[in] aInstance The OpenThread instance. [in] aHost Information about the host to unregister.
Return Values	OT_ERROR_NONE Successfully unregistered host. OT_ERROR_INVALID_STATE mDNS module is not enabled.

otMdnsUnregisterKey

otError otMdnsUnregisterKey(
  otInstance *aInstance,
  const otMdnsKey *aKey
)

Unregisters a key record on mDNS.

The fields in aKey follow these rules:

• If the key is associated with a host entry, the mName field specifies the host name and the mServiceType MUST be NULL.
• If the key is associated with a service entry, the mName filed specifies the service instance label (always treated as a single label) and the mServiceType filed specifies the service type (e.g., "_tst._udp"). In this case the DNS name for key record is ..
• Other fields in aKey structure are ignored in an otMdnsUnregisterKey() call.

If there is no previously registered key with the same name, no action is performed.

If there is a previously registered key with the same name, the mDNS module will send "goodbye" announcements for the key record.

Details
Parameters	[in] aInstance The OpenThread instance. [in] aKey Information about the key to unregister.
Return Values	OT_ERROR_NONE Successfully unregistered key OT_ERROR_INVALID_STATE mDNS module is not enabled.

otMdnsUnregisterService

otError otMdnsUnregisterService(
  otInstance *aInstance,
  const otMdnsService *aService
)

Unregisters a service on mDNS module.

The fields in aService follow these rules:

• The mServiceInstance specifies the service instance label. It is treated as a single DNS name label. It may contain dot . character which is allowed in a service instance label.
• The mServiceType specifies the service type (e.g., "_tst._udp"). It is treated as multiple dot . separated labels. It MUST NOT contain the domain name.
• Other fields in aService structure are ignored in an otMdnsUnregisterService() call.

If there is no previously registered service with the same name, no action is performed.

If there is a previously registered service with the same name, the mDNS module will send "goodbye" announcements for all related records.

Details
Parameters	[in] aInstance The OpenThread instance. [in] aService Information about the service to unregister.
Return Values	OT_ERROR_NONE Successfully unregistered service. OT_ERROR_INVALID_STATE mDNS module is not enabled.

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.