MRM FocusDelegate Class

The FocusDelegate class acquires permission to render audio and is notified of focus state changes as dictated by the AVS Client.

FocusDelegate Class Declaration

This is a sample declaration of the FocusDelegate class:

class FocusDelegate {
    FocusState requestFocus(void (*focusCallback) (WHA *whaInstance,
        FocusState focusState, FocusChangeReason changeReason));
    bool releaseFocus();
}

requestFocus()

Implement this function to return the FocusState to be granted to the MRM SDK. The MRM SDK calls this function when it wishes to render audio and access the Content Channel.

Whatever the decision of FocusManager, the MRM SDK expects a callback via the provided focusCallback pointer.

FocusState requestFocus(void (*focusCallback) (WHA *whaInstance,
    FocusState focusState, FocusChangeReason changeReason));

This function has one argument, a pointer to a callback that takes the WHA, FocusState and FocusChangeReason:

void (*focusCallback) (WHA *whaInstance, FocusState focusState, FocusChangeReason changeReason)

This callback is called when the client is changing the WHA focus state to the value of FocusState.

This callback should be thread safe and blocking.

The focusCallback should be used until either updated via another call to this function or until releaseFocus() is called.

The caller can call requestFocus() even if it already has focus. If focus was previous granted, the old callback is considered invalid and the new result should be used.

The focusCallback should only be called if FOREGROUND or BACKGROUND was returned from this call. Once NO_FOCUS is passed to the callback, the callback should not be triggered again. This callback is valid until a call of requestFocus() has returned or after a call to releaseFocus() has returned.

When the call returns, the application will have made some change to ensure that the new state has taken effect or will take effect soon. The change is then dispatched.

If NO_FOCUS is returned from this call, the MRM SDK assumes that it will not be able to play until it learns otherwise by trying to acquire focus later. It is critical that calls that return NO_FOCUS are not considered an error in the write() implementation of the PlaybackDelegate class. Failure to do so may lead to incorrect eventing.

releaseFocus()

This function is called by the MRM SDK when it indicates it is surrendering the focus (release its usage of the Content Channel).

This should be a blocking call.

Implement this function to return true if focus was released.

When the focus is not released, the player is expected to remain in its current state. The MRM SDK may call releaseFocus() later in an attempt to release focus.

boolean releaseFocus();

FocusState Enum

This describes the desired focus state the system would like the MRM Player to enter in.

enum FocusState {
    // MRM is in the foreground and plays at regular volume
    FOREGROUND,
    // MRM is in the background, and plays attenuated or stops, depending
    // on the content that is played (e.g music vs. audio book)
    BACKGROUND,
    // MRM should not be outputting any music
    NO_FOCUS
}

FocusChangeReason Enum

This describes the reason the focus was lost or gained.

enum FocusChangeReason {
    // The reason for the focus change is "normal" such as losing internet
    // connectivity, buffer underrun, etc.
    NORMAL,
    // The reason is explicitly due to AVS_COMMS feature, which requires
    // separate UX handling from the MRM SDK
    AVS_COMMS
}