Multicast DNS

Represents a host/service/key entry state.

Represents a discovered host address and its TTL.

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

Represents an address resolver.

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

Represents address resolver result.

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

Represents a browse result.

Represents a service browser.

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

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

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.

Represents a host/service/key entry state.

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.

Represents an mDNS entry iterator.

Represents an mDNS key record.

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

Represents a local host IPv4 or IPv6 address entry.

Represents the callback function used to report a record querier result.

Represents a record querier.

Represents a record query result.

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.

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

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.

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

Represents an SRV service resolver.

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

Represents an SRV resolver result.

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

Represents a TXT service resolver.

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

Represents a TXT resolver result.

Allocates a new iterator.

Requires OPENTHREAD_CONFIG_MULTICAST_DNS_ENTRY_ITERATION_API_ENABLE.

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

Frees a previously allocated iterator.

Requires OPENTHREAD_CONFIG_MULTICAST_DNS_ENTRY_ITERATION_API_ENABLE.

Indicates whether the auto-enable mode is enabled or disabled.

Requires OPENTHREAD_CONFIG_BORDER_ROUTING_ENABLE.

Gets the local host name.

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.

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.

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.

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.

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.

Iterates over the local host IPv6 and IPv4 addresses tracked by OpenThread mDNS module.

Requires OPENTHREAD_CONFIG_MULTICAST_DNS_ENTRY_ITERATION_API_ENABLE.

The platform layer is responsible for monitoring and reporting all host IPv4 and IPv6 addresses to the OpenThread mDNS module, which then tracks the full address list (see otPlatMdnsHandleHostAddressEvent()). This function allows iteration through this tracked list, primarily intended for information and debugging purposes.

Iterates over record querier entries.

Requires OPENTHREAD_CONFIG_MULTICAST_DNS_ENTRY_ITERATION_API_ENABLE.

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

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.

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.

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.

Indicates whether the mDNS module is enabled.

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

Indicates whether verbose logging is enabled for the mDNS module.

Requires OPENTHREAD_CONFIG_MULTICAST_DNS_VERBOSE_LOGGING_ENABLE.

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.

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

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 if it is not NULL. Otherwise, if it is NULL, it indicates that this service is for the local host (this device itself).
• 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().

Enables or disables the mDNS auto-enable mode.

Requires OPENTHREAD_CONFIG_BORDER_ROUTING_ENABLE.

When this mode is enabled, the mDNS module uses the same infrastructure network interface as the Border Routing manager. The mDNS module is then automatically enabled or disabled based on the operational state of that interface (see otBorderRoutingInit() and otPlatInfraIfStateChanged()).

It is recommended to use the auto-enable mode on Border Routers. The default state of this mode at initialization is controlled by the OPENTHREAD_CONFIG_MULTICAST_DNS_AUTO_ENABLE_ON_INFRA_IF configuration.

The auto-enable mode can be disabled by a call to otMdnsSetAutoEnableMode(false) or by an explicit call to otMdnsSetEnabled(). Deactivating the auto-enable mode with otMdnsSetAutoEnableMode(false) will not change the current operational state of the mDNS module (e.g., if it is currently enabled, it remains enabled).

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.

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.

Sets the local host name.

The local host name can be set only when the mDNS module is disabled. If not set the mDNS module itself will auto-generate the local host name.

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

Enables or disables verbose logging for the mDNS module at run-time.

Requires OPENTHREAD_CONFIG_MULTICAST_DNS_VERBOSE_LOGGING_ENABLE.

The initial state of verbose logging (enabled or disabled at startup) is determined by the configuration OPENTHREAD_CONFIG_MULTICAST_DEFAULT_DNS_VERBOSE_LOGGING_STATE.

When enabled, the mDNS module emits verbose logs for every sent or received mDNS message, including the header and all question and resource records. These logs are generated regardless of the current log level configured on the device.

This feature can generate a large volume of logs, so its use is recommended only during development, integration, or debugging.

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.

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.

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.

Starts a record querier.

Initiates a continuous query for a given mRecordType as specified in aQuerier. The queried name is specified by the combination of mFirstLabel and mNextLabels (optional rest of the labels) in aQuerier. The mFirstLabel MUST be non-NULL but mNextLabels can be NULL if there are no other labels. The mNextLabels MUST NOT include the domain name. The reason for a separate first label is to allow it to include a dot . character (as allowed for service instance labels).

Discovered results are reported through the mCallback function in aQuerier, providing the record data bytes (RDATA). For NS, CNAME, SOA, PTR, MX, RP, AFSDB, RT, PX, SRV, KX, DNAME, and NSEC record types, the RDATA format contains one or more DNS names (which may use DNS name compression). For the above list, the reported record data bytes via mCallback will be decompressed to contain the full DNS name(s). For all other record types, the record data bytes are provided exactly as they appear in the received mDNS response. This aligns the implementation with RFC 6762 (section 18.14) regarding the use of name compression.

A removed record data is indicated 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 querier instances can be started for the same name, provided they use different callback functions.

The record querier MUST not be used for record types PTR, SRV, TXT, A, and AAAA. Otherwise, OT_ERROR_INVALID_ARGS will be returned. For these, browsers/resolvers can be used. This design is intentional to enable the implementation of an "opportunistic cache mechanism", where, depending on currently active service browsers/resolvers, the mDNS implementation will also monitor and cache related records (e.g., when a service is resolved, the address records associated with its host name are cached even if there is no active address resolver for this hostname).

The aQuerier 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.

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.

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.

Stops a service browser.

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

Stops an IPv4 address resolver.

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

Stops an IPv6 address resolver.

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

Stops a record querier.

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

The aQuerier 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.

Stops an SRV record resolver.

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

Stops a TXT record resolver.

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

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.

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.

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.