SRP#

This module includes functions that control SRP client behavior.

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.

Modules#

otSrpClientHostInfo

otSrpClientService

otSrpClientBuffersServiceEntry

otSrpServerTtlConfig

otSrpServerLeaseConfig

otSrpServerLeaseInfo

otSrpServerResponseCounters

Enumerations#

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

Specifies an SRP client item (service or host info) state.

enum
OT_SRP_SERVER_STATE_DISABLED = 0
OT_SRP_SERVER_STATE_RUNNING = 1
OT_SRP_SERVER_STATE_STOPPED = 2
}

Represents the state of the SRP server.

enum
OT_SRP_SERVER_ADDRESS_MODE_UNICAST = 0
OT_SRP_SERVER_ADDRESS_MODE_ANYCAST = 1
}

Represents the address mode used by the SRP server.

Typedefs#

typedef struct otSrpClientHostInfo

Represents an SRP client host info.

typedef struct otSrpClientService

Represents an SRP client service.

typedef void(*
otSrpClientCallback)(otError aError, const otSrpClientHostInfo *aHostInfo, const otSrpClientService *aServices, const otSrpClientService *aRemovedServices, void *aContext)

Pointer type defines the callback used by SRP client to notify user of changes/events/errors.

typedef void(*
otSrpClientAutoStartCallback)(const otSockAddr *aServerSockAddr, void *aContext)

Pointer type defines the callback used by SRP client to notify user when it is auto-started or stopped.

Represents a SRP client service pool entry.

typedef struct otSrpServerHost

This opaque type represents a SRP service host.

typedef struct otSrpServerService

This opaque type represents a SRP service.

typedef uint32_t

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

Represents the address mode used by the SRP server.

typedef struct otSrpServerTtlConfig

Includes SRP server TTL configurations.

typedef struct otSrpServerLeaseConfig

Includes SRP server LEASE and KEY-LEASE configurations.

typedef struct otSrpServerLeaseInfo

Includes SRP server lease information of a host/service.

Includes the statistics of SRP server responses.

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

Handles SRP service updates.

Functions#

otSrpClientStart(otInstance *aInstance, const otSockAddr *aServerSockAddr)

Starts the SRP client operation.

void
otSrpClientStop(otInstance *aInstance)

Stops the SRP client operation.

bool
otSrpClientIsRunning(otInstance *aInstance)

Indicates whether the SRP client is running or not.

const otSockAddr *
otSrpClientGetServerAddress(otInstance *aInstance)

Gets the socket address (IPv6 address and port number) of the SRP server which is being used by SRP client.

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

Sets the callback to notify caller of events/changes from SRP client.

void
otSrpClientEnableAutoStartMode(otInstance *aInstance, otSrpClientAutoStartCallback aCallback, void *aContext)

Enables the auto-start mode.

void
otSrpClientDisableAutoStartMode(otInstance *aInstance)

Disables the auto-start mode.

bool
otSrpClientIsAutoStartModeEnabled(otInstance *aInstance)

Indicates the current state of auto-start mode (enabled or disabled).

uint32_t
otSrpClientGetTtl(otInstance *aInstance)

Gets the TTL value in every record included in SRP update requests.

void
otSrpClientSetTtl(otInstance *aInstance, uint32_t aTtl)

Sets the TTL value in every record included in SRP update requests.

uint32_t
otSrpClientGetLeaseInterval(otInstance *aInstance)

Gets the default lease interval used in SRP update requests.

void
otSrpClientSetLeaseInterval(otInstance *aInstance, uint32_t aInterval)

Sets the default lease interval used in SRP update requests.

uint32_t
otSrpClientGetKeyLeaseInterval(otInstance *aInstance)

Gets the default key lease interval used in SRP update requests.

void
otSrpClientSetKeyLeaseInterval(otInstance *aInstance, uint32_t aInterval)

Sets the default key lease interval used in SRP update requests.

otSrpClientGetHostInfo(otInstance *aInstance)

Gets the host info.

otSrpClientSetHostName(otInstance *aInstance, const char *aName)

Sets the host name label.

otSrpClientEnableAutoHostAddress(otInstance *aInstance)

Enables auto host address mode.

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

Sets/updates the list of host IPv6 address.

otSrpClientAddService(otInstance *aInstance, otSrpClientService *aService)

Adds a service to be registered with server.

otSrpClientRemoveService(otInstance *aInstance, otSrpClientService *aService)

Requests a service to be unregistered with server.

otSrpClientClearService(otInstance *aInstance, otSrpClientService *aService)

Clears a service, immediately removing it from the client service list.

otSrpClientGetServices(otInstance *aInstance)

Gets the list of services being managed by client.

otSrpClientRemoveHostAndServices(otInstance *aInstance, bool aRemoveKeyLease, bool aSendUnregToServer)

Starts the remove process of the host info and all services.

void
otSrpClientClearHostAndServices(otInstance *aInstance)

Clears all host info and all the services.

const char *
otSrpClientGetDomainName(otInstance *aInstance)

Gets the domain name being used by SRP client.

otSrpClientSetDomainName(otInstance *aInstance, const char *aName)

Sets the domain name to be used by SRP client.

const char *
otSrpClientItemStateToString(otSrpClientItemState aItemState)

Converts a otSrpClientItemState to a string.

void
otSrpClientSetServiceKeyRecordEnabled(otInstance *aInstance, bool aEnabled)

Enables/disables "service key record inclusion" mode.

bool

Indicates whether the "service key record inclusion" mode is enabled or disabled.

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

Gets the string buffer to use for SRP client host name.

otSrpClientBuffersGetHostAddressesArray(otInstance *aInstance, uint8_t *aArrayLength)

Gets the array of IPv6 address entries to use as SRP client host address list.

otSrpClientBuffersAllocateService(otInstance *aInstance)

Allocates a new service entry from the pool.

void
otSrpClientBuffersFreeService(otInstance *aInstance, otSrpClientBuffersServiceEntry *aService)

Frees a previously allocated service entry.

void
otSrpClientBuffersFreeAllServices(otInstance *aInstance)

Frees all previously allocated service entries.

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

Gets the string buffer for service name from a service entry.

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

Gets the string buffer for service instance name from a service entry.

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

Gets the buffer for TXT record from a service entry.

const char **
otSrpClientBuffersGetSubTypeLabelsArray(otSrpClientBuffersServiceEntry *aEntry, uint16_t *aArrayLength)

Gets the array for service subtype labels from the service entry.

const char *
otSrpServerGetDomain(otInstance *aInstance)

Returns the domain authorized to the SRP server.

otSrpServerSetDomain(otInstance *aInstance, const char *aDomain)

Sets the domain on the SRP server.

otSrpServerGetState(otInstance *aInstance)

Returns the state of the SRP server.

uint16_t
otSrpServerGetPort(otInstance *aInstance)

Returns the port the SRP server is listening to.

otSrpServerGetAddressMode(otInstance *aInstance)

Returns the address mode being used by the SRP server.

otSrpServerSetAddressMode(otInstance *aInstance, otSrpServerAddressMode aMode)

Sets the address mode to be used by the SRP server.

uint8_t

Returns the sequence number used with anycast address mode.

otSrpServerSetAnycastModeSequenceNumber(otInstance *aInstance, uint8_t aSequenceNumber)

Sets the sequence number used with anycast address mode.

void
otSrpServerSetEnabled(otInstance *aInstance, bool aEnabled)

Enables/disables the SRP server.

void
otSrpServerSetAutoEnableMode(otInstance *aInstance, bool aEnabled)

Enables/disables the auto-enable mode on SRP server.

bool
otSrpServerIsAutoEnableMode(otInstance *aInstance)

Indicates whether the auto-enable mode is enabled or disabled.

void
otSrpServerGetTtlConfig(otInstance *aInstance, otSrpServerTtlConfig *aTtlConfig)

Returns SRP server TTL configuration.

otSrpServerSetTtlConfig(otInstance *aInstance, const otSrpServerTtlConfig *aTtlConfig)

Sets SRP server TTL configuration.

void
otSrpServerGetLeaseConfig(otInstance *aInstance, otSrpServerLeaseConfig *aLeaseConfig)

Returns SRP server LEASE and KEY-LEASE configurations.

otSrpServerSetLeaseConfig(otInstance *aInstance, const otSrpServerLeaseConfig *aLeaseConfig)

Sets SRP server LEASE and KEY-LEASE configurations.

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

Sets the SRP service updates handler on SRP server.

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

Reports the result of processing a SRP update to the SRP server.

otSrpServerGetNextHost(otInstance *aInstance, const otSrpServerHost *aHost)

Returns the next registered host on the SRP server.

otSrpServerGetResponseCounters(otInstance *aInstance)

Returns the response counters of the SRP server.

bool
otSrpServerHostIsDeleted(const otSrpServerHost *aHost)

Tells if the SRP service host has been deleted.

const char *
otSrpServerHostGetFullName(const otSrpServerHost *aHost)

Returns the full name of the host.

bool
otSrpServerHostMatchesFullName(const otSrpServerHost *aHost, const char *aFullName)

Indicates whether the host matches a given host name.

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

Returns the addresses of given host.

void
otSrpServerHostGetLeaseInfo(const otSrpServerHost *aHost, otSrpServerLeaseInfo *aLeaseInfo)

Returns the LEASE and KEY-LEASE information of a given host.

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

Returns the next service of given host.

bool
otSrpServerServiceIsDeleted(const otSrpServerService *aService)

Indicates whether or not the SRP service has been deleted.

const char *
otSrpServerServiceGetInstanceName(const otSrpServerService *aService)

Returns the full service instance name of the service.

bool
otSrpServerServiceMatchesInstanceName(const otSrpServerService *aService, const char *aInstanceName)

Indicates whether this service matches a given service instance name.

const char *
otSrpServerServiceGetInstanceLabel(const otSrpServerService *aService)

Returns the service instance label (first label in instance name) of the service.

const char *
otSrpServerServiceGetServiceName(const otSrpServerService *aService)

Returns the full service name of the service.

bool
otSrpServerServiceMatchesServiceName(const otSrpServerService *aService, const char *aServiceName)

Indicates whether this service matches a given service name.

uint16_t
otSrpServerServiceGetNumberOfSubTypes(const otSrpServerService *aService)

Gets the number of sub-types of the service.

const char *
otSrpServerServiceGetSubTypeServiceNameAt(const otSrpServerService *aService, uint16_t aIndex)

Gets the sub-type service name (full name) of the service at a given index.

bool
otSrpServerServiceHasSubTypeServiceName(const otSrpServerService *aService, const char *aSubTypeServiceName)

Indicates whether or not the service has a given sub-type.

otSrpServerParseSubTypeServiceName(const char *aSubTypeServiceName, char *aLabel, uint8_t aLabelSize)

Parses a sub-type service name (full name) and extracts the sub-type label.

uint16_t
otSrpServerServiceGetPort(const otSrpServerService *aService)

Returns the port of the service instance.

uint16_t
otSrpServerServiceGetWeight(const otSrpServerService *aService)

Returns the weight of the service instance.

uint16_t
otSrpServerServiceGetPriority(const otSrpServerService *aService)

Returns the priority of the service instance.

uint32_t
otSrpServerServiceGetTtl(const otSrpServerService *aService)

Returns the TTL of the service instance.

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

Returns the TXT record data of the service instance.

otSrpServerServiceGetHost(const otSrpServerService *aService)

Returns the host which the service instance reside on.

void
otSrpServerServiceGetLeaseInfo(const otSrpServerService *aService, otSrpServerLeaseInfo *aLeaseInfo)

Returns the LEASE and KEY-LEASE information of a given service.

Enumeration Documentation#

otSrpClientItemState#

otSrpClientItemState

Specifies an SRP client item (service or host info) state.

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


Definition at line 57 of file include/openthread/srp_client.h

otSrpServerState#

otSrpServerState

Represents the state of the SRP server.

Enumerator
OT_SRP_SERVER_STATE_DISABLED

The SRP server is disabled.

OT_SRP_SERVER_STATE_RUNNING

The SRP server is enabled and running.

OT_SRP_SERVER_STATE_STOPPED

The SRP server is enabled but stopped.


Definition at line 75 of file include/openthread/srp_server.h

otSrpServerAddressMode#

otSrpServerAddressMode

Represents the address mode used by the SRP server.

Address mode specifies how the address and port number are determined by the SRP server and how this info is published in the Thread Network Data.

Enumerator
OT_SRP_SERVER_ADDRESS_MODE_UNICAST

Unicast address mode.

OT_SRP_SERVER_ADDRESS_MODE_ANYCAST

Anycast address mode.


Definition at line 88 of file include/openthread/srp_server.h

Typedef Documentation#

otSrpClientHostInfo#

typedef struct otSrpClientHostInfo otSrpClientHostInfo

Represents an SRP client host info.


Definition at line 79 of file include/openthread/srp_client.h

otSrpClientService#

typedef struct otSrpClientService otSrpClientService

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

The mState, mData, mNext fields are used/managed by OT core only. Their value is ignored when an instance of otSrpClientService is passed in otSrpClientAddService() or otSrpClientRemoveService() or other functions. The caller does not need to set these fields.

The mLease and mKeyLease fields specify the desired lease and key lease intervals for this service. Zero value indicates that the interval is unspecified and then the default lease or key lease intervals from otSrpClientGetLeaseInterval() and otSrpClientGetKeyLeaseInterval() are used for this service. If the key lease interval (whether set explicitly or determined from the default) is shorter than the lease interval for a service, SRP client will re-use the lease interval value for key lease interval as well. For example, if in service mLease is explicitly set to 2 days and mKeyLease is set to zero and default key lease is set to 1 day, then when registering this service, the requested key lease for this service is also set to 2 days.


Definition at line 115 of file include/openthread/srp_client.h

otSrpClientCallback#

typedef void(* otSrpClientCallback) (otError aError, const otSrpClientHostInfo *aHostInfo, const otSrpClientService *aServices, const otSrpClientService *aRemovedServices, void *aContext) )(otError aError, const otSrpClientHostInfo *aHostInfo, const otSrpClientService *aServices, const otSrpClientService *aRemovedServices, void *aContext)

Pointer type defines the callback used by SRP client to notify user of changes/events/errors.

Parameters
[in]aError

The error (see above).

[in]aHostInfo

A pointer to host info.

[in]aServices

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

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


Definition at line 171 of file include/openthread/srp_client.h

otSrpClientAutoStartCallback#

typedef void(* otSrpClientAutoStartCallback) (const otSockAddr *aServerSockAddr, void *aContext) )(const otSockAddr *aServerSockAddr, void *aContext)

Pointer type defines the callback used by SRP client to notify user when it is auto-started or stopped.

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

[in]aContext

A pointer to an arbitrary context (provided when callback was registered).

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.


Definition at line 189 of file include/openthread/srp_client.h

otSrpClientBuffersServiceEntry#

typedef struct otSrpClientBuffersServiceEntry otSrpClientBuffersServiceEntry

Represents a SRP client service pool entry.


Definition at line 63 of file include/openthread/srp_client_buffers.h

otSrpServerHost#

typedef struct otSrpServerHost otSrpServerHost

This opaque type represents a SRP service host.


Definition at line 60 of file include/openthread/srp_server.h

otSrpServerService#

typedef struct otSrpServerService otSrpServerService

This opaque type represents a SRP service.


Definition at line 65 of file include/openthread/srp_server.h

otSrpServerServiceUpdateId#

typedef uint32_t otSrpServerServiceUpdateId

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


Definition at line 70 of file include/openthread/srp_server.h

otSrpServerAddressMode#

typedef enum otSrpServerAddressMode otSrpServerAddressMode

Represents the address mode used by the SRP server.

Address mode specifies how the address and port number are determined by the SRP server and how this info is published in the Thread Network Data.


Definition at line 92 of file include/openthread/srp_server.h

otSrpServerTtlConfig#

typedef struct otSrpServerTtlConfig otSrpServerTtlConfig

Includes SRP server TTL configurations.


Definition at line 101 of file include/openthread/srp_server.h

otSrpServerLeaseConfig#

typedef struct otSrpServerLeaseConfig otSrpServerLeaseConfig

Includes SRP server LEASE and KEY-LEASE configurations.


Definition at line 112 of file include/openthread/srp_server.h

otSrpServerLeaseInfo#

typedef struct otSrpServerLeaseInfo otSrpServerLeaseInfo

Includes SRP server lease information of a host/service.


Definition at line 123 of file include/openthread/srp_server.h

otSrpServerResponseCounters#

typedef struct otSrpServerResponseCounters otSrpServerResponseCounters

Includes the statistics of SRP server responses.


Definition at line 136 of file include/openthread/srp_server.h

otSrpServerServiceUpdateHandler#

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

Handles SRP service updates.

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.

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.

See Also


Definition at line 347 of file include/openthread/srp_server.h

Function Documentation#

otSrpClientStart#

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

Starts the SRP client operation.

Parameters
[in]aInstance

A pointer to the OpenThread instance.

[in]aServerSockAddr

The socket address (IPv6 address and port number) of the SRP server.

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


Definition at line 215 of file include/openthread/srp_client.h

otSrpClientStop#

void otSrpClientStop (otInstance * aInstance)

Stops the SRP client operation.

Parameters
[in]aInstance

A pointer to the OpenThread instance.

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.


Definition at line 225 of file include/openthread/srp_client.h

otSrpClientIsRunning#

bool otSrpClientIsRunning (otInstance * aInstance)

Indicates whether the SRP client is running or not.

Parameters
[in]aInstance

A pointer to the OpenThread instance.

Returns

  • TRUE if the SRP client is running, FALSE otherwise.


Definition at line 234 of file include/openthread/srp_client.h

otSrpClientGetServerAddress#

const otSockAddr * otSrpClientGetServerAddress (otInstance * aInstance)

Gets the socket address (IPv6 address and port number) of the SRP server which is being used by SRP client.

Parameters
[in]aInstance

A pointer to the OpenThread instance.

If the client is not running, the address is unspecified (all zero) with zero port number.

Returns

  • A pointer to the SRP server's socket address (is always non-NULL).


Definition at line 246 of file include/openthread/srp_client.h

otSrpClientSetCallback#

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

Sets the callback to notify caller of events/changes from SRP client.

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.

The SRP client allows a single callback to be registered. So consecutive calls to this function will overwrite any previously set callback functions.


Definition at line 258 of file include/openthread/srp_client.h

otSrpClientEnableAutoStartMode#

void otSrpClientEnableAutoStartMode (otInstance * aInstance, otSrpClientAutoStartCallback aCallback, void * aContext)

Enables the auto-start mode.

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.

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 to discover SRP servers and select the preferred server and automatically start and stop the client when an SRP server is detected.

There are three categories of Network Data entries indicating presence of SRP sever. They are preferred in the following order:

1) Preferred unicast entries where server address is included in the service data. If there are multiple options, the one with numerically lowest IPv6 address is preferred.

2) Anycast entries each having a seq number. A larger sequence number in the sense specified by Serial Number Arithmetic logic in RFC-1982 is considered more recent and therefore preferred. The largest seq number using serial number arithmetic is preferred if it is well-defined (i.e., the seq number is larger than all other seq numbers). If it is not well-defined, then the numerically largest seq number is preferred.

3) Unicast entries where the server address info is included in server data. If there are multiple options, the one with numerically lowest IPv6 address is preferred.

When there is a change in the Network Data entries, client will check that the currently selected server is still present in the Network Data and is still the preferred one. Otherwise the client will switch to the new preferred server or stop if there is none.

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.


Definition at line 298 of file include/openthread/srp_client.h

otSrpClientDisableAutoStartMode#

void otSrpClientDisableAutoStartMode (otInstance * aInstance)

Disables the auto-start mode.

Parameters
[in]aInstance

A pointer to the OpenThread instance.

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.


Definition at line 312 of file include/openthread/srp_client.h

otSrpClientIsAutoStartModeEnabled#

bool otSrpClientIsAutoStartModeEnabled (otInstance * aInstance)

Indicates the current state of auto-start mode (enabled or disabled).

Parameters
[in]aInstance

A pointer to the OpenThread instance.

This is only available when auto-start feature OPENTHREAD_CONFIG_SRP_CLIENT_AUTO_START_API_ENABLE is enabled.

Returns

  • TRUE if the auto-start mode is enabled, FALSE otherwise.


Definition at line 323 of file include/openthread/srp_client.h

otSrpClientGetTtl#

uint32_t otSrpClientGetTtl (otInstance * aInstance)

Gets the TTL value in every record included in SRP update requests.

Parameters
[in]aInstance

A pointer to the OpenThread instance.

Note that this is the TTL requested by the SRP client. The server may choose to accept a different TTL.

By default, the TTL will equal the lease interval. Passing 0 or a value larger than the lease interval via otSrpClientSetTtl() will also cause the TTL to equal the lease interval.

Returns

  • The TTL (in seconds).


Definition at line 337 of file include/openthread/srp_client.h

otSrpClientSetTtl#

void otSrpClientSetTtl (otInstance * aInstance, uint32_t aTtl)

Sets the TTL value in every record included in SRP update requests.

Parameters
[in]aInstance

A pointer to the OpenThread instance.

[in]aTtl

The TTL (in seconds). If value is zero or greater than lease interval, the TTL is set to the lease interval.

Changing the TTL does not impact the TTL of already registered services/host-info. It only affects future SRP update messages (i.e., adding new services and/or refreshes of the existing services).


Definition at line 349 of file include/openthread/srp_client.h

otSrpClientGetLeaseInterval#

uint32_t otSrpClientGetLeaseInterval (otInstance * aInstance)

Gets the default lease interval used in SRP update requests.

Parameters
[in]aInstance

A pointer to the OpenThread instance.

The default interval is used only for otSrpClientService instances with mLease set to zero.

Note that this is the lease duration requested by the SRP client. The server may choose to accept a different lease interval.

Returns

  • The lease interval (in seconds).


Definition at line 363 of file include/openthread/srp_client.h

otSrpClientSetLeaseInterval#

void otSrpClientSetLeaseInterval (otInstance * aInstance, uint32_t aInterval)

Sets the default lease interval used in SRP update requests.

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.

The default interval is used only for otSrpClientService instances with mLease set to zero.

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


Definition at line 377 of file include/openthread/srp_client.h

otSrpClientGetKeyLeaseInterval#

uint32_t otSrpClientGetKeyLeaseInterval (otInstance * aInstance)

Gets the default key lease interval used in SRP update requests.

Parameters
[in]aInstance

A pointer to the OpenThread instance.

The default interval is used only for otSrpClientService instances with mKeyLease set to zero.

Note that this is the lease duration requested by the SRP client. The server may choose to accept a different lease interval.

Returns

  • The key lease interval (in seconds).


Definition at line 391 of file include/openthread/srp_client.h

otSrpClientSetKeyLeaseInterval#

void otSrpClientSetKeyLeaseInterval (otInstance * aInstance, uint32_t aInterval)

Sets the default key lease interval used in SRP update requests.

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.

The default interval is used only for otSrpClientService instances with mKeyLease set to zero.

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


Definition at line 405 of file include/openthread/srp_client.h

otSrpClientGetHostInfo#

const otSrpClientHostInfo * otSrpClientGetHostInfo (otInstance * aInstance)

Gets the host info.

Parameters
[in]aInstance

A pointer to the OpenThread instance.

Returns

  • A pointer to host info structure.


Definition at line 414 of file include/openthread/srp_client.h

otSrpClientSetHostName#

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

Sets the host name label.

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.

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


Definition at line 436 of file include/openthread/srp_client.h

otSrpClientEnableAutoHostAddress#

otError otSrpClientEnableAutoHostAddress (otInstance * aInstance)

Enables auto host address mode.

Parameters
N/AaInstance

When enabled host IPv6 addresses are automatically set by SRP client using all the preferred unicast addresses on Thread netif excluding all link-local and mesh-local addresses. If there is no preferred address, then Mesh Local EID address is added. The SRP client will automatically re-register when/if addresses on Thread netif are updated (new addresses are added or existing addresses are removed or marked as non-preferred).

The auto host address mode can be enabled before start or during operation of SRP client except when the host info is being removed (client is busy handling a remove request from an call to otSrpClientRemoveHostAndServices() and host info still being in either STATE_TO_REMOVE or STATE_REMOVING states).

After auto host address mode is enabled, it can be disabled by a call to otSrpClientSetHostAddresses() which then explicitly sets the host addresses.


Definition at line 456 of file include/openthread/srp_client.h

otSrpClientSetHostAddresses#

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

Sets/updates the list of host IPv6 address.

Parameters
[in]aInstance

A pointer to the OpenThread instance.

[in]aIp6Addresses

A pointer to the an array containing the host IPv6 addresses.

[in]aNumAddresses

The number of addresses in the aIp6Addresses array.

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

Calling this function disables auto host address mode if it was previously enabled from a successful call to otSrpClientEnableAutoHostAddress().


Definition at line 484 of file include/openthread/srp_client.h

otSrpClientAddService#

otError otSrpClientAddService (otInstance * aInstance, otSrpClientService * aService)

Adds a service to be registered with server.

Parameters
[in]aInstance

A pointer to the OpenThread instance.

[in]aService

A pointer to a otSrpClientService instance to add.

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

  • It is removed explicitly by a call to otSrpClientRemoveService() or removed along with other services by a call to otSrpClientRemoveHostAndServices() and only after theotSrpClientCallback` is called indicating the service was removed. Or,

  • A call to otSrpClientClearHostAndServices() which removes the host and all related services immediately.


Definition at line 510 of file include/openthread/srp_client.h

otSrpClientRemoveService#

otError otSrpClientRemoveService (otInstance * aInstance, otSrpClientService * aService)

Requests a service to be unregistered with server.

Parameters
[in]aInstance

A pointer to the OpenThread instance.

[in]aService

A pointer to a otSrpClientService instance to remove.

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.


Definition at line 530 of file include/openthread/srp_client.h

otSrpClientClearService#

otError otSrpClientClearService (otInstance * aInstance, otSrpClientService * aService)

Clears a service, immediately removing it from the client service list.

Parameters
[in]aInstance

A pointer to the OpenThread instance.

[in]aService

A pointer to a otSrpClientService instance to delete.

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 aService entry can be reclaimed and re-used by the caller immediately.

Can be used along with a subsequent call to otSrpClientAddService() (potentially reusing the same aService entry with the same service and instance names) to update some of the parameters in an existing service.


Definition at line 549 of file include/openthread/srp_client.h

otSrpClientGetServices#

const otSrpClientService * otSrpClientGetServices (otInstance * aInstance)

Gets the list of services being managed by client.

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.


Definition at line 558 of file include/openthread/srp_client.h

otSrpClientRemoveHostAndServices#

otError otSrpClientRemoveHostAndServices (otInstance * aInstance, bool aRemoveKeyLease, bool aSendUnregToServer)

Starts the remove process of the host info and all services.

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.

[in]aSendUnregToServer

A boolean indicating whether to send update to server when host info is not registered.

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

The aSendUnregToServer determines the behavior when the host info is not yet registered with the server. If 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 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 aSendUnregToServer does not matter and the SRP client will always send an update message to server requesting removal of all info.

One situation where 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.


Definition at line 590 of file include/openthread/srp_client.h

otSrpClientClearHostAndServices#

void otSrpClientClearHostAndServices (otInstance * aInstance)

Clears all host info and all the services.

Parameters
[in]aInstance

A pointer to the OpenThread instance.

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.


Definition at line 600 of file include/openthread/srp_client.h

otSrpClientGetDomainName#

const char * otSrpClientGetDomainName (otInstance * aInstance)

Gets the domain name being used by SRP client.

Parameters
[in]aInstance

A pointer to the OpenThread instance.

Requires OPENTHREAD_CONFIG_SRP_CLIENT_DOMAIN_NAME_API_ENABLE to be enabled.

If domain name is not set, "default.service.arpa" will be used.

Returns

  • The domain name string.


Definition at line 613 of file include/openthread/srp_client.h

otSrpClientSetDomainName#

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

Sets the domain name to be used by SRP client.

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

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


Definition at line 634 of file include/openthread/srp_client.h

otSrpClientItemStateToString#

const char * otSrpClientItemStateToString (otSrpClientItemState aItemState)

Converts a otSrpClientItemState to a string.

Parameters
[in]aItemState

An item state.

Returns

  • A string representation of aItemState.


Definition at line 643 of file include/openthread/srp_client.h

otSrpClientSetServiceKeyRecordEnabled#

void otSrpClientSetServiceKeyRecordEnabled (otInstance * aInstance, bool aEnabled)

Enables/disables "service key record inclusion" mode.

Parameters
[in]aInstance

A pointer to the OpenThread instance.

[in]aEnabled

TRUE to enable, FALSE to disable the "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.

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.


Definition at line 660 of file include/openthread/srp_client.h

otSrpClientIsServiceKeyRecordEnabled#

bool otSrpClientIsServiceKeyRecordEnabled (otInstance * aInstance)

Indicates whether the "service key record inclusion" mode is enabled or disabled.

Parameters
[in]aInstance

A pointer to the OpenThread instance.

Is available when OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE configuration is enabled.

Returns

  • TRUE if "service key record inclusion" mode is enabled, FALSE otherwise.


Definition at line 671 of file include/openthread/srp_client.h

otSrpClientBuffersGetHostNameString#

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

Gets the string buffer to use for SRP client host name.

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.


Definition at line 74 of file include/openthread/srp_client_buffers.h

otSrpClientBuffersGetHostAddressesArray#

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

Gets the array of IPv6 address entries to use as SRP client host address list.

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


Definition at line 85 of file include/openthread/srp_client_buffers.h

otSrpClientBuffersAllocateService#

otSrpClientBuffersServiceEntry * otSrpClientBuffersAllocateService (otInstance * aInstance)

Allocates a new service entry from the pool.

Parameters
[in]aInstance

A pointer to the OpenThread instance.

The returned service entry instance will be initialized as follows:

  • mService.mName will point to an allocated string buffer which can be retrieved using the function otSrpClientBuffersGetServiceEntryServiceNameString().

  • mService.mInstanceName will point to an allocated string buffer which can be retrieved using the function otSrpClientBuffersGetServiceEntryInstanceNameString().

  • mService.mSubTypeLabels points to an array that is returned from otSrpClientBuffersGetSubTypeLabelsArray().

  • mService.mTxtEntries will point to mTxtEntry.

  • mService.mNumTxtEntries will be set to one.

  • Other mService fields (port, priority, weight) are set to zero.

  • mTxtEntry.mKey is set to NULL (value is treated as already encoded).

  • mTxtEntry.mValue will point to an allocated buffer which can be retrieved using the function otSrpClientBuffersGetServiceEntryTxtBuffer().

  • mTxtEntry.mValueLength is set to zero.

  • All related data/string buffers and arrays are cleared to all zero.

Returns

  • A pointer to the newly allocated service entry or NULL if not more entry available in the pool.


Definition at line 110 of file include/openthread/srp_client_buffers.h

otSrpClientBuffersFreeService#

void otSrpClientBuffersFreeService (otInstance * aInstance, otSrpClientBuffersServiceEntry * aService)

Frees a previously allocated service entry.

Parameters
[in]aInstance

A pointer to the OpenThread instance.

[in]aService

A pointer to the service entry to free (MUST NOT be NULL).

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


Definition at line 121 of file include/openthread/srp_client_buffers.h

otSrpClientBuffersFreeAllServices#

void otSrpClientBuffersFreeAllServices (otInstance * aInstance)

Frees all previously allocated service entries.

Parameters
[in]aInstance

A pointer to the OpenThread instance.


Definition at line 128 of file include/openthread/srp_client_buffers.h

otSrpClientBuffersGetServiceEntryServiceNameString#

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

Gets the string buffer for service name from a service entry.

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.


Definition at line 139 of file include/openthread/srp_client_buffers.h

otSrpClientBuffersGetServiceEntryInstanceNameString#

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

Gets the string buffer for service instance name from a service entry.

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.


Definition at line 150 of file include/openthread/srp_client_buffers.h

otSrpClientBuffersGetServiceEntryTxtBuffer#

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

Gets the buffer for TXT record from a service entry.

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.


Definition at line 160 of file include/openthread/srp_client_buffers.h

otSrpClientBuffersGetSubTypeLabelsArray#

const char ** otSrpClientBuffersGetSubTypeLabelsArray (otSrpClientBuffersServiceEntry * aEntry, uint16_t * aArrayLength)

Gets the array for service subtype labels from the service entry.

Parameters
[in]aEntry

A pointer to a previously allocated service entry (MUST NOT be NULL).

[out]aArrayLength

A pointer to a variable to return the array length (MUST NOT be NULL).

Returns

  • A pointer to the array.


Definition at line 170 of file include/openthread/srp_client_buffers.h

otSrpServerGetDomain#

const char * otSrpServerGetDomain (otInstance * aInstance)

Returns the domain authorized to the SRP server.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

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.

Returns

  • A pointer to the dot-joined domain string.


Definition at line 148 of file include/openthread/srp_server.h

otSrpServerSetDomain#

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

Sets the domain on the SRP server.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aDomain

The domain to be set. MUST NOT be NULL.

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


Definition at line 164 of file include/openthread/srp_server.h

otSrpServerGetState#

otSrpServerState otSrpServerGetState (otInstance * aInstance)

Returns the state of the SRP server.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

Returns

  • The current state of the SRP server.


Definition at line 173 of file include/openthread/srp_server.h

otSrpServerGetPort#

uint16_t otSrpServerGetPort (otInstance * aInstance)

Returns the port the SRP server is listening to.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

Returns

  • The port of the SRP server. It returns 0 if the server is not running.


Definition at line 182 of file include/openthread/srp_server.h

otSrpServerGetAddressMode#

otSrpServerAddressMode otSrpServerGetAddressMode (otInstance * aInstance)

Returns the address mode being used by the SRP server.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

Returns

  • The SRP server's address mode.


Definition at line 191 of file include/openthread/srp_server.h

otSrpServerSetAddressMode#

otError otSrpServerSetAddressMode (otInstance * aInstance, otSrpServerAddressMode aMode)

Sets the address mode to be used by the SRP server.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aMode

The address mode to use.


Definition at line 202 of file include/openthread/srp_server.h

otSrpServerGetAnycastModeSequenceNumber#

uint8_t otSrpServerGetAnycastModeSequenceNumber (otInstance * aInstance)

Returns the sequence number used with anycast address mode.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

The sequence number is included in "DNS/SRP Service Anycast Address" entry published in the Network Data.

Returns

  • The anycast sequence number.


Definition at line 213 of file include/openthread/srp_server.h

otSrpServerSetAnycastModeSequenceNumber#

otError otSrpServerSetAnycastModeSequenceNumber (otInstance * aInstance, uint8_t aSequenceNumber)

Sets the sequence number used with anycast address mode.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aSequenceNumber

The sequence number to use.


Definition at line 224 of file include/openthread/srp_server.h

otSrpServerSetEnabled#

void otSrpServerSetEnabled (otInstance * aInstance, bool aEnabled)

Enables/disables the SRP server.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aEnabled

A boolean to enable/disable the SRP server.

On a Border Router, it is recommended to use otSrpServerSetAutoEnableMode() instead.


Definition at line 234 of file include/openthread/srp_server.h

otSrpServerSetAutoEnableMode#

void otSrpServerSetAutoEnableMode (otInstance * aInstance, bool aEnabled)

Enables/disables the auto-enable mode on SRP server.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aEnabled

A boolean to enable/disable the auto-enable mode.

Requires OPENTHREAD_CONFIG_BORDER_ROUTING_ENABLE feature.

When this mode is enabled, the Border Routing Manager controls if/when to enable or disable the SRP server. SRP sever is auto-enabled if/when Border Routing is started and it is done with the initial prefix and route configurations (when the OMR and on-link prefixes are determined, advertised in emitted Router Advertisement message on infrastructure side and published in the Thread Network Data). The SRP server is auto-disabled if/when BR is stopped (e.g., if the infrastructure network interface is brought down or if BR gets detached).

This mode can be disabled by a otSrpServerSetAutoEnableMode() call with aEnabled set to false or if the SRP server is explicitly enabled or disabled by a call to otSrpServerSetEnabled() function. Disabling auto-enable mode using otSrpServerSetAutoEnableMode(false) will not change the current state of SRP sever (e.g., if it is enabled it stays enabled).


Definition at line 255 of file include/openthread/srp_server.h

otSrpServerIsAutoEnableMode#

bool otSrpServerIsAutoEnableMode (otInstance * aInstance)

Indicates whether the auto-enable mode is enabled or disabled.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

Requires OPENTHREAD_CONFIG_BORDER_ROUTING_ENABLE feature.


Definition at line 267 of file include/openthread/srp_server.h

otSrpServerGetTtlConfig#

void otSrpServerGetTtlConfig (otInstance * aInstance, otSrpServerTtlConfig * aTtlConfig)

Returns SRP server TTL configuration.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[out]aTtlConfig

A pointer to an otSrpServerTtlConfig instance.


Definition at line 275 of file include/openthread/srp_server.h

otSrpServerSetTtlConfig#

otError otSrpServerSetTtlConfig (otInstance * aInstance, const otSrpServerTtlConfig * aTtlConfig)

Sets SRP server TTL configuration.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aTtlConfig

A pointer to an otSrpServerTtlConfig instance.

The granted TTL will always be no greater than the max lease interval configured via otSrpServerSetLeaseConfig(), regardless of the minimum and maximum TTL configuration.


Definition at line 289 of file include/openthread/srp_server.h

otSrpServerGetLeaseConfig#

void otSrpServerGetLeaseConfig (otInstance * aInstance, otSrpServerLeaseConfig * aLeaseConfig)

Returns SRP server LEASE and KEY-LEASE configurations.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[out]aLeaseConfig

A pointer to an otSrpServerLeaseConfig instance.


Definition at line 297 of file include/openthread/srp_server.h

otSrpServerSetLeaseConfig#

otError otSrpServerSetLeaseConfig (otInstance * aInstance, const otSrpServerLeaseConfig * aLeaseConfig)

Sets SRP server LEASE and KEY-LEASE configurations.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aLeaseConfig

A pointer to an otSrpServerLeaseConfig instance.

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.


Definition at line 313 of file include/openthread/srp_server.h

otSrpServerSetServiceUpdateHandler#

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

Sets the SRP service updates handler on SRP server.

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.


Definition at line 360 of file include/openthread/srp_server.h

otSrpServerHandleServiceUpdateResult#

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

Reports the result of processing a SRP update to the SRP server.

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.

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


Definition at line 376 of file include/openthread/srp_server.h

otSrpServerGetNextHost#

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

Returns the next registered host on the SRP server.

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.


Definition at line 386 of file include/openthread/srp_server.h

otSrpServerGetResponseCounters#

const otSrpServerResponseCounters * otSrpServerGetResponseCounters (otInstance * aInstance)

Returns the response counters of the SRP server.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

Returns

  • A pointer to the response counters of the SRP server.


Definition at line 395 of file include/openthread/srp_server.h

otSrpServerHostIsDeleted#

bool otSrpServerHostIsDeleted (const otSrpServerHost * aHost)

Tells if the SRP service host has been deleted.

Parameters
[in]aHost

A pointer to the SRP service host.

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.

Returns

  • TRUE if the host has been deleted, FALSE if not.


Definition at line 407 of file include/openthread/srp_server.h

otSrpServerHostGetFullName#

const char * otSrpServerHostGetFullName (const otSrpServerHost * aHost)

Returns the full name of the host.

Parameters
[in]aHost

A pointer to the SRP service host.

Returns

  • A pointer to the null-terminated host name string.


Definition at line 416 of file include/openthread/srp_server.h

otSrpServerHostMatchesFullName#

bool otSrpServerHostMatchesFullName (const otSrpServerHost * aHost, const char * aFullName)

Indicates whether the host matches a given host name.

Parameters
[in]aHost

A pointer to the SRP service host.

[in]aFullName

A full host name.

DNS name matches are performed using a case-insensitive string comparison (i.e., "Abc" and "aBc" are considered to be the same).


Definition at line 430 of file include/openthread/srp_server.h

otSrpServerHostGetAddresses#

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

Returns the addresses of given host.

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.


Definition at line 440 of file include/openthread/srp_server.h

otSrpServerHostGetLeaseInfo#

void otSrpServerHostGetLeaseInfo (const otSrpServerHost * aHost, otSrpServerLeaseInfo * aLeaseInfo)

Returns the LEASE and KEY-LEASE information of a given host.

Parameters
[in]aHost

A pointer to the SRP server host.

[out]aLeaseInfo

A pointer to where to output the LEASE and KEY-LEASE information.


Definition at line 448 of file include/openthread/srp_server.h

otSrpServerHostGetNextService#

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

Returns the next service of given host.

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.


Definition at line 458 of file include/openthread/srp_server.h

otSrpServerServiceIsDeleted#

bool otSrpServerServiceIsDeleted (const otSrpServerService * aService)

Indicates whether or not the SRP service has been deleted.

Parameters
[in]aService

A pointer to the SRP service.

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.

Returns

  • TRUE if the service has been deleted, FALSE if not.


Definition at line 472 of file include/openthread/srp_server.h

otSrpServerServiceGetInstanceName#

const char * otSrpServerServiceGetInstanceName (const otSrpServerService * aService)

Returns the full service instance name of the service.

Parameters
[in]aService

A pointer to the SRP service.

Returns

  • A pointer to the null-terminated service instance name string.


Definition at line 481 of file include/openthread/srp_server.h

otSrpServerServiceMatchesInstanceName#

bool otSrpServerServiceMatchesInstanceName (const otSrpServerService * aService, const char * aInstanceName)

Indicates whether this service matches a given service instance name.

Parameters
[in]aService

A pointer to the SRP service.

[in]aInstanceName

The service instance name.

DNS name matches are performed using a case-insensitive string comparison (i.e., "Abc" and "aBc" are considered to be the same).


Definition at line 495 of file include/openthread/srp_server.h

otSrpServerServiceGetInstanceLabel#

const char * otSrpServerServiceGetInstanceLabel (const otSrpServerService * aService)

Returns the service instance label (first label in instance name) of the service.

Parameters
[in]aService

A pointer to the SRP service.

Returns

  • A pointer to the null-terminated service instance label string..


Definition at line 504 of file include/openthread/srp_server.h

otSrpServerServiceGetServiceName#

const char * otSrpServerServiceGetServiceName (const otSrpServerService * aService)

Returns the full service name of the service.

Parameters
[in]aService

A pointer to the SRP service.

Returns

  • A pointer to the null-terminated service name string.


Definition at line 513 of file include/openthread/srp_server.h

otSrpServerServiceMatchesServiceName#

bool otSrpServerServiceMatchesServiceName (const otSrpServerService * aService, const char * aServiceName)

Indicates whether this service matches a given service name.

Parameters
[in]aService

A pointer to the SRP service.

[in]aServiceName

The service name.

DNS name matches are performed using a case-insensitive string comparison (i.e., "Abc" and "aBc" are considered to be the same).


Definition at line 527 of file include/openthread/srp_server.h

otSrpServerServiceGetNumberOfSubTypes#

uint16_t otSrpServerServiceGetNumberOfSubTypes (const otSrpServerService * aService)

Gets the number of sub-types of the service.

Parameters
[in]aService

A pointer to the SRP service.

Returns

  • The number of sub-types of aService.


Definition at line 536 of file include/openthread/srp_server.h

otSrpServerServiceGetSubTypeServiceNameAt#

const char * otSrpServerServiceGetSubTypeServiceNameAt (const otSrpServerService * aService, uint16_t aIndex)

Gets the sub-type service name (full name) of the service at a given index.

Parameters
[in]aService

A pointer to the SRP service.

[in]aIndex

The index to get.

The full service name for a sub-type service follows "<sub-label>._sub.<service-labels>.<domain>.".

Returns

  • A pointer to sub-type service name at aIndex, or NULL if no sub-type at this index.


Definition at line 548 of file include/openthread/srp_server.h

otSrpServerServiceHasSubTypeServiceName#

bool otSrpServerServiceHasSubTypeServiceName (const otSrpServerService * aService, const char * aSubTypeServiceName)

Indicates whether or not the service has a given sub-type.

Parameters
[in]aService

A pointer to the SRP service.

[in]aSubTypeServiceName

The sub-type service name (full name) to check.

DNS name matches are performed using a case-insensitive string comparison (i.e., "Abc" and "aBc" are considered to be the same).


Definition at line 562 of file include/openthread/srp_server.h

otSrpServerParseSubTypeServiceName#

otError otSrpServerParseSubTypeServiceName (const char * aSubTypeServiceName, char * aLabel, uint8_t aLabelSize)

Parses a sub-type service name (full name) and extracts the sub-type label.

Parameters
[in]aSubTypeServiceName

A sub-type service name (full name).

[out]aLabel

A pointer to a buffer to copy the extracted sub-type label.

[in]aLabelSize

Maximum size of aLabel buffer.

The full service name for a sub-type service follows "<sub-label>._sub.<service-labels>.<domain>.".


Definition at line 578 of file include/openthread/srp_server.h

otSrpServerServiceGetPort#

uint16_t otSrpServerServiceGetPort (const otSrpServerService * aService)

Returns the port of the service instance.

Parameters
[in]aService

A pointer to the SRP service.

Returns

  • The port of the service.


Definition at line 587 of file include/openthread/srp_server.h

otSrpServerServiceGetWeight#

uint16_t otSrpServerServiceGetWeight (const otSrpServerService * aService)

Returns the weight of the service instance.

Parameters
[in]aService

A pointer to the SRP service.

Returns

  • The weight of the service.


Definition at line 596 of file include/openthread/srp_server.h

otSrpServerServiceGetPriority#

uint16_t otSrpServerServiceGetPriority (const otSrpServerService * aService)

Returns the priority of the service instance.

Parameters
[in]aService

A pointer to the SRP service.

Returns

  • The priority of the service.


Definition at line 605 of file include/openthread/srp_server.h

otSrpServerServiceGetTtl#

uint32_t otSrpServerServiceGetTtl (const otSrpServerService * aService)

Returns the TTL of the service instance.

Parameters
[in]aService

A pointer to the SRP service.

Returns

  • The TTL of the service instance..


Definition at line 614 of file include/openthread/srp_server.h

otSrpServerServiceGetTxtData#

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

Returns the TXT record data of the service instance.

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


Definition at line 624 of file include/openthread/srp_server.h

otSrpServerServiceGetHost#

const otSrpServerHost * otSrpServerServiceGetHost (const otSrpServerService * aService)

Returns the host which the service instance reside on.

Parameters
[in]aService

A pointer to the SRP service.

Returns

  • A pointer to the host instance.


Definition at line 633 of file include/openthread/srp_server.h

otSrpServerServiceGetLeaseInfo#

void otSrpServerServiceGetLeaseInfo (const otSrpServerService * aService, otSrpServerLeaseInfo * aLeaseInfo)

Returns the LEASE and KEY-LEASE information of a given service.

Parameters
[in]aService

A pointer to the SRP server service.

[out]aLeaseInfo

A pointer to where to output the LEASE and KEY-LEASE information.


Definition at line 641 of file include/openthread/srp_server.h