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

#include <CapabilityAgent.h>

Inheritance diagram for alexaClientSDK::avsCommon::avs::CapabilityAgent:
Inheritance graph
[legend]
Collaboration diagram for alexaClientSDK::avsCommon::avs::CapabilityAgent:
Collaboration graph
[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 ()
 
- 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< DirectiveInfocreateDirectiveInfo (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::ExceptionEncounteredSenderInterfacem_exceptionEncounteredSender
 Object to use to send exceptionEncountered messages. More...
 

Detailed Description

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

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
nameSpaceThe namespace of the capability agent.
exceptionEncounteredSenderObject 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
eventNameThe name of the event to be include in the header.
dialogRequestIdStringThe value associated with the "dialogRequestId" key.
payloadThe payload value associated with the "payload" key.
contextOptional 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
messageIdThe 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

◆ createDirectiveInfo()

std::shared_ptr< CapabilityAgent::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
directiveThe AVSDirective to be processed.
resultThe 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
messageIdThe 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
infoThe DirectiveInfo instance for the AVSDirective to process.

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

◆ onDeregistered()

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

◆ 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
newFocusThe new Focus of the channel.
behaviorThe 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::capabilityAgents::speechSynthesizer::SpeechSynthesizer, alexaClientSDK::acsdkAlerts::AlertsCapabilityAgent, and alexaClientSDK::capabilityAgents::templateRuntime::TemplateRuntime.

◆ 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
infoThe DirectiveInfo instance for the AVSDirective to process.

Implemented in alexaClientSDK::avsCommon::test::MockCapabilityAgent, alexaClientSDK::capabilityAgents::aip::AudioInputProcessor, alexaClientSDK::capabilityAgents::externalMediaPlayer::ExternalMediaPlayer, alexaClientSDK::acsdkAudioPlayer::AudioPlayer, alexaClientSDK::capabilityAgents::speechSynthesizer::SpeechSynthesizer, alexaClientSDK::acsdkAlerts::AlertsCapabilityAgent, alexaClientSDK::acsdkNotifications::NotificationsCapabilityAgent, alexaClientSDK::capabilityAgents::modeController::ModeControllerCapabilityAgent, alexaClientSDK::capabilityAgents::rangeController::RangeControllerCapabilityAgent, alexaClientSDK::capabilityAgents::templateRuntime::TemplateRuntime, alexaClientSDK::capabilityAgents::toggleController::ToggleControllerCapabilityAgent, alexaClientSDK::capabilityAgents::mrm::MRMCapabilityAgent, 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
messageIdThe 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
infoThe AVSDirective that encountered the error and ancillary information.
messageThe error message to include in the ExceptionEncountered message.
typeThe 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 files:

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