#include <ContextManagerInterface.h>

Inheritance diagram for alexaClientSDK::avsCommon::sdkInterfaces::ContextManagerInterface:

Public Member Functions
virtual	~ContextManagerInterface ()=default

virtual void	setStateProvider (const avs::CapabilityTag &capabilityIdentifier, std::shared_ptr< StateProviderInterface > stateProvider)=0

virtual void	addStateProvider (const avsCommon::avs::CapabilityTag &capabilityIdentifier, std::shared_ptr< avsCommon::sdkInterfaces::StateProviderInterface > stateProvider)=0

virtual void	removeStateProvider (const avs::CapabilityTag &capabilityIdentifier)=0

virtual SetStateResult	setState (const avs::CapabilityTag &capabilityIdentifier, const std::string &jsonState, const avs::StateRefreshPolicy &refreshPolicy, const ContextRequestToken stateRequestToken=0)=0

virtual void	reportStateChange (const avs::CapabilityTag &capabilityIdentifier, const avs::CapabilityState &capabilityState, AlexaStateChangeCauseType cause)=0

virtual void	provideStateResponse (const avs::CapabilityTag &capabilityIdentifier, const avs::CapabilityState &capabilityState, ContextRequestToken stateRequestToken)=0

virtual void	provideStateUnavailableResponse (const avs::CapabilityTag &capabilityIdentifier, ContextRequestToken stateRequestToken, bool isEndpointUnreachable)=0

virtual ContextRequestToken	getContext (std::shared_ptr< ContextRequesterInterface > contextRequester, const std::string &endpointId="", const std::chrono::milliseconds &timeout=std::chrono::seconds(2))=0

virtual ContextRequestToken	getContextWithoutReportableStateProperties (std::shared_ptr< ContextRequesterInterface > contextRequester, const std::string &endpointId="", const std::chrono::milliseconds &timeout=std::chrono::seconds(2))=0

virtual void	addContextManagerObserver (std::shared_ptr< ContextManagerObserverInterface > observer)=0

virtual void	removeContextManagerObserver (const std::shared_ptr< ContextManagerObserverInterface > &observer)=0

Detailed Description

Interface to get the context and set the state. State refers to the client component's state. Context is a container used to communicate the state of the client components to AVS.

See also: https://developer.amazon.com/docs/alexa/alexa-voice-service/context.html.

Note: Implementations must be thread-safe.

Constructor & Destructor Documentation

◆ ~ContextManagerInterface()

virtual alexaClientSDK::avsCommon::sdkInterfaces::ContextManagerInterface::~ContextManagerInterface ( )

virtualdefault

Destructor.

Member Function Documentation

◆ addContextManagerObserver()

virtual void alexaClientSDK::avsCommon::sdkInterfaces::ContextManagerInterface::addContextManagerObserver ( std::shared_ptr< ContextManagerObserverInterface > observer )

pure virtual

Adds an observer to be notified of context changes.

Parameters

observer The observer to add.

◆ addStateProvider()

virtual void alexaClientSDK::avsCommon::sdkInterfaces::ContextManagerInterface::addStateProvider	(	const avsCommon::avs::CapabilityTag &	capabilityIdentifier,
		std::shared_ptr< avsCommon::sdkInterfaces::StateProviderInterface >	stateProvider
	)

pure virtual

Registers a StateProviderInterface with the ContextManager. When the context manager receives a getContext request, it queries the registered StateProviderInterfaces for updated state, if needed. If a StateProviderInterface tries to register a CapabilityMessageIdentifier that is already present, the older StateProviderInterface will be replaced with the new one.

Parameters

capabilityIdentifier	The capability message identifier of the `StateProviderInterface`.
stateProvider	The `StateProviderInterface` that will be mapped against the `capabilityIdentifier`.

◆ getContext()

virtual ContextRequestToken alexaClientSDK::avsCommon::sdkInterfaces::ContextManagerInterface::getContext	(	std::shared_ptr< ContextRequesterInterface >	contextRequester,
		const std::string &	endpointId = `""`,
		const std::chrono::milliseconds &	timeout = `std::chrono::seconds(2)`
	)

pure virtual

Request the ContextManager for context. If a request to the StateProviderInterfaces for updated states is not in progress, then requests will be sent to the StateProviderInterfaces via the provideState requests. If updated states have already been requested, this @ getContext request will be put on a queue and updated when the head of queue's request arrives. Once updated states are available, the context requester is informed via onContextAvailable. If any error is encountered while updating states, the context requester is informed via onContextFailure with the details of the error.

Note: If you are using RequestToken to track the context response, make sure that the access is synchronized with the onContextAvailable response.

Parameters

contextRequester	The context requester asking for context.
endpointId	The `endpointId` used to select which context is being requested.
timeout	The maximum time this request should take. After the timeout, the context manager will abort the request.

Returns: A token that can be used to correlate this request with the context response.

Warning: An empty endpointId will select the defaultEndpoint context for now. This argument will become required in future versions of the SDK.

◆ getContextWithoutReportableStateProperties()

virtual ContextRequestToken alexaClientSDK::avsCommon::sdkInterfaces::ContextManagerInterface::getContextWithoutReportableStateProperties	(	std::shared_ptr< ContextRequesterInterface >	contextRequester,
		const std::string &	endpointId = `""`,
		const std::chrono::milliseconds &	timeout = `std::chrono::seconds(2)`
	)

pure virtual

Request the ContextManager for context while skipping state from StateProviders which have reportable state properties.

See also: https://developer.amazon.com/en-US/docs/alexa/alexa-voice-service/reportable-state-properties.html

Note: An example use case of when this method can be is used is to get the Context sent in SpeechRecognizer.Recognize event. The reason being, sending all state information can make the context bloated which might adversely effect user perceived latency. Additionally, state from reportable state properties can be sent to the cloud either by using StateReport event or the ChangeReport event.; This method is functionally similar to the getContext() method except that it skips state information of reportable state properties.; If you are using RequestToken to track the context response, make sure that the access is synchronized with the onContextAvailable response.

Parameters

contextRequester	The context requester asking for context.
endpointId	The `endpointId` used to select which context is being requested.
timeout	The maximum time this request should take. After the timeout, the context manager will abort the request.

Returns: A token that can be used to correlate this request with the context response.

Warning: An empty endpointId will select the defaultEndpoint context for now. This argument will become required in future versions of the SDK.

◆ provideStateResponse()

virtual void alexaClientSDK::avsCommon::sdkInterfaces::ContextManagerInterface::provideStateResponse	(	const avs::CapabilityTag &	capabilityIdentifier,
		const avs::CapabilityState &	capabilityState,
		ContextRequestToken	stateRequestToken
	)

pure virtual

Provides the capability state information as a response to provideState request.

When a provideState request is sent to a StateProviderInterface, the ContextManager will provide a stateRequestToken. The same token needs to be sent on a provideState in response to the provideState. If the token sent in the provideState request does not match the token in the ContextManager, the response will be dropped.

Parameters

capabilityIdentifier	Identifies which capability state is being provided.
capabilityState	The new state being provided.
stateRequestToken	The token that was provided in a `provideState` request.

Implemented in alexaClientSDK::contextManager::ContextManager.

◆ provideStateUnavailableResponse()

virtual void alexaClientSDK::avsCommon::sdkInterfaces::ContextManagerInterface::provideStateUnavailableResponse	(	const avs::CapabilityTag &	capabilityIdentifier,
		ContextRequestToken	stateRequestToken,
		bool	isEndpointUnreachable
	)

pure virtual

Response method used to inform that the capability state is not available.

The same token needs to be sent on a setState in response to the provideState. If the token sent in the setState request does not match the token in the ContextManager, setState will return an error.

Parameters

capabilityIdentifier	The capability message identifier of the `StateProviderInterface` whose state is not available.
stateRequestToken	The token that was provided in a `provideState` request.
isEndpointUnreachable	Whether the failure was due to the endpoint being unreachable.

Implemented in alexaClientSDK::contextManager::ContextManager.

◆ removeContextManagerObserver()

virtual void alexaClientSDK::avsCommon::sdkInterfaces::ContextManagerInterface::removeContextManagerObserver ( const std::shared_ptr< ContextManagerObserverInterface > & observer )

pure virtual

Removes an observer from being notified of context changes.

Parameters

observer The observer to remove.

◆ removeStateProvider()

virtual void alexaClientSDK::avsCommon::sdkInterfaces::ContextManagerInterface::removeStateProvider ( const avs::CapabilityTag & capabilityIdentifier )

pure virtual

Remove the state provider for the given capability with the ContextManager.

Parameters

capabilityIdentifier The capability message identifier of the StateProviderInterface.

Implemented in alexaClientSDK::contextManager::ContextManager.

◆ reportStateChange()

virtual void alexaClientSDK::avsCommon::sdkInterfaces::ContextManagerInterface::reportStateChange	(	const avs::CapabilityTag &	capabilityIdentifier,
		const avs::CapabilityState &	capabilityState,
		AlexaStateChangeCauseType	cause
	)

pure virtual

Function used to proactively notify the context manager that the state of a capability has changed.

Parameters

capabilityIdentifier	Identifies which capability has an updated state.
capabilityState	The new state being reported.
cause	The reason for the state change.

Implemented in alexaClientSDK::contextManager::ContextManager.

◆ setState()

virtual SetStateResult alexaClientSDK::avsCommon::sdkInterfaces::ContextManagerInterface::setState	(	const avs::CapabilityTag &	capabilityIdentifier,
		const std::string &	jsonState,
		const avs::StateRefreshPolicy &	refreshPolicy,
		const ContextRequestToken	stateRequestToken = `0`
	)

pure virtual

Sets the state information. The refresh policy indicates to the ContextManager whether on a getContext request the state needs to be updated. If the refreshPolicy is ALWAYS, then the StateProviderInterface needs to be registered with the ContextManager, else setState returns an error.

For the states for which the refresh policy is ALWAYS, the ContextManager requests for provideStates from the StateProviderInterfaces. When a provideState request is sent to a StateProviderInterface, the ContextManager will provide a stateRequestToken. The same token needs to be sent on a setState in response to the provideState. If the token sent in the setState request does not match the token in the ContextManager, setState will return an error.

Deprecated:: Use the provideStateResponse for responding to provideState request and reportStateChange to proactively report to the ContextManager that the state has changed.

Note: Token needs to be set only if the setState is in response to a provideState request. Setting the token to 0 is equivalent to no token.

The jsonState is the json value that is associated with the key "payload".

Parameters

capabilityIdentifier	The capability message identifier of the `StateProviderInterface` whose state is being updated.
jsonState	The state of the `StateProviderInterface`. The `StateProviderInterface` with a `refreshPolicy` of SOMETIMES can pass in an empty string to indicate no contexts needs to be sent by the provider.
refreshPolicy	The refresh policy for the state.
stateRequestToken	The token that was provided in a `provideState` request. Defaults to 0.

Returns: The status of the setState operation.

Implemented in alexaClientSDK::contextManager::ContextManager.

◆ setStateProvider()

virtual void alexaClientSDK::avsCommon::sdkInterfaces::ContextManagerInterface::setStateProvider	(	const avs::CapabilityTag &	capabilityIdentifier,
		std::shared_ptr< StateProviderInterface >	stateProvider
	)

pure virtual

Registers a StateProviderInterface with the ContextManager. When the context manager receives a getContext request, it queries the registered queryable StateProviderInterfaces for updated state. If a StateProviderInterface tries to register a CapabilityMessageIdentifier that is already present, the older StateProviderInterface will be replaced with the new one.

Deprecated:: Use addStateProvider to add or replace the state provider and removeStateProvider to remove a state provider.

Note: If a StateProviderInterface wants to unregister with the ContextManager, then it needs to set the pointer to the StateProviderInterface to a nullptr.

Parameters

capabilityIdentifier	The capability message identifier of the `StateProviderInterface`.
stateProvider	The `StateProviderInterface` that will be mapped against the `capabilityIdentifier`.

The documentation for this class was generated from the following file:

/workplace/avs-device-sdk/AVSCommon/SDKInterfaces/include/AVSCommon/SDKInterfaces/ContextManagerInterface.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~ContextManagerInterface()

Member Function Documentation

◆ addContextManagerObserver()

◆ addStateProvider()

◆ getContext()

◆ getContextWithoutReportableStateProperties()

◆ provideStateResponse()

◆ provideStateUnavailableResponse()

◆ removeContextManagerObserver()

◆ removeStateProvider()

◆ reportStateChange()

◆ setState()

◆ setStateProvider()