Skip to content

Most visited

Recently visited

navigation

MediaButtonReceiver

public class MediaButtonReceiver
extends BroadcastReceiver

java.lang.Object
   ↳ android.content.BroadcastReceiver
     ↳ android.support.v4.media.session.MediaButtonReceiver


A media button receiver receives and helps translate hardware media playback buttons, such as those found on wired and wireless headsets, into the appropriate callbacks in your app.

You can add this MediaButtonReceiver to your app by adding it directly to your AndroidManifest.xml:

 <receiver android:name="android.support.v4.media.session.MediaButtonReceiver" >
   <intent-filter>
     <action android:name="android.intent.action.MEDIA_BUTTON" />
   </intent-filter>
 </receiver>
 
This class assumes you have a Service in your app that controls media playback via a MediaSessionCompat - all Intents received by the MediaButtonReceiver will be forwarded to that service.

First priority is given to a Service that includes an intent filter that handles ACTION_MEDIA_BUTTON:

 <service android:name="com.example.android.MediaPlaybackService" >
   <intent-filter>
     <action android:name="android.intent.action.MEDIA_BUTTON" />
   </intent-filter>
 </service>
 
If such a Service is not found, MediaButtonReceiver will attempt to find a media browser service implementation. If neither is available or more than one valid service/media browser service is found, an IllegalStateException will be thrown.

Events can then be handled in onStartCommand(Intent, int, int) by calling handleIntent(MediaSessionCompat, Intent), passing in your current MediaSessionCompat:

 private MediaSessionCompat mMediaSessionCompat = ...;

 public int onStartCommand(Intent intent, int flags, int startId) {
   MediaButtonReceiver.handleIntent(mMediaSessionCompat, intent);
   return super.onStartCommand(intent, flags, startId);
 }
 
This ensures that the correct callbacks to MediaSessionCompat.Callback will be triggered based on the incoming KeyEvent.

Summary

Public constructors

MediaButtonReceiver()

Public methods

static KeyEvent handleIntent(MediaSessionCompat mediaSessionCompat, Intent intent)

Extracts any available KeyEvent from an ACTION_MEDIA_BUTTON intent, passing it onto the MediaSessionCompat using dispatchMediaButtonEvent(KeyEvent), which in turn will trigger callbacks to the MediaSessionCompat.Callback registered via setCallback(MediaSessionCompat.Callback).

void onReceive(Context context, Intent intent)

This method is called when the BroadcastReceiver is receiving an Intent broadcast.

Inherited methods

From class android.content.BroadcastReceiver
From class java.lang.Object

Public constructors

MediaButtonReceiver

MediaButtonReceiver ()

Public methods

handleIntent

KeyEvent handleIntent (MediaSessionCompat mediaSessionCompat, 
                Intent intent)

Extracts any available KeyEvent from an ACTION_MEDIA_BUTTON intent, passing it onto the MediaSessionCompat using dispatchMediaButtonEvent(KeyEvent), which in turn will trigger callbacks to the MediaSessionCompat.Callback registered via setCallback(MediaSessionCompat.Callback).

The returned KeyEvent is non-null if any KeyEvent is found and can be used if any additional processing is needed beyond what is done in the MediaSessionCompat.Callback. An example of is to prevent redelivery of a KEYCODE_MEDIA_PLAY_PAUSE Intent in the case of the Service being restarted (which, by default, will redeliver the last received Intent).

 KeyEvent keyEvent = MediaButtonReceiver.handleIntent(mediaSession, intent);
 if (keyEvent != null && keyEvent.getKeyCode() == KeyEvent.KEYCODE_MEDIA_PLAY_PAUSE) {
   Intent emptyIntent = new Intent(intent);
   emptyIntent.setAction("");
   startService(emptyIntent);
 }
 

Parameters
mediaSessionCompat MediaSessionCompat: A MediaSessionCompat that has a MediaSessionCompat.Callback set.
intent Intent: The intent to parse.
Returns
KeyEvent The extracted KeyEvent if found, or null.

onReceive

void onReceive (Context context, 
                Intent intent)

This method is called when the BroadcastReceiver is receiving an Intent broadcast. During this time you can use the other methods on BroadcastReceiver to view/modify the current result values. This method is always called within the main thread of its process, unless you explicitly asked for it to be scheduled on a different thread using registerReceiver(BroadcastReceiver, IntentFilter, String, android.os.Handler). When it runs on the main thread you should never perform long-running operations in it (there is a timeout of 10 seconds that the system allows before considering the receiver to be blocked and a candidate to be killed). You cannot launch a popup dialog in your implementation of onReceive().

If this BroadcastReceiver was launched through a <receiver> tag, then the object is no longer alive after returning from this function. This means you should not perform any operations that return a result to you asynchronously -- in particular, for interacting with services, you should use startService(Intent) instead of bindService(Intent, ServiceConnection, int). If you wish to interact with a service that is already running, you can use peekService(Context, Intent).

The Intent filters used in registerReceiver(BroadcastReceiver, IntentFilter) and in application manifests are not guaranteed to be exclusive. They are hints to the operating system about how to find suitable recipients. It is possible for senders to force delivery to specific recipients, bypassing filter resolution. For this reason, onReceive() implementations should respond only to known actions, ignoring any unexpected Intents that they may receive.

Parameters
context Context: The Context in which the receiver is running.
intent Intent: The Intent being received.
This site uses cookies to store your preferences for site-specific language and display options.

Hooray!

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.