| /* |
| * Copyright (c) 2020, The OpenThread Authors. |
| * All rights reserved. |
| * |
| * Redistribution and use in source and binary forms, with or without |
| * modification, are permitted provided that the following conditions are met: |
| * 1. Redistributions of source code must retain the above copyright |
| * notice, this list of conditions and the following disclaimer. |
| * 2. Redistributions in binary form must reproduce the above copyright |
| * notice, this list of conditions and the following disclaimer in the |
| * documentation and/or other materials provided with the distribution. |
| * 3. Neither the name of the copyright holder nor the |
| * names of its contributors may be used to endorse or promote products |
| * derived from this software without specific prior written permission. |
| * |
| * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" |
| * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE |
| * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR |
| * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF |
| * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS |
| * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN |
| * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
| * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE |
| * POSSIBILITY OF SUCH DAMAGE. |
| */ |
| |
| /** |
| * @file |
| * @brief |
| * This file defines the OpenThread SRP (Service Registration Protocol) client APIs. |
| */ |
| |
| #ifndef OPENTHREAD_SRP_CLIENT_H_ |
| #define OPENTHREAD_SRP_CLIENT_H_ |
| |
| #include <openthread/dns.h> |
| #include <openthread/ip6.h> |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| /** |
| * @addtogroup api-srp |
| * |
| * @brief |
| * This module includes functions that control SRP client behavior. |
| * |
| * @{ |
| * |
| */ |
| |
| /** |
| * This enumeration specifies an SRP client item (service or host info) state. |
| * |
| */ |
| typedef enum |
| { |
| OT_SRP_CLIENT_ITEM_STATE_TO_ADD, ///< Item to be added/registered. |
| OT_SRP_CLIENT_ITEM_STATE_ADDING, ///< Item is being added/registered. |
| OT_SRP_CLIENT_ITEM_STATE_TO_REFRESH, ///< Item to be refreshed (re-register to renew lease). |
| OT_SRP_CLIENT_ITEM_STATE_REFRESHING, ///< Item is being refreshed. |
| OT_SRP_CLIENT_ITEM_STATE_TO_REMOVE, ///< Item to be removed. |
| OT_SRP_CLIENT_ITEM_STATE_REMOVING, ///< Item is being removed. |
| OT_SRP_CLIENT_ITEM_STATE_REGISTERED, ///< Item is registered with server. |
| OT_SRP_CLIENT_ITEM_STATE_REMOVED, ///< Item is removed. |
| } otSrpClientItemState; |
| |
| /** |
| * This structure represents an SRP client host info. |
| * |
| */ |
| typedef struct otSrpClientHostInfo |
| { |
| const char * mName; ///< Host name (label) string (NULL if not yet set). |
| const otIp6Address * mAddresses; ///< Pointer to an array of host IPv6 addresses (NULL if not yet set). |
| uint8_t mNumAddresses; ///< Number of IPv6 addresses in `mAddresses` array. |
| otSrpClientItemState mState; ///< Host info state. |
| } otSrpClientHostInfo; |
| |
| /** |
| * This structure represents an SRP client service. |
| * |
| * The values in this structure, including the string buffers for the names and the TXT record entries, MUST persist |
| * and stay constant after an instance of this structure is passed to OpenThread from `otSrpClientAddService()` or |
| * `otSrpClientRemoveService()`. |
| * |
| */ |
| typedef struct otSrpClientService |
| { |
| const char * mName; ///< The service name labels (e.g., "_chip._udp", not the full domain name). |
| const char * mInstanceName; ///< The service instance name label (not the full name). |
| const char *const * mSubTypeLabels; ///< Array of service sub-type labels (must end with `NULL` or can be `NULL`). |
| const otDnsTxtEntry *mTxtEntries; ///< Array of TXT entries (number of entries is given by `mNumTxtEntries`). |
| uint16_t mPort; ///< The service port number. |
| uint16_t mPriority; ///< The service priority. |
| uint16_t mWeight; ///< The service weight. |
| uint8_t mNumTxtEntries; ///< Number of entries in the `mTxtEntries` array. |
| |
| /** |
| * @note The following fields are used/managed by OT core only. Their values do not matter and are ignored when an |
| * instance of `otSrpClientService` is passed in `otSrpClientAddService()` or `otSrpClientRemoveService()`. The |
| * user should not modify these fields. |
| * |
| */ |
| |
| otSrpClientItemState mState; ///< Service state (managed by OT core). |
| uint32_t mData; ///< Internal data (used by OT core). |
| struct otSrpClientService *mNext; ///< Pointer to next entry in a linked-list (managed by OT core). |
| } otSrpClientService; |
| |
| /** |
| * This function pointer type defines the callback used by SRP client to notify user of changes/events/errors. |
| * |
| * This callback is invoked on a successful registration of an update (i.e., add/remove of host-info and/or some |
| * service(s)) with the SRP server, or if there is a failure or error (e.g., server rejects a update request or client |
| * times out waiting for response, etc). |
| * |
| * In case of a successful reregistration of an update, `aError` parameter would be `OT_ERROR_NONE` and the host info |
| * and the full list of services is provided as input parameters to the callback. Note that host info and services each |
| * track its own state in the corresponding `mState` member variable of the related data structure (the state |
| * indicating whether the host-info/service is registered or removed or still being added/removed, etc). |
| * |
| * The list of removed services is passed as its own linked-list `aRemovedServices` in the callback. Note that when the |
| * callback is invoked, the SRP client (OpenThread implementation) is done with the removed service instances listed in |
| * `aRemovedServices` and no longer tracks/stores them (i.e., if from the callback we call `otSrpClientGetServices()` |
| * the removed services will not be present in the returned list). Providing a separate list of removed services in |
| * the callback helps indicate to user which items are now removed and allow user to re-claim/reuse the instances. |
| * |
| * If the server rejects an SRP update request, the DNS response code (RFC 2136) is mapped to the following errors: |
| * |
| * - (0) NOERROR Success (no error condition) -> OT_ERROR_NONE |
| * - (1) FORMERR Server unable to interpret due to format error -> OT_ERROR_PARSE |
| * - (2) SERVFAIL Server encountered an internal failure -> OT_ERROR_FAILED |
| * - (3) NXDOMAIN Name that ought to exist, does not exist -> OT_ERROR_NOT_FOUND |
| * - (4) NOTIMP Server does not support the query type (OpCode) -> OT_ERROR_NOT_IMPLEMENTED |
| * - (5) REFUSED Server refused for policy/security reasons -> OT_ERROR_SECURITY |
| * - (6) YXDOMAIN Some name that ought not to exist, does exist -> OT_ERROR_DUPLICATED |
| * - (7) YXRRSET Some RRset that ought not to exist, does exist -> OT_ERROR_DUPLICATED |
| * - (8) NXRRSET Some RRset that ought to exist, does not exist -> OT_ERROR_NOT_FOUND |
| * - (9) NOTAUTH Service is not authoritative for zone -> OT_ERROR_SECURITY |
| * - (10) NOTZONE A name is not in the zone -> OT_ERROR_PARSE |
| * - (20) BADNAME Bad name -> OT_ERROR_PARSE |
| * - (21) BADALG Bad algorithm -> OT_ERROR_SECURITY |
| * - (22) BADTRUN Bad truncation -> OT_ERROR_PARSE |
| * - Other response codes -> OT_ERROR_FAILED |
| * |
| * The following errors are also possible: |
| * |
| * - OT_ERROR_RESPONSE_TIMEOUT : Timed out waiting for response from server (client would continue to retry). |
| * - OT_ERROR_INVALID_ARGS : The provided service structure is invalid (e.g., bad service name or `otDnsTxtEntry`). |
| * - OT_ERROR_NO_BUFS : Insufficient buffer to prepare or send the update message. |
| * |
| * Note that in case of any failure, the client continues the operation, i.e. it prepares and (re)transmits the SRP |
| * update message to the server, after some wait interval. The retry wait interval starts from the minimum value and |
| * is increased by the growth factor every failure up to the max value (please see configuration parameter |
| * `OPENTHREAD_CONFIG_SRP_CLIENT_MIN_RETRY_WAIT_INTERVAL` and the related ones for more details). |
| * |
| * @param[in] aError The error (see above). |
| * @param[in] aHostInfo A pointer to host info. |
| * @param[in] aServices The head of linked-list containing all services (excluding the ones removed). NULL if |
| * the list is empty. |
| * @param[in] aRemovedServices The head of linked-list containing all removed services. NULL if the list is empty. |
| * @param[in] aContext A pointer to an arbitrary context (provided when callback was registered). |
| * |
| */ |
| typedef void (*otSrpClientCallback)(otError aError, |
| const otSrpClientHostInfo *aHostInfo, |
| const otSrpClientService * aServices, |
| const otSrpClientService * aRemovedServices, |
| void * aContext); |
| |
| /** |
| * This function pointer type defines the callback used by SRP client to notify user when it is auto-started or stopped. |
| * |
| * This is only used when auto-start feature `OPENTHREAD_CONFIG_SRP_CLIENT_AUTO_START_API_ENABLE` is enabled. |
| * |
| * This callback is invoked when auto-start mode is enabled and the SRP client is either automatically started or |
| * stopped. |
| * |
| * @param[in] aServerSockAddr A non-NULL pointer indicates SRP server was started and pointer will give the |
| * selected server socket address. A NULL pointer indicates SRP server was stopped. |
| * @param[in] aContext A pointer to an arbitrary context (provided when callback was registered). |
| * |
| */ |
| typedef void (*otSrpClientAutoStartCallback)(const otSockAddr *aServerSockAddr, void *aContext); |
| |
| /** |
| * This function starts the SRP client operation. |
| * |
| * SRP client will prepare and send "SRP Update" message to the SRP server once all the following conditions are met: |
| * |
| * - The SRP client is started - `otSrpClientStart()` is called. |
| * - Host name is set - `otSrpClientSetHostName()` is called. |
| * - At least one host IPv6 address is set - `otSrpClientSetHostName()` is called. |
| * - At least one service is added - `otSrpClientAddService()` is called. |
| * |
| * It does not matter in which order these functions are called. When all conditions are met, the SRP client will |
| * wait for a short delay before preparing an "SRP Update" message and sending it to server. This delay allows for user |
| * to add multiple services and/or IPv6 addresses before the first SRP Update message is sent (ensuring a single SRP |
| * Update is sent containing all the info). The config `OPENTHREAD_CONFIG_SRP_CLIENT_UPDATE_TX_DELAY` specifies the |
| * delay interval. |
| * |
| * @param[in] aInstance A pointer to the OpenThread instance. |
| * @param[in] aServerSockAddr The socket address (IPv6 address and port number) of the SRP server. |
| * |
| * @retval OT_ERROR_NONE SRP client operation started successfully or it is already running with same server |
| * socket address and callback. |
| * @retval OT_ERROR_BUSY SRP client is busy running with a different socket address. |
| * @retval OT_ERROR_FAILED Failed to open/connect the client's UDP socket. |
| * |
| */ |
| otError otSrpClientStart(otInstance *aInstance, const otSockAddr *aServerSockAddr); |
| |
| /** |
| * This function stops the SRP client operation. |
| * |
| * This function stops any further interactions with the SRP server. Note that it does not remove or clear host info |
| * and/or list of services. It marks all services to be added/removed again once the client is (re)started. |
| * |
| * @param[in] aInstance A pointer to the OpenThread instance. |
| * |
| */ |
| void otSrpClientStop(otInstance *aInstance); |
| |
| /** |
| * This function indicates whether the SRP client is running or not. |
| * |
| * @param[in] aInstance A pointer to the OpenThread instance. |
| * |
| * @returns TRUE if the SRP client is running, FALSE otherwise. |
| * |
| */ |
| bool otSrpClientIsRunning(otInstance *aInstance); |
| |
| /** |
| * This function gets the socket address (IPv6 address and port number) of the SRP server which is being used by SRP |
| * client. |
| * |
| * If the client is not running, the address is unspecified (all zero) with zero port number. |
| * |
| * @param[in] aInstance A pointer to the OpenThread instance. |
| * |
| * @returns A pointer to the SRP server's socket address (is always non-NULL). |
| * |
| */ |
| const otSockAddr *otSrpClientGetServerAddress(otInstance *aInstance); |
| |
| /** |
| * This function sets the callback to notify caller of events/changes from SRP client. |
| * |
| * The SRP client allows a single callback to be registered. So consecutive calls to this function will overwrite any |
| * previously set callback functions. |
| * |
| * @param[in] aInstance A pointer to the OpenThread instance. |
| * @param[in] aCallback The callback to notify of events and changes. Can be NULL if not needed. |
| * @param[in] aContext An arbitrary context used with @p aCallback. |
| * |
| */ |
| void otSrpClientSetCallback(otInstance *aInstance, otSrpClientCallback aCallback, void *aContext); |
| |
| /** |
| * This function enables the auto-start mode. |
| * |
| * This is only available when auto-start feature `OPENTHREAD_CONFIG_SRP_CLIENT_AUTO_START_API_ENABLE` is enabled. |
| * |
| * Config option `OPENTHREAD_CONFIG_SRP_CLIENT_AUTO_START_DEFAULT_MODE` specifies the default auto-start mode (whether |
| * it is enabled or disabled at the start of OT stack). |
| * |
| * When auto-start is enabled, the SRP client will monitor the Thread Network Data for SRP Server Service entries |
| * and automatically start and stop the client when an SRP server is detected. |
| * |
| * If multiple SRP servers are found, a random one will be selected. If the selected SRP server is no longer |
| * detected (not longer present in the Thread Network Data), the SRP client will be stopped and then it may switch |
| * to another SRP server (if available). |
| * |
| * When the SRP client is explicitly started through a successful call to `otSrpClientStart()`, the given SRP server |
| * address in `otSrpClientStart()` will continue to be used regardless of the state of auto-start mode and whether the |
| * same SRP server address is discovered or not in the Thread Network Data. In this case, only an explicit |
| * `otSrpClientStop()` call will stop the client. |
| * |
| * @param[in] aInstance A pointer to the OpenThread instance. |
| * @param[in] aCallback A callback to notify when client is auto-started/stopped. Can be NULL if not needed. |
| * @param[in] aContext A context to be passed when invoking @p aCallback. |
| * |
| */ |
| void otSrpClientEnableAutoStartMode(otInstance *aInstance, otSrpClientAutoStartCallback aCallback, void *aContext); |
| |
| /** |
| * This function disables the auto-start mode. |
| * |
| * This is only available when auto-start feature `OPENTHREAD_CONFIG_SRP_CLIENT_AUTO_START_API_ENABLE` is enabled. |
| * |
| * Disabling the auto-start mode will not stop the client if it is already running but the client stops monitoring |
| * the Thread Network Data to verify that the selected SRP server is still present in it. |
| * |
| * Note that a call to `otSrpClientStop()` will also disable the auto-start mode. |
| * |
| * @param[in] aInstance A pointer to the OpenThread instance. |
| * |
| */ |
| void otSrpClientDisableAutoStartMode(otInstance *aInstance); |
| |
| /** |
| * This function indicates the current state of auto-start mode (enabled or disabled). |
| * |
| * This is only available when auto-start feature `OPENTHREAD_CONFIG_SRP_CLIENT_AUTO_START_API_ENABLE` is enabled. |
| * |
| * @param[in] aInstance A pointer to the OpenThread instance. |
| * |
| * @returns TRUE if the auto-start mode is enabled, FALSE otherwise. |
| * |
| */ |
| bool otSrpClientIsAutoStartModeEnabled(otInstance *aInstance); |
| |
| /** |
| * This function gets the lease interval used in SRP update requests. |
| * |
| * Note that this is the lease duration requested by the SRP client. The server may choose to accept a different lease |
| * interval. |
| * |
| * @param[in] aInstance A pointer to the OpenThread instance. |
| * |
| * @returns The lease interval (in seconds). |
| * |
| */ |
| uint32_t otSrpClientGetLeaseInterval(otInstance *aInstance); |
| |
| /** |
| * This function sets the lease interval used in SRP update requests. |
| * |
| * Changing the lease interval does not impact the accepted lease interval of already registered services/host-info. |
| * It only affects any future SRP update messages (i.e., adding new services and/or refreshes of the existing services). |
| * |
| * @param[in] aInstance A pointer to the OpenThread instance. |
| * @param[in] aInterval The lease interval (in seconds). If zero, the default value specified by |
| * `OPENTHREAD_CONFIG_SRP_CLIENT_DEFAULT_LEASE` would be used. |
| * |
| */ |
| void otSrpClientSetLeaseInterval(otInstance *aInstance, uint32_t aInterval); |
| |
| /** |
| * This function gets the key lease interval used in SRP update requests. |
| * |
| * Note that this is the lease duration requested by the SRP client. The server may choose to accept a different lease |
| * interval. |
| * |
| * @param[in] aInstance A pointer to the OpenThread instance. |
| * |
| * @returns The key lease interval (in seconds). |
| * |
| */ |
| uint32_t otSrpClientGetKeyLeaseInterval(otInstance *aInstance); |
| |
| /** |
| * This function sets the key lease interval used in SRP update requests. |
| * |
| * Changing the lease interval does not impact the accepted lease interval of already registered services/host-info. |
| * It only affects any future SRP update messages (i.e., adding new services and/or refreshes of existing services). |
| * |
| * @param[in] aInstance A pointer to the OpenThread instance. |
| * @param[in] aInterval The key lease interval (in seconds). If zero, the default value specified by |
| * `OPENTHREAD_CONFIG_SRP_CLIENT_DEFAULT_KEY_LEASE` would be used. |
| * |
| */ |
| void otSrpClientSetKeyLeaseInterval(otInstance *aInstance, uint32_t aInterval); |
| |
| /** |
| * This function gets the host info. |
| * |
| * @param[in] aInstance A pointer to the OpenThread instance. |
| * |
| * @returns A pointer to host info structure. |
| * |
| */ |
| const otSrpClientHostInfo *otSrpClientGetHostInfo(otInstance *aInstance); |
| |
| /** |
| * This function sets the host name label. |
| * |
| * After a successful call to this function, `otSrpClientCallback` will be called to report the status of host info |
| * registration with SRP server. |
| * |
| * The name string buffer pointed to by @p aName MUST persist and stay unchanged after returning from this function. |
| * OpenThread will keep the pointer to the string. |
| * |
| * The host name can be set before client is started or after start but before host info is registered with server |
| * (host info should be in either `STATE_TO_ADD` or `STATE_REMOVED`). |
| * |
| * @param[in] aInstance A pointer to the OpenThread instance. |
| * @param[in] aName A pointer to host name label string (MUST NOT be NULL). Pointer to the string buffer MUST |
| * persist and remain valid and constant after return from this function. |
| * |
| * @retval OT_ERROR_NONE The host name label was set successfully. |
| * @retval OT_ERROR_INVALID_ARGS The @p aName is NULL. |
| * @retval OT_ERROR_INVALID_STATE The host name is already set and registered with the server. |
| * |
| */ |
| otError otSrpClientSetHostName(otInstance *aInstance, const char *aName); |
| |
| /** |
| * This function sets/updates the list of host IPv6 address. |
| * |
| * Host IPv6 addresses can be set/changed before start or during operation of SRP client (e.g. to add/remove or change |
| * a previously registered host address), except when the host info is being removed (client is busy handling a remove |
| * request from an earlier call to `otSrpClientRemoveHostAndServices()` and host info still being in either |
| * `STATE_TO_REMOVE` or `STATE_REMOVING` states). |
| * |
| * The host IPv6 address array pointed to by @p aIp6Addresses MUST persist and remain unchanged after returning from |
| * this function (with `OT_ERROR_NONE`). OpenThread will save the pointer to the array. |
| * |
| * After a successful call to this function, `otSrpClientCallback` will be called to report the status of the address |
| * registration with SRP server. |
| * |
| * @param[in] aInstance A pointer to the OpenThread instance. |
| * @param[in] aIp6Addresses A pointer to the an array containing the host IPv6 addresses. |
| * @param[in] aNumAddresses The number of addresses in the @p aIp6Addresses array. |
| * |
| * @retval OT_ERROR_NONE The host IPv6 address list change started successfully. The `otSrpClientCallback` |
| * will be called to report the status of registering addresses with server. |
| * @retval OT_ERROR_INVALID_ARGS The address list is invalid (e.g., must contain at least one address). |
| * @retval OT_ERROR_INVALID_STATE Host is being removed and therefore cannot change host address. |
| * |
| */ |
| otError otSrpClientSetHostAddresses(otInstance *aInstance, const otIp6Address *aIp6Addresses, uint8_t aNumAddresses); |
| |
| /** |
| * This function adds a service to be registered with server. |
| * |
| * After a successful call to this function, `otSrpClientCallback` will be called to report the status of the service |
| * addition/registration with SRP server. |
| * |
| * The `otSrpClientService` instance being pointed to by @p aService MUST persist and remain unchanged after returning |
| * from this function (with `OT_ERROR_NONE`). OpenThread will save the pointer to the service instance. |
| * |
| * The `otSrpClientService` instance is not longer tracked by OpenThread and can be reclaimed only when |
| * |
| * - It is removed explicitly by a call to `otSrpClientRemoveService()` or removed along with other services by a |
| * call to `otSrpClientRemoveHostAndServices() and only after the `otSrpClientCallback` is called indicating the |
| * service was removed. Or, |
| * - A call to `otSrpClientClearHostAndServices()` which removes the host and all related services immediately. |
| * |
| * @param[in] aInstance A pointer to the OpenThread instance. |
| * @param[in] aService A pointer to a `otSrpClientService` instance to add. |
| |
| * @retval OT_ERROR_NONE The addition of service started successfully. The `otSrpClientCallback` will be |
| * called to report the status. |
| * @retval OT_ERROR_ALREADY A service with the same service and instance names is already in the list. |
| * @retval OT_ERROR_INVALID_ARGS The service structure is invalid (e.g., bad service name or `otDnsTxtEntry`). |
| * |
| */ |
| otError otSrpClientAddService(otInstance *aInstance, otSrpClientService *aService); |
| |
| /** |
| * This function requests a service to be unregistered with server. |
| * |
| * After a successful call to this function, `otSrpClientCallback` will be called to report the status of remove |
| * request with SRP server. |
| |
| * The `otSrpClientService` instance being pointed to by @p aService MUST persist and remain unchanged after returning |
| * from this function (with `OT_ERROR_NONE`). OpenThread will keep the service instance during the remove process. |
| * Only after the `otSrpClientCallback` is called indicating the service instance is removed from SRP client |
| * service list and can be be freed/reused. |
| * |
| * @param[in] aInstance A pointer to the OpenThread instance. |
| * @param[in] aService A pointer to a `otSrpClientService` instance to remove. |
| * |
| * @retval OT_ERROR_NONE The removal of service started successfully. The `otSrpClientCallback` will be called to |
| * report the status. |
| * @retval OT_ERROR_NOT_FOUND The service could not be found in the list. |
| * |
| */ |
| otError otSrpClientRemoveService(otInstance *aInstance, otSrpClientService *aService); |
| |
| /** |
| * This function clears a service, immediately removing it from the client service list. |
| * |
| * Unlike `otSrpClientRemoveService()` which sends an update message to the server to remove the service, this function |
| * clears the service from the client's service list without any interaction with the server. On a successful call to |
| * this function, the `otSrpClientCallback` will NOT be called and the @p aService entry can be reclaimed and re-used |
| * by the caller immediately. |
| * |
| * This function can be used along with a subsequent call to `otSrpClientAddService()` (potentially reusing the same @p |
| * aService entry with the same service and instance names) to update some of the parameters in an existing service. |
| * |
| * @param[in] aInstance A pointer to the OpenThread instance. |
| * @param[in] aService A pointer to a `otSrpClientService` instance to delete. |
| * |
| * @retval OT_ERROR_NONE The @p aService is deleted successfully. It can be reclaimed and re-used immediately. |
| * @retval OT_ERROR_NOT_FOUND The service could not be found in the list. |
| * |
| */ |
| otError otSrpClientClearService(otInstance *aInstance, otSrpClientService *aService); |
| |
| /** |
| * This function gets the list of services being managed by client. |
| * |
| * @param[in] aInstance A pointer to the OpenThread instance. |
| * |
| * @returns A pointer to the head of linked-list of all services or NULL if the list is empty. |
| * |
| */ |
| const otSrpClientService *otSrpClientGetServices(otInstance *aInstance); |
| |
| /** |
| * This function starts the remove process of the host info and all services. |
| * |
| * After returning from this function, `otSrpClientCallback` will be called to report the status of remove request with |
| * SRP server. |
| * |
| * If the host info is to be permanently removed from server, @p aRemoveKeyLease should be set to `true` which removes |
| * the key lease associated with host on server. Otherwise, the key lease record is kept as before, which ensures |
| * that the server holds the host name in reserve for when the client is once again able to provide and register its |
| * service(s). |
| * |
| * The @p aSendUnregToServer determines the behavior when the host info is not yet registered with the server. If |
| * @p aSendUnregToServer is set to `false` (which is the default/expected value) then the SRP client will immediately |
| * remove the host info and services without sending an update message to server (no need to update the server if |
| * nothing is yet registered with it). If @p aSendUnregToServer is set to `true` then the SRP client will send an |
| * update message to the server. Note that if the host info is registered then the value of @p aSendUnregToServer does |
| * not matter and the SRP client will always send an update message to server requesting removal of all info. |
| * |
| * One situation where @p aSendUnregToServer can be useful is on a device reset/reboot, caller may want to remove any |
| * previously registered services with the server. In this case, caller can `otSrpClientSetHostName()` and then request |
| * `otSrpClientRemoveHostAndServices()` with `aSendUnregToServer` as `true`. |
| * |
| * @param[in] aInstance A pointer to the OpenThread instance. |
| * @param[in] aRemoveKeyLease A boolean indicating whether or not the host key lease should also be removed. |
| * @param[in] aSendUnregToServer A boolean indicating whether to send update to server when host info is not registered. |
| * |
| * @retval OT_ERROR_NONE The removal of host info and services started successfully. The `otSrpClientCallback` |
| * will be called to report the status. |
| * @retval OT_ERROR_ALREADY The host info is already removed. |
| * |
| */ |
| otError otSrpClientRemoveHostAndServices(otInstance *aInstance, bool aRemoveKeyLease, bool aSendUnregToServer); |
| |
| /** |
| * This function clears all host info and all the services. |
| * |
| * Unlike `otSrpClientRemoveHostAndServices()` which sends an update message to the server to remove all the info, this |
| * function clears all the info immediately without any interaction with the server. |
| * |
| * @param[in] aInstance A pointer to the OpenThread instance. |
| * |
| */ |
| void otSrpClientClearHostAndServices(otInstance *aInstance); |
| |
| /** |
| * This function gets the domain name being used by SRP client. |
| * |
| * This function requires `OPENTHREAD_CONFIG_SRP_CLIENT_DOMAIN_NAME_API_ENABLE` to be enabled. |
| * |
| * If domain name is not set, "default.service.arpa" will be used. |
| * |
| * @param[in] aInstance A pointer to the OpenThread instance. |
| * |
| * @returns The domain name string. |
| * |
| */ |
| const char *otSrpClientGetDomainName(otInstance *aInstance); |
| |
| /** |
| * This function sets the domain name to be used by SRP client. |
| * |
| * This function requires `OPENTHREAD_CONFIG_SRP_CLIENT_DOMAIN_NAME_API_ENABLE` to be enabled. |
| * |
| * If not set "default.service.arpa" will be used. |
| * |
| * The name string buffer pointed to by @p aName MUST persist and stay unchanged after returning from this function. |
| * OpenThread will keep the pointer to the string. |
| * |
| * The domain name can be set before client is started or after start but before host info is registered with server |
| * (host info should be in either `STATE_TO_ADD` or `STATE_TO_REMOVE`). |
| * |
| * @param[in] aInstance A pointer to the OpenThread instance. |
| * @param[in] aName A pointer to the domain name string. If NULL sets it to default "default.service.arpa". |
| * |
| * @retval OT_ERROR_NONE The domain name label was set successfully. |
| * @retval OT_ERROR_INVALID_STATE The host info is already registered with server. |
| * |
| */ |
| otError otSrpClientSetDomainName(otInstance *aInstance, const char *aName); |
| |
| /** |
| * This function converts a `otSrpClientItemState` to a string. |
| * |
| * @param[in] aItemState An item state. |
| * |
| * @returns A string representation of @p aItemState. |
| * |
| */ |
| const char *otSrpClientItemStateToString(otSrpClientItemState aItemState); |
| |
| /** |
| * This function enables/disables "service key record inclusion" mode. |
| * |
| * When enabled, SRP client will include KEY record in Service Description Instructions in the SRP update messages |
| * that it sends. |
| * |
| * This function is available when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` configuration is enabled. |
| * |
| * @note KEY record is optional in Service Description Instruction (it is required and always included in the Host |
| * Description Instruction). The default behavior of SRP client is to not include it. This function is intended to |
| * override the default behavior for testing only. |
| * |
| * @param[in] aInstance A pointer to the OpenThread instance. |
| * @param[in] aEnabled TRUE to enable, FALSE to disable the "service key record inclusion" mode. |
| * |
| */ |
| void otSrpClientSetServiceKeyRecordEnabled(otInstance *aInstance, bool aEnabled); |
| |
| /** |
| * This method indicates whether the "service key record inclusion" mode is enabled or disabled. |
| * |
| * This function is available when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` configuration is enabled. |
| * |
| * @param[in] aInstance A pointer to the OpenThread instance. |
| * |
| * @returns TRUE if "service key record inclusion" mode is enabled, FALSE otherwise. |
| * |
| */ |
| bool otSrpClientIsServiceKeyRecordEnabled(otInstance *aInstance); |
| |
| /** |
| * @} |
| * |
| */ |
| |
| #ifdef __cplusplus |
| } // extern "C" |
| #endif |
| |
| #endif // OPENTHREAD_SRP_CLIENT_H_ |