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.
AudioPlayerAgent.OnPlayStateChanged
OnPlayStateChanged enables you to respond to changes in the playback state of an audio track. For example, it allows you to transition the play state of a track once it has completed downloading or to move to the next track when a track finishes, as shown in the following excerpt:
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 34.4 describes the PlayState enum values that can be handled in the OnPlayStateChanged method.
Whereas the OnPlayStateChanged method is used to respond to playback state changes, the OnError method is called when an error occurs during playback, and not OnPlayStateChanged.
AudioPlayerAgent.OnUserAction
The name of the OnUserAction method is somewhat misleading. The task of the OnUserAction method is to handle BackgroundAudioPlayer actions that occur in your foreground app.
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 34.2). User actions do not directly affect the BackgroundAudioPlayer, but rather your AudioPlayerAgent is responsible for manipulating the player via the OnUserAction method.
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.
Tip
The volume up and volume down buttons and the play/pause button of the UVC can be simulated in the Windows Phone emulator using the F9, F10, and F11 keys, respectively.
Although a function key simulates pressing the play/pause button, the play/pause button is not a required hardware button on Windows Phone devices and therefore may not be present on every device.
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 34.5 lists the UserAction enum values that can be handled in the OnUserAction method.
Note
The param object argument, of the OnUserAction method, is used only with the action argument UserAction.Seek, in which case the param argument is a TimeSpan that indicates the requested track position.
AudioPlayerAgent.OnError
OnError is called when an Exception is raised during playback of an audio track. The method is generally called when the agent encounters a connection error when downloading an audio file from a remote server and offers the opportunity to transition to a different track, one that is potentially stored locally if the error is due to an absence of network connectivity.
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();
}
}