1 /* 2 * Copyright (c) 2023, 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 platform abstraction for DNS-SD (e.g., mDNS) on the infrastructure network. 33 */ 34 35 #ifndef OPENTHREAD_PLATFORM_DNSSD_H_ 36 #define OPENTHREAD_PLATFORM_DNSSD_H_ 37 38 #include <stdint.h> 39 40 #include <openthread/dns.h> 41 #include <openthread/error.h> 42 #include <openthread/instance.h> 43 #include <openthread/ip6.h> 44 45 #ifdef __cplusplus 46 extern "C" { 47 #endif 48 49 /** 50 * @addtogroup plat-dns-sd 51 * 52 * @brief 53 * This module includes the platform abstraction for DNS-SD (e.g., mDNS) on the infrastructure network. 54 * 55 * @{ 56 * 57 * The DNS-SD platform APIs are used only when `OPENTHREAD_CONFIG_PLATFORM_DNSSD_ENABLE` is enabled. 58 */ 59 60 /** 61 * Represents the state of the DNS-SD platform. 62 */ 63 typedef enum otPlatDnssdState 64 { 65 OT_PLAT_DNSSD_STOPPED, ///< Stopped and unable to register any service or host, or start any browser/resolver. 66 OT_PLAT_DNSSD_READY, ///< Running and ready to register service or host. 67 } otPlatDnssdState; 68 69 /** 70 * Represents a request ID for registering/unregistering a service or host. 71 */ 72 typedef uint32_t otPlatDnssdRequestId; 73 74 /** 75 * Represents the callback function used when registering/unregistering a host or service. 76 * 77 * See `otPlatDnssdRegisterService()`, `otPlatDnssdUnregisterService()`, `otPlatDnssdRegisterHost()`, and 78 * `otPlatDnssdUnregisterHost()` for more details about when to invoke the callback and the `aError` values that can 79 * be returned in each case. 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 typedef void (*otPlatDnssdRegisterCallback)(otInstance *aInstance, otPlatDnssdRequestId aRequestId, otError aError); 86 87 /** 88 * Represents a DNS-SD service. 89 * 90 * See `otPlatDnssdRegisterService()`, `otPlatDnssdUnregisterService()` for more details about fields in each case. 91 */ 92 typedef struct otPlatDnssdService 93 { 94 const char *mHostName; ///< The host name (does not include domain name). 95 const char *mServiceInstance; ///< The service instance name label (not the full name). 96 const char *mServiceType; ///< The service type (e.g., "_mt._udp", does not include domain name). 97 const char *const *mSubTypeLabels; ///< Array of sub-type labels (can be NULL if no label). 98 uint16_t mSubTypeLabelsLength; ///< Length of array of sub-type labels. 99 const uint8_t *mTxtData; ///< Encoded TXT data bytes. 100 uint16_t mTxtDataLength; ///< Length of TXT data. 101 uint16_t mPort; ///< The service port number. 102 uint16_t mPriority; ///< The service priority. 103 uint16_t mWeight; ///< The service weight. 104 uint32_t mTtl; ///< The service TTL in seconds. 105 uint32_t mInfraIfIndex; ///< The infrastructure network interface index. 106 } otPlatDnssdService; 107 108 /** 109 * Represents a DNS-SD host. 110 * 111 * See `otPlatDnssdRegisterHost()`, `otPlatDnssdUnregisterHost()` for more details about fields in each case. 112 */ 113 typedef struct otPlatDnssdHost 114 { 115 const char *mHostName; ///< The host name (does not include domain name). 116 const otIp6Address *mAddresses; ///< Array of IPv6 host addresses. 117 uint16_t mAddressesLength; ///< Number of entries in @p mAddresses array. 118 uint32_t mTtl; ///< The host TTL in seconds. 119 uint32_t mInfraIfIndex; ///< The infrastructure network interface index. 120 } otPlatDnssdHost; 121 122 /** 123 * Represents a DNS-SD key record. 124 * 125 * See `otPlatDnssdRegisterKey()`, `otPlatDnssdUnregisterKey()` for more details about fields in each case. 126 */ 127 typedef struct otPlatDnssdKey 128 { 129 const char *mName; ///< A host or a service instance name (does not include domain name). 130 const char *mServiceType; ///< The service type if key is for a service (does not include domain name). 131 const uint8_t *mKeyData; ///< Byte array containing the key record data. 132 uint16_t mKeyDataLength; ///< Length of @p mKeyData in bytes. 133 uint16_t mClass; ///< The resource record class. 134 uint32_t mTtl; ///< The TTL in seconds. 135 uint32_t mInfraIfIndex; ///< The infrastructure network interface index. 136 } otPlatDnssdKey; 137 138 /** 139 * Callback to notify state changes of the DNS-SD platform. 140 * 141 * The OpenThread stack will call `otPlatDnssdGetState()` (from this callback or later) to get the new state. The 142 * platform MUST therefore ensure that the returned state from `otPlatDnssdGetState()` is updated before calling this. 143 * 144 * When the platform signals a state change to `OT_PLAT_DNSSD_STOPPED` using this callback, all active browsers and 145 * resolvers are considered to be stopped, and any previously registered host, service, key entries as removed. 146 * 147 * @param[in] aInstance The OpenThread instance structure. 148 */ 149 extern void otPlatDnssdStateHandleStateChange(otInstance *aInstance); 150 151 /** 152 * Gets the current state of the DNS-SD module. 153 * 154 * The platform MUST notify the OpenThread stack whenever its state gets changed by invoking 155 * `otPlatDnssdStateHandleStateChange()`. 156 * 157 * @param[in] aInstance The OpenThread instance. 158 * 159 * @returns The current state of the DNS-SD module. 160 */ 161 otPlatDnssdState otPlatDnssdGetState(otInstance *aInstance); 162 163 /** 164 * Registers or updates a service on the infrastructure network's DNS-SD module. 165 * 166 * The @p aService and all its contained information (strings and buffers) are only valid during this call. The 167 * platform MUST save a copy of the information if it wants to retain the information after returning from this 168 * function. 169 * 170 * The fields in @p aService follow these rules: 171 * 172 * - The `mServiceInstance` and `mServiceType` fields specify the service instance label and service type name, 173 * respectively. They are never NULL. 174 * - The `mHostName` field specifies the host name of the service if it is not NULL. Otherwise, if it is NULL, it 175 * indicates that this service is for the device itself and leaves the host name selection to DNS-SD platform. 176 * - The `mSubTypeLabels` is an array of strings representing sub-types associated with the service. It can be NULL 177 * if there are no sub-types. Otherwise, the array length is specified by `mSubTypeLabelsLength`. 178 * - The `mTxtData` and `mTxtDataLength` fields specify the encoded TXT data. 179 * - The `mPort`, `mWeight`, and `mPriority` fields specify the service's parameters (as specified in DNS SRV record). 180 * - The `mTtl` field specifies the TTL if non-zero. If zero, the platform can choose the TTL to use. 181 * - The `mInfraIfIndex` field, if non-zero, specifies the infrastructure network interface index to use for this 182 * request. If zero, the platform implementation can decided the interface. 183 * 184 * When the `mHostName` field in @p aService is not NULL (indicating that this registration is on behalf of another 185 * host), the OpenThread stack will ensure that `otPlatDnssdRegisterHost()` is also called for the same host before any 186 * service registration requests for the same host. 187 * 188 * Once the registration request is finished, either successfully or failed, the platform reports the outcome by 189 * invoking the @p aCallback and passing the same @p aRequestId in the callback. The @p aCallback function pointer can 190 * be NULL, which indicates that the OpenThread stack does not need to be notified of the outcome of the request. 191 * If the outcome is determined, the platform implementation may invoke the @p aCallback before returning from this 192 * function. The OpenThread stack will ensure to handle such a situation. 193 * 194 * On success, the @p aCallback MUST be called (if non-NULL) with `OT_ERROR_NONE` as the `aError` input parameter. If 195 * the registration causes a name conflict on DNS-SD domain (the service instance name is already claimed by another 196 * host), the `OT_ERROR_DUPLICATED` error MUST be used. The platform implementation can use other `OT_ERROR` types for 197 * other types of errors. 198 * 199 * The platform implementation MUST not assume that the @p aRequestId used in subsequent requests will be different. 200 * OpenThread may reuse the same request ID again for a different request. 201 * 202 * The OpenThread stack will not register the same service (with no changes) that was registered successfully earlier. 203 * Therefore, the platform implementation does not need to check for duplicate/same service and can assume that calls 204 * to this function are either registering a new entry or changing some parameter in a previously registered item. As 205 * a result, these changes always need to be synced on the infrastructure DNS-SD module. 206 * 207 * The OpenThread stack does not require the platform implementation to always invoke the @p aCallback function. 208 * The OpenThread stack has its own mechanism to time out an aged request with no response. This relaxes the 209 * requirement for platform implementations. 210 * 211 * @param[in] aInstance The OpenThread instance. 212 * @param[in] aService Information about the service to register. 213 * @param[in] aRequestId The ID associated with this request. 214 * @param[in] aCallback The callback function pointer to report the outcome (may be NULL if no callback needed). 215 */ 216 void otPlatDnssdRegisterService(otInstance *aInstance, 217 const otPlatDnssdService *aService, 218 otPlatDnssdRequestId aRequestId, 219 otPlatDnssdRegisterCallback aCallback); 220 221 /** 222 * Unregisters a service on the infrastructure network's DNS-SD module. 223 * 224 * The @p aService and all its contained information (strings and buffers) are only valid during this call. The 225 * platform MUST save a copy of the information if it wants to retain the information after returning from this 226 * function. 227 * 228 * The fields in @p aService follow these rules: 229 * 230 * - The `mServiceInstance` and `mServiceType` fields specify the service instance label and service type name, 231 * respectively. They are never NULL. 232 * - The `mHostName` field specifies the host name of the service if it is not NULL. Otherwise, if it is NULL, it 233 * indicates that this service is for the device itself and leaves the host name selection to DNS-SD platform. 234 * - The `mInfraIfIndex` field, if non-zero, specifies the infrastructure network interface index to use for this 235 * request. If zero, the platform implementation can decided the interface. 236 * - The rest of the fields in @p aService structure MUST be ignored in `otPlatDnssdUnregisterService()` call and may 237 * be set to zero by the OpenThread stack. 238 * 239 * Regarding the invocation of the @p aCallback and the reuse of the @p aRequestId, this function follows the same 240 * rules as described in `otPlatDnssdRegisterService()`. 241 * 242 * The OpenThread stack may request the unregistration of a service that was not previously registered, and the 243 * platform implementation MUST handle this case. In such a case, the platform can use either `OT_ERROR_NOT_FOUND` to 244 * indicate that there was no such registration, or `OT_ERROR_NONE` when invoking the @p aCallback function. The 245 * OpenThread stack will handle either case correctly. 246 * 247 * @param[in] aInstance The OpenThread instance. 248 * @param[in] aService Information about the service to unregister. 249 * @param[in] aRequestId The ID associated with this request. 250 * @param[in] aCallback The callback function pointer to report the outcome (may be NULL if no callback needed). 251 */ 252 void otPlatDnssdUnregisterService(otInstance *aInstance, 253 const otPlatDnssdService *aService, 254 otPlatDnssdRequestId aRequestId, 255 otPlatDnssdRegisterCallback aCallback); 256 257 /** 258 * Registers or updates a host on the infrastructure network's DNS-SD module. 259 * 260 * The @p aHost and all its contained information (strings and arrays) are only valid during this call. The 261 * platform MUST save a copy of the information if it wants to retain the information after returning from this 262 * function. 263 * 264 * The fields in @p aHost follow these rules: 265 * 266 * - The `mHostName` field specifies the host name to register. It is never NULL. 267 * - The `mAddresses` field is an array of IPv6 addresses to register with the host. `mAddressesLength` field provides 268 * the number of entries in `mAddresses` array. The platform implementation MUST not filter or remove any of 269 * addresses in the list. 270 * The OpenThread stack will already ensure that the given addresses are externally reachable. For example, when 271 * registering host from an SRP registration, link-local or mesh-local addresses associated with the host which are 272 * intended for use within Thread mesh are not included in `mAddresses` array passed to this API. The `mAddresses` 273 * array can be empty with zero `mAddressesLength`. In such a case, the platform MUST stop advertising any addresses 274 * for this host name on the infrastructure DNS-SD. 275 * - The `mTtl` field specifies the TTL if non-zero. If zero, the platform can choose the TTL to use. 276 * - The `mInfraIfIndex` field, if non-zero, specifies the infrastructure network interface index to use for this 277 * request. If zero, the platform implementation can decided the interface. 278 * 279 * Regarding the invocation of the @p aCallback and the reuse of the @p aRequestId, this function follows the same 280 * rules as described in `otPlatDnssdRegisterService()`. 281 * 282 * The OpenThread stack will not register the same host (with no changes) that was registered successfully earlier. 283 * Therefore, the platform implementation does not need to check for duplicate/same host and can assume that calls 284 * to this function are either registering a new entry or changing some parameter in a previously registered item. As 285 * a result, these changes always need to be synced on the infrastructure DNS-SD module. 286 * 287 * @param[in] aInstance The OpenThread instance. 288 * @param[in] aHost Information about the host to register. 289 * @param[in] aRequestId The ID associated with this request. 290 * @param[in] aCallback The callback function pointer to report the outcome (may be NULL if no callback needed). 291 */ 292 void otPlatDnssdRegisterHost(otInstance *aInstance, 293 const otPlatDnssdHost *aHost, 294 otPlatDnssdRequestId aRequestId, 295 otPlatDnssdRegisterCallback aCallback); 296 297 /** 298 * Unregisters a host on the infrastructure network's DNS-SD module. 299 * 300 * The @p aHost and all its contained information (strings and arrays) are only valid during this call. The 301 * platform MUST save a copy of the information if it wants to retain the information after returning from this 302 * function. 303 * 304 * The fields in @p aHost follow these rules: 305 * 306 * - The `mHostName` field specifies the host name to unregister. It is never NULL. 307 * - The `mInfraIfIndex` field, if non-zero, specifies the infrastructure network interface index to use for this 308 * request. If zero, the platform implementation can decided the interface. 309 * - The rest of the fields in @p aHost structure MUST be ignored in `otPlatDnssdUnregisterHost()` call and may 310 * be set to zero by the OpenThread stack. 311 * 312 * Regarding the invocation of the @p aCallback and the reuse of the @p aRequestId, this function follows the same 313 * rules as described in `otPlatDnssdRegisterService()`. 314 * 315 * The OpenThread stack may request the unregistration of a host that was not previously registered, and the platform 316 * implementation MUST handle this case. In such a case, the platform can use either `OT_ERROR_NOT_FOUND` to indicate 317 * that there was no such registration, or `OT_ERROR_NONE` when invoking the @p aCallback function. OpenThread stack 318 * will handle either case correctly. 319 * 320 * When unregistering a host, the OpenThread stack will also unregister any previously registered services 321 * associated with the same host (by calling `otPlatDnssdUnregisterService()`). However, the platform implementation 322 * MAY assume that unregistering a host also unregisters all its associated services. 323 * 324 * @param[in] aInstance The OpenThread instance. 325 * @param[in] aHost Information about the host to unregister. 326 * @param[in] aRequestId The ID associated with this request. 327 * @param[in] aCallback The callback function pointer to report the outcome (may be NULL if no callback needed). 328 */ 329 void otPlatDnssdUnregisterHost(otInstance *aInstance, 330 const otPlatDnssdHost *aHost, 331 otPlatDnssdRequestId aRequestId, 332 otPlatDnssdRegisterCallback aCallback); 333 334 /** 335 * Registers or updates a key record on the infrastructure network's DNS-SD module. 336 * 337 * The @p aKey and all its contained information (strings and arrays) are only valid during this call. The 338 * platform MUST save a copy of the information if it wants to retain the information after returning from this 339 * function. 340 * 341 * The fields in @p aKey follow these rules: 342 * 343 * - If the key is associated with a host, `mName` field specifies the host name and `mServiceType` will be NULL. 344 * - If the key is associated with a service, `mName` field specifies the service instance label and `mServiceType` 345 * field specifies the service type. In this case the DNS name for key record is `{mName}.{mServiceTye}`. 346 * - The `mKeyData` field contains the key record's data with `mKeyDataLength` as its length in byes. It is never NULL. 347 * - The `mClass` fields specifies the resource record class to use when registering key record. 348 * - The `mTtl` field specifies the TTL if non-zero. If zero, the platform can choose the TTL to use. 349 * - The `mInfraIfIndex` field, if non-zero, specifies the infrastructure network interface index to use for this 350 * request. If zero, the platform implementation can decided the interface. 351 * 352 * Regarding the invocation of the @p aCallback and the reuse of the @p aRequestId, this function follows the same 353 * rules as described in `otPlatDnssdRegisterService()`. 354 * 355 * The OpenThread stack will not register the same key (with no changes) that was registered successfully earlier. 356 * Therefore, the platform implementation does not need to check for duplicate/same name and can assume that calls 357 * to this function are either registering a new key or changing the key data in a previously registered one. As 358 * a result, these changes always need to be synced on the infrastructure DNS-SD module. 359 * 360 * @param[in] aInstance The OpenThread instance. 361 * @param[in] aKey Information about the key record to register. 362 * @param[in] aRequestId The ID associated with this request. 363 * @param[in] aCallback The callback function pointer to report the outcome (may be NULL if no callback needed). 364 */ 365 void otPlatDnssdRegisterKey(otInstance *aInstance, 366 const otPlatDnssdKey *aKey, 367 otPlatDnssdRequestId aRequestId, 368 otPlatDnssdRegisterCallback aCallback); 369 370 /** 371 * Unregisters a key record on the infrastructure network's DNS-SD module. 372 * 373 * The @p aKey and all its contained information (strings and arrays) are only valid during this call. The 374 * platform MUST save a copy of the information if it wants to retain the information after returning from this 375 * function. 376 * 377 * The fields in @p aKey follow these rules: 378 * 379 * - If the key is associated with a host, `mName` field specifies the host name and `mServiceType` will be NULL. 380 * - If the key is associated with a service, `mName` field specifies the service instance label and `mServiceType` 381 * field specifies the service type. In this case the DNS name for key record is `{mName}.{mServiceTye}`. 382 * - The `mInfraIfIndex` field, if non-zero, specifies the infrastructure network interface index to use for this 383 * request. If zero, the platform implementation can decided the interface. 384 * - The rest of the fields in @p aKey structure MUST be ignored in `otPlatDnssdUnregisterKey()` call and may 385 * be set to zero by the OpenThread stack. 386 * 387 * Regarding the invocation of the @p aCallback and the reuse of the @p aRequestId, this function follows the same 388 * rules as described in `otPlatDnssdRegisterService()`. 389 * 390 * The OpenThread stack may request the unregistration of a key that was not previously registered, and the platform 391 * implementation MUST handle this case. In such a case, the platform can use either `OT_ERROR_NOT_FOUND` to indicate 392 * that there was no such registration, or `OT_ERROR_NONE` when invoking the @p aCallback function. the OpenThread 393 * stack will handle either case correctly. 394 * 395 * @param[in] aInstance The OpenThread instance. 396 * @param[in] aKey Information about the key to unregister. 397 * @param[in] aRequestId The ID associated with this request. 398 * @param[in] aCallback The callback function pointer to report the outcome (may be NULL if no callback needed). 399 */ 400 void otPlatDnssdUnregisterKey(otInstance *aInstance, 401 const otPlatDnssdKey *aKey, 402 otPlatDnssdRequestId aRequestId, 403 otPlatDnssdRegisterCallback aCallback); 404 405 //====================================================================================================================== 406 407 /** 408 * Represents a browse result. 409 */ 410 typedef struct otPlatDnssdBrowseResult 411 { 412 const char *mServiceType; ///< The service type (e.g., "_mt._udp"). 413 const char *mSubTypeLabel; ///< The sub-type label if browsing for sub-type, NULL otherwise. 414 const char *mServiceInstance; ///< Service instance label. 415 uint32_t mTtl; ///< TTL in seconds. Zero TTL indicates that service is removed. 416 uint32_t mInfraIfIndex; ///< The infrastructure network interface index. 417 } otPlatDnssdBrowseResult; 418 419 /** 420 * Represents the callback function used to report a browse result. 421 * 422 * @param[in] aInstance The OpenThread instance. 423 * @param[in] aResult The browse result. 424 */ 425 typedef void (*otPlatDnssdBrowseCallback)(otInstance *aInstance, const otPlatDnssdBrowseResult *aResult); 426 427 /** 428 * Represents a service browser. 429 */ 430 typedef struct otPlatDnssdBrowser 431 { 432 const char *mServiceType; ///< The service type (e.g., "_mt._udp"). MUST NOT include domain name. 433 const char *mSubTypeLabel; ///< The sub-type label if browsing for sub-type, NULL otherwise. 434 uint32_t mInfraIfIndex; ///< The infrastructure network interface index. 435 otPlatDnssdBrowseCallback mCallback; ///< The callback to report result. 436 } otPlatDnssdBrowser; 437 438 /** 439 * Represents an SRV resolver result. 440 */ 441 typedef struct otPlatDnssdSrvResult 442 { 443 const char *mServiceInstance; ///< The service instance name label. 444 const char *mServiceType; ///< The service type. 445 const char *mHostName; ///< The host name (e.g., "myhost"). Can be NULL when `mTtl` is zero. 446 uint16_t mPort; ///< The service port number. 447 uint16_t mPriority; ///< The service priority. 448 uint16_t mWeight; ///< The service weight. 449 uint32_t mTtl; ///< The service TTL in seconds. Zero TTL indicates SRV record is removed. 450 uint32_t mInfraIfIndex; ///< The infrastructure network interface index. 451 } otPlatDnssdSrvResult; 452 453 /** 454 * Represents the callback function used to report an SRV resolve result. 455 * 456 * @param[in] aInstance The OpenThread instance. 457 * @param[in] aResult The SRV resolve result. 458 */ 459 typedef void (*otPlatDnssdSrvCallback)(otInstance *aInstance, const otPlatDnssdSrvResult *aResult); 460 461 /** 462 * Represents an SRV service resolver. 463 */ 464 typedef struct otPlatDnssdSrvResolver 465 { 466 const char *mServiceInstance; ///< The service instance label. 467 const char *mServiceType; ///< The service type. 468 uint32_t mInfraIfIndex; ///< The infrastructure network interface index. 469 otPlatDnssdSrvCallback mCallback; ///< The callback to report result. 470 } otPlatDnssdSrvResolver; 471 472 /** 473 * Represents a TXT resolver result. 474 */ 475 typedef struct otPlatDnssdTxtResult 476 { 477 const char *mServiceInstance; ///< The service instance name label. 478 const char *mServiceType; ///< The service type. 479 const uint8_t *mTxtData; ///< Encoded TXT data bytes. Can be NULL when `mTtl` is zero. 480 uint16_t mTxtDataLength; ///< Length of TXT data. 481 uint32_t mTtl; ///< The TXT data TTL in seconds. Zero TTL indicates record is removed. 482 uint32_t mInfraIfIndex; ///< The infrastructure network interface index. 483 } otPlatDnssdTxtResult; 484 485 /** 486 * Represents the callback function used to report a TXT resolve result. 487 * 488 * @param[in] aInstance The OpenThread instance. 489 * @param[in] aResult The TXT resolve result. 490 */ 491 typedef void (*otPlatDnssdTxtCallback)(otInstance *aInstance, const otPlatDnssdTxtResult *aResult); 492 493 /** 494 * Represents a TXT service resolver. 495 */ 496 typedef struct otPlatDnssdTxtResolver 497 { 498 const char *mServiceInstance; ///< Service instance label. 499 const char *mServiceType; ///< Service type. 500 uint32_t mInfraIfIndex; ///< The infrastructure network interface index. 501 otPlatDnssdTxtCallback mCallback; 502 } otPlatDnssdTxtResolver; 503 504 /** 505 * Represents a discovered host address and its TTL. 506 */ 507 typedef struct otPlatDnssdAddressAndTtl 508 { 509 otIp6Address mAddress; ///< The IPv6 address. For IPv4 address the IPv4-mapped IPv6 address format is used. 510 uint32_t mTtl; ///< The TTL in seconds. 511 } otPlatDnssdAddressAndTtl; 512 513 /** 514 * Represents address resolver result. 515 */ 516 typedef struct otPlatDnssdAddressResult 517 { 518 const char *mHostName; ///< The host name. 519 const otPlatDnssdAddressAndTtl *mAddresses; ///< Array of host addresses and their TTL. Can be NULL if empty. 520 uint16_t mAddressesLength; ///< Number of entries in `mAddresses` array. 521 uint32_t mInfraIfIndex; ///< The infrastructure network interface index. 522 } otPlatDnssdAddressResult; 523 524 /** 525 * Represents the callback function use to report a IPv6/IPv4 address resolve result. 526 * 527 * @param[in] aInstance The OpenThread instance. 528 * @param[in] aResult The address resolve result. 529 */ 530 typedef void (*otPlatDnssdAddressCallback)(otInstance *aInstance, const otPlatDnssdAddressResult *aResult); 531 532 /** 533 * Represents an address resolver. 534 */ 535 typedef struct otPlatDnssdAddressResolver 536 { 537 const char *mHostName; ///< The host name (e.g., "myhost"). MUST NOT contain domain name. 538 uint32_t mInfraIfIndex; ///< The infrastructure network interface index. 539 otPlatDnssdAddressCallback mCallback; ///< The callback to report result. 540 } otPlatDnssdAddressResolver; 541 542 /** 543 * Starts a service browser. 544 * 545 * Initiates a continuous search for the specified `mServiceType` in @p aBrowser. For sub-type services, 546 * `mSubTypeLabel` specifies the sub-type, for base services, `mSubTypeLabel` is set to NULL. 547 * 548 * Discovered services should be reported through the `mCallback` function in @p aBrowser. Services that have been 549 * removed are reported with a TTL value of zero. The callback may be invoked immediately with cached information 550 * (if available) and potentially before this function returns. When cached results are used, the reported TTL value 551 * should reflect the original TTL from the last received response. 552 * 553 * Multiple browsers can be started for the same service, provided they use different callback functions. 554 * 555 * The @p aBrowser and all its contained information (strings) are only valid during this call. The platform MUST save 556 * a copy of the information if it wants to retain the information after returning from this function. 557 * 558 * @param[in] aInstance The OpenThread instance. 559 * @param[in] aBrowser The browser to be started. 560 */ 561 void otPlatDnssdStartBrowser(otInstance *aInstance, const otPlatDnssdBrowser *aBrowser); 562 563 /** 564 * Stops a service browser. 565 * 566 * No action is performed if no matching browser with the same service and callback is currently active. 567 * 568 * The @p aBrowser and all its contained information (strings) are only valid during this call. The platform MUST save 569 * a copy of the information if it wants to retain the information after returning from this function. 570 * 571 * @param[in] aInstance The OpenThread instance. 572 * @param[in] aBrowser The browser to stop. 573 */ 574 void otPlatDnssdStopBrowser(otInstance *aInstance, const otPlatDnssdBrowser *aBrowser); 575 576 /** 577 * Starts an SRV record resolver. 578 * 579 * Initiates a continuous SRV record resolver for the specified service in @p aResolver. 580 * 581 * Discovered information should be reported through the `mCallback` function in @p aResolver. When the service is 582 * removed it is reported with a TTL value of zero. In this case, `mHostName` may be NULL and other result fields (such 583 * as `mPort`) will be ignored by the OpenThread stack. 584 * 585 * The callback may be invoked immediately with cached information (if available) and potentially before this function 586 * returns. When cached result is used, the reported TTL value should reflect the original TTL from the last received 587 * response. 588 * 589 * Multiple resolvers can be started for the same service, provided they use different callback functions. 590 * 591 * The @p aResolver and all its contained information (strings) are only valid during this call. The platform MUST save 592 * a copy of the information if it wants to retain the information after returning from this function. 593 * 594 * @param[in] aInstance The OpenThread instance. 595 * @param[in] aResolver The resolver to be started. 596 */ 597 void otPlatDnssdStartSrvResolver(otInstance *aInstance, const otPlatDnssdSrvResolver *aResolver); 598 599 /** 600 * Stops an SRV record resolver. 601 * 602 * No action is performed if no matching resolver with the same service and callback is currently active. 603 * 604 * The @p aResolver and all its contained information (strings) are only valid during this call. The platform MUST save 605 * a copy of the information if it wants to retain the information after returning from this function. 606 * 607 * @param[in] aInstance The OpenThread instance. 608 * @param[in] aResolver The resolver to stop. 609 */ 610 void otPlatDnssdStopSrvResolver(otInstance *aInstance, const otPlatDnssdSrvResolver *aResolver); 611 612 /** 613 * Starts a TXT record resolver. 614 * 615 * Initiates a continuous TXT record resolver for the specified service in @p aResolver. 616 * 617 * Discovered information should be reported through the `mCallback` function in @p aResolver. When the TXT record is 618 * removed it is reported with a TTL value of zero. In this case, `mTxtData` may be NULL, and other result fields 619 * (such as `mTxtDataLength`) will be ignored by the OpenThread stack. 620 * 621 * The callback may be invoked immediately with cached information (if available) and potentially before this function 622 * returns. When cached result is used, the reported TTL value should reflect the original TTL from the last received 623 * response. 624 * 625 * Multiple resolvers can be started for the same service, provided they use different callback functions. 626 * 627 * The @p aResolver and all its contained information (strings) are only valid during this call. The platform MUST save 628 * a copy of the information if it wants to retain the information after returning from this function. 629 * 630 * @param[in] aInstance The OpenThread instance. 631 * @param[in] aResolver The resolver to be started. 632 */ 633 void otPlatDnssdStartTxtResolver(otInstance *aInstance, const otPlatDnssdTxtResolver *aResolver); 634 635 /** 636 * Stops a TXT record resolver. 637 * 638 * No action is performed if no matching resolver with the same service and callback is currently active. 639 * 640 * The @p aResolver and all its contained information (strings) are only valid during this call. The platform MUST save 641 * a copy of the information if it wants to retain the information after returning from this function. 642 * 643 * @param[in] aInstance The OpenThread instance. 644 * @param[in] aResolver The resolver to stop. 645 */ 646 void otPlatDnssdStopTxtResolver(otInstance *aInstance, const otPlatDnssdTxtResolver *aResolver); 647 648 /** 649 * Starts an IPv6 address resolver. 650 * 651 * Initiates a continuous IPv6 address resolver for the specified host name in @p aResolver. 652 * 653 * Discovered addresses should be reported through the `mCallback` function in @p aResolver. The callback should be 654 * invoked whenever addresses are added or removed, providing an updated list. If all addresses are removed, the 655 * callback should be invoked with an empty list (`mAddressesLength` set to zero). 656 * 657 * The callback may be invoked immediately with cached information (if available) and potentially before this function 658 * returns. When cached result is used, the reported TTL values should reflect the original TTL from the last received 659 * response. 660 * 661 * Multiple resolvers can be started for the same host name, provided they use different callback functions. 662 * 663 * The @p aResolver and all its contained information (strings) are only valid during this call. The platform MUST save 664 * a copy of the information if it wants to retain the information after returning from this function. 665 * 666 * @param[in] aInstance The OpenThread instance. 667 * @param[in] aResolver The resolver to be started. 668 */ 669 void otPlatDnssdStartIp6AddressResolver(otInstance *aInstance, const otPlatDnssdAddressResolver *aResolver); 670 671 /** 672 * Stops an IPv6 address resolver. 673 * 674 * No action is performed if no matching resolver with the same host name and callback is currently active. 675 * 676 * The @p aResolver and all its contained information (strings) are only valid during this call. The platform MUST save 677 * a copy of the information if it wants to retain the information after returning from this function. 678 * 679 * @param[in] aInstance The OpenThread instance. 680 * @param[in] aResolver The resolver to stop. 681 */ 682 void otPlatDnssdStopIp6AddressResolver(otInstance *aInstance, const otPlatDnssdAddressResolver *aResolver); 683 684 /** 685 * Starts an IPv4 address resolver. 686 * 687 * Initiates a continuous IPv4 address resolver for the specified host name in @p aResolver. 688 * 689 * Discovered addresses should be reported through the `mCallback` function in @p aResolver. The IPv4 addresses are 690 * represented using the IPv4-mapped IPv6 address format in `mAddresses` array. The callback should be invoked 691 * whenever addresses are added or removed, providing an updated list. If all addresses are removed, the callback 692 * should be invoked with an empty list (`mAddressesLength` set to zero). 693 * 694 * The callback may be invoked immediately with cached information (if available) and potentially before this function 695 * returns. When cached result is used, the reported TTL values will reflect the original TTL from the last received 696 * response. 697 * 698 * Multiple resolvers can be started for the same host name, provided they use different callback functions. 699 * 700 * The @p aResolver and all its contained information (strings) are only valid during this call. The platform MUST save 701 * a copy of the information if it wants to retain the information after returning from this function. 702 * 703 * @param[in] aInstance The OpenThread instance. 704 * @param[in] aResolver The resolver to be started. 705 */ 706 void otPlatDnssdStartIp4AddressResolver(otInstance *aInstance, const otPlatDnssdAddressResolver *aResolver); 707 708 /** 709 * Stops an IPv4 address resolver. 710 * 711 * No action is performed if no matching resolver with the same host name and callback is currently active. 712 * 713 * The @p aResolver and all its contained information (strings) are only valid during this call. The platform MUST save 714 * a copy of the information if it wants to retain the information after returning from this function. 715 * 716 * @param[in] aInstance The OpenThread instance. 717 * @param[in] aResolver The resolver to stop. 718 */ 719 void otPlatDnssdStopIp4AddressResolver(otInstance *aInstance, const otPlatDnssdAddressResolver *aResolver); 720 721 /** 722 * @} 723 */ 724 725 #ifdef __cplusplus 726 } // extern "C" 727 #endif 728 729 #endif // OPENTHREAD_PLATFORM_DNSSD_H_ 730