Multicast DNS#

otMdnsEntryState#

otMdnsEntryState

Represents a host/service/key entry state.

otMdnsRequestId#

typedef otPlatDnssdRequestId otMdnsRequestId

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

otMdnsRegisterCallback#

typedef 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.

otMdnsConflictCallback#

typedef void(* otMdnsConflictCallback) (otInstance *aInstance, const char *aName, const char *aServiceType) )(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.

otMdnsHost#

typedef 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.

otMdnsService#

typedef 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.

otMdnsKey#

typedef otPlatDnssdKey otMdnsKey

Represents an mDNS key record.

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

otMdnsIterator#

typedef struct otMdnsIterator otMdnsIterator

Represents an mDNS entry iterator.

otMdnsEntryState#

typedef enum otMdnsEntryState otMdnsEntryState

Represents a host/service/key entry state.

otMdnsBrowser#

typedef otPlatDnssdBrowser otMdnsBrowser

Represents a service browser.

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

otMdnsBrowseCallback#

typedef otPlatDnssdBrowseCallback otMdnsBrowseCallback

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

otMdnsBrowseResult#

typedef otPlatDnssdBrowseResult otMdnsBrowseResult

Represents a browse result.

otMdnsSrvResolver#

typedef otPlatDnssdSrvResolver otMdnsSrvResolver

Represents an SRV service resolver.

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

otMdnsSrvCallback#

typedef otPlatDnssdSrvCallback otMdnsSrvCallback

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

otMdnsSrvResult#

typedef otPlatDnssdSrvResult otMdnsSrvResult

Represents an SRV resolver result.

otMdnsTxtResolver#

typedef otPlatDnssdTxtResolver otMdnsTxtResolver

Represents a TXT service resolver.

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

otMdnsTxtCallback#

typedef otPlatDnssdTxtCallback otMdnsTxtCallback

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

otMdnsTxtResult#

typedef otPlatDnssdTxtResult otMdnsTxtResult

Represents a TXT resolver result.

otMdnsAddressResolver#

typedef otPlatDnssdAddressResolver otMdnsAddressResolver

Represents an address resolver.

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

otMdnsAddressCallback#

typedef otPlatDnssdAddressCallback otMdnsAddressCallback

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

otMdnsAddressAndTtl#

typedef otPlatDnssdAddressAndTtl otMdnsAddressAndTtl

Represents a discovered host address and its TTL.

otMdnsAddressResult#

typedef otPlatDnssdAddressResult otMdnsAddressResult

Represents address resolver result.

otMdnsCacheInfo#

typedef struct otMdnsCacheInfo otMdnsCacheInfo

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

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.

otMdnsIsEnabled#

bool otMdnsIsEnabled (otInstance * aInstance)

Indicates whether the mDNS module is enabled.

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

otMdnsIsQuestionUnicastAllowed#

bool otMdnsIsQuestionUnicastAllowed (otInstance * aInstance)

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

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.

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.

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.

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

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.

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 <mName>.<mServiceTye>.

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

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 <mName>.<mServiceTye>.

• 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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.