Windows Phone 8 : AudioPlayerAgent Sample (part 2) - AudioPlayerAgent Virtual Methods

AudioPlayerAgent has the following three virtual methods that can be overridden in your implementation:

- OnPlayStateChanged

- OnUserAction

- OnError

The following sections explore each method in detail.

protected override void OnPlayStateChanged(
    BackgroundAudioPlayer player, AudioTrack track, PlayState playState)
{
    switch (playState)
    {
        case PlayState.TrackReady:
            /* The track to play is set in the PlayTrack method. */
            player.Play();
            break;

        case PlayState.TrackEnded:
            PlayNextTrack(player);
            break;
    }

    NotifyComplete();
}

Table 1 describes the PlayState enum values that can be handled in the OnPlayStateChanged method.

TABLE 1. PlayState Enum

Two actions cause the AudioPlayerAgent.OnUserAction method to be called. The first action occurs when the user presses the Universal Volume Control (UVC), and an onscreen menu is displayed allowing the user to play, pause, and skip forward and backward between tracks (see Figure 2). User actions do not directly affect the BackgroundAudioPlayer, but rather your AudioPlayerAgent is responsible for manipulating the player via the OnUserAction method.

FIGURE 2 Tapping the onscreen menu background launches your app.

The second action occurs when your app is in the foreground and it calls one of the playback related methods on the BackgroundAudioPlayer.Instance object, such as Play. This type of action may or may not have been directed by the user.

OnUserAction is passed a UserAction enum value that allows you to determine the behavior of the audio player agent. In some cases, the player can be put into action immediately. See the following excerpt:

protected override void OnUserAction(
    BackgroundAudioPlayer player, AudioTrack track, UserAction action,
    object param)
{
    /* User actions can be initiated from the main application
     * or from the UVC (Universal Volume Control). */
    switch (action)
    {

        case UserAction.Play:
            PlayTrack(player);
            break;

        case UserAction.Pause:
            player.Pause();
            break;

        case UserAction.SkipPrevious:
            PlayPreviousTrack(player);
            break;

        case UserAction.SkipNext:
            PlayNextTrack(player);
            break;

        case UserAction.Stop:
            player.Stop();
            break;
    }

    NotifyComplete();
}

Table 1 lists the UserAction enum values that can be handled in the OnUserAction method.

TABLE 1. UserAction Enum

In the following excerpt you see that when an error is determined to be fatal, the Abort method is called, signaling to the OS that playback should be disabled. The method implementation is identical to the base class implementation and need not be implemented if you do not want to provide explicit error handling:

protected override void OnError(BackgroundAudioPlayer player,
                                AudioTrack track,
                                Exception error, bool isFatal)
{
    if (isFatal)
    {
        Abort();
    }
    else
    {
        NotifyComplete();
    }
}