#include <CapabilityAgent.h>

Inheritance diagram for alexaClientSDK::avsCommon::avs::CapabilityAgent:

[legend]

Collaboration diagram for alexaClientSDK::avsCommon::avs::CapabilityAgent:

[legend]

Classes
class	DirectiveInfo

Public Member Functions
virtual	~CapabilityAgent ()=default

void	preHandleDirective (std::shared_ptr< AVSDirective > directive, std::unique_ptr< sdkInterfaces::DirectiveHandlerResultInterface > result) override final

bool	handleDirective (const std::string &messageId) override final

void	cancelDirective (const std::string &messageId) override final

void	onDeregistered () override

void	onFocusChanged (FocusState newFocus, MixingBehavior behavior) override

Public Member Functions inherited from alexaClientSDK::avsCommon::sdkInterfaces::DirectiveHandlerInterface
virtual	~DirectiveHandlerInterface ()=default

virtual void	handleDirectiveImmediately (std::shared_ptr< avsCommon::avs::AVSDirective > directive)=0

virtual void	preHandleDirective (std::shared_ptr< avsCommon::avs::AVSDirective > directive, std::unique_ptr< DirectiveHandlerResultInterface > result)=0

virtual avs::DirectiveHandlerConfiguration	getConfiguration () const =0

Public Member Functions inherited from alexaClientSDK::avsCommon::sdkInterfaces::ChannelObserverInterface
virtual	~ChannelObserverInterface ()=default

Public Member Functions inherited from alexaClientSDK::avsCommon::sdkInterfaces::StateProviderInterface
virtual	~StateProviderInterface ()=default

virtual void	provideState (const avs::NamespaceAndName &stateProviderName, const ContextRequestToken stateRequestToken)

virtual void	provideState (const avs::CapabilityTag &stateProviderName, const ContextRequestToken stateRequestToken)

virtual bool	canStateBeRetrieved ()

virtual bool	hasReportableStateProperties ()

virtual bool	shouldQueryState ()

Public Member Functions inherited from alexaClientSDK::avsCommon::sdkInterfaces::ContextRequesterInterface
virtual	~ContextRequesterInterface ()=default

virtual void	onContextAvailable (const std::string &jsonContext)

virtual void	onContextAvailable (const endpoints::EndpointIdentifier &endpointId, const avs::AVSContext &endpointContext, ContextRequestToken requestToken)

virtual void	onContextFailure (const ContextRequestError error)

virtual void	onContextFailure (const ContextRequestError error, ContextRequestToken token)

Protected Member Functions
	CapabilityAgent (const std::string &nameSpace, std::shared_ptr< sdkInterfaces::ExceptionEncounteredSenderInterface > exceptionEncounteredSender)

virtual std::shared_ptr< DirectiveInfo >	createDirectiveInfo (std::shared_ptr< AVSDirective > directive, std::unique_ptr< sdkInterfaces::DirectiveHandlerResultInterface > result)

virtual void	preHandleDirective (std::shared_ptr< DirectiveInfo > info)=0

virtual void	handleDirective (std::shared_ptr< DirectiveInfo > info)=0

virtual void	cancelDirective (std::shared_ptr< DirectiveInfo > info)=0

void	removeDirective (const std::string &messageId)

void	sendExceptionEncounteredAndReportFailed (std::shared_ptr< DirectiveInfo > info, const std::string &message, avsCommon::avs::ExceptionErrorType type=avsCommon::avs::ExceptionErrorType::INTERNAL_ERROR)

const std::pair< std::string, std::string >	buildJsonEventString (const std::string &eventName, const std::string &dialogRequestIdString="", const std::string &payload="{}", const std::string &context="") const

Protected Attributes
const std::string	m_namespace
	The namespace of the capability agent. More...

std::shared_ptr< sdkInterfaces::ExceptionEncounteredSenderInterface >	m_exceptionEncounteredSender
	Object to use to send exceptionEncountered messages. More...

Detailed Description

CapabilityAgent implements methods which most capability agents will need, namely:

DirectiveHandlerInterface,
Building the JSON event string given the name, payload and context,
A map of the message Id to AVSDirective and DirectiveResultInterface. Derived capability agents may extend this class. They may have to implement the following interfaces:
ChannelObserverInterface: To use the Activity Focus Manager Library,
StateProviderInterface: To provide state to the ContextManager.
ContextRequesterInterface: To request context from the ContextManager, as necessary.

Constructor & Destructor Documentation

◆ ~CapabilityAgent()

virtual alexaClientSDK::avsCommon::avs::CapabilityAgent::~CapabilityAgent ( )

virtualdefault

Destructor.

◆ CapabilityAgent()

alexaClientSDK::avsCommon::avs::CapabilityAgent::CapabilityAgent	(	const std::string &	nameSpace,
		std::shared_ptr< sdkInterfaces::ExceptionEncounteredSenderInterface >	exceptionEncounteredSender
	)

protected

Constructor for a Capability Agent.

Parameters

nameSpace	The namespace of the capability agent.
exceptionEncounteredSender	Object to use to send ExceptionEncountered messages.

Member Function Documentation

◆ buildJsonEventString()

const std::pair<std::string, std::string> alexaClientSDK::avsCommon::avs::CapabilityAgent::buildJsonEventString	(	const std::string &	eventName,
		const std::string &	dialogRequestIdString = `""`,
		const std::string &	payload = `"{}"`,
		const std::string &	context = `""`
	)		const

protected

Builds a JSON event string which includes the header, the payload and an optional context. The header includes the namespace, name, message Id and an optional dialogRequestId. The message Id required for the header is a random string that is generated and added to the header.

Parameters

eventName	The name of the event to be include in the header.
dialogRequestIdString	The value associated with the "dialogRequestId" key.
payload	The payload value associated with the "payload" key.
context	Optional `context` to be sent with the event message.

Returns: A pair object consisting of the messageId and the event JSON string if successful, else a pair of empty strings.

◆ cancelDirective() [1/2]

void alexaClientSDK::avsCommon::avs::CapabilityAgent::cancelDirective ( const std::string & messageId )

finaloverridevirtual

Cancel an ongoing preHandleDirective() or handleDirective() operation for the specified AVSDirective. Once this has been called the DirectiveHandler should not expect to receive further calls regarding this directive.

Note: The implementation of this method MUST be thread-safe.; The implementation of this method MUST return quickly. Failure to do so blocks the processing of subsequent AVSDirectives.

Parameters

messageId The message ID of a directive previously passed to preHandleDirective().

Implements alexaClientSDK::avsCommon::sdkInterfaces::DirectiveHandlerInterface.

◆ cancelDirective() [2/2]

virtual void alexaClientSDK::avsCommon::avs::CapabilityAgent::cancelDirective ( std::shared_ptr< DirectiveInfo > info )

protectedpure virtual

Cancel an ongoing preHandleDirective() or handleDirective() operation for the AVSDirective in . Once this has been called the CapabilityAgent should not expect to receive further calls regarding this directive.

Note: The implementation of this method MUST be thread-safe.; The implementation of this method MUST return quickly. Failure to do so blocks the processing of subsequent AVSDirectives.

Parameters

info	The `DirectiveInfo` instance for the `AVSDirective` to process.

Implemented in alexaClientSDK::capabilityAgents::aip::AudioInputProcessor, alexaClientSDK::avsCommon::test::MockCapabilityAgent, alexaClientSDK::acsdkAudioPlayer::AudioPlayer, alexaClientSDK::acsdkExternalMediaPlayer::ExternalMediaPlayer, alexaClientSDK::acsdkAlerts::AlertsCapabilityAgent, alexaClientSDK::capabilityAgents::speechSynthesizer::SpeechSynthesizer, alexaClientSDK::acsdkNotifications::NotificationsCapabilityAgent, alexaClientSDK::aplCapabilityCommon::BaseAPLCapabilityAgent, alexaClientSDK::capabilityAgents::mrm::MRMCapabilityAgent, alexaClientSDK::capabilityAgents::modeController::ModeControllerCapabilityAgent, alexaClientSDK::capabilityAgents::rangeController::RangeControllerCapabilityAgent, alexaClientSDK::capabilityAgents::toggleController::ToggleControllerCapabilityAgent, and alexaClientSDK::capabilityAgents::powerController::PowerControllerCapabilityAgent.

◆ createDirectiveInfo()

virtual std::shared_ptr<DirectiveInfo> alexaClientSDK::avsCommon::avs::CapabilityAgent::createDirectiveInfo	(	std::shared_ptr< AVSDirective >	directive,
		std::unique_ptr< sdkInterfaces::DirectiveHandlerResultInterface >	result
	)

protectedvirtual

Create a DirectiveInfo instance with which to track the handling of an AVSDirective.

Note: This method is virtual to allow derived CapabilityAgent's to extend DirectiveInfo with additional information.

Parameters

directive	The `AVSDirective` to be processed.
result	The object with which to communicate the outcome of processing the `AVSDirective`.

Returns: A DirectiveInfo instance with which to track the processing of directive.

◆ handleDirective() [1/2]

bool alexaClientSDK::avsCommon::avs::CapabilityAgent::handleDirective ( const std::string & messageId )

finaloverridevirtual

Handle the action specified by the directive identified by messageId. The handling of subsequent directives with the same DialogRequestId may be blocked until the DirectiveHandler calls the setSucceeded() method of the DirectiveHandlingResult instance passed in to the preHandleDirective() call for the directive specified by messageId. If handling of this directive fails such that subsequent directives with the same DialogRequestId should be cancelled, this DirectiveHandler should instead call setFailed() to indicate a failure.

Note: If this operation fails, an ExceptionEncountered message should be sent to AVS.; The implementation of this method MUST be thread-safe.; The implementation of this method MUST return quickly. Failure to do so blocks the processing of subsequent AVSDirectives.

Parameters

messageId The message ID of a directive previously passed to preHandleDirective().

Returns: false when messageId is not recognized, else true. Any errors related to handling of a valid messageId should be reported using DirectiveHandlerResultInterface::setFailed().

Implements alexaClientSDK::avsCommon::sdkInterfaces::DirectiveHandlerInterface.

◆ handleDirective() [2/2]

virtual void alexaClientSDK::avsCommon::avs::CapabilityAgent::handleDirective ( std::shared_ptr< DirectiveInfo > info )

protectedpure virtual

Handle the action specified by the AVSDirective in info. The handling of subsequent directives with the same DialogRequestId may be blocked until the DirectiveHandler calls the setSucceeded() method of the DirectiveHandlingResult present in info. If handling of this directive fails setFailed() should be called to indicate a failure.

Note: The implementation of this method MUST be thread-safe.; The implementation of this method MUST return quickly. Failure to do so blocks the processing of subsequent AVSDirectives.

Parameters

info	The `DirectiveInfo` instance for the `AVSDirective` to process.

Implemented in alexaClientSDK::capabilityAgents::aip::AudioInputProcessor, alexaClientSDK::avsCommon::test::MockCapabilityAgent, alexaClientSDK::acsdkAudioPlayer::AudioPlayer, alexaClientSDK::acsdkExternalMediaPlayer::ExternalMediaPlayer, alexaClientSDK::acsdkAlerts::AlertsCapabilityAgent, alexaClientSDK::capabilityAgents::speechSynthesizer::SpeechSynthesizer, alexaClientSDK::acsdkNotifications::NotificationsCapabilityAgent, alexaClientSDK::aplCapabilityCommon::BaseAPLCapabilityAgent, alexaClientSDK::capabilityAgents::mrm::MRMCapabilityAgent, alexaClientSDK::capabilityAgents::modeController::ModeControllerCapabilityAgent, alexaClientSDK::capabilityAgents::rangeController::RangeControllerCapabilityAgent, alexaClientSDK::capabilityAgents::toggleController::ToggleControllerCapabilityAgent, and alexaClientSDK::capabilityAgents::powerController::PowerControllerCapabilityAgent.

◆ onDeregistered()

void alexaClientSDK::avsCommon::avs::CapabilityAgent::onDeregistered ( )

overridevirtual

Notification that this handler has been de-registered and will not receive any more calls.

Implements alexaClientSDK::avsCommon::sdkInterfaces::DirectiveHandlerInterface.

Reimplemented in alexaClientSDK::capabilityAgents::aip::AudioInputProcessor, alexaClientSDK::acsdkAudioPlayer::AudioPlayer, alexaClientSDK::acsdkExternalMediaPlayer::ExternalMediaPlayer, alexaClientSDK::acsdkAlerts::AlertsCapabilityAgent, and alexaClientSDK::capabilityAgents::speechSynthesizer::SpeechSynthesizer.

◆ onFocusChanged()

void alexaClientSDK::avsCommon::avs::CapabilityAgent::onFocusChanged	(	FocusState	newFocus,
		MixingBehavior	behavior
	)

overridevirtual

Used to notify the observer of the Channel of focus changes. Once called, the client should make a user observable change only and return immediately. Any additional work that needs to be done should be done on a separate thread or after returning. "User observable change" here refers to events that the end user of the product can visibly see or hear. For example, Alexa speech or music playing would be examples of user observable changes. Other work, such as database storing, logging, or communicating via network should be done on a different thread. Not doing so could result in delays for other clients trying to access the Channel.

Parameters

newFocus	The new Focus of the channel.
behavior	The mixingBehavior for the ChannelObserver to take as per the interrupt model

Note: when newFocus is FocusState::FOREGROUND, the MixingBehavior shall be guaranteed to be PRIMARY when newFocus is FocusState::NONE, the MixingBehavior shall be guaranteed to be MUST_STOP

Implements alexaClientSDK::avsCommon::sdkInterfaces::ChannelObserverInterface.

Reimplemented in alexaClientSDK::capabilityAgents::aip::AudioInputProcessor, alexaClientSDK::acsdkBluetooth::Bluetooth, alexaClientSDK::acsdkAudioPlayer::AudioPlayer, alexaClientSDK::acsdkAlerts::AlertsCapabilityAgent, and alexaClientSDK::capabilityAgents::speechSynthesizer::SpeechSynthesizer.

◆ preHandleDirective() [1/2]

void alexaClientSDK::avsCommon::avs::CapabilityAgent::preHandleDirective	(	std::shared_ptr< AVSDirective >	directive,
		std::unique_ptr< sdkInterfaces::DirectiveHandlerResultInterface >	result
	)

finaloverride

◆ preHandleDirective() [2/2]

virtual void alexaClientSDK::avsCommon::avs::CapabilityAgent::preHandleDirective ( std::shared_ptr< DirectiveInfo > info )

protectedpure virtual

Notification that a directive has arrived. This notification gives the DirectiveHandler a chance to prepare for handling of an AVSDirective. If an error occurs during the pre-Handling phase and that error should cancel the handling of subsequent AVSDirectives with the same DialogRequestId, the DirectiveHandler should call the setFailed method on the result instance passed in to this call.

Note: The implementation of this method MUST be thread-safe.; The implementation of this method MUST return quickly. Failure to do so blocks the processing of subsequent AVSDirectives.

Parameters

info	The `DirectiveInfo` instance for the `AVSDirective` to process.

Implemented in alexaClientSDK::capabilityAgents::aip::AudioInputProcessor, alexaClientSDK::avsCommon::test::MockCapabilityAgent, alexaClientSDK::acsdkAudioPlayer::AudioPlayer, alexaClientSDK::acsdkExternalMediaPlayer::ExternalMediaPlayer, alexaClientSDK::acsdkAlerts::AlertsCapabilityAgent, alexaClientSDK::capabilityAgents::speechSynthesizer::SpeechSynthesizer, alexaClientSDK::acsdkNotifications::NotificationsCapabilityAgent, alexaClientSDK::aplCapabilityCommon::BaseAPLCapabilityAgent, alexaClientSDK::capabilityAgents::mrm::MRMCapabilityAgent, alexaClientSDK::capabilityAgents::modeController::ModeControllerCapabilityAgent, alexaClientSDK::capabilityAgents::rangeController::RangeControllerCapabilityAgent, alexaClientSDK::capabilityAgents::toggleController::ToggleControllerCapabilityAgent, and alexaClientSDK::capabilityAgents::powerController::PowerControllerCapabilityAgent.

◆ removeDirective()

void alexaClientSDK::avsCommon::avs::CapabilityAgent::removeDirective ( const std::string & messageId )

protected

This function releases resources associated with the AVSDirective which is no longer in use by a CapabilityAgent.

Note: This function should be called from handleDirective() and cancelDirective() implementations after the outcome of handleDirective() or cancelDirective() has been reported.

Parameters

messageId The message Id of the AVSDirective.

◆ sendExceptionEncounteredAndReportFailed()

void alexaClientSDK::avsCommon::avs::CapabilityAgent::sendExceptionEncounteredAndReportFailed	(	std::shared_ptr< DirectiveInfo >	info,
		const std::string &	message,
		avsCommon::avs::ExceptionErrorType	type = `avsCommon::avs::ExceptionErrorType::INTERNAL_ERROR`
	)

protected

Send ExceptionEncountered and report a failure to handle the AVSDirective.

Parameters

info	The `AVSDirective` that encountered the error and ancillary information.
message	The error message to include in the ExceptionEncountered message.
type	The type of Exception that was encountered.

Member Data Documentation

◆ m_exceptionEncounteredSender

std::shared_ptr<sdkInterfaces::ExceptionEncounteredSenderInterface> alexaClientSDK::avsCommon::avs::CapabilityAgent::m_exceptionEncounteredSender

protected

Object to use to send exceptionEncountered messages.

◆ m_namespace

const std::string alexaClientSDK::avsCommon::avs::CapabilityAgent::m_namespace

protected

The namespace of the capability agent.

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

/workplace/avs-device-sdk/AVSCommon/AVS/include/AVSCommon/AVS/CapabilityAgent.h

Classes

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ~CapabilityAgent()

◆ CapabilityAgent()

Member Function Documentation

◆ buildJsonEventString()

◆ cancelDirective() [1/2]

◆ cancelDirective() [2/2]

◆ createDirectiveInfo()

◆ handleDirective() [1/2]

◆ handleDirective() [2/2]

◆ onDeregistered()

◆ onFocusChanged()

◆ preHandleDirective() [1/2]

◆ preHandleDirective() [2/2]

◆ removeDirective()

◆ sendExceptionEncounteredAndReportFailed()

Member Data Documentation

◆ m_exceptionEncounteredSender

◆ m_namespace