nl::Weave::Profiles::ServiceDirectory::WeaveServiceManager

#include <src/lib/profiles/service-directory/ServiceDirectory.h>

The manager object for the Weave service directory.

Summary

The Weave service manager is the main interface for applications to the directory service. As such, it hides the complications inherent in looking up the directory entry associated with a service endpoint, doing DNS lookup on one or more of the host names found there, attempting to connect, securing the connection and so on. It may also manage a cache of service directory information.

Constructors and Destructors
WeaveServiceManager(void)
This method initializes the WeaveServiceManager instance.
~WeaveServiceManager(void)
This method destructs the WeaveServiceManager instance.

Public types
@303{
  kWeave_DefaultSendTimeout = 15000
} 		enum
OnConnectBegin)(struct ServiceConnectBeginArgs &args) nl::Weave::Profiles::ServiceDirectory::WeaveServiceManager::OnConnectBegin
void(*
An application callback made immediately prior to connection establishment.
OnServiceEndpointQueryBegin)(void) nl::Weave::Profiles::ServiceDirectory::WeaveServiceManager::OnServiceEndpointQueryBegin
void(*
An application callback to mark the time of an outgoing service directory query.
OnServiceEndpointQueryEndWithTimeInfo)(uint64_t timeQueryReceiptMsec, uint32_t timeProcessMsec) nl::Weave::Profiles::ServiceDirectory::WeaveServiceManager::OnServiceEndpointQueryEndWithTimeInfo
void(*
An application callback to deliver time values from a service directory response.
RootDirectoryAccessor)(uint8_t *aDirectory, uint16_t aLength) nl::Weave::Profiles::ServiceDirectory::WeaveServiceManager::RootDirectoryAccessor
An accessor function for the root directory info.
StatusHandler)(void *anAppState, WEAVE_ERROR anError, StatusReport *aStatusReport) nl::Weave::Profiles::ServiceDirectory::WeaveServiceManager::StatusHandler
void(*
A handler for error and status conditions.

Public functions
SetConnectBeginCallback(OnConnectBegin aConnectBegin)
void
Set a callback function to be called immediately prior to connection establishment.
cancel(uint64_t aServiceEp, void *aAppState)
void
This method cancels a connect request.
clearCache(void)
void
This method clears the state and cache of the manager if the state is in the terminal kServiceMgrState_Resolved state, which means that response from Service Directory endpoint was received.
connect(uint64_t aServiceEp, WeaveAuthMode aAuthMode, void *aAppState, StatusHandler aStatusHandler, WeaveConnection::ConnectionCompleteFunct aConnectionCompleteHandler, const uint32_t aConnectTimeoutMsecs, const InterfaceId aConnectIntf)
This method requests connect to a Weave service.
init(WeaveExchangeManager *aExchangeMgr, uint8_t *aCache, uint16_t aCacheLen, RootDirectoryAccessor aAccessor, WeaveAuthMode aDirAuthMode, OnServiceEndpointQueryBegin aServiceEndpointQueryBegin, OnServiceEndpointQueryEndWithTimeInfo aServiceEndpointQueryEndWithTimeInfo, OnConnectBegin aConnectBegin)
This method initializes the service manager object.
lookup(uint64_t aServiceEp, HostPortList *outHostPortList)
This method looks up directory information for a service endpoint.
lookup(uint64_t aServiceEp, uint8_t *aControlByte, uint8_t **aDirectoryEntry)
This method looks up directory information for a service endpoint.
onConnectionClosed(WEAVE_ERROR aError)
void
This method handles the connection closed event reported by the associated Weave exchange context.
onConnectionComplete(WEAVE_ERROR aError)
void
This method handles the connect completed event for service endpoint query transaction.
onResponseReceived(uint32_t aProfileId, uint8_t aMsgType, PacketBuffer *aMsg)
void
This method handles any response message in the conversation with directory service.
onResponseTimeout(void)
void
This method handles the timeout event, in which no response was received from directory service.
relocate(WEAVE_ERROR aError)
void
This method relocates the service directory cache.
relocate(void)
void
This method relocates the service directory cache.
replaceOrAddCacheEntry(uint16_t port, const char *hostName, uint8_t hostLen, uint64_t serviceEndpointId)
Add the overriding directory entry of a hostname and port id at the beginning of the directory list.
reset(WEAVE_ERROR aError)
void
This method resets the service manager to its initial state.
reset(void)
void
This method resets the service manager to its initial state.
unresolve(WEAVE_ERROR aError)
void
This method invalidates the service directory cache.
unresolve(void)
void
This method invalidates the service directory cache.

Classes
nl::Weave::Profiles::ServiceDirectory::WeaveServiceManager::ConnectRequest

This class represents a single transaction managed by the service manager.

Public types

@303

 @303
Properties
kWeave_DefaultSendTimeout

Number of milliseconds a response must be received for the directory query before the exchange context times out.

OnConnectBegin

void(* OnConnectBegin)(struct ServiceConnectBeginArgs &args)

An application callback made immediately prior to connection establishment.

This callback can be used by applications to observe and optionally alter the arguments passed to #WeaveConnection::Connect() during the course of establishing a service connection. This callback will be called both for the connection to the target service endpoint, as well as the connection to the Service Directory endpoint in the event that a directory lookup must be performed.

OnServiceEndpointQueryBegin

void(* OnServiceEndpointQueryBegin)(void)

An application callback to mark the time of an outgoing service directory query.

This is called when we are about to send out service endpoint query request. This is used to match with OnServiceEndpointQueryEnd to compensate for message flight time.

OnServiceEndpointQueryEndWithTimeInfo

void(* OnServiceEndpointQueryEndWithTimeInfo)(uint64_t timeQueryReceiptMsec, uint32_t timeProcessMsec)

An application callback to deliver time values from a service directory response.

This is called when we get time information from service directory query response Note this callback would only happen if a response is successfully parsed and time information is included

Details
Parameters
[in] timeQueryReceiptMsec
The number of msec since POSIX epoch, when the query was received at server side.
[in] timeProcessMsec
The number of msec spent on processing this query.

RootDirectoryAccessor

WEAVE_ERROR(* RootDirectoryAccessor)(uint8_t *aDirectory, uint16_t aLength)

An accessor function for the root directory info.

You gotta start somewhere and with the service directory you gotta start with a stub directory that contains the address of a server you can hit to get at everything else. Since the disposition and provenance of this information is likely to vary from device to device, we provide an accessor callback here.

Details
Parameters
[out] aDirectory
A pointer to a buffer to write the directory information.
[in] aLength
The length of the given buffer in bytes.
Returns
WEAVE_NO_ERROR on success, otherwise the loading process would be aborted.

StatusHandler

void(* StatusHandler)(void *anAppState, WEAVE_ERROR anError, StatusReport *aStatusReport)

A handler for error and status conditions.

A user of the service manager may be informed of problems in trying to execute a connect request in one of two ways. It may receive a status report from the service or it may receive an internally generated WEAVE_ERROR. In either case, the information comes through this callback.

Details
Parameters
[in] anAppState
A pointer to an application object that was passed in to the corresponding conect() call.
[in] anError
An Weave error code indicating error happened in the process of trying to execute the connect request. This shall be WEAVE_NO_ERROR in the case where no error arose and a status report is available.
[in] aStatusReport
A pointer to a status report generated by the remote directory service. This argument shall be NULL in the case where there was no status report and an internal error is passed in the previous argument.

Public functions

SetConnectBeginCallback

void SetConnectBeginCallback(
  OnConnectBegin aConnectBegin
)

Set a callback function to be called immediately prior to connection establishment.

Details
Parameters
[in] aConnectBegin
A pointer to the callback function. A value of NULL disables the callback.

WeaveServiceManager

 WeaveServiceManager(
  void
)

This method initializes the WeaveServiceManager instance.

Note that init() must be called to further initialize this instance.

cancel

void cancel(
  uint64_t aServiceEp,
  void *aAppState
)

This method cancels a connect request.

This method cancels a connect request given the service endpoint ID and the application state object passed in at request time as identifiers. If it is the last connect request, this method clears up any pending service directory connection state as well.

Details
Parameters
[in] aServiceEp
The service endpoint ID of the request being canceled.
[in] anAppState
A pointer to the app state object given to the connect() call.

clearCache

void clearCache(
  void
)

This method clears the state and cache of the manager if the state is in the terminal kServiceMgrState_Resolved state, which means that response from Service Directory endpoint was received.

connect

WEAVE_ERROR connect(
  uint64_t aServiceEp,
  WeaveAuthMode aAuthMode,
  void *aAppState,
  StatusHandler aStatusHandler,
  WeaveConnection::ConnectionCompleteFunct aConnectionCompleteHandler,
  const uint32_t aConnectTimeoutMsecs,
  const InterfaceId aConnectIntf
)

This method requests connect to a Weave service.

This is the top-level connect call. It essentially produces a secure connection to the Weave service given a service endpoint and an authentication mode or dies trying.

This method can only be called after successful call to init(), and a connection request can be potentially canceled by cancel().

This method can be called before the local cache is filled with data from either default provisioned data or a trip to the directory service. Service manager would just queue the request before the cache content can be determined.

Details
Parameters
[in] aServiceEp
The service endpoint identifier, as defined in ServiceDirectory.h, for the service of interest.
[in] aAuthMode
The authentication mode to use when connecting to the service of interest.
[in] aAppState
A pointer to an application state object, passed to the callbacks as an argument.
[in] aStatusHandler
A callback to invoke in the case of an error that occurs before the connection is completed.
[in] aConnectionCompleteHandler
A callback to invoke in the case where the requested connection is completed. Note that the connection may fail with an Weave error code.
[in] aConnectTimeoutMsecs
The optional TCP connect timeout in milliseconds.
[in] aConnectIntf
The optional interface over which the connection is to be established.
Returns
WEAVE_NO_ERROR on success; otherwise, a respective error code.

init

WEAVE_ERROR init(
  WeaveExchangeManager *aExchangeMgr,
  uint8_t *aCache,
  uint16_t aCacheLen,
  RootDirectoryAccessor aAccessor,
  WeaveAuthMode aDirAuthMode,
  OnServiceEndpointQueryBegin aServiceEndpointQueryBegin,
  OnServiceEndpointQueryEndWithTimeInfo aServiceEndpointQueryEndWithTimeInfo,
  OnConnectBegin aConnectBegin
)

This method initializes the service manager object.

In order to be used, a service manager object must be initialized. After a successful call to this method, clients can start calling connect(), lookup(), and other methods.

Details
Parameters
[in] aExchangeMgr
A pointer to the exchange manager to use for all service directory profile exchanges.
[in] aCache
A pointer to a buffer which can be used to cache directory information.
[in] aCacheLen
The length in bytes of the cache.
[in] aAccessor
The callback, as defined in ServiceDirectory.h to invoke in order to load the root directory as a starting point for directory lookup.
[in] aDirAuthMode
The authentication mode to use when talking to the directory service.
[in] aServiceEndpointQueryBegin
A function pointer of type OnServiceEndpointQueryBegin, that is called at the start of a service directory request and allows application code to mark the time if it wishes to use the time synchronization offered by the service directory protocol.
[in] aServiceEndpointQueryEndWithTimeInfo
A function pointer of type OnServiceEndpointQueryEndWithTimeInfo, that is called on receipt of a service directory that allows applications to synchronize with the Weave service using the time fields given in the response. This callback would be made after the service manager receives a response with time information. The cache should already be filled successfully before the callback is made.
[in] aConnectBegin
A function pointer of type OnConnectBegin, that is called immediately prior to connection establishment and allows applications to observe and optionally alter the arguments passed to #WeaveConnection::Connect(). A value of NULL (the default) disables the callback.
Returns
WEAVE_ERROR_INVALID_ARGUMENT if a function argument is invalid; otherwise, WEAVE_NO_ERROR.

lookup

WEAVE_ERROR lookup(
  uint64_t aServiceEp,
  HostPortList *outHostPortList
)

This method looks up directory information for a service endpoint.

If the service directory has been resolved, i.e. if there has been a successful connect() operation, then this method will populate the supplied HostPortList object.

Note: The HostPortList is bound to the WeaveServiceManager object; it remains valid until the service directory cache is cleared or until another service directory lookup occurs.

Details
Parameters
[in] aServiceEp
The identifier of the service endpoint to look up.
[out] outHostPortList
The pointer to the HostPortList that will be populated on successful lookup of the directory entry. Must not be NULL.
Return Values
WEAVE_NO_ERROR
on success; otherwise, a respective error code.
WEAVE_ERROR_INVALID_SERVICE_EP
if the given service endpoint is not found.
WEAVE_ERROR_INVALID_DIRECTORY_ENTRY_TYPE
if directory contains an unknown directory entry type.

lookup

WEAVE_ERROR lookup(
  uint64_t aServiceEp,
  uint8_t *aControlByte,
  uint8_t **aDirectoryEntry
)

This method looks up directory information for a service endpoint.

If the service directory has been resolved, i.e. if there has been a successful connect() operation, then this method will return a directory entry given a service endpoint identifier.

This method exposes the details of the internal implementation of the service directory, implementations should strongly favor using the variant of this method that generates the HostPortList.

Details
Parameters
[in] aServiceEp
The identifier of the service endpoint to look up.
[out] aControlByte
A pointer to the place to write the directory entry control byte.
[out] aDirectoryEntry
A pointer-pointer to be directed to the directory entry.
Return Values
WEAVE_NO_ERROR
on success; otherwise, a respective error code.
WEAVE_ERROR_INVALID_SERVICE_EP
if the given service endpoint is not found.
WEAVE_ERROR_INVALID_DIRECTORY_ENTRY_TYPE
if directory contains an unknown directory entry type.

onConnectionClosed

void onConnectionClosed(
  WEAVE_ERROR aError
)

This method handles the connection closed event reported by the associated Weave exchange context.

Details
Parameters
[in] aError
An Weave error indicating the reason for this connection to be closed.

onConnectionComplete

void onConnectionComplete(
  WEAVE_ERROR aError
)

This method handles the connect completed event for service endpoint query transaction.

There are a couple of possibilities. First, the connection could have failed in which case we're done. Otherwise, the connection is actually complete and what we want to do is open an exchange context and send a directory query.

Details
Parameters
[in] aError
An Weave error if there is any error during the connection setup.

onResponseReceived

void onResponseReceived(
  uint32_t aProfileId,
  uint8_t aMsgType,
  PacketBuffer *aMsg
)

This method handles any response message in the conversation with directory service.

Details
Parameters
[in] aProfileId
The profile ID for this incoming message.
[in] aMsgType
The profile-specific type for this message.
[in] aMsg
The content of this message.

onResponseTimeout

void onResponseTimeout(
  void
)

This method handles the timeout event, in which no response was received from directory service.

relocate

void relocate(
  WEAVE_ERROR aError
)

This method relocates the service directory cache.

When a service endpoint returns a status report with status code kStatus_Relocated, the application could call unresolve() to clear up the cache and cancel connection requests. This method simplifies error handling by calling unresolve() in the first time, and reset() if the problem is not resolved yet.

This version of the method - here for backwards compatibility - takes and logs an error then calls relocate(void) .

Details
Parameters
[in] aError
an error to log.
See also:
relocate(void)

relocate

void relocate(
  void
)

This method relocates the service directory cache.

When a service endpoint returns a status report with status code kStatus_Relocated, the application could call unresolve() to clear up the cache and cancel connection requests. This method simplifies error handling by calling unresolve() in the first time, and reset() if the problem is not resolved yet.

See also:
relocate(WEAVE_ERROR)

replaceOrAddCacheEntry

WEAVE_ERROR replaceOrAddCacheEntry(
  uint16_t port,
  const char *hostName,
  uint8_t hostLen,
  uint64_t serviceEndpointId
)

Add the overriding directory entry of a hostname and port id at the beginning of the directory list.

reset

void reset(
  WEAVE_ERROR aError
)

This method resets the service manager to its initial state.

This method resets all service manager states including communications state, cache state, and the state of any pending connect requests.

This version of the method - here for backwards compatibility - takes and logs an error then calls reset(void) .

Details
Parameters
[in] aError
The error that triggered this operation.
See also:
reset(void)

reset

void reset(
  void
)

This method resets the service manager to its initial state.

This method resets all service manager states including communications state, cache state and the state of any pending connect requests.

See also:
reset(WEAVE_ERROR)

unresolve

void unresolve(
  WEAVE_ERROR aError
)

This method invalidates the service directory cache.

This method sets the service directory cache state so that on the next request the service manager will issue a service directory query.

This version of the method - here for backward compatibility - takes and logs an error then calls unresolve(void) .

Details
Parameters
[in] aError
The error that triggered this operation.
See also:
unresolve(void)

unresolve

void unresolve(
  void
)

This method invalidates the service directory cache.

This method sets the service directory cache state so that on the next request the service manager will issue a service directory query.

See also:
unresolve(WEAVE_ERROR)

~WeaveServiceManager

 ~WeaveServiceManager(
  void
)

This method destructs the WeaveServiceManager instance.