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 * Represents the state of an 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 running. 142 OT_SRP_SERVER_STATE_STOPPED = 2, ///< The SRP server is 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 * @param[in] aInstance A pointer to an OpenThread instance. 306 * @param[in] aEnabled A boolean to enable/disable the SRP server. 307 * 308 */ 309 void otSrpServerSetEnabled(otInstance *aInstance, bool aEnabled); 310 311 /** 312 * This function returns SRP server TTL configuration. 313 * 314 * @param[in] aInstance A pointer to an OpenThread instance. 315 * @param[out] aTtlConfig A pointer to an `otSrpServerTtlConfig` instance. 316 * 317 */ 318 void otSrpServerGetTtlConfig(otInstance *aInstance, otSrpServerTtlConfig *aTtlConfig); 319 320 /** 321 * This function sets SRP server TTL configuration. 322 * 323 * The granted TTL will always be no greater than the max lease interval configured via `otSrpServerSetLeaseConfig()`, 324 * regardless of the minimum and maximum TTL configuration. 325 * 326 * @param[in] aInstance A pointer to an OpenThread instance. 327 * @param[in] aTtlConfig A pointer to an `otSrpServerTtlConfig` instance. 328 * 329 * @retval OT_ERROR_NONE Successfully set the TTL configuration. 330 * @retval OT_ERROR_INVALID_ARGS The TTL configuration is not valid. 331 * 332 */ 333 otError otSrpServerSetTtlConfig(otInstance *aInstance, const otSrpServerTtlConfig *aTtlConfig); 334 335 /** 336 * This function returns SRP server LEASE and KEY-LEASE configurations. 337 * 338 * @param[in] aInstance A pointer to an OpenThread instance. 339 * @param[out] aLeaseConfig A pointer to an `otSrpServerLeaseConfig` instance. 340 * 341 */ 342 void otSrpServerGetLeaseConfig(otInstance *aInstance, otSrpServerLeaseConfig *aLeaseConfig); 343 344 /** 345 * This function sets SRP server LEASE and KEY-LEASE configurations. 346 * 347 * When a non-zero LEASE time is requested from a client, the granted value will be 348 * limited in range [aMinLease, aMaxLease]; and a non-zero KEY-LEASE will be granted 349 * in range [aMinKeyLease, aMaxKeyLease]. For zero LEASE or KEY-LEASE time, zero will 350 * be granted. 351 * 352 * @param[in] aInstance A pointer to an OpenThread instance. 353 * @param[in] aLeaseConfig A pointer to an `otSrpServerLeaseConfig` instance. 354 * 355 * @retval OT_ERROR_NONE Successfully set the LEASE and KEY-LEASE ranges. 356 * @retval OT_ERROR_INVALID_ARGS The LEASE or KEY-LEASE range is not valid. 357 * 358 */ 359 otError otSrpServerSetLeaseConfig(otInstance *aInstance, const otSrpServerLeaseConfig *aLeaseConfig); 360 361 /** 362 * This function handles SRP service updates. 363 * 364 * This function is called by the SRP server to notify that a SRP host and possibly SRP services 365 * are being updated. It is important that the SRP updates are not committed until the handler 366 * returns the result by calling otSrpServerHandleServiceUpdateResult or times out after @p aTimeout. 367 * 368 * A SRP service observer should always call otSrpServerHandleServiceUpdateResult with error code 369 * OT_ERROR_NONE immediately after receiving the update events. 370 * 371 * A more generic handler may perform validations on the SRP host/services and rejects the SRP updates 372 * if any validation fails. For example, an Advertising Proxy should advertise (or remove) the host and 373 * services on a multicast-capable link and returns specific error code if any failure occurs. 374 * 375 * @param[in] aId The service update transaction ID. This ID must be passed back with 376 * `otSrpServerHandleServiceUpdateResult`. 377 * @param[in] aHost A pointer to the otSrpServerHost object which contains the SRP updates. The 378 * handler should publish/un-publish the host and each service points to this 379 * host with below rules: 380 * 1. If the host is not deleted (indicated by `otSrpServerHostIsDeleted`), 381 * then it should be published or updated with mDNS. Otherwise, the host 382 * should be un-published (remove AAAA RRs). 383 * 2. For each service points to this host, it must be un-published if the host 384 * is to be un-published. Otherwise, the handler should publish or update the 385 * service when it is not deleted (indicated by `otSrpServerServiceIsDeleted`) 386 * and un-publish it when deleted. 387 * @param[in] aTimeout The maximum time in milliseconds for the handler to process the service event. 388 * @param[in] aContext A pointer to application-specific context. 389 * 390 * @sa otSrpServerSetServiceUpdateHandler 391 * @sa otSrpServerHandleServiceUpdateResult 392 * 393 */ 394 typedef void (*otSrpServerServiceUpdateHandler)(otSrpServerServiceUpdateId aId, 395 const otSrpServerHost * aHost, 396 uint32_t aTimeout, 397 void * aContext); 398 399 /** 400 * This function sets the SRP service updates handler on SRP server. 401 * 402 * @param[in] aInstance A pointer to an OpenThread instance. 403 * @param[in] aServiceHandler A pointer to a service handler. Use NULL to remove the handler. 404 * @param[in] aContext A pointer to arbitrary context information. 405 * May be NULL if not used. 406 * 407 */ 408 void otSrpServerSetServiceUpdateHandler(otInstance * aInstance, 409 otSrpServerServiceUpdateHandler aServiceHandler, 410 void * aContext); 411 412 /** 413 * This function reports the result of processing a SRP update to the SRP server. 414 * 415 * The Service Update Handler should call this function to return the result of its 416 * processing of a SRP update. 417 * 418 * @param[in] aInstance A pointer to an OpenThread instance. 419 * @param[in] aId The service update transaction ID. This should be the same ID 420 * provided via `otSrpServerServiceUpdateHandler`. 421 * @param[in] aError An error to be returned to the SRP server. Use OT_ERROR_DUPLICATED 422 * to represent DNS name conflicts. 423 * 424 */ 425 void otSrpServerHandleServiceUpdateResult(otInstance *aInstance, otSrpServerServiceUpdateId aId, otError aError); 426 427 /** 428 * This function returns the next registered host on the SRP server. 429 * 430 * @param[in] aInstance A pointer to an OpenThread instance. 431 * @param[in] aHost A pointer to current host; use NULL to get the first host. 432 * 433 * @returns A pointer to the registered host. NULL, if no more hosts can be found. 434 * 435 */ 436 const otSrpServerHost *otSrpServerGetNextHost(otInstance *aInstance, const otSrpServerHost *aHost); 437 438 /** 439 * This function returns the response counters of the SRP server. 440 * 441 * @param[in] aInstance A pointer to an OpenThread instance. 442 * 443 * @returns A pointer to the response counters of the SRP server. 444 * 445 */ 446 const otSrpServerResponseCounters *otSrpServerGetResponseCounters(otInstance *aInstance); 447 448 /** 449 * This function tells if the SRP service host has been deleted. 450 * 451 * A SRP service host can be deleted but retains its name for future uses. 452 * In this case, the host instance is not removed from the SRP server/registry. 453 * 454 * @param[in] aHost A pointer to the SRP service host. 455 * 456 * @returns TRUE if the host has been deleted, FALSE if not. 457 * 458 */ 459 bool otSrpServerHostIsDeleted(const otSrpServerHost *aHost); 460 461 /** 462 * This function returns the full name of the host. 463 * 464 * @param[in] aHost A pointer to the SRP service host. 465 * 466 * @returns A pointer to the null-terminated host name string. 467 * 468 */ 469 const char *otSrpServerHostGetFullName(const otSrpServerHost *aHost); 470 471 /** 472 * This function returns the addresses of given host. 473 * 474 * @param[in] aHost A pointer to the SRP service host. 475 * @param[out] aAddressesNum A pointer to where we should output the number of the addresses to. 476 * 477 * @returns A pointer to the array of IPv6 Address. 478 * 479 */ 480 const otIp6Address *otSrpServerHostGetAddresses(const otSrpServerHost *aHost, uint8_t *aAddressesNum); 481 482 /** 483 * This function returns the LEASE and KEY-LEASE information of a given host. 484 * 485 * @param[in] aHost A pointer to the SRP server host. 486 * @param[out] aLeaseInfo A pointer to where to output the LEASE and KEY-LEASE information. 487 * 488 */ 489 void otSrpServerHostGetLeaseInfo(const otSrpServerHost *aHost, otSrpServerLeaseInfo *aLeaseInfo); 490 491 /** 492 * This function returns the next service (excluding any sub-type services) of given host. 493 * 494 * @note This function is being deprecated and will be removed. `otSrpServerHostFindNextService()` can be used 495 * instead. 496 * 497 * @param[in] aHost A pointer to the SRP service host. 498 * @param[in] aService A pointer to current SRP service instance; use NULL to get the first service. 499 * 500 * @returns A pointer to the next service or NULL if there is no more services. 501 * 502 */ 503 const otSrpServerService *otSrpServerHostGetNextService(const otSrpServerHost * aHost, 504 const otSrpServerService *aService); 505 506 /** 507 * This function finds the next matching service on the host. 508 * 509 * The combination of flags and service and instance names enables iterating over the full list of services and/or a 510 * subset of them matching certain conditions, or finding a specific service. 511 * 512 * To iterate over all services of a host: 513 * service = otSrpServerHostFindNextService(host, service, OT_SRP_SERVER_FLAGS_ANY_SERVICE, NULL, NULL); 514 * 515 * To iterate over base services only (exclude sub-types): 516 * service = otSrpServerHostFindNextService(host, service, OT_SRP_SERVER_FLAGS_BASE_TYPE_SERVICE_ONLY, NULL, NULL); 517 * 518 * To iterate over sub-types of a specific instance name `instanceName`: 519 * service = otSrpServerHostFindNextService(host, service, OT_SRP_SERVER_FLAGS_SUB_TYPE_SERVICE_ONLY, NULL, 520 * instanceName); 521 * 522 * To find a specific service with service name `serviceName` and service instance name `instanceName`: 523 * service = otSrpServerHostFindNextService(host, NULL, OT_SRP_SERVER_FLAGS_ANY_SERVICE, serviceName, instanceName); 524 * 525 * To find the base type service with a given service instance name `instanceName`: 526 * service = otSrpServerHostFindNextService(host, NULL, OT_SRP_SERVER_FLAGS_BASE_TYPE_SERVICE_ONLY, NULL, 527 * instanceName); 528 * 529 * @param[in] aHost A pointer to the SRP service host (MUST NOT be NULL). 530 * @param[in] aPrevService A pointer to the previous service or NULL to start from the beginning of the list. 531 * @param[in] aFlags Flags indicating which services to include (base/sub-type, active/deleted). 532 * @param[in] aServiceName The service name to match. Set to NULL to accept any name. 533 * @param[in] aInstanceName The service instance name to match. Set to NULL to accept any name. 534 * 535 * @returns A pointer to the next matching service or NULL if no matching service could be found. 536 * 537 */ 538 const otSrpServerService *otSrpServerHostFindNextService(const otSrpServerHost * aHost, 539 const otSrpServerService *aPrevService, 540 otSrpServerServiceFlags aFlags, 541 const char * aServiceName, 542 const char * aInstanceName); 543 544 /** 545 * This function indicates whether or not the SRP service has been deleted. 546 * 547 * A SRP service can be deleted but retains its name for future uses. 548 * In this case, the service instance is not removed from the SRP server/registry. 549 * It is guaranteed that all services are deleted if the host is deleted. 550 * 551 * @param[in] aService A pointer to the SRP service. 552 * 553 * @returns TRUE if the service has been deleted, FALSE if not. 554 * 555 */ 556 bool otSrpServerServiceIsDeleted(const otSrpServerService *aService); 557 558 /** 559 * This function indicates whether or not the SRP service is sub-type. 560 * 561 * @param[in] aService A pointer to the SRP service. 562 * 563 * @returns TRUE if the service is a sub-type, FALSE if not. 564 * 565 */ 566 bool otSrpServerServiceIsSubType(const otSrpServerService *aService); 567 568 /** 569 * This function returns the full service instance name of the service. 570 * 571 * @note This function is being deprecated and will be removed. `otSrpServerServiceGetInstanceName()` can be used 572 * instead. 573 * 574 * @param[in] aService A pointer to the SRP service. 575 * 576 * @returns A pointer to the null-terminated service instance name string. 577 * 578 */ 579 const char *otSrpServerServiceGetFullName(const otSrpServerService *aService); 580 581 /** 582 * This function returns the full service instance name of the service. 583 * 584 * @param[in] aService A pointer to the SRP service. 585 * 586 * @returns A pointer to the null-terminated service instance name string. 587 * 588 */ 589 const char *otSrpServerServiceGetInstanceName(const otSrpServerService *aService); 590 591 /** 592 * This function returns the full service name of the service. 593 * 594 * @param[in] aService A pointer to the SRP service. 595 * 596 * @returns A pointer to the null-terminated service name string. 597 * 598 */ 599 const char *otSrpServerServiceGetServiceName(const otSrpServerService *aService); 600 601 /** 602 * This function gets the sub-type label from service name. 603 * 604 * This function is intended to be used when the @p aService is a sub-type, i.e., `otSrpServerServiceIsSubType()` for 605 * the service returns TRUE. If it is not a sub-type this function returns `OT_ERROR_INVALID_ARGS`. 606 * 607 * The full service name for a sub-type service follows "<sub-label>._sub.<service-labels>.<domain>.". This function 608 * copies the `<sub-label>` into the @p aLabel buffer. 609 * 610 * The @p aLabel is ensured to always be null-terminated after returning even in case of failure. 611 * 612 * @param[in] aService A pointer to the SRP service. 613 * @param[out] aLabel A pointer to a buffer to copy the sub-type label name into. 614 * @param[in] aMaxSize Maximum size of @p aLabel buffer. 615 * 616 * @retval OT_ERROR_NONE @p aLabel was updated successfully. 617 * @retval OT_ERROR_NO_BUFS The sub-type label could not fit in @p aLabel buffer (number of chars from label 618 * that could fit are copied in @p aLabel ensuring it is null-terminated). 619 * @retval OT_ERROR_INVALID_ARGS SRP service is not a sub-type. 620 * 621 */ 622 otError otSrpServerServiceGetServiceSubTypeLabel(const otSrpServerService *aService, char *aLabel, uint8_t aMaxSize); 623 624 /** 625 * This function returns the port of the service instance. 626 * 627 * @param[in] aService A pointer to the SRP service. 628 * 629 * @returns The port of the service. 630 * 631 */ 632 uint16_t otSrpServerServiceGetPort(const otSrpServerService *aService); 633 634 /** 635 * This function returns the weight of the service instance. 636 * 637 * @param[in] aService A pointer to the SRP service. 638 * 639 * @returns The weight of the service. 640 * 641 */ 642 uint16_t otSrpServerServiceGetWeight(const otSrpServerService *aService); 643 644 /** 645 * This function returns the priority of the service instance. 646 * 647 * @param[in] aService A pointer to the SRP service. 648 * 649 * @returns The priority of the service. 650 * 651 */ 652 uint16_t otSrpServerServiceGetPriority(const otSrpServerService *aService); 653 654 /** 655 * This function returns the TTL of the service instance. 656 * 657 * @param[in] aService A pointer to the SRP service. 658 * 659 * @returns The TTL of the service instance.. 660 * 661 */ 662 uint32_t otSrpServerServiceGetTtl(const otSrpServerService *aService); 663 664 /** 665 * This function returns the TXT record data of the service instance. 666 * 667 * @param[in] aService A pointer to the SRP service. 668 * @param[out] aDataLength A pointer to return the TXT record data length. MUST NOT be NULL. 669 * 670 * @returns A pointer to the buffer containing the TXT record data (the TXT data length is returned in @p aDataLength). 671 * 672 */ 673 const uint8_t *otSrpServerServiceGetTxtData(const otSrpServerService *aService, uint16_t *aDataLength); 674 675 /** 676 * This function returns the host which the service instance reside on. 677 * 678 * @param[in] aService A pointer to the SRP service. 679 * 680 * @returns A pointer to the host instance. 681 * 682 */ 683 const otSrpServerHost *otSrpServerServiceGetHost(const otSrpServerService *aService); 684 685 /** 686 * This function returns the LEASE and KEY-LEASE information of a given service. 687 * 688 * @param[in] aService A pointer to the SRP server service. 689 * @param[out] aLeaseInfo A pointer to where to output the LEASE and KEY-LEASE information. 690 * 691 */ 692 void otSrpServerServiceGetLeaseInfo(const otSrpServerService *aService, otSrpServerLeaseInfo *aLeaseInfo); 693 /** 694 * @} 695 * 696 */ 697 698 #ifdef __cplusplus 699 } // extern "C" 700 #endif 701 702 #endif // OPENTHREAD_SRP_SERVER_H_ 703