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 OpenThread SRP (Service Registration Protocol) client APIs. 33 */ 34 35 #ifndef OPENTHREAD_SRP_CLIENT_H_ 36 #define OPENTHREAD_SRP_CLIENT_H_ 37 38 #include <openthread/dns.h> 39 #include <openthread/ip6.h> 40 41 #ifdef __cplusplus 42 extern "C" { 43 #endif 44 45 /** 46 * @addtogroup api-srp 47 * 48 * @brief 49 * This module includes functions that control SRP client behavior. 50 * 51 * @{ 52 * 53 */ 54 55 /** 56 * This enumeration specifies an SRP client item (service or host info) state. 57 * 58 */ 59 typedef enum 60 { 61 OT_SRP_CLIENT_ITEM_STATE_TO_ADD, ///< Item to be added/registered. 62 OT_SRP_CLIENT_ITEM_STATE_ADDING, ///< Item is being added/registered. 63 OT_SRP_CLIENT_ITEM_STATE_TO_REFRESH, ///< Item to be refreshed (re-register to renew lease). 64 OT_SRP_CLIENT_ITEM_STATE_REFRESHING, ///< Item is being refreshed. 65 OT_SRP_CLIENT_ITEM_STATE_TO_REMOVE, ///< Item to be removed. 66 OT_SRP_CLIENT_ITEM_STATE_REMOVING, ///< Item is being removed. 67 OT_SRP_CLIENT_ITEM_STATE_REGISTERED, ///< Item is registered with server. 68 OT_SRP_CLIENT_ITEM_STATE_REMOVED, ///< Item is removed. 69 } otSrpClientItemState; 70 71 /** 72 * This structure represents an SRP client host info. 73 * 74 */ 75 typedef struct otSrpClientHostInfo 76 { 77 const char * mName; ///< Host name (label) string (NULL if not yet set). 78 const otIp6Address * mAddresses; ///< Array of host IPv6 addresses (NULL if not set or auto address is enabled). 79 uint8_t mNumAddresses; ///< Number of IPv6 addresses in `mAddresses` array. 80 bool mAutoAddress; ///< Indicates whether auto address mode is enabled or not. 81 otSrpClientItemState mState; ///< Host info state. 82 } otSrpClientHostInfo; 83 84 /** 85 * This structure represents an SRP client service. 86 * 87 * The values in this structure, including the string buffers for the names and the TXT record entries, MUST persist 88 * and stay constant after an instance of this structure is passed to OpenThread from `otSrpClientAddService()` or 89 * `otSrpClientRemoveService()`. 90 * 91 */ 92 typedef struct otSrpClientService 93 { 94 const char * mName; ///< The service name labels (e.g., "_chip._udp", not the full domain name). 95 const char * mInstanceName; ///< The service instance name label (not the full name). 96 const char *const * mSubTypeLabels; ///< Array of service sub-type labels (must end with `NULL` or can be `NULL`). 97 const otDnsTxtEntry *mTxtEntries; ///< Array of TXT entries (number of entries is given by `mNumTxtEntries`). 98 uint16_t mPort; ///< The service port number. 99 uint16_t mPriority; ///< The service priority. 100 uint16_t mWeight; ///< The service weight. 101 uint8_t mNumTxtEntries; ///< Number of entries in the `mTxtEntries` array. 102 103 /** 104 * @note The following fields are used/managed by OT core only. Their values do not matter and are ignored when an 105 * instance of `otSrpClientService` is passed in `otSrpClientAddService()` or `otSrpClientRemoveService()`. The 106 * user should not modify these fields. 107 * 108 */ 109 110 otSrpClientItemState mState; ///< Service state (managed by OT core). 111 uint32_t mData; ///< Internal data (used by OT core). 112 struct otSrpClientService *mNext; ///< Pointer to next entry in a linked-list (managed by OT core). 113 } otSrpClientService; 114 115 /** 116 * This function pointer type defines the callback used by SRP client to notify user of changes/events/errors. 117 * 118 * This callback is invoked on a successful registration of an update (i.e., add/remove of host-info and/or some 119 * service(s)) with the SRP server, or if there is a failure or error (e.g., server rejects a update request or client 120 * times out waiting for response, etc). 121 * 122 * In case of a successful reregistration of an update, `aError` parameter would be `OT_ERROR_NONE` and the host info 123 * and the full list of services is provided as input parameters to the callback. Note that host info and services each 124 * track its own state in the corresponding `mState` member variable of the related data structure (the state 125 * indicating whether the host-info/service is registered or removed or still being added/removed, etc). 126 * 127 * The list of removed services is passed as its own linked-list `aRemovedServices` in the callback. Note that when the 128 * callback is invoked, the SRP client (OpenThread implementation) is done with the removed service instances listed in 129 * `aRemovedServices` and no longer tracks/stores them (i.e., if from the callback we call `otSrpClientGetServices()` 130 * the removed services will not be present in the returned list). Providing a separate list of removed services in 131 * the callback helps indicate to user which items are now removed and allow user to re-claim/reuse the instances. 132 * 133 * If the server rejects an SRP update request, the DNS response code (RFC 2136) is mapped to the following errors: 134 * 135 * - (0) NOERROR Success (no error condition) -> OT_ERROR_NONE 136 * - (1) FORMERR Server unable to interpret due to format error -> OT_ERROR_PARSE 137 * - (2) SERVFAIL Server encountered an internal failure -> OT_ERROR_FAILED 138 * - (3) NXDOMAIN Name that ought to exist, does not exist -> OT_ERROR_NOT_FOUND 139 * - (4) NOTIMP Server does not support the query type (OpCode) -> OT_ERROR_NOT_IMPLEMENTED 140 * - (5) REFUSED Server refused for policy/security reasons -> OT_ERROR_SECURITY 141 * - (6) YXDOMAIN Some name that ought not to exist, does exist -> OT_ERROR_DUPLICATED 142 * - (7) YXRRSET Some RRset that ought not to exist, does exist -> OT_ERROR_DUPLICATED 143 * - (8) NXRRSET Some RRset that ought to exist, does not exist -> OT_ERROR_NOT_FOUND 144 * - (9) NOTAUTH Service is not authoritative for zone -> OT_ERROR_SECURITY 145 * - (10) NOTZONE A name is not in the zone -> OT_ERROR_PARSE 146 * - (20) BADNAME Bad name -> OT_ERROR_PARSE 147 * - (21) BADALG Bad algorithm -> OT_ERROR_SECURITY 148 * - (22) BADTRUN Bad truncation -> OT_ERROR_PARSE 149 * - Other response codes -> OT_ERROR_FAILED 150 * 151 * The following errors are also possible: 152 * 153 * - OT_ERROR_RESPONSE_TIMEOUT : Timed out waiting for response from server (client would continue to retry). 154 * - OT_ERROR_INVALID_ARGS : The provided service structure is invalid (e.g., bad service name or `otDnsTxtEntry`). 155 * - OT_ERROR_NO_BUFS : Insufficient buffer to prepare or send the update message. 156 * 157 * Note that in case of any failure, the client continues the operation, i.e. it prepares and (re)transmits the SRP 158 * update message to the server, after some wait interval. The retry wait interval starts from the minimum value and 159 * is increased by the growth factor every failure up to the max value (please see configuration parameter 160 * `OPENTHREAD_CONFIG_SRP_CLIENT_MIN_RETRY_WAIT_INTERVAL` and the related ones for more details). 161 * 162 * @param[in] aError The error (see above). 163 * @param[in] aHostInfo A pointer to host info. 164 * @param[in] aServices The head of linked-list containing all services (excluding the ones removed). NULL if 165 * the list is empty. 166 * @param[in] aRemovedServices The head of linked-list containing all removed services. NULL if the list is empty. 167 * @param[in] aContext A pointer to an arbitrary context (provided when callback was registered). 168 * 169 */ 170 typedef void (*otSrpClientCallback)(otError aError, 171 const otSrpClientHostInfo *aHostInfo, 172 const otSrpClientService * aServices, 173 const otSrpClientService * aRemovedServices, 174 void * aContext); 175 176 /** 177 * This function pointer type defines the callback used by SRP client to notify user when it is auto-started or stopped. 178 * 179 * This is only used when auto-start feature `OPENTHREAD_CONFIG_SRP_CLIENT_AUTO_START_API_ENABLE` is enabled. 180 * 181 * This callback is invoked when auto-start mode is enabled and the SRP client is either automatically started or 182 * stopped. 183 * 184 * @param[in] aServerSockAddr A non-NULL pointer indicates SRP server was started and pointer will give the 185 * selected server socket address. A NULL pointer indicates SRP server was stopped. 186 * @param[in] aContext A pointer to an arbitrary context (provided when callback was registered). 187 * 188 */ 189 typedef void (*otSrpClientAutoStartCallback)(const otSockAddr *aServerSockAddr, void *aContext); 190 191 /** 192 * This function starts the SRP client operation. 193 * 194 * SRP client will prepare and send "SRP Update" message to the SRP server once all the following conditions are met: 195 * 196 * - The SRP client is started - `otSrpClientStart()` is called. 197 * - Host name is set - `otSrpClientSetHostName()` is called. 198 * - At least one host IPv6 address is set - `otSrpClientSetHostName()` is called. 199 * - At least one service is added - `otSrpClientAddService()` is called. 200 * 201 * It does not matter in which order these functions are called. When all conditions are met, the SRP client will 202 * wait for a short delay before preparing an "SRP Update" message and sending it to server. This delay allows for user 203 * to add multiple services and/or IPv6 addresses before the first SRP Update message is sent (ensuring a single SRP 204 * Update is sent containing all the info). The config `OPENTHREAD_CONFIG_SRP_CLIENT_UPDATE_TX_DELAY` specifies the 205 * delay interval. 206 * 207 * @param[in] aInstance A pointer to the OpenThread instance. 208 * @param[in] aServerSockAddr The socket address (IPv6 address and port number) of the SRP server. 209 * 210 * @retval OT_ERROR_NONE SRP client operation started successfully or it is already running with same server 211 * socket address and callback. 212 * @retval OT_ERROR_BUSY SRP client is busy running with a different socket address. 213 * @retval OT_ERROR_FAILED Failed to open/connect the client's UDP socket. 214 * 215 */ 216 otError otSrpClientStart(otInstance *aInstance, const otSockAddr *aServerSockAddr); 217 218 /** 219 * This function stops the SRP client operation. 220 * 221 * This function stops any further interactions with the SRP server. Note that it does not remove or clear host info 222 * and/or list of services. It marks all services to be added/removed again once the client is (re)started. 223 * 224 * @param[in] aInstance A pointer to the OpenThread instance. 225 * 226 */ 227 void otSrpClientStop(otInstance *aInstance); 228 229 /** 230 * This function indicates whether the SRP client is running or not. 231 * 232 * @param[in] aInstance A pointer to the OpenThread instance. 233 * 234 * @returns TRUE if the SRP client is running, FALSE otherwise. 235 * 236 */ 237 bool otSrpClientIsRunning(otInstance *aInstance); 238 239 /** 240 * This function gets the socket address (IPv6 address and port number) of the SRP server which is being used by SRP 241 * client. 242 * 243 * If the client is not running, the address is unspecified (all zero) with zero port number. 244 * 245 * @param[in] aInstance A pointer to the OpenThread instance. 246 * 247 * @returns A pointer to the SRP server's socket address (is always non-NULL). 248 * 249 */ 250 const otSockAddr *otSrpClientGetServerAddress(otInstance *aInstance); 251 252 /** 253 * This function sets the callback to notify caller of events/changes from SRP client. 254 * 255 * The SRP client allows a single callback to be registered. So consecutive calls to this function will overwrite any 256 * previously set callback functions. 257 * 258 * @param[in] aInstance A pointer to the OpenThread instance. 259 * @param[in] aCallback The callback to notify of events and changes. Can be NULL if not needed. 260 * @param[in] aContext An arbitrary context used with @p aCallback. 261 * 262 */ 263 void otSrpClientSetCallback(otInstance *aInstance, otSrpClientCallback aCallback, void *aContext); 264 265 /** 266 * This function enables the auto-start mode. 267 * 268 * This is only available when auto-start feature `OPENTHREAD_CONFIG_SRP_CLIENT_AUTO_START_API_ENABLE` is enabled. 269 * 270 * Config option `OPENTHREAD_CONFIG_SRP_CLIENT_AUTO_START_DEFAULT_MODE` specifies the default auto-start mode (whether 271 * it is enabled or disabled at the start of OT stack). 272 * 273 * When auto-start is enabled, the SRP client will monitor the Thread Network Data for SRP Server Service entries 274 * and automatically start and stop the client when an SRP server is detected. 275 * 276 * If multiple SRP servers are found, a random one will be selected. If the selected SRP server is no longer 277 * detected (not longer present in the Thread Network Data), the SRP client will be stopped and then it may switch 278 * to another SRP server (if available). 279 * 280 * When the SRP client is explicitly started through a successful call to `otSrpClientStart()`, the given SRP server 281 * address in `otSrpClientStart()` will continue to be used regardless of the state of auto-start mode and whether the 282 * same SRP server address is discovered or not in the Thread Network Data. In this case, only an explicit 283 * `otSrpClientStop()` call will stop the client. 284 * 285 * @param[in] aInstance A pointer to the OpenThread instance. 286 * @param[in] aCallback A callback to notify when client is auto-started/stopped. Can be NULL if not needed. 287 * @param[in] aContext A context to be passed when invoking @p aCallback. 288 * 289 */ 290 void otSrpClientEnableAutoStartMode(otInstance *aInstance, otSrpClientAutoStartCallback aCallback, void *aContext); 291 292 /** 293 * This function disables the auto-start mode. 294 * 295 * This is only available when auto-start feature `OPENTHREAD_CONFIG_SRP_CLIENT_AUTO_START_API_ENABLE` is enabled. 296 * 297 * Disabling the auto-start mode will not stop the client if it is already running but the client stops monitoring 298 * the Thread Network Data to verify that the selected SRP server is still present in it. 299 * 300 * Note that a call to `otSrpClientStop()` will also disable the auto-start mode. 301 * 302 * @param[in] aInstance A pointer to the OpenThread instance. 303 * 304 */ 305 void otSrpClientDisableAutoStartMode(otInstance *aInstance); 306 307 /** 308 * This function indicates the current state of auto-start mode (enabled or disabled). 309 * 310 * This is only available when auto-start feature `OPENTHREAD_CONFIG_SRP_CLIENT_AUTO_START_API_ENABLE` is enabled. 311 * 312 * @param[in] aInstance A pointer to the OpenThread instance. 313 * 314 * @returns TRUE if the auto-start mode is enabled, FALSE otherwise. 315 * 316 */ 317 bool otSrpClientIsAutoStartModeEnabled(otInstance *aInstance); 318 319 /** 320 * This function gets the TTL value in every record included in SRP update requests. 321 * 322 * Note that this is the TTL requested by the SRP client. The server may choose to accept a different TTL. 323 * 324 * By default, the TTL will equal the lease interval. Passing 0 or a value larger than the lease interval via 325 * `otSrpClientSetTtl()` will also cause the TTL to equal the lease interval. 326 * 327 * @param[in] aInstance A pointer to the OpenThread instance. 328 * 329 * @returns The TTL (in seconds). 330 * 331 */ 332 uint32_t otSrpClientGetTtl(otInstance *aInstance); 333 334 /** 335 * This function sets the TTL value in every record included in SRP update requests. 336 * 337 * Changing the TTL does not impact the TTL of already registered services/host-info. 338 * It only affects future SRP update messages (i.e., adding new services and/or refreshes of the existing services). 339 * 340 * @param[in] aInstance A pointer to the OpenThread instance. 341 * @param[in] aTtl The TTL (in seconds). If value is zero or greater than lease interval, the TTL is set to the 342 * lease interval. 343 * 344 */ 345 void otSrpClientSetTtl(otInstance *aInstance, uint32_t aTtl); 346 347 /** 348 * This function gets the lease interval used in SRP update requests. 349 * 350 * Note that this is the lease duration requested by the SRP client. The server may choose to accept a different lease 351 * interval. 352 * 353 * @param[in] aInstance A pointer to the OpenThread instance. 354 * 355 * @returns The lease interval (in seconds). 356 * 357 */ 358 uint32_t otSrpClientGetLeaseInterval(otInstance *aInstance); 359 360 /** 361 * This function sets the lease interval used in SRP update requests. 362 * 363 * Changing the lease interval does not impact the accepted lease interval of already registered services/host-info. 364 * It only affects any future SRP update messages (i.e., adding new services and/or refreshes of the existing services). 365 * 366 * @param[in] aInstance A pointer to the OpenThread instance. 367 * @param[in] aInterval The lease interval (in seconds). If zero, the default value specified by 368 * `OPENTHREAD_CONFIG_SRP_CLIENT_DEFAULT_LEASE` would be used. 369 * 370 */ 371 void otSrpClientSetLeaseInterval(otInstance *aInstance, uint32_t aInterval); 372 373 /** 374 * This function gets the key lease interval used in SRP update requests. 375 * 376 * Note that this is the lease duration requested by the SRP client. The server may choose to accept a different lease 377 * interval. 378 * 379 * @param[in] aInstance A pointer to the OpenThread instance. 380 * 381 * @returns The key lease interval (in seconds). 382 * 383 */ 384 uint32_t otSrpClientGetKeyLeaseInterval(otInstance *aInstance); 385 386 /** 387 * This function sets the key lease interval used in SRP update requests. 388 * 389 * Changing the lease interval does not impact the accepted lease interval of already registered services/host-info. 390 * It only affects any future SRP update messages (i.e., adding new services and/or refreshes of existing services). 391 * 392 * @param[in] aInstance A pointer to the OpenThread instance. 393 * @param[in] aInterval The key lease interval (in seconds). If zero, the default value specified by 394 * `OPENTHREAD_CONFIG_SRP_CLIENT_DEFAULT_KEY_LEASE` would be used. 395 * 396 */ 397 void otSrpClientSetKeyLeaseInterval(otInstance *aInstance, uint32_t aInterval); 398 399 /** 400 * This function gets the host info. 401 * 402 * @param[in] aInstance A pointer to the OpenThread instance. 403 * 404 * @returns A pointer to host info structure. 405 * 406 */ 407 const otSrpClientHostInfo *otSrpClientGetHostInfo(otInstance *aInstance); 408 409 /** 410 * This function sets the host name label. 411 * 412 * After a successful call to this function, `otSrpClientCallback` will be called to report the status of host info 413 * registration with SRP server. 414 * 415 * The name string buffer pointed to by @p aName MUST persist and stay unchanged after returning from this function. 416 * OpenThread will keep the pointer to the string. 417 * 418 * The host name can be set before client is started or after start but before host info is registered with server 419 * (host info should be in either `STATE_TO_ADD` or `STATE_REMOVED`). 420 * 421 * @param[in] aInstance A pointer to the OpenThread instance. 422 * @param[in] aName A pointer to host name label string (MUST NOT be NULL). Pointer to the string buffer MUST 423 * persist and remain valid and constant after return from this function. 424 * 425 * @retval OT_ERROR_NONE The host name label was set successfully. 426 * @retval OT_ERROR_INVALID_ARGS The @p aName is NULL. 427 * @retval OT_ERROR_INVALID_STATE The host name is already set and registered with the server. 428 * 429 */ 430 otError otSrpClientSetHostName(otInstance *aInstance, const char *aName); 431 432 /** 433 * This function enables auto host address mode. 434 * 435 * When enabled host IPv6 addresses are automatically set by SRP client using all the unicast addresses on Thread netif 436 * excluding all link-local and mesh-local addresses. If there is no valid address, then Mesh Local EID address is 437 * added. The SRP client will automatically re-register when/if addresses on Thread netif are updated (new addresses 438 * are added or existing addresses are removed). 439 * 440 * The auto host address mode can be enabled before start or during operation of SRP client except when the host info 441 * is being removed (client is busy handling a remove request from an call to `otSrpClientRemoveHostAndServices()` and 442 * host info still being in either `STATE_TO_REMOVE` or `STATE_REMOVING` states). 443 * 444 * After auto host address mode is enabled, it can be disabled by a call to `otSrpClientSetHostAddresses()` which 445 * then explicitly sets the host addresses. 446 * 447 * @retval OT_ERROR_NONE Successfully enabled auto host address mode. 448 * @retval OT_ERROR_INVALID_STATE Host is being removed and therefore cannot enable auto host address mode. 449 * 450 */ 451 otError otSrpClientEnableAutoHostAddress(otInstance *aInstance); 452 453 /** 454 * This function sets/updates the list of host IPv6 address. 455 * 456 * Host IPv6 addresses can be set/changed before start or during operation of SRP client (e.g. to add/remove or change 457 * a previously registered host address), except when the host info is being removed (client is busy handling a remove 458 * request from an earlier call to `otSrpClientRemoveHostAndServices()` and host info still being in either 459 * `STATE_TO_REMOVE` or `STATE_REMOVING` states). 460 * 461 * The host IPv6 address array pointed to by @p aIp6Addresses MUST persist and remain unchanged after returning from 462 * this function (with `OT_ERROR_NONE`). OpenThread will save the pointer to the array. 463 * 464 * After a successful call to this function, `otSrpClientCallback` will be called to report the status of the address 465 * registration with SRP server. 466 * 467 * Calling this function disables auto host address mode if it was previously enabled from a successful call to 468 * `otSrpClientEnableAutoHostAddress()`. 469 * 470 * @param[in] aInstance A pointer to the OpenThread instance. 471 * @param[in] aIp6Addresses A pointer to the an array containing the host IPv6 addresses. 472 * @param[in] aNumAddresses The number of addresses in the @p aIp6Addresses array. 473 * 474 * @retval OT_ERROR_NONE The host IPv6 address list change started successfully. The `otSrpClientCallback` 475 * will be called to report the status of registering addresses with server. 476 * @retval OT_ERROR_INVALID_ARGS The address list is invalid (e.g., must contain at least one address). 477 * @retval OT_ERROR_INVALID_STATE Host is being removed and therefore cannot change host address. 478 * 479 */ 480 otError otSrpClientSetHostAddresses(otInstance *aInstance, const otIp6Address *aIp6Addresses, uint8_t aNumAddresses); 481 482 /** 483 * This function adds a service to be registered with server. 484 * 485 * After a successful call to this function, `otSrpClientCallback` will be called to report the status of the service 486 * addition/registration with SRP server. 487 * 488 * The `otSrpClientService` instance being pointed to by @p aService MUST persist and remain unchanged after returning 489 * from this function (with `OT_ERROR_NONE`). OpenThread will save the pointer to the service instance. 490 * 491 * The `otSrpClientService` instance is not longer tracked by OpenThread and can be reclaimed only when 492 * 493 * - It is removed explicitly by a call to `otSrpClientRemoveService()` or removed along with other services by a 494 * call to `otSrpClientRemoveHostAndServices() and only after the `otSrpClientCallback` is called indicating the 495 * service was removed. Or, 496 * - A call to `otSrpClientClearHostAndServices()` which removes the host and all related services immediately. 497 * 498 * @param[in] aInstance A pointer to the OpenThread instance. 499 * @param[in] aService A pointer to a `otSrpClientService` instance to add. 500 501 * @retval OT_ERROR_NONE The addition of service started successfully. The `otSrpClientCallback` will be 502 * called to report the status. 503 * @retval OT_ERROR_ALREADY A service with the same service and instance names is already in the list. 504 * @retval OT_ERROR_INVALID_ARGS The service structure is invalid (e.g., bad service name or `otDnsTxtEntry`). 505 * 506 */ 507 otError otSrpClientAddService(otInstance *aInstance, otSrpClientService *aService); 508 509 /** 510 * This function requests a service to be unregistered with server. 511 * 512 * After a successful call to this function, `otSrpClientCallback` will be called to report the status of remove 513 * request with SRP server. 514 515 * The `otSrpClientService` instance being pointed to by @p aService MUST persist and remain unchanged after returning 516 * from this function (with `OT_ERROR_NONE`). OpenThread will keep the service instance during the remove process. 517 * Only after the `otSrpClientCallback` is called indicating the service instance is removed from SRP client 518 * service list and can be be freed/reused. 519 * 520 * @param[in] aInstance A pointer to the OpenThread instance. 521 * @param[in] aService A pointer to a `otSrpClientService` instance to remove. 522 * 523 * @retval OT_ERROR_NONE The removal of service started successfully. The `otSrpClientCallback` will be called to 524 * report the status. 525 * @retval OT_ERROR_NOT_FOUND The service could not be found in the list. 526 * 527 */ 528 otError otSrpClientRemoveService(otInstance *aInstance, otSrpClientService *aService); 529 530 /** 531 * This function clears a service, immediately removing it from the client service list. 532 * 533 * Unlike `otSrpClientRemoveService()` which sends an update message to the server to remove the service, this function 534 * clears the service from the client's service list without any interaction with the server. On a successful call to 535 * this function, the `otSrpClientCallback` will NOT be called and the @p aService entry can be reclaimed and re-used 536 * by the caller immediately. 537 * 538 * This function can be used along with a subsequent call to `otSrpClientAddService()` (potentially reusing the same @p 539 * aService entry with the same service and instance names) to update some of the parameters in an existing service. 540 * 541 * @param[in] aInstance A pointer to the OpenThread instance. 542 * @param[in] aService A pointer to a `otSrpClientService` instance to delete. 543 * 544 * @retval OT_ERROR_NONE The @p aService is deleted successfully. It can be reclaimed and re-used immediately. 545 * @retval OT_ERROR_NOT_FOUND The service could not be found in the list. 546 * 547 */ 548 otError otSrpClientClearService(otInstance *aInstance, otSrpClientService *aService); 549 550 /** 551 * This function gets the list of services being managed by client. 552 * 553 * @param[in] aInstance A pointer to the OpenThread instance. 554 * 555 * @returns A pointer to the head of linked-list of all services or NULL if the list is empty. 556 * 557 */ 558 const otSrpClientService *otSrpClientGetServices(otInstance *aInstance); 559 560 /** 561 * This function starts the remove process of the host info and all services. 562 * 563 * After returning from this function, `otSrpClientCallback` will be called to report the status of remove request with 564 * SRP server. 565 * 566 * If the host info is to be permanently removed from server, @p aRemoveKeyLease should be set to `true` which removes 567 * the key lease associated with host on server. Otherwise, the key lease record is kept as before, which ensures 568 * that the server holds the host name in reserve for when the client is once again able to provide and register its 569 * service(s). 570 * 571 * The @p aSendUnregToServer determines the behavior when the host info is not yet registered with the server. If 572 * @p aSendUnregToServer is set to `false` (which is the default/expected value) then the SRP client will immediately 573 * remove the host info and services without sending an update message to server (no need to update the server if 574 * nothing is yet registered with it). If @p aSendUnregToServer is set to `true` then the SRP client will send an 575 * update message to the server. Note that if the host info is registered then the value of @p aSendUnregToServer does 576 * not matter and the SRP client will always send an update message to server requesting removal of all info. 577 * 578 * One situation where @p aSendUnregToServer can be useful is on a device reset/reboot, caller may want to remove any 579 * previously registered services with the server. In this case, caller can `otSrpClientSetHostName()` and then request 580 * `otSrpClientRemoveHostAndServices()` with `aSendUnregToServer` as `true`. 581 * 582 * @param[in] aInstance A pointer to the OpenThread instance. 583 * @param[in] aRemoveKeyLease A boolean indicating whether or not the host key lease should also be removed. 584 * @param[in] aSendUnregToServer A boolean indicating whether to send update to server when host info is not registered. 585 * 586 * @retval OT_ERROR_NONE The removal of host info and services started successfully. The `otSrpClientCallback` 587 * will be called to report the status. 588 * @retval OT_ERROR_ALREADY The host info is already removed. 589 * 590 */ 591 otError otSrpClientRemoveHostAndServices(otInstance *aInstance, bool aRemoveKeyLease, bool aSendUnregToServer); 592 593 /** 594 * This function clears all host info and all the services. 595 * 596 * Unlike `otSrpClientRemoveHostAndServices()` which sends an update message to the server to remove all the info, this 597 * function clears all the info immediately without any interaction with the server. 598 * 599 * @param[in] aInstance A pointer to the OpenThread instance. 600 * 601 */ 602 void otSrpClientClearHostAndServices(otInstance *aInstance); 603 604 /** 605 * This function gets the domain name being used by SRP client. 606 * 607 * This function requires `OPENTHREAD_CONFIG_SRP_CLIENT_DOMAIN_NAME_API_ENABLE` to be enabled. 608 * 609 * If domain name is not set, "default.service.arpa" will be used. 610 * 611 * @param[in] aInstance A pointer to the OpenThread instance. 612 * 613 * @returns The domain name string. 614 * 615 */ 616 const char *otSrpClientGetDomainName(otInstance *aInstance); 617 618 /** 619 * This function sets the domain name to be used by SRP client. 620 * 621 * This function requires `OPENTHREAD_CONFIG_SRP_CLIENT_DOMAIN_NAME_API_ENABLE` to be enabled. 622 * 623 * If not set "default.service.arpa" will be used. 624 * 625 * The name string buffer pointed to by @p aName MUST persist and stay unchanged after returning from this function. 626 * OpenThread will keep the pointer to the string. 627 * 628 * The domain name can be set before client is started or after start but before host info is registered with server 629 * (host info should be in either `STATE_TO_ADD` or `STATE_TO_REMOVE`). 630 * 631 * @param[in] aInstance A pointer to the OpenThread instance. 632 * @param[in] aName A pointer to the domain name string. If NULL sets it to default "default.service.arpa". 633 * 634 * @retval OT_ERROR_NONE The domain name label was set successfully. 635 * @retval OT_ERROR_INVALID_STATE The host info is already registered with server. 636 * 637 */ 638 otError otSrpClientSetDomainName(otInstance *aInstance, const char *aName); 639 640 /** 641 * This function converts a `otSrpClientItemState` to a string. 642 * 643 * @param[in] aItemState An item state. 644 * 645 * @returns A string representation of @p aItemState. 646 * 647 */ 648 const char *otSrpClientItemStateToString(otSrpClientItemState aItemState); 649 650 /** 651 * This function enables/disables "service key record inclusion" mode. 652 * 653 * When enabled, SRP client will include KEY record in Service Description Instructions in the SRP update messages 654 * that it sends. 655 * 656 * This function is available when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` configuration is enabled. 657 * 658 * @note KEY record is optional in Service Description Instruction (it is required and always included in the Host 659 * Description Instruction). The default behavior of SRP client is to not include it. This function is intended to 660 * override the default behavior for testing only. 661 * 662 * @param[in] aInstance A pointer to the OpenThread instance. 663 * @param[in] aEnabled TRUE to enable, FALSE to disable the "service key record inclusion" mode. 664 * 665 */ 666 void otSrpClientSetServiceKeyRecordEnabled(otInstance *aInstance, bool aEnabled); 667 668 /** 669 * This method indicates whether the "service key record inclusion" mode is enabled or disabled. 670 * 671 * This function is available when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` configuration is enabled. 672 * 673 * @param[in] aInstance A pointer to the OpenThread instance. 674 * 675 * @returns TRUE if "service key record inclusion" mode is enabled, FALSE otherwise. 676 * 677 */ 678 bool otSrpClientIsServiceKeyRecordEnabled(otInstance *aInstance); 679 680 /** 681 * @} 682 * 683 */ 684 685 #ifdef __cplusplus 686 } // extern "C" 687 #endif 688 689 #endif // OPENTHREAD_SRP_CLIENT_H_ 690