Google is committed to advancing racial equity for Black communities. See how.

SRP

This module includes functions that control SRP client behavior.

Summary

This module includes functions of the Service Registration Protocol.

This module includes functions for SRP client buffers and service pool.

Functions in this module are only available when feature OPENTHREAD_CONFIG_SRP_CLIENT_BUFFERS_ENABLE is enabled.

Enumerations

otSrpClientItemState{
  OT_SRP_CLIENT_ITEM_STATE_TO_ADD,
  OT_SRP_CLIENT_ITEM_STATE_ADDING,
  OT_SRP_CLIENT_ITEM_STATE_TO_REFRESH,
  OT_SRP_CLIENT_ITEM_STATE_REFRESHING,
  OT_SRP_CLIENT_ITEM_STATE_TO_REMOVE,
  OT_SRP_CLIENT_ITEM_STATE_REMOVING,
  OT_SRP_CLIENT_ITEM_STATE_REGISTERED,
  OT_SRP_CLIENT_ITEM_STATE_REMOVED
}
enum
This enumeration specifies an SRP client item (service or host info) state.

Typedefs

otSrpClientAutoStartCallback)(const otSockAddr *aServerSockAddr, void *aContext) typedef
void(*
This function pointer type defines the callback used by SRP client to notify user when it is auto-started or stopped.
otSrpClientBuffersServiceEntry typedef
This struct represents a SRP client service pool entry.
otSrpClientCallback)(otError aError, const otSrpClientHostInfo *aHostInfo, const otSrpClientService *aServices, const otSrpClientService *aRemovedServices, void *aContext) typedef
void(*
This function pointer type defines the callback used by SRP client to notify user of changes/events/errors.
otSrpClientHostInfo typedef
This structure represents an SRP client host info.
otSrpClientService typedef
This structure represents an SRP client service.
otSrpServerHost typedef
void
This opaque type represents a SRP service host.
otSrpServerService typedef
void
This opaque type represents a SRP service.
otSrpServerServiceUpdateHandler)(otSrpServerServiceUpdateId aId, const otSrpServerHost *aHost, uint32_t aTimeout, void *aContext) typedef
void(*
This method handles SRP service updates.
otSrpServerServiceUpdateId typedef
uint32_t
The ID of a SRP service update transaction on the SRP Server.

Functions

otSrpClientAddService(otInstance *aInstance, otSrpClientService *aService)
This function adds a service to be registered with server.
otSrpClientBuffersAllocateService(otInstance *aInstance)
This function allocates a new service entry from the pool.
otSrpClientBuffersFreeAllServices(otInstance *aInstance)
void
This function frees all previously allocated service entries.
otSrpClientBuffersFreeService(otInstance *aInstance, otSrpClientBuffersServiceEntry *aService)
void
This function frees a previously allocated service entry.
otSrpClientBuffersGetHostAddressesArray(otInstance *aInstance, uint8_t *aArrayLength)
This function gets the array of IPv6 address entries to use as SRP client host address list.
otSrpClientBuffersGetHostNameString(otInstance *aInstance, uint16_t *aSize)
char *
This function gets the string buffer to use for SRP client host name.
otSrpClientBuffersGetServiceEntryInstanceNameString(otSrpClientBuffersServiceEntry *aEntry, uint16_t *aSize)
char *
This function gets the string buffer for service instance name from a service entry.
otSrpClientBuffersGetServiceEntryServiceNameString(otSrpClientBuffersServiceEntry *aEntry, uint16_t *aSize)
char *
This function gets the string buffer for service name from a service entry.
otSrpClientBuffersGetServiceEntryTxtBuffer(otSrpClientBuffersServiceEntry *aEntry, uint16_t *aSize)
uint8_t *
This function gets the buffer for TXT record from a service entry.
otSrpClientClearHostAndServices(otInstance *aInstance)
void
This function clears all host info and all the services.
otSrpClientDisableAutoStartMode(otInstance *aInstance)
void
This function disables the auto-start mode.
otSrpClientEnableAutoStartMode(otInstance *aInstance, otSrpClientAutoStartCallback aCallback, void *aContext)
void
This function enables the auto-start mode.
otSrpClientGetDomainName(otInstance *aInstance)
const char *
This function gets the domain name being used by SRP client.
otSrpClientGetHostInfo(otInstance *aInstance)
This function gets the host info.
otSrpClientGetKeyLeaseInterval(otInstance *aInstance)
uint32_t
This function gets the key lease interval used in SRP update requests.
otSrpClientGetLeaseInterval(otInstance *aInstance)
uint32_t
This function gets the lease interval used in SRP update requests.
otSrpClientGetServerAddress(otInstance *aInstance)
const otSockAddr *
This function gets the socket address (IPv6 address and port number) of the SRP server which is being used by SRP client.
otSrpClientGetServices(otInstance *aInstance)
This function gets the list of services being managed by client.
otSrpClientIsAutoStartModeEnabled(otInstance *aInstance)
bool
This function indicates the current state of auto-start mode (enabled or disabled).
otSrpClientIsRunning(otInstance *aInstance)
bool
This function indicates whether the SRP client is running or not.
otSrpClientIsServiceKeyRecordEnabled(otInstance *aInstance)
bool
This method indicates whether the "service key record inclusion" mode is enabled or disabled.
otSrpClientItemStateToString(otSrpClientItemState aItemState)
const char *
This function converts a otSrpClientItemState to a string.
otSrpClientRemoveHostAndServices(otInstance *aInstance, bool aRemoveKeyLease)
This function starts the remove process of the host info and all services.
otSrpClientRemoveService(otInstance *aInstance, otSrpClientService *aService)
This function requests a service to be unregistered with server.
otSrpClientSetCallback(otInstance *aInstance, otSrpClientCallback aCallback, void *aContext)
void
This function sets the callback to notify caller of events/changes from SRP client.
otSrpClientSetDomainName(otInstance *aInstance, const char *aName)
This function sets the domain name to be used by SRP client.
otSrpClientSetHostAddresses(otInstance *aInstance, const otIp6Address *aIp6Addresses, uint8_t aNumAddresses)
This function sets/updates the list of host IPv6 address.
otSrpClientSetHostName(otInstance *aInstance, const char *aName)
This function sets the host name label.
otSrpClientSetKeyLeaseInterval(otInstance *aInstance, uint32_t aInterval)
void
This function sets the key lease interval used in SRP update requests.
otSrpClientSetLeaseInterval(otInstance *aInstance, uint32_t aInterval)
void
This function sets the lease interval used in SRP update requests.
otSrpClientSetServiceKeyRecordEnabled(otInstance *aInstance, bool aEnabled)
void
This function enables/disables "service key record inclusion" mode.
otSrpClientStart(otInstance *aInstance, const otSockAddr *aServerSockAddr)
This function starts the SRP client operation.
otSrpClientStop(otInstance *aInstance)
void
This function stops the SRP client operation.
otSrpServerGetDomain(otInstance *aInstance)
const char *
This method returns the domain authorized to the SRP server.
otSrpServerGetNextHost(otInstance *aInstance, const otSrpServerHost *aHost)
const otSrpServerHost *
This method returns the next registered host on the SRP server.
otSrpServerHandleServiceUpdateResult(otInstance *aInstance, otSrpServerServiceUpdateId aId, otError aError)
void
This method reports the result of processing a SRP update to the SRP server.
otSrpServerHostGetAddresses(const otSrpServerHost *aHost, uint8_t *aAddressesNum)
const otIp6Address *
This method returns the addresses of given host.
otSrpServerHostGetFullName(const otSrpServerHost *aHost)
const char *
This method returns the full name of the host.
otSrpServerHostGetNextService(const otSrpServerHost *aHost, const otSrpServerService *aService)
This method returns the next service of given host.
otSrpServerHostIsDeleted(const otSrpServerHost *aHost)
bool
This method tells if the SRP service host has been deleted.
otSrpServerServiceGetFullName(const otSrpServerService *aService)
const char *
This method returns the full name of the service.
otSrpServerServiceGetHost(const otSrpServerService *aService)
const otSrpServerHost *
This method returns the host which the service instance reside on.
otSrpServerServiceGetPort(const otSrpServerService *aService)
uint16_t
This method returns the port of the service instance.
otSrpServerServiceGetPriority(const otSrpServerService *aService)
uint16_t
This method returns the priority of the service instance.
otSrpServerServiceGetTxtData(const otSrpServerService *aService, uint16_t *aDataLength)
const uint8_t *
This function returns the TXT record data of the service instance.
otSrpServerServiceGetWeight(const otSrpServerService *aService)
uint16_t
This method returns the weight of the service instance.
otSrpServerServiceIsDeleted(const otSrpServerService *aService)
bool
This method tells if the SRP service has been deleted.
otSrpServerSetDomain(otInstance *aInstance, const char *aDomain)
This method sets the domain on the SRP server.
otSrpServerSetEnabled(otInstance *aInstance, bool aEnabled)
void
This method enables/disables the SRP server.
otSrpServerSetLeaseRange(otInstance *aInstance, uint32_t aMinLease, uint32_t aMaxLease, uint32_t aMinKeyLease, uint32_t aMaxKeyLease)
This method sets LEASE & KEY-LEASE range that is acceptable by the SRP server.
otSrpServerSetServiceUpdateHandler(otInstance *aInstance, otSrpServerServiceUpdateHandler aServiceHandler, void *aContext)
void
This method sets the SRP service updates handler on SRP server.

Structs

otSrpClientBuffersServiceEntry

This struct represents a SRP client service pool entry.

otSrpClientHostInfo

This structure represents an SRP client host info.

otSrpClientService

This structure represents an SRP client service.

Enumerations

otSrpClientItemState

 otSrpClientItemState

This enumeration specifies an SRP client item (service or host info) state.

Properties
OT_SRP_CLIENT_ITEM_STATE_ADDING

Item is being added/registered.

OT_SRP_CLIENT_ITEM_STATE_REFRESHING

Item is being refreshed.

OT_SRP_CLIENT_ITEM_STATE_REGISTERED

Item is registered with server.

OT_SRP_CLIENT_ITEM_STATE_REMOVED

Item is removed.

OT_SRP_CLIENT_ITEM_STATE_REMOVING

Item is being removed.

OT_SRP_CLIENT_ITEM_STATE_TO_ADD

Item to be added/registered.

OT_SRP_CLIENT_ITEM_STATE_TO_REFRESH

Item to be refreshed (re-register to renew lease).

OT_SRP_CLIENT_ITEM_STATE_TO_REMOVE

Item to be removed.

Typedefs

otSrpClientAutoStartCallback

void(* otSrpClientAutoStartCallback)(const otSockAddr *aServerSockAddr, 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.

Details
Parameters
[in] aSeverSockAddress
A non-NULL pointer indicates SRP sever was started and pointer will give the selected server socket address. A NULL pointer indicates SRP sever was stopped.
[in] aContext
A pointer to an arbitrary context (provided when callback was registered).

otSrpClientBuffersServiceEntry

struct otSrpClientBuffersServiceEntry otSrpClientBuffersServiceEntry

This struct represents a SRP client service pool entry.

otSrpClientCallback

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 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).

Details
Parameters
[in] aError
The error (see above).
[in] aHostInfo
A pointer to host info.
[in] aService
The head of linked-list containing all services (excluding the ones removed). NULL if the list is empty.
[in] aRemovedServices
The head of linked-list containing all removed services. NULL if the list is empty.
[in] aContext
A pointer to an arbitrary context (provided when callback was registered).

otSrpClientHostInfo

struct otSrpClientHostInfo otSrpClientHostInfo

This structure represents an SRP client host info.

otSrpClientService

struct otSrpClientService otSrpClientService

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().

otSrpServerHost

void otSrpServerHost

This opaque type represents a SRP service host.

otSrpServerService

void otSrpServerService

This opaque type represents a SRP service.

otSrpServerServiceUpdateHandler

void(* otSrpServerServiceUpdateHandler)(otSrpServerServiceUpdateId aId, const otSrpServerHost *aHost, uint32_t aTimeout, void *aContext)

This method handles SRP service updates.

This function is called by the SRP server to notify that a SRP host and possibly SRP services are being updated. It is important that the SRP updates are not committed until the handler returns the result by calling otSrpServerHandleServiceUpdateResult or times out after aTimeout.

A SRP service observer should always call otSrpServerHandleServiceUpdateResult with error code OT_ERROR_NONE immediately after receiving the update events.

A more generic handler may perform validations on the SRP host/services and rejects the SRP updates if any validation fails. For example, an Advertising Proxy should advertise (or remove) the host and services on a multicast-capable link and returns specific error code if any failure occurs.

Details
Parameters
[in] aId
The service update transaction ID. This ID must be passed back with otSrpServerHandleServiceUpdateResult.
[in] aHost
A pointer to the otSrpServerHost object which contains the SRP updates. The handler should publish/un-publish the host and each service points to this host with below rules:
  1. If the host is not deleted (indicated by otSrpServerHostIsDeleted), then it should be published or updated with mDNS. Otherwise, the host should be un-published (remove AAAA RRs).
  2. For each service points to this host, it must be un-published if the host is to be un-published. Otherwise, the handler should publish or update the service when it is not deleted (indicated by otSrpServerServiceIsDeleted) and un-publish it when deleted.
[in] aTimeout
The maximum time in milliseconds for the handler to process the service event.
[in] aContext
A pointer to application-specific context.
See also:
otSrpServerSetServiceUpdateHandler
otSrpServerHandleServiceUpdateResult

otSrpServerServiceUpdateId

uint32_t otSrpServerServiceUpdateId

The ID of a SRP service update transaction on the SRP Server.

Functions

otSrpClientAddService

otError otSrpClientAddService(
  otInstance *aInstance,
  otSrpClientService *aService
)

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 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

Details
Parameters
[in] aInstance
A pointer to the OpenThread instance.
[in] aService
A pointer to a otSrpClientService instance to add.
Return Values
OT_ERROR_NONE
The addition of service started successfully. The otSrpClientCallback will be called to report the status.
OT_ERROR_ALREADY
The same service is already in the list.
OT_ERROR_INVALID_ARGS
The service structure is invalid (e.g., bad service name or otDnsTxtEntry).

otSrpClientBuffersAllocateService

otSrpClientBuffersServiceEntry * otSrpClientBuffersAllocateService(
  otInstance *aInstance
)

This function allocates a new service entry from the pool.

The returned service entry instance will be initialized as follows:

Details
Parameters
[in] aInstance
A pointer to the OpenThread instance.
Returns
A pointer to the newly allocated service entry or NULL if not more entry available in the pool.

otSrpClientBuffersFreeAllServices

void otSrpClientBuffersFreeAllServices(
  otInstance *aInstance
)

This function frees all previously allocated service entries.

Details
Parameters
[in] aInstance
A pointer to the OpenThread instance.

otSrpClientBuffersFreeService

void otSrpClientBuffersFreeService(
  otInstance *aInstance,
  otSrpClientBuffersServiceEntry *aService
)

This function frees a previously allocated service entry.

The aService MUST be previously allocated using otSrpClientBuffersAllocateService() and not yet freed. Otherwise the behavior of this function is undefined.

Details
Parameters
[in] aInstance
A pointer to the OpenThread instance.
[in] aSevice
A pointer to the service entry to free (MUST NOT be NULL).

otSrpClientBuffersGetHostAddressesArray

otIp6Address * otSrpClientBuffersGetHostAddressesArray(
  otInstance *aInstance,
  uint8_t *aArrayLength
)

This function gets the array of IPv6 address entries to use as SRP client host address list.

Details
Parameters
[in] aInstance
A pointer to the OpenThread instance.
[out] aArrayLength
Pointer to a variable to return the array length i.e., number of IPv6 address entries in the array (MUST NOT be NULL).
Returns
A pointer to an array of otIp6Address entries (number of entries is returned in aArrayLength).

otSrpClientBuffersGetHostNameString

char * otSrpClientBuffersGetHostNameString(
  otInstance *aInstance,
  uint16_t *aSize
)

This function gets the string buffer to use for SRP client host name.

Details
Parameters
[in] aInstance
A pointer to the OpenThread instance.
[out] aSize
Pointer to a variable to return the size (number of bytes) of the string buffer (MUST NOT be NULL).
Returns
A pointer to char buffer to use for SRP client host name.

otSrpClientBuffersGetServiceEntryInstanceNameString

char * otSrpClientBuffersGetServiceEntryInstanceNameString(
  otSrpClientBuffersServiceEntry *aEntry,
  uint16_t *aSize
)

This function gets the string buffer for service instance name from a service entry.

Details
Parameters
[in] aEntry
A pointer to a previously allocated service entry (MUST NOT be NULL).
[out] aSize
A pointer to a variable to return the size (number of bytes) of the string buffer (MUST NOT be NULL).
Returns
A pointer to the string buffer.

otSrpClientBuffersGetServiceEntryServiceNameString

char * otSrpClientBuffersGetServiceEntryServiceNameString(
  otSrpClientBuffersServiceEntry *aEntry,
  uint16_t *aSize
)

This function gets the string buffer for service name from a service entry.

Details
Parameters
[in] aEntry
A pointer to a previously allocated service entry (MUST NOT be NULL).
[out] aSize
A pointer to a variable to return the size (number of bytes) of the string buffer (MUST NOT be NULL).
Returns
A pointer to the string buffer.

otSrpClientBuffersGetServiceEntryTxtBuffer

uint8_t * otSrpClientBuffersGetServiceEntryTxtBuffer(
  otSrpClientBuffersServiceEntry *aEntry,
  uint16_t *aSize
)

This function gets the buffer for TXT record from a service entry.

Details
Parameters
[in] aEntry
A pointer to a previously allocated service entry (MUST NOT be NULL).
[out] aSize
A pointer to a variable to return the size (number of bytes) of the buffer (MUST NOT be NULL).
Returns
A pointer to the buffer.

otSrpClientClearHostAndServices

void otSrpClientClearHostAndServices(
  otInstance *aInstance
)

This function clears all host info and all the services.

Unlike otSrpClientRemoveHostAndServices() which sends an update message to server to remove/unregister all the info, this function clears all the info immediately without any interaction with server.

Details
Parameters
[in] aInstance
A pointer to the OpenThread instance.

otSrpClientDisableAutoStartMode

void otSrpClientDisableAutoStartMode(
  otInstance *aInstance
)

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.

Details
Parameters
[in] aInstance
A pointer to the OpenThread instance.

otSrpClientEnableAutoStartMode

void otSrpClientEnableAutoStartMode(
  otInstance *aInstance,
  otSrpClientAutoStartCallback 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.

Details
Parameters
[in] aInstance
A pointer to the OpenThread instance.
[in] aCallback
A callback to notify when client is auto-started/stopped. Can be NULL if not needed.
[in] aContext
A context to be passed when invoking aCallback.

otSrpClientGetDomainName

const char * otSrpClientGetDomainName(
  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.

Details
Parameters
[in] aInstance
A pointer to the OpenThread instance.
Returns
The domain name string.

otSrpClientGetHostInfo

const otSrpClientHostInfo * otSrpClientGetHostInfo(
  otInstance *aInstance
)

This function gets the host info.

Details
Parameters
[in] aInstance
A pointer to the OpenThread instance.
Returns
A pointer to host info structure.

otSrpClientGetKeyLeaseInterval

uint32_t otSrpClientGetKeyLeaseInterval(
  otInstance *aInstance
)

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.

Details
Parameters
[in] aInstance
A pointer to the OpenThread instance.
Returns
The key lease interval (in seconds).

otSrpClientGetLeaseInterval

uint32_t otSrpClientGetLeaseInterval(
  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.

Details
Parameters
[in] aInstance
A pointer to the OpenThread instance.
Returns
The lease interval (in seconds).

otSrpClientGetServerAddress

const otSockAddr * otSrpClientGetServerAddress(
  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.

Details
Parameters
[in] aInstance
A pointer to the OpenThread instance.
Returns
A pointer to the SRP server's socket address (is always non-NULL).

otSrpClientGetServices

const otSrpClientService * otSrpClientGetServices(
  otInstance *aInstance
)

This function gets the list of services being managed by client.

Details
Parameters
[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.

otSrpClientIsAutoStartModeEnabled

bool otSrpClientIsAutoStartModeEnabled(
  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.

Details
Parameters
[in] aInstance
A pointer to the OpenThread instance.
Returns
TRUE if the auto-start mode is enabled, FALSE otherwise.

otSrpClientIsRunning

bool otSrpClientIsRunning(
  otInstance *aInstance
)

This function indicates whether the SRP client is running or not.

Details
Parameters
[in] aInstance
A pointer to the OpenThread instance.
Returns
TRUE if the SRP client is running, FALSE otherwise.

otSrpClientIsServiceKeyRecordEnabled

bool otSrpClientIsServiceKeyRecordEnabled(
  otInstance *aInstance
)

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.

Details
Parameters
[in] aInstance
A pointer to the OpenThread instance.
Returns
TRUE if "service key record inclusion" mode is enabled, FALSE otherwise.

otSrpClientItemStateToString

const char * otSrpClientItemStateToString(
  otSrpClientItemState aItemState
)

This function converts a otSrpClientItemState to a string.

Details
Parameters
[in] aItemState
An item state.
Returns
A string representation of aItemState.

otSrpClientRemoveHostAndServices

otError otSrpClientRemoveHostAndServices(
  otInstance *aInstance,
  bool aRemoveKeyLease
)

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, 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).

Details
Parameters
[in] aInstance
A pointer to the OpenThread instance.
[in] aRemoveKeyLease
A boolean indicating whether or not the host key lease should also be removed.
Return Values
OT_ERROR_NONE
The removal of host info and services started successfully. The otSrpClientCallback will be called to report the status.
OT_ERROR_ALREADY
The host info is already removed.

otSrpClientRemoveService

otError otSrpClientRemoveService(
  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 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.

Details
Parameters
[in] aInstance
A pointer to the OpenThread instance.
[in] aService
A pointer to a otSrpClientService instance to remove.
Return Values
OT_ERROR_NONE
The removal of service started successfully. The otSrpClientCallback will be called to report the status.
OT_ERROR_NOT_FOUND
The service could not be found in the list.

otSrpClientSetCallback

void otSrpClientSetCallback(
  otInstance *aInstance,
  otSrpClientCallback aCallback,
  void *aContext
)

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.

Details
Parameters
[in] aInstance
A pointer to the OpenThread instance.
[in] aCallback
The callback to notify of events and changes. Can be NULL if not needed.
[in] aContext
An arbitrary context used with aCallback.

otSrpClientSetDomainName

otError otSrpClientSetDomainName(
  otInstance *aInstance,
  const char *aName
)

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 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).

Details
Parameters
[in] aInstance
A pointer to the OpenThread instance.
[in] aName
A pointer to the domain name string. If NULL sets it to default "default.service.arpa".
Return Values
OT_ERROR_NONE
The domain name label was set successfully.
OT_ERROR_INVALID_STATE
The host info is already registered with server.

otSrpClientSetHostAddresses

otError otSrpClientSetHostAddresses(
  otInstance *aInstance,
  const otIp6Address *aIp6Addresses,
  uint8_t aNumAddresses
)

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 aAddresses 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.

Details
Parameters
[in] aInstance
A pointer to the OpenThread instance.
[in] aAddresses
A pointer to the an array containing the host IPv6 addresses.
[in] aNumAddresses
The number of addresses in the aAddresses array.
Return Values
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.
OT_ERROR_INVALID_ARGS
The address list is invalid (e.g., must contain at least one address).
OT_ERROR_INVALID_STATE
Host is being removed and therefore cannot change host address.

otSrpClientSetHostName

otError otSrpClientSetHostName(
  otInstance *aInstance,
  const char *aName
)

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 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).

Details
Parameters
[in] aInstance
A pointer to the OpenThread instance.
[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.
Return Values
OT_ERROR_NONE
The host name label was set successfully.
OT_ERROR_INVALID_ARGS
The aName is NULL.
OT_ERROR_INVALID_STATE
The host name is already set and registered with the server.

otSrpClientSetKeyLeaseInterval

void otSrpClientSetKeyLeaseInterval(
  otInstance *aInstance,
  uint32_t aInterval
)

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).

Details
Parameters
[in] aInstance
A pointer to the OpenThread instance.
[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.

otSrpClientSetLeaseInterval

void otSrpClientSetLeaseInterval(
  otInstance *aInstance,
  uint32_t aInterval
)

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).

Details
Parameters
[in] aInstance
A pointer to the OpenThread instance.
[in] aInterval
The lease interval (in seconds). If zero, the default value specified by OPENTHREAD_CONFIG_SRP_CLIENT_DEFAULT_LEASE would be used.

otSrpClientSetServiceKeyRecordEnabled

void otSrpClientSetServiceKeyRecordEnabled(
  otInstance *aInstance,
  bool aEnabled
)

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.

Details
Parameters
[in] aInstance
A pointer to the OpenThread instance.
[in] aEnabled
TRUE to enable, FALSE to disable the "service key record inclusion" mode.

otSrpClientStart

otError otSrpClientStart(
  otInstance *aInstance,
  const otSockAddr *aServerSockAddr
)

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:

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.

Details
Parameters
[in] aInstance
A pointer to the OpenThread instance.
[in] aServerSockAddr
The socket address (IPv6 address and port number) of the SRP server.
Return Values
OT_ERROR_NONE
SRP client operation started successfully or it is already running with same server socket address and callback.
OT_ERROR_BUSY
SRP client is busy running with a different socket address.
OT_ERROR_FAILED
Failed to open/connect the client's UDP socket.

otSrpClientStop

void otSrpClientStop(
  otInstance *aInstance
)

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.

Details
Parameters
[in] aInstance
A pointer to the OpenThread instance.

otSrpServerGetDomain

const char * otSrpServerGetDomain(
  otInstance *aInstance
)

This method returns the domain authorized to the SRP server.

If the domain if not set by SetDomain, "default.service.arpa." will be returned. A trailing dot is always appended even if the domain is set without it.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Returns
A pointer to the dot-joined domain string.

otSrpServerGetNextHost

const otSrpServerHost * otSrpServerGetNextHost(
  otInstance *aInstance,
  const otSrpServerHost *aHost
)

This method returns the next registered host on the SRP server.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aHost
A pointer to current host; use NULL to get the first host.
Returns
A pointer to the registered host. NULL, if no more hosts can be found.

otSrpServerHandleServiceUpdateResult

void otSrpServerHandleServiceUpdateResult(
  otInstance *aInstance,
  otSrpServerServiceUpdateId aId,
  otError aError
)

This method reports the result of processing a SRP update to the SRP server.

The Service Update Handler should call this function to return the result of its processing of a SRP update.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aId
The service update transaction ID. This should be the same ID provided via otSrpServerServiceUpdateHandler.
[in] aError
An error to be returned to the SRP server. Use OT_ERROR_DUPLICATED to represent DNS name conflicts.

otSrpServerHostGetAddresses

const otIp6Address * otSrpServerHostGetAddresses(
  const otSrpServerHost *aHost,
  uint8_t *aAddressesNum
)

This method returns the addresses of given host.

Details
Parameters
[in] aHost
A pointer to the SRP service host.
[out] aAddressesNum
A pointer to where we should output the number of the addresses to.
Returns
A pointer to the array of IPv6 Address.

otSrpServerHostGetFullName

const char * otSrpServerHostGetFullName(
  const otSrpServerHost *aHost
)

This method returns the full name of the host.

Details
Parameters
[in] aHost
A pointer to the SRP service host.
Returns
A pointer to the null-terminated host name string.

otSrpServerHostGetNextService

const otSrpServerService * otSrpServerHostGetNextService(
  const otSrpServerHost *aHost,
  const otSrpServerService *aService
)

This method returns the next service of given host.

Details
Parameters
[in] aHost
A pointer to the SRP service host.
[in] aService
A pointer to current SRP service instance; use NULL to get the first service.
Returns
A pointer to the next service or NULL if there is no more services.

otSrpServerHostIsDeleted

bool otSrpServerHostIsDeleted(
  const otSrpServerHost *aHost
)

This method tells if the SRP service host has been deleted.

A SRP service host can be deleted but retains its name for future uses. In this case, the host instance is not removed from the SRP server/registry.

Details
Parameters
[in] aHost
A pointer to the SRP service host.
Returns
TRUE if the host has been deleted, FALSE if not.

otSrpServerServiceGetFullName

const char * otSrpServerServiceGetFullName(
  const otSrpServerService *aService
)

This method returns the full name of the service.

Details
Parameters
[in] aService
A pointer to the SRP service.
Returns
A pointer to the null-terminated service name string.

otSrpServerServiceGetHost

const otSrpServerHost * otSrpServerServiceGetHost(
  const otSrpServerService *aService
)

This method returns the host which the service instance reside on.

Details
Parameters
[in] aService
A pointer to the SRP service.
Returns
A pointer to the host instance.

otSrpServerServiceGetPort

uint16_t otSrpServerServiceGetPort(
  const otSrpServerService *aService
)

This method returns the port of the service instance.

Details
Parameters
[in] aService
A pointer to the SRP service.
Returns
The port of the service.

otSrpServerServiceGetPriority

uint16_t otSrpServerServiceGetPriority(
  const otSrpServerService *aService
)

This method returns the priority of the service instance.

Details
Parameters
[in] aService
A pointer to the SRP service.
Returns
The priority of the service.

otSrpServerServiceGetTxtData

const uint8_t * otSrpServerServiceGetTxtData(
  const otSrpServerService *aService,
  uint16_t *aDataLength
)

This function returns the TXT record data of the service instance.

Details
Parameters
[in] aService
A pointer to the SRP service.
[out] aDataLength
A pointer to return the TXT record data length. MUST NOT be NULL.
Returns
A pointer to the buffer containing the TXT record data (the TXT data length is returned in aDataLength).

otSrpServerServiceGetWeight

uint16_t otSrpServerServiceGetWeight(
  const otSrpServerService *aService
)

This method returns the weight of the service instance.

Details
Parameters
[in] aService
A pointer to the SRP service.
Returns
The weight of the service.

otSrpServerServiceIsDeleted

bool otSrpServerServiceIsDeleted(
  const otSrpServerService *aService
)

This method tells if the SRP service has been deleted.

A SRP service can be deleted but retains its name for future uses. In this case, the service instance is not removed from the SRP server/registry. It is guaranteed that all services are deleted if the host is deleted.

Details
Parameters
[in] aService
A pointer to the SRP service.
Returns
TRUE if the service has been deleted, FALSE if not.

otSrpServerSetDomain

otError otSrpServerSetDomain(
  otInstance *aInstance,
  const char *aDomain
)

This method sets the domain on the SRP server.

A trailing dot will be appended to aDomain if it is not already there. This method should only be called before the SRP server is enabled.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aDomain
The domain to be set. MUST NOT be NULL.
Return Values
OT_ERROR_NONE
Successfully set the domain to aDomain.
OT_ERROR_INVALID_STATE
The SRP server is already enabled and the Domain cannot be changed.
OT_ERROR_INVALID_ARGS
The argument aDomain is not a valid DNS domain name.
OT_ERROR_NO_BUFS
There is no memory to store content of aDomain.

otSrpServerSetEnabled

void otSrpServerSetEnabled(
  otInstance *aInstance,
  bool aEnabled
)

This method enables/disables the SRP server.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aEnabled
A boolean to enable/disable the SRP server.

otSrpServerSetLeaseRange

otError otSrpServerSetLeaseRange(
  otInstance *aInstance,
  uint32_t aMinLease,
  uint32_t aMaxLease,
  uint32_t aMinKeyLease,
  uint32_t aMaxKeyLease
)

This method sets LEASE & KEY-LEASE range that is acceptable by the SRP server.

When a non-zero LEASE time is requested from a client, the granted value will be limited in range [aMinLease, aMaxLease]; and a non-zero KEY-LEASE will be granted in range [aMinKeyLease, aMaxKeyLease]. For zero LEASE or KEY-LEASE time, zero will be granted.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aMinLease
The minimum LEASE interval in seconds.
[in] aMaxLease
The maximum LEASE interval in seconds.
[in] aMinKeyLease
The minimum KEY-LEASE interval in seconds.
[in] aMaxKeyLease
The maximum KEY-LEASE interval in seconds.
Return Values
OT_ERROR_NONE
Successfully set the LEASE and KEY-LEASE ranges.
OT_ERROR_INVALID_ARGS
The LEASE or KEY-LEASE range is not valid.

otSrpServerSetServiceUpdateHandler

void otSrpServerSetServiceUpdateHandler(
  otInstance *aInstance,
  otSrpServerServiceUpdateHandler aServiceHandler,
  void *aContext
)

This method sets the SRP service updates handler on SRP server.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aServiceHandler
A pointer to a service handler. Use NULL to remove the handler.
[in] aContext
A pointer to arbitrary context information. May be NULL if not used.