MRM CloudDelegate Class
The CloudDelegate
class provides access to network access to AVS and Multi-Room Music (MRM). Additionally, this class provides several interface points into the AVS Client.
- CloudDelegate Class Declaration
- hasAlexaConnection()
- sendEvent()
- forwardAVSDirective()
- updateClusterStateContext()
- About ClusterState
CloudDelegate Class Declaration
This is a sample declaration of the DeviceInfoDelegate
class:
class CloudDelegate {
public:
virtual ~CloudDelegate() {};
virtual bool hasAlexaConnection() = 0;
virtual void sendEvent(const char *nameSpace, const char *name,
const char *payload, const char *uri) = 0;
virtual void forwardAVSDirective(const char *message) = 0;
virtual void updateClusterStateContext(const char *context) = 0;
hasAlexaConnection()
The MRM SDK uses this function to query the latest connection state between the local AVS client and Alexa Voice Service. Specifically, when the MRM SDK is told to have an Alexa connection state change via the API postAlexaConnectionChanged()
, the MRM SDK pushes this event change into its working queue. When the MRM SDK processes this change, it calls this function for the latest connection state.
Implement this function to return true if there is a valid connection to Alexa from the standpoint of the AVS client.
bool hasAlexaConnection() = 0;
sendEvent()
The MRM SDK calls this function to send a Cluster
event to the Alexa.
The parameters are valid until this function returns. The client should retain a copy of the parameters for any further handling.
This function must not block and must be thread safe. The client is expected to copy any strings and handle asynchronously.
The AVS client is responsible to use the parameters from the MRM SDK to construct a valid message (see the sample context and event below). Any missing elements should be taken care of by the AVS client. The MRM SDK expects the AVS client to generate unique messageId
s for the events that are sent to Alexa.
In general, WHA class doesn't expect to be notified if the event fails to be sent for any reason on the AVS client side. If an event fails to be sent, this Event can be discarded. Sufficient logging within the client for debugging is expected.
void sendEvent(const char *nameSpace, const char *name,
const char *payload, const char *uri);
Parameter | Description |
---|---|
const char *nameSpace | Message namespace |
const char *name | Message name |
const char *payload | Stringified JSON payload |
const char *uri | URI specifying custom endpoint. Use the default path "/{{API version}}/events" when it is empty. Otherwise, use "/{{API version}}/{{uri}}" to send up this Event. |
ClusterState Context
ClusterState
includes state information for device applications that implement MRM use cases. This component should be added in Context
when a device is part of a cluster. If a device is part of multiple clusters, the component will include the component states for all of these clusters.
ClusterManager
encloses the context of a single device to the AVS context specification.
Sample Context
{
"header": {
"namespace":"WholeHomeAudio",
"name":"ClusterState"
},
"payload": {
"clusters": [
{
"clusterId": ""
"eventingRole": "",
"clusterContext":[
{
// Enclosed context for AudioPlayer.PlaybackState and
// AudioFocusManager.
}
]
}
]
}
}
}
Payload Parameters
Parameter | Description | Type |
---|---|---|
clusterId | A unique identifier for the cluster provided in the SetClusters directive. |
string |
eventingRole | Identifies a device in a cluster as a primary or secondary device. Accepted values: Master , Slave . |
string |
clusterContext | Enclosed context for AudioPlayer.PlaybackState and AudioFocusManger . Objects in this array should conform to the context specification provided by AVS. |
array |
Cluster Event
The ClusterEvent
encloses an event for a single AVS device within a cluster. The individual events contained within ClusterEvent
are from existing Alexa interfaces. Supported interface include:
ClusterEvent
s are sent by each device individually. This allows each device within a cluster to independently declare its supported capabilities using the Capabilities API and ensures that the cloud appropriately interprets the event for a given device.
Sample Event
{
"context": [
// This is an array of context objects that are used to
// communicate the state of all client components to Alexa.
// ClusterState is required, other states are optional.
// See Context for details.
],
"event":{
"header": {
"namespace":"WholeHomeAudio",
"name":"ClusterEvent",
"messageId": ""
},
"payload": {
"clusterId": "",
"eventingRole": "",
"event": {
// Enclosed event from the AudioPlayer, System, or
// PlaybackController interface.
}
}
}
}
Parameter | Description | Type |
---|---|---|
clusterId | A unique identifier for the cluster provided in the SetClusters directive. |
string |
eventingRole | Identifies a device in a cluster as a primary or secondary device. Accepted values: Master , Slave . |
string |
event | An enclosed event from an existing Alexa interface. | object |
forwardAVSDirective()
Implement this function to receive and handle a Directive from the MRM SDK. Since this is an AVS Directive, the Client is expected to parse and process it the same way a typical Directive it receives from the Alexa Cloud.
The message is a stringified AVS Directive JSON extracted from a MDM payload without any modification. It is originally generated by Alexa Service. See ResetUserInactivity Directive for a sample JSON structure.
The MRM SDK doesn't expect to be notified if there are errors when the AVS Client handles the directive.
This function must not block and must be thread safe. The Client is expected to copy the message and handle asynchronously.
A Directive with a namespace of "MultiDeviceMessage" encloses multiple AVS Directives targeted for different software versions.
void forwardAVSDirective(const char *message);
Parameter | Description |
---|---|
const char *message | Stringified AVS Directive. |
updateClusterStateContext()
This enables the MDM SDK to set the ClusterState element that the Client SDK sends to AVS in subsequent Events.
This context element is updated each time this call is made. The AVS client is required to persist the current ClusterState to send up to AVS with all Events which require context. If the context is a nullptr
, the AVS client needs to delete its persisted ClusterState context and should no longer send this component in the context section of future events.
The AVS client is expected to not modify the context content. The context is valid until this function returns. The client should retain a copy of context for any further handling.
This function must not block and must be thread safe. The client is expected to handle context asynchronously.
void updateClusterStateContext(const char *context);
Parameter | Description |
---|---|
const char *context | Stringified ClusterState JSON. |
About ClusterState
The MRM SDK sends a ClusterState context (see Context). This context indicates the WHA cluster playback state. The Client should put this into the client's full context in the same manner as another context such as an alarm.
The following illustrates inclusion of the ClusterState context:
"context": [
{
"header": {
"namespace": "AudioPlayer",
"name": "PlaybackState"
},
"payload": {
"token": "",
"offsetInMilliseconds": ,
"playerActivity": ""
}
},
{
"header": {
"namespace": "SpeechRecognizer",
"name": "RecognizerState"
},
"payload": {
"wakeword": "ALEXA"
}
},
{
"header": {
"namespace": "Speaker",
"name": "VolumeState"
},
"payload": {
"volume": ,
"muted":
}
},
{
// ClusterStateContext generated by MRM SDK
}
]