1 /* 2 * Copyright (c) 2020, 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 defines the API for server of the Service Registration Protocol (SRP). 33 */ 34 35 #ifndef OPENTHREAD_SRP_SERVER_H_ 36 #define OPENTHREAD_SRP_SERVER_H_ 37 38 #include <stdint.h> 39 40 #include <openthread/dns.h> 41 #include <openthread/instance.h> 42 #include <openthread/ip6.h> 43 44 #ifdef __cplusplus 45 extern "C" { 46 #endif 47 48 /** 49 * @addtogroup api-srp 50 * 51 * @brief 52 * This module includes functions of the Service Registration Protocol. 53 * 54 * @{ 55 * 56 */ 57 58 /** 59 * This opaque type represents a SRP service host. 60 * 61 */ 62 typedef struct otSrpServerHost otSrpServerHost; 63 64 /** 65 * This opaque type represents a SRP service. 66 * 67 */ 68 typedef struct otSrpServerService otSrpServerService; 69 70 /** 71 * The ID of a SRP service update transaction on the SRP Server. 72 * 73 */ 74 typedef uint32_t otSrpServerServiceUpdateId; 75 76 /** 77 * The service flag type to indicate which services to include or exclude when searching in (or iterating over) the 78 * list of SRP services. 79 * 80 * This is a combination of bit-flags. The specific bit-flags are defined in the enumeration `OT_SRP_SERVER_FLAG_*`. 81 * 82 */ 83 typedef uint8_t otSrpServerServiceFlags; 84 85 enum 86 { 87 OT_SRP_SERVER_SERVICE_FLAG_BASE_TYPE = 1 << 0, ///< Include base services (not a sub-type). 88 OT_SRP_SERVER_SERVICE_FLAG_SUB_TYPE = 1 << 1, ///< Include sub-type services. 89 OT_SRP_SERVER_SERVICE_FLAG_ACTIVE = 1 << 2, ///< Include active (not deleted) services. 90 OT_SRP_SERVER_SERVICE_FLAG_DELETED = 1 << 3, ///< Include deleted services. 91 }; 92 93 enum 94 { 95 /** 96 * This constant defines an `otSrpServerServiceFlags` combination accepting any service (base/sub-type, 97 * active/deleted). 98 * 99 */ 100 OT_SRP_SERVER_FLAGS_ANY_SERVICE = (OT_SRP_SERVER_SERVICE_FLAG_BASE_TYPE | OT_SRP_SERVER_SERVICE_FLAG_SUB_TYPE | 101 OT_SRP_SERVER_SERVICE_FLAG_ACTIVE | OT_SRP_SERVER_SERVICE_FLAG_DELETED), 102 103 /** 104 * This constant defines an `otSrpServerServiceFlags` combination accepting base service only. 105 * 106 */ 107 OT_SRP_SERVER_FLAGS_BASE_TYPE_SERVICE_ONLY = 108 (OT_SRP_SERVER_SERVICE_FLAG_BASE_TYPE | OT_SRP_SERVER_SERVICE_FLAG_ACTIVE | OT_SRP_SERVER_SERVICE_FLAG_DELETED), 109 110 /** 111 * This constant defines an `otSrpServerServiceFlags` combination accepting sub-type service only. 112 * 113 */ 114 OT_SRP_SERVER_FLAGS_SUB_TYPE_SERVICE_ONLY = 115 (OT_SRP_SERVER_SERVICE_FLAG_SUB_TYPE | OT_SRP_SERVER_SERVICE_FLAG_ACTIVE | OT_SRP_SERVER_SERVICE_FLAG_DELETED), 116 117 /** 118 * This constant defines an `otSrpServerServiceFlags` combination accepting any active service (not deleted). 119 * 120 */ 121 OT_SRP_SERVER_FLAGS_ANY_TYPE_ACTIVE_SERVICE = 122 (OT_SRP_SERVER_SERVICE_FLAG_BASE_TYPE | OT_SRP_SERVER_SERVICE_FLAG_SUB_TYPE | 123 OT_SRP_SERVER_SERVICE_FLAG_ACTIVE), 124 125 /** 126 * This constant defines an `otSrpServerServiceFlags` combination accepting any deleted service. 127 * 128 */ 129 OT_SRP_SERVER_FLAGS_ANY_TYPE_DELETED_SERVICE = 130 (OT_SRP_SERVER_SERVICE_FLAG_BASE_TYPE | OT_SRP_SERVER_SERVICE_FLAG_SUB_TYPE | 131 OT_SRP_SERVER_SERVICE_FLAG_ACTIVE), 132 }; 133 134 /** 135 * This enumeration represents the state of the SRP server. 136 * 137 */ 138 typedef enum 139 { 140 OT_SRP_SERVER_STATE_DISABLED = 0, ///< The SRP server is disabled. 141 OT_SRP_SERVER_STATE_RUNNING = 1, ///< The SRP server is enabled and running. 142 OT_SRP_SERVER_STATE_STOPPED = 2, ///< The SRP server is enabled but stopped. 143 } otSrpServerState; 144 145 /** 146 * This enumeration represents the address mode used by the SRP server. 147 * 148 * Address mode specifies how the address and port number are determined by the SRP server and how this info is 149 * published in the Thread Network Data. 150 * 151 */ 152 typedef enum otSrpServerAddressMode 153 { 154 OT_SRP_SERVER_ADDRESS_MODE_UNICAST = 0, ///< Unicast address mode. 155 OT_SRP_SERVER_ADDRESS_MODE_ANYCAST = 1, ///< Anycast address mode. 156 } otSrpServerAddressMode; 157 158 /** 159 * This structure includes SRP server TTL configurations. 160 * 161 */ 162 typedef struct otSrpServerTtlConfig 163 { 164 uint32_t mMinTtl; ///< The minimum TTL in seconds. 165 uint32_t mMaxTtl; ///< The maximum TTL in seconds. 166 } otSrpServerTtlConfig; 167 168 /** 169 * This structure includes SRP server LEASE and KEY-LEASE configurations. 170 * 171 */ 172 typedef struct otSrpServerLeaseConfig 173 { 174 uint32_t mMinLease; ///< The minimum LEASE interval in seconds. 175 uint32_t mMaxLease; ///< The maximum LEASE interval in seconds. 176 uint32_t mMinKeyLease; ///< The minimum KEY-LEASE interval in seconds. 177 uint32_t mMaxKeyLease; ///< The maximum KEY-LEASE interval in seconds. 178 } otSrpServerLeaseConfig; 179 180 /** 181 * This structure includes SRP server lease information of a host/service. 182 * 183 */ 184 typedef struct otSrpServerLeaseInfo 185 { 186 uint32_t mLease; ///< The lease time of a host/service in milliseconds. 187 uint32_t mKeyLease; ///< The key lease time of a host/service in milliseconds. 188 uint32_t mRemainingLease; ///< The remaining lease time of the host/service in milliseconds. 189 uint32_t mRemainingKeyLease; ///< The remaining key lease time of a host/service in milliseconds. 190 } otSrpServerLeaseInfo; 191 192 /** 193 * This structure includes the statistics of SRP server responses. 194 * 195 */ 196 typedef struct otSrpServerResponseCounters 197 { 198 uint32_t mSuccess; ///< The number of successful responses. 199 uint32_t mServerFailure; ///< The number of server failure responses. 200 uint32_t mFormatError; ///< The number of format error responses. 201 uint32_t mNameExists; ///< The number of 'name exists' responses. 202 uint32_t mRefused; ///< The number of refused responses. 203 uint32_t mOther; ///< The number of other responses. 204 } otSrpServerResponseCounters; 205 206 /** 207 * This function returns the domain authorized to the SRP server. 208 * 209 * If the domain if not set by SetDomain, "default.service.arpa." will be returned. 210 * A trailing dot is always appended even if the domain is set without it. 211 * 212 * @param[in] aInstance A pointer to an OpenThread instance. 213 * 214 * @returns A pointer to the dot-joined domain string. 215 * 216 */ 217 const char *otSrpServerGetDomain(otInstance *aInstance); 218 219 /** 220 * This function sets the domain on the SRP server. 221 * 222 * A trailing dot will be appended to @p aDomain if it is not already there. 223 * This function should only be called before the SRP server is enabled. 224 * 225 * @param[in] aInstance A pointer to an OpenThread instance. 226 * @param[in] aDomain The domain to be set. MUST NOT be NULL. 227 * 228 * @retval OT_ERROR_NONE Successfully set the domain to @p aDomain. 229 * @retval OT_ERROR_INVALID_STATE The SRP server is already enabled and the Domain cannot be changed. 230 * @retval OT_ERROR_INVALID_ARGS The argument @p aDomain is not a valid DNS domain name. 231 * @retval OT_ERROR_NO_BUFS There is no memory to store content of @p aDomain. 232 * 233 */ 234 otError otSrpServerSetDomain(otInstance *aInstance, const char *aDomain); 235 236 /** 237 * This function returns the state of the SRP server. 238 * 239 * @param[in] aInstance A pointer to an OpenThread instance. 240 * 241 * @returns The current state of the SRP server. 242 * 243 */ 244 otSrpServerState otSrpServerGetState(otInstance *aInstance); 245 246 /** 247 * This function returns the port the SRP server is listening to. 248 * 249 * @param[in] aInstance A pointer to an OpenThread instance. 250 * 251 * @returns The port of the SRP server. It returns 0 if the server is not running. 252 * 253 */ 254 uint16_t otSrpServerGetPort(otInstance *aInstance); 255 256 /** 257 * This function returns the address mode being used by the SRP server. 258 * 259 * @param[in] aInstance A pointer to an OpenThread instance. 260 * 261 * @returns The SRP server's address mode. 262 * 263 */ 264 otSrpServerAddressMode otSrpServerGetAddressMode(otInstance *aInstance); 265 266 /** 267 * This function sets the address mode to be used by the SRP server. 268 * 269 * @param[in] aInstance A pointer to an OpenThread instance. 270 * @param[in] aMode The address mode to use. 271 * 272 * @retval OT_ERROR_NONE Successfully set the address mode. 273 * @retval OT_ERROR_INVALID_STATE The SRP server is enabled and the address mode cannot be changed. 274 * 275 */ 276 otError otSrpServerSetAddressMode(otInstance *aInstance, otSrpServerAddressMode aMode); 277 278 /** 279 * This function returns the sequence number used with anycast address mode. 280 * 281 * The sequence number is included in "DNS/SRP Service Anycast Address" entry published in the Network Data. 282 * 283 * @param[in] aInstance A pointer to an OpenThread instance. 284 * 285 * @returns The anycast sequence number. 286 * 287 */ 288 uint8_t otSrpServerGetAnycastModeSequenceNumber(otInstance *aInstance); 289 290 /** 291 * This function sets the sequence number used with anycast address mode. 292 * 293 * @param[in] aInstance A pointer to an OpenThread instance. 294 * @param[in] aSequenceNumber The sequence number to use. 295 * 296 * @retval OT_ERROR_NONE Successfully set the address mode. 297 * @retval OT_ERROR_INVALID_STATE The SRP server is enabled and the sequence number cannot be changed. 298 * 299 */ 300 otError otSrpServerSetAnycastModeSequenceNumber(otInstance *aInstance, uint8_t aSequenceNumber); 301 302 /** 303 * This function enables/disables the SRP server. 304 * 305 * On a Border Router, it is recommended to use `otSrpServerSetAutoEnableMode()` instead. 306 * 307 * @param[in] aInstance A pointer to an OpenThread instance. 308 * @param[in] aEnabled A boolean to enable/disable the SRP server. 309 * 310 */ 311 void otSrpServerSetEnabled(otInstance *aInstance, bool aEnabled); 312 313 /** 314 * This function enables/disables the auto-enable mode on SRP server. 315 * 316 * This function requires `OPENTHREAD_CONFIG_BORDER_ROUTING_ENABLE` feature. 317 * 318 * When this mode is enabled, the Border Routing Manager controls if/when to enable or disable the SRP server. 319 * SRP sever is auto-enabled if/when Border Routing is started and it is done with the initial prefix and route 320 * configurations (when the OMR and on-link prefixes are determined, advertised in emitted Router Advertisement message 321 * on infrastructure side and published in the Thread Network Data). The SRP server is auto-disabled if/when BR is 322 * stopped (e.g., if the infrastructure network interface is brought down or if BR gets detached). 323 * 324 * This mode can be disabled by a `otSrpServerSetAutoEnableMode()` call with @p aEnabled set to `false` or if the SRP 325 * server is explicitly enabled or disabled by a call to `otSrpServerSetEnabled()` function. Disabling auto-enable mode 326 * using `otSrpServerSetAutoEnableMode(false)` will not change the current state of SRP sever (e.g., if it is enabled 327 * it stays enabled). 328 * 329 * @param[in] aInstance A pointer to an OpenThread instance. 330 * @param[in] aEnabled A boolean to enable/disable the auto-enable mode. 331 * 332 */ 333 void otSrpServerSetAutoEnableMode(otInstance *aInstance, bool aEnabled); 334 335 /** 336 * This function indicates whether the auto-enable mode is enabled or disabled. 337 * 338 * This function requires `OPENTHREAD_CONFIG_BORDER_ROUTING_ENABLE` feature. 339 * 340 * @param[in] aInstance A pointer to an OpenThread instance. 341 * 342 * @retval TRUE The auto-enable mode is enabled. 343 * @retval FALSE The auto-enable mode is disabled. 344 * 345 */ 346 bool otSrpServerIsAutoEnableMode(otInstance *aInstance); 347 348 /** 349 * This function returns SRP server TTL configuration. 350 * 351 * @param[in] aInstance A pointer to an OpenThread instance. 352 * @param[out] aTtlConfig A pointer to an `otSrpServerTtlConfig` instance. 353 * 354 */ 355 void otSrpServerGetTtlConfig(otInstance *aInstance, otSrpServerTtlConfig *aTtlConfig); 356 357 /** 358 * This function sets SRP server TTL configuration. 359 * 360 * The granted TTL will always be no greater than the max lease interval configured via `otSrpServerSetLeaseConfig()`, 361 * regardless of the minimum and maximum TTL configuration. 362 * 363 * @param[in] aInstance A pointer to an OpenThread instance. 364 * @param[in] aTtlConfig A pointer to an `otSrpServerTtlConfig` instance. 365 * 366 * @retval OT_ERROR_NONE Successfully set the TTL configuration. 367 * @retval OT_ERROR_INVALID_ARGS The TTL configuration is not valid. 368 * 369 */ 370 otError otSrpServerSetTtlConfig(otInstance *aInstance, const otSrpServerTtlConfig *aTtlConfig); 371 372 /** 373 * This function returns SRP server LEASE and KEY-LEASE configurations. 374 * 375 * @param[in] aInstance A pointer to an OpenThread instance. 376 * @param[out] aLeaseConfig A pointer to an `otSrpServerLeaseConfig` instance. 377 * 378 */ 379 void otSrpServerGetLeaseConfig(otInstance *aInstance, otSrpServerLeaseConfig *aLeaseConfig); 380 381 /** 382 * This function sets SRP server LEASE and KEY-LEASE configurations. 383 * 384 * When a non-zero LEASE time is requested from a client, the granted value will be 385 * limited in range [aMinLease, aMaxLease]; and a non-zero KEY-LEASE will be granted 386 * in range [aMinKeyLease, aMaxKeyLease]. For zero LEASE or KEY-LEASE time, zero will 387 * be granted. 388 * 389 * @param[in] aInstance A pointer to an OpenThread instance. 390 * @param[in] aLeaseConfig A pointer to an `otSrpServerLeaseConfig` instance. 391 * 392 * @retval OT_ERROR_NONE Successfully set the LEASE and KEY-LEASE ranges. 393 * @retval OT_ERROR_INVALID_ARGS The LEASE or KEY-LEASE range is not valid. 394 * 395 */ 396 otError otSrpServerSetLeaseConfig(otInstance *aInstance, const otSrpServerLeaseConfig *aLeaseConfig); 397 398 /** 399 * This function handles SRP service updates. 400 * 401 * This function is called by the SRP server to notify that a SRP host and possibly SRP services 402 * are being updated. It is important that the SRP updates are not committed until the handler 403 * returns the result by calling otSrpServerHandleServiceUpdateResult or times out after @p aTimeout. 404 * 405 * A SRP service observer should always call otSrpServerHandleServiceUpdateResult with error code 406 * OT_ERROR_NONE immediately after receiving the update events. 407 * 408 * A more generic handler may perform validations on the SRP host/services and rejects the SRP updates 409 * if any validation fails. For example, an Advertising Proxy should advertise (or remove) the host and 410 * services on a multicast-capable link and returns specific error code if any failure occurs. 411 * 412 * @param[in] aId The service update transaction ID. This ID must be passed back with 413 * `otSrpServerHandleServiceUpdateResult`. 414 * @param[in] aHost A pointer to the otSrpServerHost object which contains the SRP updates. The 415 * handler should publish/un-publish the host and each service points to this 416 * host with below rules: 417 * 1. If the host is not deleted (indicated by `otSrpServerHostIsDeleted`), 418 * then it should be published or updated with mDNS. Otherwise, the host 419 * should be un-published (remove AAAA RRs). 420 * 2. For each service points to this host, it must be un-published if the host 421 * is to be un-published. Otherwise, the handler should publish or update the 422 * service when it is not deleted (indicated by `otSrpServerServiceIsDeleted`) 423 * and un-publish it when deleted. 424 * @param[in] aTimeout The maximum time in milliseconds for the handler to process the service event. 425 * @param[in] aContext A pointer to application-specific context. 426 * 427 * @sa otSrpServerSetServiceUpdateHandler 428 * @sa otSrpServerHandleServiceUpdateResult 429 * 430 */ 431 typedef void (*otSrpServerServiceUpdateHandler)(otSrpServerServiceUpdateId aId, 432 const otSrpServerHost *aHost, 433 uint32_t aTimeout, 434 void *aContext); 435 436 /** 437 * This function sets the SRP service updates handler on SRP server. 438 * 439 * @param[in] aInstance A pointer to an OpenThread instance. 440 * @param[in] aServiceHandler A pointer to a service handler. Use NULL to remove the handler. 441 * @param[in] aContext A pointer to arbitrary context information. 442 * May be NULL if not used. 443 * 444 */ 445 void otSrpServerSetServiceUpdateHandler(otInstance *aInstance, 446 otSrpServerServiceUpdateHandler aServiceHandler, 447 void *aContext); 448 449 /** 450 * This function reports the result of processing a SRP update to the SRP server. 451 * 452 * The Service Update Handler should call this function to return the result of its 453 * processing of a SRP update. 454 * 455 * @param[in] aInstance A pointer to an OpenThread instance. 456 * @param[in] aId The service update transaction ID. This should be the same ID 457 * provided via `otSrpServerServiceUpdateHandler`. 458 * @param[in] aError An error to be returned to the SRP server. Use OT_ERROR_DUPLICATED 459 * to represent DNS name conflicts. 460 * 461 */ 462 void otSrpServerHandleServiceUpdateResult(otInstance *aInstance, otSrpServerServiceUpdateId aId, otError aError); 463 464 /** 465 * This function returns the next registered host on the SRP server. 466 * 467 * @param[in] aInstance A pointer to an OpenThread instance. 468 * @param[in] aHost A pointer to current host; use NULL to get the first host. 469 * 470 * @returns A pointer to the registered host. NULL, if no more hosts can be found. 471 * 472 */ 473 const otSrpServerHost *otSrpServerGetNextHost(otInstance *aInstance, const otSrpServerHost *aHost); 474 475 /** 476 * This function returns the response counters of the SRP server. 477 * 478 * @param[in] aInstance A pointer to an OpenThread instance. 479 * 480 * @returns A pointer to the response counters of the SRP server. 481 * 482 */ 483 const otSrpServerResponseCounters *otSrpServerGetResponseCounters(otInstance *aInstance); 484 485 /** 486 * This function tells if the SRP service host has been deleted. 487 * 488 * A SRP service host can be deleted but retains its name for future uses. 489 * In this case, the host instance is not removed from the SRP server/registry. 490 * 491 * @param[in] aHost A pointer to the SRP service host. 492 * 493 * @returns TRUE if the host has been deleted, FALSE if not. 494 * 495 */ 496 bool otSrpServerHostIsDeleted(const otSrpServerHost *aHost); 497 498 /** 499 * This function returns the full name of the host. 500 * 501 * @param[in] aHost A pointer to the SRP service host. 502 * 503 * @returns A pointer to the null-terminated host name string. 504 * 505 */ 506 const char *otSrpServerHostGetFullName(const otSrpServerHost *aHost); 507 508 /** 509 * This function returns the addresses of given host. 510 * 511 * @param[in] aHost A pointer to the SRP service host. 512 * @param[out] aAddressesNum A pointer to where we should output the number of the addresses to. 513 * 514 * @returns A pointer to the array of IPv6 Address. 515 * 516 */ 517 const otIp6Address *otSrpServerHostGetAddresses(const otSrpServerHost *aHost, uint8_t *aAddressesNum); 518 519 /** 520 * This function returns the LEASE and KEY-LEASE information of a given host. 521 * 522 * @param[in] aHost A pointer to the SRP server host. 523 * @param[out] aLeaseInfo A pointer to where to output the LEASE and KEY-LEASE information. 524 * 525 */ 526 void otSrpServerHostGetLeaseInfo(const otSrpServerHost *aHost, otSrpServerLeaseInfo *aLeaseInfo); 527 528 /** 529 * This function returns the next service (excluding any sub-type services) of given host. 530 * 531 * @note This function is being deprecated and will be removed. `otSrpServerHostFindNextService()` can be used 532 * instead. 533 * 534 * @param[in] aHost A pointer to the SRP service host. 535 * @param[in] aService A pointer to current SRP service instance; use NULL to get the first service. 536 * 537 * @returns A pointer to the next service or NULL if there is no more services. 538 * 539 */ 540 const otSrpServerService *otSrpServerHostGetNextService(const otSrpServerHost *aHost, 541 const otSrpServerService *aService); 542 543 /** 544 * This function finds the next matching service on the host. 545 * 546 * The combination of flags and service and instance names enables iterating over the full list of services and/or a 547 * subset of them matching certain conditions, or finding a specific service. 548 * 549 * To iterate over all services of a host: 550 * service = otSrpServerHostFindNextService(host, service, OT_SRP_SERVER_FLAGS_ANY_SERVICE, NULL, NULL); 551 * 552 * To iterate over base services only (exclude sub-types): 553 * service = otSrpServerHostFindNextService(host, service, OT_SRP_SERVER_FLAGS_BASE_TYPE_SERVICE_ONLY, NULL, NULL); 554 * 555 * To iterate over sub-types of a specific instance name `instanceName`: 556 * service = otSrpServerHostFindNextService(host, service, OT_SRP_SERVER_FLAGS_SUB_TYPE_SERVICE_ONLY, NULL, 557 * instanceName); 558 * 559 * To find a specific service with service name `serviceName` and service instance name `instanceName`: 560 * service = otSrpServerHostFindNextService(host, NULL, OT_SRP_SERVER_FLAGS_ANY_SERVICE, serviceName, instanceName); 561 * 562 * To find the base type service with a given service instance name `instanceName`: 563 * service = otSrpServerHostFindNextService(host, NULL, OT_SRP_SERVER_FLAGS_BASE_TYPE_SERVICE_ONLY, NULL, 564 * instanceName); 565 * 566 * @param[in] aHost A pointer to the SRP service host (MUST NOT be NULL). 567 * @param[in] aPrevService A pointer to the previous service or NULL to start from the beginning of the list. 568 * @param[in] aFlags Flags indicating which services to include (base/sub-type, active/deleted). 569 * @param[in] aServiceName The service name to match. Set to NULL to accept any name. 570 * @param[in] aInstanceName The service instance name to match. Set to NULL to accept any name. 571 * 572 * @returns A pointer to the next matching service or NULL if no matching service could be found. 573 * 574 */ 575 const otSrpServerService *otSrpServerHostFindNextService(const otSrpServerHost *aHost, 576 const otSrpServerService *aPrevService, 577 otSrpServerServiceFlags aFlags, 578 const char *aServiceName, 579 const char *aInstanceName); 580 581 /** 582 * This function indicates whether or not the SRP service has been deleted. 583 * 584 * A SRP service can be deleted but retains its name for future uses. 585 * In this case, the service instance is not removed from the SRP server/registry. 586 * It is guaranteed that all services are deleted if the host is deleted. 587 * 588 * @param[in] aService A pointer to the SRP service. 589 * 590 * @returns TRUE if the service has been deleted, FALSE if not. 591 * 592 */ 593 bool otSrpServerServiceIsDeleted(const otSrpServerService *aService); 594 595 /** 596 * This function indicates whether or not the SRP service is sub-type. 597 * 598 * @param[in] aService A pointer to the SRP service. 599 * 600 * @returns TRUE if the service is a sub-type, FALSE if not. 601 * 602 */ 603 bool otSrpServerServiceIsSubType(const otSrpServerService *aService); 604 605 /** 606 * This function returns the full service instance name of the service. 607 * 608 * @note This function is being deprecated and will be removed. `otSrpServerServiceGetInstanceName()` can be used 609 * instead. 610 * 611 * @param[in] aService A pointer to the SRP service. 612 * 613 * @returns A pointer to the null-terminated service instance name string. 614 * 615 */ 616 const char *otSrpServerServiceGetFullName(const otSrpServerService *aService); 617 618 /** 619 * This function returns the full service instance name of the service. 620 * 621 * @param[in] aService A pointer to the SRP service. 622 * 623 * @returns A pointer to the null-terminated service instance name string. 624 * 625 */ 626 const char *otSrpServerServiceGetInstanceName(const otSrpServerService *aService); 627 628 /** 629 * This function returns the full service name of the service. 630 * 631 * @param[in] aService A pointer to the SRP service. 632 * 633 * @returns A pointer to the null-terminated service name string. 634 * 635 */ 636 const char *otSrpServerServiceGetServiceName(const otSrpServerService *aService); 637 638 /** 639 * This function gets the sub-type label from service name. 640 * 641 * This function is intended to be used when the @p aService is a sub-type, i.e., `otSrpServerServiceIsSubType()` for 642 * the service returns TRUE. If it is not a sub-type this function returns `OT_ERROR_INVALID_ARGS`. 643 * 644 * The full service name for a sub-type service follows "<sub-label>._sub.<service-labels>.<domain>.". This function 645 * copies the `<sub-label>` into the @p aLabel buffer. 646 * 647 * The @p aLabel is ensured to always be null-terminated after returning even in case of failure. 648 * 649 * @param[in] aService A pointer to the SRP service. 650 * @param[out] aLabel A pointer to a buffer to copy the sub-type label name into. 651 * @param[in] aMaxSize Maximum size of @p aLabel buffer. 652 * 653 * @retval OT_ERROR_NONE @p aLabel was updated successfully. 654 * @retval OT_ERROR_NO_BUFS The sub-type label could not fit in @p aLabel buffer (number of chars from label 655 * that could fit are copied in @p aLabel ensuring it is null-terminated). 656 * @retval OT_ERROR_INVALID_ARGS SRP service is not a sub-type. 657 * 658 */ 659 otError otSrpServerServiceGetServiceSubTypeLabel(const otSrpServerService *aService, char *aLabel, uint8_t aMaxSize); 660 661 /** 662 * This function returns the port of the service instance. 663 * 664 * @param[in] aService A pointer to the SRP service. 665 * 666 * @returns The port of the service. 667 * 668 */ 669 uint16_t otSrpServerServiceGetPort(const otSrpServerService *aService); 670 671 /** 672 * This function returns the weight of the service instance. 673 * 674 * @param[in] aService A pointer to the SRP service. 675 * 676 * @returns The weight of the service. 677 * 678 */ 679 uint16_t otSrpServerServiceGetWeight(const otSrpServerService *aService); 680 681 /** 682 * This function returns the priority of the service instance. 683 * 684 * @param[in] aService A pointer to the SRP service. 685 * 686 * @returns The priority of the service. 687 * 688 */ 689 uint16_t otSrpServerServiceGetPriority(const otSrpServerService *aService); 690 691 /** 692 * This function returns the TTL of the service instance. 693 * 694 * @param[in] aService A pointer to the SRP service. 695 * 696 * @returns The TTL of the service instance.. 697 * 698 */ 699 uint32_t otSrpServerServiceGetTtl(const otSrpServerService *aService); 700 701 /** 702 * This function returns the TXT record data of the service instance. 703 * 704 * @param[in] aService A pointer to the SRP service. 705 * @param[out] aDataLength A pointer to return the TXT record data length. MUST NOT be NULL. 706 * 707 * @returns A pointer to the buffer containing the TXT record data (the TXT data length is returned in @p aDataLength). 708 * 709 */ 710 const uint8_t *otSrpServerServiceGetTxtData(const otSrpServerService *aService, uint16_t *aDataLength); 711 712 /** 713 * This function returns the host which the service instance reside on. 714 * 715 * @param[in] aService A pointer to the SRP service. 716 * 717 * @returns A pointer to the host instance. 718 * 719 */ 720 const otSrpServerHost *otSrpServerServiceGetHost(const otSrpServerService *aService); 721 722 /** 723 * This function returns the LEASE and KEY-LEASE information of a given service. 724 * 725 * @param[in] aService A pointer to the SRP server service. 726 * @param[out] aLeaseInfo A pointer to where to output the LEASE and KEY-LEASE information. 727 * 728 */ 729 void otSrpServerServiceGetLeaseInfo(const otSrpServerService *aService, otSrpServerLeaseInfo *aLeaseInfo); 730 /** 731 * @} 732 * 733 */ 734 735 #ifdef __cplusplus 736 } // extern "C" 737 #endif 738 739 #endif // OPENTHREAD_SRP_SERVER_H_ 740
