1 /* 2 * Copyright (c) 2024, The OpenThread Authors. 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions are met: 7 * 1. Redistributions of source code must retain the above copyright 8 * notice, this list of conditions and the following disclaimer. 9 * 2. Redistributions in binary form must reproduce the above copyright 10 * notice, this list of conditions and the following disclaimer in the 11 * documentation and/or other materials provided with the distribution. 12 * 3. Neither the name of the copyright holder nor the 13 * names of its contributors may be used to endorse or promote products 14 * derived from this software without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 26 * POSSIBILITY OF SUCH DAMAGE. 27 */ 28 29 /** 30 * @file 31 * @brief 32 * This file includes the mDNS related APIs. 33 * 34 */ 35 36 #ifndef OPENTHREAD_MULTICAST_DNS_H_ 37 #define OPENTHREAD_MULTICAST_DNS_H_ 38 39 #include <stdint.h> 40 41 #include <openthread/error.h> 42 #include <openthread/instance.h> 43 #include <openthread/ip6.h> 44 #include <openthread/platform/dnssd.h> 45 46 #ifdef __cplusplus 47 extern "C" { 48 #endif 49 50 /** 51 * @addtogroup api-mdns 52 * 53 * @brief 54 * This module includes APIs for Multicast DNS (mDNS). 55 * 56 * @{ 57 * 58 * The mDNS APIs are available when the mDNS support `OPENTHREAD_CONFIG_MULTICAST_DNS_ENABLE` is enabled and the 59 * `OPENTHREAD_CONFIG_MULTICAST_DNS_PUBLIC_API_ENABLE` is also enabled. 60 * 61 */ 62 63 /** 64 * Represents a request ID (`uint32_t` value) for registering a host, a service, or a key service. 65 * 66 */ 67 typedef otPlatDnssdRequestId otMdnsRequestId; 68 69 /** 70 * Represents the callback function to report the outcome of a host, service, or key registration request. 71 * 72 * The outcome of a registration request is reported back by invoking this callback with one of the following `aError` 73 * inputs: 74 * 75 * - `OT_ERROR_NONE` indicates registration was successful. 76 * - `OT_ERROR_DUPLICATED` indicates a name conflict while probing, i.e., name is claimed by another mDNS responder. 77 * 78 * See `otMdnsRegisterHost()`, `otMdnsRegisterService()`, and `otMdnsRegisterKey()` for more details about when 79 * the callback will be invoked. 80 * 81 * @param[in] aInstance The OpenThread instance. 82 * @param[in] aRequestId The request ID. 83 * @param[in] aError Error indicating the outcome of request. 84 * 85 */ 86 typedef otPlatDnssdRegisterCallback otMdnsRegisterCallback; 87 88 /** 89 * Represents the callback function to report a detected name conflict after successful registration of an entry. 90 * 91 * If a conflict is detected while registering an entry, it is reported through the provided `otMdnsRegisterCallback`. 92 * The `otMdnsConflictCallback` is used only when a name conflict is detected after an entry has been successfully 93 * registered. 94 * 95 * A non-NULL @p aServiceType indicates that conflict is for a service entry. In this case @p aName specifies the 96 * service instance label (treated as as a single DNS label and can potentially include dot `.` character). 97 * 98 * A NULL @p aServiceType indicates that conflict is for a host entry. In this case @p Name specifies the host name. It 99 * does not include the domain name. 100 * 101 * @param[in] aInstance The OpenThread instance. 102 * @param[in] aName The host name or the service instance label. 103 * @param[in] aServiceType The service type (e.g., `_tst._udp`). 104 * 105 */ 106 typedef void (*otMdnsConflictCallback)(otInstance *aInstance, const char *aName, const char *aServiceType); 107 108 /** 109 * Represents an mDNS host. 110 * 111 * This type is used to register or unregister a host (`otMdnsRegisterHost()` and `otMdnsUnregisterHost()`). 112 * 113 * See the description of each function for more details on how different fields are used in each case. 114 * 115 */ 116 typedef otPlatDnssdHost otMdnsHost; 117 118 /** 119 * Represents an mDNS service. 120 * 121 * This type is used to register or unregister a service (`otMdnsRegisterService()` and `otMdnsUnregisterService()`). 122 * 123 * See the description of each function for more details on how different fields are used in each case. 124 * 125 */ 126 typedef otPlatDnssdService otMdnsService; 127 128 /** 129 * Represents an mDNS key record. 130 * 131 * See `otMdnsRegisterKey()`, `otMdnsUnregisterKey()` for more details about fields in each case. 132 * 133 */ 134 typedef otPlatDnssdKey otMdnsKey; 135 136 /** 137 * Represents an mDNS entry iterator. 138 * 139 */ 140 typedef struct otMdnsIterator otMdnsIterator; 141 142 /** 143 * Represents a host/service/key entry state. 144 * 145 */ 146 typedef enum otMdnsEntryState 147 { 148 OT_MDNS_ENTRY_STATE_PROBING, ///< Probing to claim the name. 149 OT_MDNS_ENTRY_STATE_REGISTERED, ///< Entry is successfully registered. 150 OT_MDNS_ENTRY_STATE_CONFLICT, ///< Name conflict was detected. 151 OT_MDNS_ENTRY_STATE_REMOVING, ///< Entry is being removed (sending "goodbye" announcements). 152 } otMdnsEntryState; 153 154 /** 155 * Enables or disables the mDNS module. 156 * 157 * The mDNS module should be enabled before registration any host, service, or key entries. Disabling mDNS will 158 * immediately stop all operations and any communication (multicast or unicast tx) and remove any previously registered 159 * entries without sending any "goodbye" announcements or invoking their callback. Once disabled, all currently active 160 * browsers and resolvers are stopped. 161 * 162 * @param[in] aInstance The OpenThread instance. 163 * @param[in] aEnable Boolean to indicate whether to enable (on `TRUE`) or disable (on `FALSE`). 164 * @param[in] aInfraIfIndex The network interface index for mDNS operation. Value is ignored when disabling 165 * 166 * @retval OT_ERROR_NONE Enabled or disabled the mDNS module successfully. 167 * @retval OT_ERROR_ALREADY mDNS is already enabled on an enable request or is already disabled on a disable request. 168 * 169 */ 170 otError otMdnsSetEnabled(otInstance *aInstance, bool aEnable, uint32_t aInfraIfIndex); 171 172 /** 173 * Indicates whether the mDNS module is enabled. 174 * 175 * @param[in] aInstance The OpenThread instance. 176 * 177 * @retval TRUE The mDNS module is enabled 178 * @retval FALSE The mDNS module is disabled. 179 * 180 */ 181 bool otMdnsIsEnabled(otInstance *aInstance); 182 183 /** 184 * Sets whether the mDNS module is allowed to send questions requesting unicast responses referred to as "QU" questions. 185 * 186 * The "QU" questions request unicast responses, in contrast to "QM" questions which request multicast responses. 187 * 188 * When allowed, the first probe will be sent as a "QU" question. This API can be used to address platform limitation 189 * where platform socket cannot accept unicast response received on mDNS port (due to it being already bound). 190 * 191 * @param[in] aInstance The OpenThread instance. 192 * @param[in] aAllow Indicates whether or not to allow "QU" questions. 193 * 194 */ 195 void otMdnsSetQuestionUnicastAllowed(otInstance *aInstance, bool aAllow); 196 197 /** 198 * Indicates whether mDNS module is allowed to send "QU" questions requesting unicast response. 199 * 200 * @retval TRUE The mDNS module is allowed to send "QU" questions. 201 * @retval FALSE The mDNS module is not allowed to send "QU" questions. 202 * 203 */ 204 bool otMdnsIsQuestionUnicastAllowed(otInstance *aInstance); 205 206 /** 207 * Sets the post-registration conflict callback. 208 * 209 * If a conflict is detected while registering an entry, it is reported through the provided `otMdnsRegisterCallback`. 210 * The `otMdnsConflictCallback` is used only when a name conflict is detected after an entry has been successfully 211 * registered. 212 * 213 * @p aCallback can be set to `NULL` if not needed. Subsequent calls will replace any previously set callback. 214 * 215 * @param[in] aInstance The OpenThread instance. 216 * @param[in] aCallback The conflict callback. 217 * 218 */ 219 void otMdnsSetConflictCallback(otInstance *aInstance, otMdnsConflictCallback aCallback); 220 221 /** 222 * Registers or updates a host on mDNS. 223 * 224 * The fields in @p aHost follow these rules: 225 * 226 * - The `mHostName` field specifies the host name to register (e.g., "myhost"). MUST NOT contain the domain name. 227 * - The `mAddresses` is array of IPv6 addresses to register with the host. `mAddressesLength` provides the number of 228 * entries in `mAddresses` array. 229 * - The `mAddresses` array can be empty with zero `mAddressesLength`. In this case, mDNS will treat it as if host is 230 * unregistered and stops advertising any addresses for this the host name. 231 * - The `mTtl` specifies the TTL if non-zero. If zero, the mDNS core will choose the default TTL of 120 seconds. 232 * - Other fields in @p aHost structure are ignored in an `otMdnsRegisterHost()` call. 233 * 234 * This function can be called again for the same `mHostName` to update a previously registered host entry, for example, 235 * to change the list of addresses of the host. In this case, the mDNS module will send "goodbye" announcements for any 236 * previously registered and now removed addresses and announce any newly added addresses. 237 * 238 * The outcome of the registration request is reported back by invoking the provided @p aCallback with @p aRequestId 239 * as its input and one of the following `aError` inputs: 240 * 241 * - `OT_ERROR_NONE` indicates registration was successful. 242 * - `OT_ERROR_DULICATED` indicates a name conflict while probing, i.e., name is claimed by another mDNS responder. 243 * 244 * For caller convenience, the OpenThread mDNS module guarantees that the callback will be invoked after this function 245 * returns, even in cases of immediate registration success. The @p aCallback can be `NULL` if caller does not want to 246 * be notified of the outcome. 247 * 248 * @param[in] aInstance The OpenThread instance. 249 * @param[in] aHost Information about the host to register. 250 * @param[in] aRequestId The ID associated with this request. 251 * @param[in] aCallback The callback function pointer to report the outcome (can be NULL if not needed). 252 * 253 * @retval OT_ERROR_NONE Successfully started registration. @p aCallback will report the outcome. 254 * @retval OT_ERROR_INVALID_STATE mDNS module is not enabled. 255 * 256 */ 257 otError otMdnsRegisterHost(otInstance *aInstance, 258 const otMdnsHost *aHost, 259 otMdnsRequestId aRequestId, 260 otMdnsRegisterCallback aCallback); 261 262 /** 263 * Unregisters a host on mDNS. 264 * 265 * The fields in @p aHost follow these rules: 266 * 267 * - The `mHostName` field specifies the host name to unregister (e.g., "myhost"). MUST NOT contain the domain name. 268 * - Other fields in @p aHost structure are ignored in an `otMdnsUnregisterHost()` call. 269 * 270 * If there is no previously registered host with the same name, no action is performed. 271 * 272 * If there is a previously registered host with the same name, the mDNS module will send "goodbye" announcement for 273 * all previously advertised address records. 274 * 275 * @param[in] aInstance The OpenThread instance. 276 * @param[in] aHost Information about the host to unregister. 277 * 278 * @retval OT_ERROR_NONE Successfully unregistered host. 279 * @retval OT_ERROR_INVALID_STATE mDNS module is not enabled. 280 * 281 */ 282 otError otMdnsUnregisterHost(otInstance *aInstance, const otMdnsHost *aHost); 283 284 /** 285 * Registers or updates a service on mDNS. 286 * 287 * The fields in @p aService follow these rules: 288 * 289 * - The `mServiceInstance` specifies the service instance label. It is treated as a single DNS name label. It may 290 * contain dot `.` character which is allowed in a service instance label. 291 * - The `mServiceType` specifies the service type (e.g., "_tst._udp"). It is treated as multiple dot `.` separated 292 * labels. It MUST NOT contain the domain name. 293 * - The `mHostName` field specifies the host name of the service. MUST NOT contain the domain name. 294 * - The `mSubTypeLabels` is an array of strings representing sub-types associated with the service. Each array entry 295 * is a sub-type label. The `mSubTypeLabels can be NULL if there is no sub-type. Otherwise, the array length is 296 * specified by `mSubTypeLabelsLength`. 297 * - The `mTxtData` and `mTxtDataLength` specify the encoded TXT data. The `mTxtData` can be NULL or `mTxtDataLength` 298 * can be zero to specify an empty TXT data. In this case mDNS module will use a single zero byte `[ 0 ]` as the 299 * TXT data. 300 * - The `mPort`, `mWeight`, and `mPriority` specify the service's parameters as specified in DNS SRV record. 301 * - The `mTtl` specifies the TTL if non-zero. If zero, the mDNS module will use the default TTL of 120 seconds. 302 * - Other fields in @p aService structure are ignored in an `otMdnsRegisterService()` call. 303 * 304 * This function can be called again for the same `mServiceInstance` and `mServiceType` to update a previously 305 * registered service entry, for example, to change the sub-types list, or update any parameter such as port, weight, 306 * priority, TTL, or host name. The mDNS module will send announcements for any changed info, e.g., will send "goodbye" 307 * announcements for any removed sub-types and announce any newly added sub-types. 308 * 309 * Regarding the invocation of the @p aCallback, this function behaves in the same way as described in 310 * `otMdnsRegisterHost()`. 311 * 312 * @param[in] aInstance The OpenThread instance. 313 * @param[in] aService Information about the service to register. 314 * @param[in] aRequestId The ID associated with this request. 315 * @param[in] aCallback The callback function pointer to report the outcome (can be NULL if not needed). 316 * 317 * @retval OT_ERROR_NONE Successfully started registration. @p aCallback will report the outcome. 318 * @retval OT_ERROR_INVALID_STATE mDNS module is not enabled. 319 * 320 */ 321 otError otMdnsRegisterService(otInstance *aInstance, 322 const otMdnsService *aService, 323 otMdnsRequestId aRequestId, 324 otMdnsRegisterCallback aCallback); 325 326 /** 327 * Unregisters a service on mDNS module. 328 * 329 * The fields in @p aService follow these rules: 330 331 * - The `mServiceInstance` specifies the service instance label. It is treated as a single DNS name label. It may 332 * contain dot `.` character which is allowed in a service instance label. 333 * - The `mServiceType` specifies the service type (e.g., "_tst._udp"). It is treated as multiple dot `.` separated 334 * labels. It MUST NOT contain the domain name. 335 * - Other fields in @p aService structure are ignored in an `otMdnsUnregisterService()` call. 336 * 337 * If there is no previously registered service with the same name, no action is performed. 338 * 339 * If there is a previously registered service with the same name, the mDNS module will send "goodbye" announcements 340 * for all related records. 341 * 342 * @param[in] aInstance The OpenThread instance. 343 * @param[in] aService Information about the service to unregister. 344 * 345 * @retval OT_ERROR_NONE Successfully unregistered service. 346 * @retval OT_ERROR_INVALID_STATE mDNS module is not enabled. 347 * 348 */ 349 otError otMdnsUnregisterService(otInstance *aInstance, const otMdnsService *aService); 350 351 /** 352 * Registers or updates a key record on mDNS module. 353 * 354 * The fields in @p aKey follow these rules: 355 * 356 * - If the key is associated with a host entry, the `mName` field specifies the host name and the `mServiceType` MUST 357 * be NULL. 358 * - If the key is associated with a service entry, the `mName` filed specifies the service instance label (always 359 * treated as a single label) and the `mServiceType` filed specifies the service type (e.g., "_tst._udp"). In this 360 * case the DNS name for key record is `<mName>.<mServiceTye>`. 361 * - The `mKeyData` field contains the key record's data with `mKeyDataLength` as its length in byes. 362 * - The `mTtl` specifies the TTL if non-zero. If zero, the mDNS module will use the default TTL of 120 seconds. 363 * - Other fields in @p aKey structure are ignored in an `otMdnsRegisterKey()` call. 364 * 365 * This function can be called again for the same name to updated a previously registered key entry, for example, to 366 * change the key data or TTL. 367 * 368 * Regarding the invocation of the @p aCallback, this function behaves in the same way as described in 369 * `otMdnsRegisterHost()`. 370 * 371 * @param[in] aInstance The OpenThread instance. 372 * @param[in] aKey Information about the key record to register. 373 * @param[in] aRequestId The ID associated with this request. 374 * @param[in] aCallback The callback function pointer to report the outcome (can be NULL if not needed). 375 * 376 * @retval OT_ERROR_NONE Successfully started registration. @p aCallback will report the outcome. 377 * @retval OT_ERROR_INVALID_STATE mDNS module is not enabled. 378 * 379 */ 380 otError otMdnsRegisterKey(otInstance *aInstance, 381 const otMdnsKey *aKey, 382 otMdnsRequestId aRequestId, 383 otMdnsRegisterCallback aCallback); 384 385 /** 386 * Unregisters a key record on mDNS. 387 * 388 * The fields in @p aKey follow these rules: 389 * 390 * - If the key is associated with a host entry, the `mName` field specifies the host name and the `mServiceType` MUST 391 * be NULL. 392 * - If the key is associated with a service entry, the `mName` filed specifies the service instance label (always 393 * treated as a single label) and the `mServiceType` filed specifies the service type (e.g., "_tst._udp"). In this 394 * case the DNS name for key record is `<mName>.<mServiceTye>`. 395 * - Other fields in @p aKey structure are ignored in an `otMdnsUnregisterKey()` call. 396 * 397 * If there is no previously registered key with the same name, no action is performed. 398 * 399 * If there is a previously registered key with the same name, the mDNS module will send "goodbye" announcements for 400 * the key record. 401 * 402 * @param[in] aInstance The OpenThread instance. 403 * @param[in] aKey Information about the key to unregister. 404 * 405 * @retval OT_ERROR_NONE Successfully unregistered key 406 * @retval OT_ERROR_INVALID_STATE mDNS module is not enabled. 407 * 408 */ 409 otError otMdnsUnregisterKey(otInstance *aInstance, const otMdnsKey *aKey); 410 411 /** 412 * Allocates a new iterator. 413 * 414 * Requires `OPENTHREAD_CONFIG_MULTICAST_DNS_ENTRY_ITERATION_API_ENABLE`. 415 * 416 * An allocated iterator must be freed by the caller using `otMdnsFreeIterator()`. 417 * 418 * @param[in] aInstance The OpenThread instance. 419 * 420 * @returns A pointer to the allocated iterator, or `NULL` if it fails to allocate. 421 * 422 */ 423 otMdnsIterator *otMdnsAllocateIterator(otInstance *aInstance); 424 425 /** 426 * Frees a previously allocated iterator. 427 * 428 * Requires `OPENTHREAD_CONFIG_MULTICAST_DNS_ENTRY_ITERATION_API_ENABLE`. 429 * 430 * @param[in] aInstance The OpenThread instance. 431 * @param[in] aIterator The iterator to free. 432 * 433 */ 434 void otMdnsFreeIterator(otInstance *aInstance, otMdnsIterator *aIterator); 435 436 /** 437 * Iterates over registered host entries. 438 * 439 * Requires `OPENTHREAD_CONFIG_MULTICAST_DNS_ENTRY_ITERATION_API_ENABLE`. 440 * 441 * On success, @p aHost is populated with information about the next host. Pointers within the `otMdnsHost` structure 442 * (like `mName`) remain valid until the next call to any OpenThread stack's public or platform API/callback. 443 * 444 * @param[in] aInstance The OpenThread instance. 445 * @param[in] aIterator Pointer to the iterator. 446 * @param[out] aHost Pointer to an `otMdnsHost` to return the information about the next host entry. 447 * @param[out] aState Pointer to an `otMdnsEntryState` to return the entry state. 448 * 449 * @retval OT_ERROR_NONE @p aHost, @p aState, & @p aIterator are updated successfully. 450 * @retval OT_ERROR_NOT_FOUND Reached the end of the list. 451 * @retval OT_ERROR_INVALID_ARG @p aIterator is not valid. 452 * 453 */ 454 otError otMdnsGetNextHost(otInstance *aInstance, 455 otMdnsIterator *aIterator, 456 otMdnsHost *aHost, 457 otMdnsEntryState *aState); 458 459 /** 460 * Iterates over registered service entries. 461 * 462 * Requires `OPENTHREAD_CONFIG_MULTICAST_DNS_ENTRY_ITERATION_API_ENABLE`. 463 * 464 * On success, @p aService is populated with information about the next service . Pointers within the `otMdnsService` 465 * structure (like `mServiceType`, `mSubTypeLabels`) remain valid until the next call to any OpenThread stack's public 466 * or platform API/callback. 467 * 468 * @param[in] aInstance The OpenThread instance. 469 * @param[in] aIterator Pointer to the iterator to use. 470 * @param[out] aService Pointer to an `otMdnsService` to return the information about the next service entry. 471 * @param[out] aState Pointer to an `otMdnsEntryState` to return the entry state. 472 * 473 * @retval OT_ERROR_NONE @p aService, @p aState, & @p aIterator are updated successfully. 474 * @retval OT_ERROR_NOT_FOUND Reached the end of the list. 475 * @retval OT_ERROR_INVALID_ARG @p aIterator is not valid. 476 * 477 */ 478 otError otMdnsGetNextService(otInstance *aInstance, 479 otMdnsIterator *aIterator, 480 otMdnsService *aService, 481 otMdnsEntryState *aState); 482 483 /** 484 * Iterates over registered key entries. 485 * 486 * Requires `OPENTHREAD_CONFIG_MULTICAST_DNS_ENTRY_ITERATION_API_ENABLE`. 487 * 488 * On success, @p aKey is populated with information about the next key. Pointers within the `otMdnsKey` structure 489 * (like `mName`) remain valid until the next call to any OpenThread stack's public or platform API/callback. 490 * 491 * @param[in] aInstance The OpenThread instance. 492 * @param[in] aIterator Pointer to the iterator to use. 493 * @param[out] aKey Pointer to an `otMdnsKey` to return the information about the next key entry. 494 * @param[out] aState Pointer to an `otMdnsEntryState` to return the entry state. 495 * 496 * @retval OT_ERROR_NONE @p aKey, @p aState, & @p aIterator are updated successfully. 497 * @retval OT_ERROR_NOT_FOUND Reached the end of the list. 498 * @retval OT_ERROR_INVALID_ARG Iterator is not valid. 499 * 500 */ 501 otError otMdnsGetNextKey(otInstance *aInstance, otMdnsIterator *aIterator, otMdnsKey *aKey, otMdnsEntryState *aState); 502 503 /** 504 * Represents a service browser. 505 * 506 * Refer to `otPlatDnssdBrowser` for documentation of member fields and `otMdnsStartBrowser()` for how they are used. 507 * 508 */ 509 typedef otPlatDnssdBrowser otMdnsBrowser; 510 511 /** 512 * Represents the callback function pointer type used to report a browse result. 513 * 514 */ 515 typedef otPlatDnssdBrowseCallback otMdnsBrowseCallback; 516 517 /** 518 * Represents a browse result. 519 * 520 */ 521 typedef otPlatDnssdBrowseResult otMdnsBrowseResult; 522 523 /** 524 * Represents an SRV service resolver. 525 * 526 * Refer to `otPlatDnssdSrvResolver` for documentation of member fields and `otMdnsStartSrvResolver()` for how they are 527 * used. 528 * 529 */ 530 typedef otPlatDnssdSrvResolver otMdnsSrvResolver; 531 532 /** 533 * Represents the callback function pointer type used to report an SRV resolve result. 534 * 535 */ 536 typedef otPlatDnssdSrvCallback otMdnsSrvCallback; 537 538 /** 539 * Represents an SRV resolver result. 540 * 541 */ 542 typedef otPlatDnssdSrvResult otMdnsSrvResult; 543 544 /** 545 * Represents a TXT service resolver. 546 * 547 * Refer to `otPlatDnssdTxtResolver` for documentation of member fields and `otMdnsStartTxtResolver()` for how they are 548 * used. 549 * 550 */ 551 typedef otPlatDnssdTxtResolver otMdnsTxtResolver; 552 553 /** 554 * Represents the callback function pointer type used to report a TXT resolve result. 555 * 556 */ 557 typedef otPlatDnssdTxtCallback otMdnsTxtCallback; 558 559 /** 560 * Represents a TXT resolver result. 561 * 562 */ 563 typedef otPlatDnssdTxtResult otMdnsTxtResult; 564 565 /** 566 * Represents an address resolver. 567 * 568 * Refer to `otPlatDnssdAddressResolver` for documentation of member fields and `otMdnsStartIp6AddressResolver()` or 569 * `otMdnsStartIp4AddressResolver()` for how they are used. 570 * 571 */ 572 typedef otPlatDnssdAddressResolver otMdnsAddressResolver; 573 574 /** 575 * Represents the callback function pointer type use to report an IPv6/IPv4 address resolve result. 576 * 577 */ 578 typedef otPlatDnssdAddressCallback otMdnsAddressCallback; 579 580 /** 581 * Represents a discovered host address and its TTL. 582 * 583 */ 584 typedef otPlatDnssdAddressAndTtl otMdnsAddressAndTtl; 585 586 /** 587 * Represents address resolver result. 588 * 589 */ 590 typedef otPlatDnssdAddressResult otMdnsAddressResult; 591 592 /** 593 * Starts a service browser. 594 * 595 * Initiates a continuous search for the specified `mServiceType` in @p aBrowser. For sub-type services, use 596 * `mSubTypeLabel` to define the sub-type, for base services, set `mSubTypeLabel` to NULL. 597 * 598 * Discovered services are reported through the `mCallback` function in @p aBrowser. Services that have been removed 599 * are reported with a TTL value of zero. The callback may be invoked immediately with cached information (if available) 600 * and potentially before this function returns. When cached results are used, the reported TTL value will reflect 601 * the original TTL from the last received response. 602 * 603 * Multiple browsers can be started for the same service, provided they use different callback functions. 604 * 605 * @param[in] aInstance The OpenThread instance. 606 * @param[in] aBrowser The browser to be started. 607 * 608 * @retval OT_ERROR_NONE Browser started successfully. 609 * @retval OT_ERROR_INVALID_STATE mDNS module is not enabled. 610 * @retval OT_ERROR_ALREADY An identical browser (same service and callback) is already active. 611 * 612 */ 613 otError otMdnsStartBrowser(otInstance *aInstance, const otMdnsBrowser *aBrowser); 614 615 /** 616 * Stops a service browser. 617 * 618 * No action is performed if no matching browser with the same service and callback is currently active. 619 * 620 * @param[in] aInstance The OpenThread instance. 621 * @param[in] aBrowser The browser to stop. 622 * 623 * @retval OT_ERROR_NONE Browser stopped successfully. 624 * @retval OT_ERROR_INVALID_STATE mDNS module is not enabled. 625 * 626 */ 627 otError otMdnsStopBrowser(otInstance *aInstance, const otMdnsBrowser *aBroswer); 628 629 /** 630 * Starts an SRV record resolver. 631 * 632 * Initiates a continuous SRV record resolver for the specified service in @p aResolver. 633 * 634 * Discovered information is reported through the `mCallback` function in @p aResolver. When the service is removed 635 * it is reported with a TTL value of zero. In this case, `mHostName` may be NULL and other result fields (such as 636 * `mPort`) should be ignored. 637 * 638 * The callback may be invoked immediately with cached information (if available) and potentially before this function 639 * returns. When cached result is used, the reported TTL value will reflect the original TTL from the last received 640 * response. 641 * 642 * Multiple resolvers can be started for the same service, provided they use different callback functions. 643 * 644 * @param[in] aInstance The OpenThread instance. 645 * @param[in] aResolver The resolver to be started. 646 * 647 * @retval OT_ERROR_NONE Resolver started successfully. 648 * @retval OT_ERROR_INVALID_STATE mDNS module is not enabled. 649 * @retval OT_ERROR_ALREADY An identical resolver (same service and callback) is already active. 650 * 651 */ 652 otError otMdnsStartSrvResolver(otInstance *aInstance, const otMdnsSrvResolver *aResolver); 653 654 /** 655 * Stops an SRV record resolver. 656 * 657 * No action is performed if no matching resolver with the same service and callback is currently active. 658 * 659 * @param[in] aInstance The OpenThread instance. 660 * @param[in] aResolver The resolver to stop. 661 * 662 * @retval OT_ERROR_NONE Resolver stopped successfully. 663 * @retval OT_ERROR_INVALID_STATE mDNS module is not enabled. 664 * 665 */ 666 otError otMdnsStopSrvResolver(otInstance *aInstance, const otMdnsSrvResolver *aResolver); 667 668 /** 669 * Starts a TXT record resolver. 670 * 671 * Initiates a continuous TXT record resolver for the specified service in @p aResolver. 672 * 673 * Discovered information is reported through the `mCallback` function in @p aResolver. When the TXT record is removed 674 * it is reported with a TTL value of zero. In this case, `mTxtData` may be NULL, and other result fields (such as 675 * `mTxtDataLength`) should be ignored. 676 * 677 * The callback may be invoked immediately with cached information (if available) and potentially before this function 678 * returns. When cached result is used, the reported TTL value will reflect the original TTL from the last received 679 * response. 680 * 681 * Multiple resolvers can be started for the same service, provided they use different callback functions. 682 * 683 * @param[in] aInstance The OpenThread instance. 684 * @param[in] aResolver The resolver to be started. 685 * 686 * @retval OT_ERROR_NONE Resolver started successfully. 687 * @retval OT_ERROR_INVALID_STATE mDNS module is not enabled. 688 * @retval OT_ERROR_ALREADY An identical resolver (same service and callback) is already active. 689 * 690 */ 691 otError otMdnsStartTxtResolver(otInstance *aInstance, const otMdnsTxtResolver *aResolver); 692 693 /** 694 * Stops a TXT record resolver. 695 * 696 * No action is performed if no matching resolver with the same service and callback is currently active. 697 * 698 * @param[in] aInstance The OpenThread instance. 699 * @param[in] aResolver The resolver to stop. 700 * 701 * @retval OT_ERROR_NONE Resolver stopped successfully. 702 * @retval OT_ERROR_INVALID_STATE mDNS module is not enabled. 703 * 704 */ 705 otError otMdnsStopTxtResolver(otInstance *aInstance, const otMdnsTxtResolver *aResolver); 706 707 /** 708 * Starts an IPv6 address resolver. 709 * 710 * Initiates a continuous IPv6 address resolver for the specified host name in @p aResolver. 711 * 712 * Discovered addresses are reported through the `mCallback` function in @p aResolver. The callback is invoked 713 * whenever addresses are added or removed, providing an updated list. If all addresses are removed, the callback is 714 * invoked with an empty list (`mAddresses` will be NULL, and `mAddressesLength` will be zero). 715 * 716 * The callback may be invoked immediately with cached information (if available) and potentially before this function 717 * returns. When cached result is used, the reported TTL values will reflect the original TTL from the last received 718 * response. 719 * 720 * Multiple resolvers can be started for the same host name, provided they use different callback functions. 721 * 722 * @param[in] aInstance The OpenThread instance. 723 * @param[in] aResolver The resolver to be started. 724 * 725 * @retval OT_ERROR_NONE Resolver started successfully. 726 * @retval OT_ERROR_INVALID_STATE mDNS module is not enabled. 727 * @retval OT_ERROR_ALREADY An identical resolver (same host and callback) is already active. 728 * 729 */ 730 otError otMdnsStartIp6AddressResolver(otInstance *aInstance, const otMdnsAddressResolver *aResolver); 731 732 /** 733 * Stops an IPv6 address resolver. 734 * 735 * No action is performed if no matching resolver with the same host name and callback is currently active. 736 * 737 * @param[in] aInstance The OpenThread instance. 738 * @param[in] aResolver The resolver to stop. 739 * 740 * @retval OT_ERROR_NONE Resolver stopped successfully. 741 * @retval OT_ERROR_INVALID_STATE mDNS module is not enabled. 742 * 743 */ 744 otError otMdnsStopIp6AddressResolver(otInstance *aInstance, const otMdnsAddressResolver *aResolver); 745 746 /** 747 * Starts an IPv4 address resolver. 748 * 749 * Initiates a continuous IPv4 address resolver for the specified host name in @p aResolver. 750 * 751 * Discovered addresses are reported through the `mCallback` function in @p aResolver. The IPv4 addresses are 752 * represented using the IPv4-mapped IPv6 address format in `mAddresses` array. The callback is invoked whenever 753 * addresses are added or removed, providing an updated list. If all addresses are removed, the callback is invoked 754 * with an empty list (`mAddresses` will be NULL, and `mAddressesLength` will be zero). 755 * 756 * The callback may be invoked immediately with cached information (if available) and potentially before this function 757 * returns. When cached result is used, the reported TTL values will reflect the original TTL from the last received 758 * response. 759 * 760 * Multiple resolvers can be started for the same host name, provided they use different callback functions. 761 * 762 * @param[in] aInstance The OpenThread instance. 763 * @param[in] aResolver The resolver to be started. 764 * 765 * @retval OT_ERROR_NONE Resolver started successfully. 766 * @retval OT_ERROR_INVALID_STATE mDNS module is not enabled. 767 * @retval OT_ERROR_ALREADY An identical resolver (same host and callback) is already active. 768 * 769 */ 770 otError otMdnsStartIp4AddressResolver(otInstance *aInstance, const otMdnsAddressResolver *aResolver); 771 772 /** 773 * Stops an IPv4 address resolver. 774 * 775 * No action is performed if no matching resolver with the same host name and callback is currently active. 776 * 777 * @param[in] aInstance The OpenThread instance. 778 * @param[in] aResolver The resolver to stop. 779 * 780 * @retval OT_ERROR_NONE Resolver stopped successfully. 781 * @retval OT_ERROR_INVALID_STATE mDNS module is not enabled. 782 * 783 */ 784 otError otMdnsStopIp4AddressResolver(otInstance *aInstance, const otMdnsAddressResolver *aResolver); 785 786 /** 787 * Represents additional information about a browser/resolver and its cached results. 788 * 789 */ 790 typedef struct otMdnsCacheInfo 791 { 792 bool mIsActive; ///< Whether this is an active browser/resolver vs an opportunistic cached one. 793 bool mHasCachedResults; ///< Whether there is any cached results. 794 } otMdnsCacheInfo; 795 796 /** 797 * Iterates over browsers. 798 * 799 * Requires `OPENTHREAD_CONFIG_MULTICAST_DNS_ENTRY_ITERATION_API_ENABLE`. 800 * 801 * On success, @p aBrowser is populated with information about the next browser. The `mCallback` field is always 802 * set to `NULL` as there may be multiple active browsers with different callbacks. Other pointers within the 803 * `otMdnsBrowser` structure remain valid until the next call to any OpenThread stack's public or platform API/callback. 804 * 805 * @param[in] aInstance The OpenThread instance. 806 * @param[in] aIterator Pointer to the iterator. 807 * @param[out] aBrowser Pointer to an `otMdnsBrowser` to return the information about the next browser. 808 * @param[out] aInfo Pointer to an `otMdnsCacheInfo` to return additional information. 809 * 810 * @retval OT_ERROR_NONE @p aBrowser, @p aInfo, & @p aIterator are updated successfully. 811 * @retval OT_ERROR_NOT_FOUND Reached the end of the list. 812 * @retval OT_ERROR_INVALID_ARG @p aIterator is not valid. 813 * 814 */ 815 otError otMdnsGetNextBrowser(otInstance *aInstance, 816 otMdnsIterator *aIterator, 817 otMdnsBrowser *aBrowser, 818 otMdnsCacheInfo *aInfo); 819 820 /** 821 * Iterates over SRV resolvers. 822 * 823 * Requires `OPENTHREAD_CONFIG_MULTICAST_DNS_ENTRY_ITERATION_API_ENABLE`. 824 * 825 * On success, @p aResolver is populated with information about the next resolver. The `mCallback` field is always 826 * set to `NULL` as there may be multiple active resolvers with different callbacks. Other pointers within the 827 * `otMdnsSrvResolver` structure remain valid until the next call to any OpenThread stack's public or platform 828 * API/callback. 829 * 830 * @param[in] aInstance The OpenThread instance. 831 * @param[in] aIterator Pointer to the iterator. 832 * @param[out] aResolver Pointer to an `otMdnsSrvResolver` to return the information about the next resolver. 833 * @param[out] aInfo Pointer to an `otMdnsCacheInfo` to return additional information. 834 * 835 * @retval OT_ERROR_NONE @p aResolver, @p aInfo, & @p aIterator are updated successfully. 836 * @retval OT_ERROR_NOT_FOUND Reached the end of the list. 837 * @retval OT_ERROR_INVALID_ARG @p aIterator is not valid. 838 * 839 */ 840 otError otMdnsGetNextSrvResolver(otInstance *aInstance, 841 otMdnsIterator *aIterator, 842 otMdnsSrvResolver *aResolver, 843 otMdnsCacheInfo *aInfo); 844 845 /** 846 * Iterates over TXT resolvers. 847 * 848 * Requires `OPENTHREAD_CONFIG_MULTICAST_DNS_ENTRY_ITERATION_API_ENABLE`. 849 * 850 * On success, @p aResolver is populated with information about the next resolver. The `mCallback` field is always 851 * set to `NULL` as there may be multiple active resolvers with different callbacks. Other pointers within the 852 * `otMdnsTxtResolver` structure remain valid until the next call to any OpenThread stack's public or platform 853 * API/callback. 854 * 855 * @param[in] aInstance The OpenThread instance. 856 * @param[in] aIterator Pointer to the iterator. 857 * @param[out] aResolver Pointer to an `otMdnsTxtResolver` to return the information about the next resolver. 858 * @param[out] aInfo Pointer to an `otMdnsCacheInfo` to return additional information. 859 * 860 * @retval OT_ERROR_NONE @p aResolver, @p aInfo, & @p aIterator are updated successfully. 861 * @retval OT_ERROR_NOT_FOUND Reached the end of the list. 862 * @retval OT_ERROR_INVALID_ARG @p aIterator is not valid. 863 * 864 */ 865 otError otMdnsGetNextTxtResolver(otInstance *aInstance, 866 otMdnsIterator *aIterator, 867 otMdnsTxtResolver *aResolver, 868 otMdnsCacheInfo *aInfo); 869 870 /** 871 * Iterates over IPv6 address resolvers. 872 * 873 * Requires `OPENTHREAD_CONFIG_MULTICAST_DNS_ENTRY_ITERATION_API_ENABLE`. 874 * 875 * On success, @p aResolver is populated with information about the next resolver. The `mCallback` field is always 876 * set to `NULL` as there may be multiple active resolvers with different callbacks. Other pointers within the 877 * `otMdnsAddressResolver` structure remain valid until the next call to any OpenThread stack's public or platform 878 * API/callback. 879 * 880 * @param[in] aInstance The OpenThread instance. 881 * @param[in] aIterator Pointer to the iterator. 882 * @param[out] aResolver Pointer to an `otMdnsAddressResolver` to return the information about the next resolver. 883 * @param[out] aInfo Pointer to an `otMdnsCacheInfo` to return additional information. 884 * 885 * @retval OT_ERROR_NONE @p aResolver, @p aInfo, & @p aIterator are updated successfully. 886 * @retval OT_ERROR_NOT_FOUND Reached the end of the list. 887 * @retval OT_ERROR_INVALID_ARG @p aIterator is not valid. 888 * 889 */ 890 otError otMdnsGetNextIp6AddressResolver(otInstance *aInstance, 891 otMdnsIterator *aIterator, 892 otMdnsAddressResolver *aResolver, 893 otMdnsCacheInfo *aInfo); 894 895 /** 896 * Iterates over IPv4 address resolvers. 897 * 898 * Requires `OPENTHREAD_CONFIG_MULTICAST_DNS_ENTRY_ITERATION_API_ENABLE`. 899 * 900 * On success, @p aResolver is populated with information about the next resolver. The `mCallback` field is always 901 * set to `NULL` as there may be multiple active resolvers with different callbacks. Other pointers within the 902 * `otMdnsAddressResolver` structure remain valid until the next call to any OpenThread stack's public or platform 903 * API/callback. 904 * 905 * @param[in] aInstance The OpenThread instance. 906 * @param[in] aIterator Pointer to the iterator. 907 * @param[out] aResolver Pointer to an `otMdnsAddressResolver` to return the information about the next resolver. 908 * @param[out] aInfo Pointer to an `otMdnsCacheInfo` to return additional information. 909 * 910 * @retval OT_ERROR_NONE @p aResolver, @p aInfo, & @p aIterator are updated successfully. 911 * @retval OT_ERROR_NOT_FOUND Reached the end of the list. 912 * @retval OT_ERROR_INVALID_ARG @p aIterator is not valid. 913 * 914 */ 915 otError otMdnsGetNextIp4AddressResolver(otInstance *aInstance, 916 otMdnsIterator *aIterator, 917 otMdnsAddressResolver *aResolver, 918 otMdnsCacheInfo *aInfo); 919 920 /** 921 * @} 922 * 923 */ 924 925 #ifdef __cplusplus 926 } // extern "C" 927 #endif 928 929 #endif // OPENTHREAD_MULTICAST_DNS_H_ 930