AlexaClientSDK  1.20.1
A cross-platform, modular SDK for interacting with the Alexa Voice Service
Public Member Functions | List of all members
alexaClientSDK::avsCommon::sdkInterfaces::ContextManagerInterface Class Referenceabstract

#include <ContextManagerInterface.h>

Inheritance diagram for alexaClientSDK::avsCommon::sdkInterfaces::ContextManagerInterface:
Inheritance graph
[legend]

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
observerThe 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
capabilityIdentifierThe capability message identifier of the StateProviderInterface.
stateProviderThe StateProviderInterface that will be mapped against the capabilityIdentifier.

Implemented in alexaClientSDK::contextManager::ContextManager.

◆ 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
contextRequesterThe context requester asking for context.
endpointIdThe endpointId used to select which context is being requested.
timeoutThe 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
contextRequesterThe context requester asking for context.
endpointIdThe endpointId used to select which context is being requested.
timeoutThe 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
capabilityIdentifierIdentifies which capability state is being provided.
capabilityStateThe new state being provided.
stateRequestTokenThe 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
capabilityIdentifierThe capability message identifier of the StateProviderInterface whose state is not available.
stateRequestTokenThe token that was provided in a provideState request.
isEndpointUnreachableWhether 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
observerThe 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
capabilityIdentifierThe 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
capabilityIdentifierIdentifies which capability has an updated state.
capabilityStateThe new state being reported.
causeThe 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
capabilityIdentifierThe capability message identifier of the StateProviderInterface whose state is being updated.
jsonStateThe 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.
refreshPolicyThe refresh policy for the state.
stateRequestTokenThe 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
capabilityIdentifierThe capability message identifier of the StateProviderInterface.
stateProviderThe StateProviderInterface that will be mapped against the capabilityIdentifier.

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

AlexaClientSDK 1.20.1 - Copyright 2016-2020 Amazon.com, Inc. or its affiliates. All Rights Reserved. Licensed under the Apache License, Version 2.0