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

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 messageIds 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:

ClusterEvents 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
    }
]