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