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

@252{
  kWeave_DefaultSendTimeout = 15000
}
enum
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

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)
This method initializes the service manager object.
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

@252

 @252
Properties
kWeave_DefaultSendTimeout

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

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

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
)

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.
Returns
WEAVE_ERROR_INVALID_ARGUMENT if a function argument is invalid; otherwise, WEAVE_NO_ERROR.

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.

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.