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
- requestFocus()
- releaseFocus()
- FocusState Enum
- FocusChangeReason Enum
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
}