Skip to content

Most visited

Recently visited

navigation

MediaBrowserServiceCompat

public abstract class MediaBrowserServiceCompat
extends Service

java.lang.Object
   ↳ android.content.Context
     ↳ android.content.ContextWrapper
       ↳ android.app.Service
         ↳ android.support.v4.media.MediaBrowserServiceCompat


Base class for media browse services.

Media browse services enable applications to browse media content provided by an application and ask the application to start playing it. They may also be used to control content that is already playing by way of a MediaSessionCompat.

To extend this class, you must declare the service in your manifest file with an intent filter with the SERVICE_INTERFACE action. For example:

 <service android:name=".MyMediaBrowserServiceCompat"
          android:label="@string/service_name" >
     <intent-filter>
         <action android:name="android.media.browse.MediaBrowserService" />
     </intent-filter>
 </service>
 

Developer Guides

For information about building your media application, read the Media Apps developer guide.

Summary

Nested classes

class MediaBrowserServiceCompat.BrowserRoot

Contains information that the browser service needs to send to the client when first connected. 

class MediaBrowserServiceCompat.Result<T>

Completion handler for asynchronous callback methods in MediaBrowserServiceCompat

Constants

String SERVICE_INTERFACE

The Intent that must be declared as handled by the service.

Inherited constants

From class android.app.Service
From class android.content.Context
From interface android.content.ComponentCallbacks2

Public constructors

MediaBrowserServiceCompat()

Public methods

void dump(FileDescriptor fd, PrintWriter writer, String[] args)

Print the Service's state into the given stream.

final Bundle getBrowserRootHints()

Gets the root hints sent from the currently connected MediaBrowserCompat.

MediaSessionCompat.Token getSessionToken()

Gets the session token, or null if it has not yet been created or if it has been destroyed.

void notifyChildrenChanged(String parentId)

Notifies all connected media browsers that the children of the specified parent id have changed in some way.

void notifyChildrenChanged(String parentId, Bundle options)

Notifies all connected media browsers that the children of the specified parent id have changed in some way.

IBinder onBind(Intent intent)

Return the communication channel to the service.

void onCreate()

Called by the system when the service is first created.

void onCustomAction(String action, Bundle extras, Result<Bundle> result)

Called to request a custom action to this service.

abstract MediaBrowserServiceCompat.BrowserRoot onGetRoot(String clientPackageName, int clientUid, Bundle rootHints)

Called to get the root information for browsing by a particular client.

abstract void onLoadChildren(String parentId, Result<List<MediaBrowserCompat.MediaItem>> result)

Called to get information about the children of a media item.

void onLoadChildren(String parentId, Result<List<MediaBrowserCompat.MediaItem>> result, Bundle options)

Called to get information about the children of a media item.

void onLoadItem(String itemId, Result<MediaBrowserCompat.MediaItem> result)

Called to get information about a specific media item.

void onSearch(String query, Bundle extras, Result<List<MediaBrowserCompat.MediaItem>> result)

Called to get the search result.

void setSessionToken(MediaSessionCompat.Token token)

Call to set the media session.

Inherited methods

From class android.app.Service
From class android.content.ContextWrapper
From class android.content.Context
From class java.lang.Object
From interface android.content.ComponentCallbacks2
From interface android.content.ComponentCallbacks

Constants

SERVICE_INTERFACE

added in version 23.2.0
String SERVICE_INTERFACE

The Intent that must be declared as handled by the service.

Constant Value: "android.media.browse.MediaBrowserService"

Public constructors

MediaBrowserServiceCompat

added in version 23.2.0
MediaBrowserServiceCompat ()

Public methods

dump

added in version 23.2.0
void dump (FileDescriptor fd, 
                PrintWriter writer, 
                String[] args)

Print the Service's state into the given stream. This gets invoked if you run "adb shell dumpsys activity service <yourservicename>" (note that for this command to work, the service must be running, and you must specify a fully-qualified service name). This is distinct from "dumpsys <servicename>", which only works for named system services and which invokes the dump(FileDescriptor, String[]) method on the IBinder interface registered with ServiceManager.

Parameters
fd FileDescriptor: The raw file descriptor that the dump is being sent to.

writer PrintWriter: The PrintWriter to which you should dump your state. This will be closed for you after you return.

args String: additional arguments to the dump request.

getBrowserRootHints

added in version 24.0.0
Bundle getBrowserRootHints ()

Gets the root hints sent from the currently connected MediaBrowserCompat. The root hints are service-specific arguments included in an optional bundle sent to the media browser service when connecting and retrieving the root id for browsing, or null if none. The contents of this bundle may affect the information returned when browsing.

Note that this will return null when connected to MediaBrowser and running on API 23 or lower.

Returns
Bundle

Throws
IllegalStateException If this method is called outside of onLoadChildren(String, MediaBrowserServiceCompat.Result>), onLoadItem(String, MediaBrowserServiceCompat.Result) or onSearch(String, Bundle, MediaBrowserServiceCompat.Result>).

See also:

getSessionToken

added in version 23.2.0
MediaSessionCompat.Token getSessionToken ()

Gets the session token, or null if it has not yet been created or if it has been destroyed.

Returns
MediaSessionCompat.Token

notifyChildrenChanged

added in version 23.2.0
void notifyChildrenChanged (String parentId)

Notifies all connected media browsers that the children of the specified parent id have changed in some way. This will cause browsers to fetch subscribed content again.

Parameters
parentId String: The id of the parent media item whose children changed.

notifyChildrenChanged

added in version 24.0.0
void notifyChildrenChanged (String parentId, 
                Bundle options)

Notifies all connected media browsers that the children of the specified parent id have changed in some way. This will cause browsers to fetch subscribed content again.

Parameters
parentId String: The id of the parent media item whose children changed.

options Bundle: A bundle of service-specific arguments to send to the media browse. The contents of this bundle may contain the information about the change.

onBind

added in version 23.2.0
IBinder onBind (Intent intent)

Return the communication channel to the service. May return null if clients can not bind to the service. The returned IBinder is usually for a complex interface that has been described using aidl.

Note that unlike other application components, calls on to the IBinder interface returned here may not happen on the main thread of the process. More information about the main thread can be found in Processes and Threads.

Parameters
intent Intent: The Intent that was used to bind to this service, as given to Context.bindService. Note that any extras that were included with the Intent at that point will not be seen here.

Returns
IBinder Return an IBinder through which clients can call on to the service.

onCreate

void onCreate ()

Called by the system when the service is first created. Do not call this method directly.

onCustomAction

added in version 25.4.0
void onCustomAction (String action, 
                Bundle extras, 
                Result<Bundle> result)

Called to request a custom action to this service.

Implementations must call either sendResult(T) or sendError(Bundle). If the requested custom action will be an expensive operation detach() may be called before returning from this function, and then the service can send the result later when the custom action is completed. Implementation can also call sendProgressUpdate(Bundle) to send an interim update to the requester.

If the requested custom action is not supported by this service, call sendError(Bundle). The default implementation will invoke sendError(Bundle).

Parameters
action String: The custom action sent from the media browser.

extras Bundle: The bundle of service-specific arguments sent from the media browser.

result Result: The MediaBrowserServiceCompat.Result to send the result of the requested custom action.

See also:

onGetRoot

added in version 23.2.0
MediaBrowserServiceCompat.BrowserRoot onGetRoot (String clientPackageName, 
                int clientUid, 
                Bundle rootHints)

Called to get the root information for browsing by a particular client.

The implementation should verify that the client package has permission to access browse media information before returning the root id; it should return null if the client is not allowed to access this information.

Parameters
clientPackageName String: The package name of the application which is requesting access to browse media.

clientUid int: The uid of the application which is requesting access to browse media.

rootHints Bundle: An optional bundle of service-specific arguments to send to the media browse service when connecting and retrieving the root id for browsing, or null if none. The contents of this bundle may affect the information returned when browsing.

Returns
MediaBrowserServiceCompat.BrowserRoot The MediaBrowserServiceCompat.BrowserRoot for accessing this app's content or null.

See also:

onLoadChildren

added in version 23.2.0
void onLoadChildren (String parentId, 
                Result<List<MediaBrowserCompat.MediaItem>> result)

Called to get information about the children of a media item.

Implementations must call result.sendResult with the list of children. If loading the children will be an expensive operation that should be performed on another thread, result.detach may be called before returning from this function, and then result.sendResult called when the loading is complete.

In case the media item does not have any children, call sendResult(T) with an empty list. When the given parentId is invalid, implementations must call result.sendResult with null, which will invoke onError(String).

Parameters
parentId String: The id of the parent media item whose children are to be queried.

result Result: The Result to send the list of children to.

onLoadChildren

added in version 24.0.0
void onLoadChildren (String parentId, 
                Result<List<MediaBrowserCompat.MediaItem>> result, 
                Bundle options)

Called to get information about the children of a media item.

Implementations must call result.sendResult with the list of children. If loading the children will be an expensive operation that should be performed on another thread, result.detach may be called before returning from this function, and then result.sendResult called when the loading is complete.

In case the media item does not have any children, call sendResult(T) with an empty list. When the given parentId is invalid, implementations must call result.sendResult with null, which will invoke onError(String).

Parameters
parentId String: The id of the parent media item whose children are to be queried.

result Result: The Result to send the list of children to.

options Bundle: A bundle of service-specific arguments sent from the media browse. The information returned through the result should be affected by the contents of this bundle.

onLoadItem

added in version 23.2.0
void onLoadItem (String itemId, 
                Result<MediaBrowserCompat.MediaItem> result)

Called to get information about a specific media item.

Implementations must call result.sendResult. If loading the item will be an expensive operation result.detach may be called before returning from this function, and then result.sendResult called when the item has been loaded.

When the given itemId is invalid, implementations must call result.sendResult with null.

The default implementation will invoke onError(String).

Parameters
itemId String: The id for the specific MediaBrowserCompat.MediaItem.

result Result: The Result to send the item to, or null if the id is invalid.

onSearch

added in version 25.3.0
void onSearch (String query, 
                Bundle extras, 
                Result<List<MediaBrowserCompat.MediaItem>> result)

Called to get the search result.

Implementations must call result.sendResult. If the search will be an expensive operation result.detach may be called before returning from this function, and then result.sendResult called when the search has been completed.

In case there are no search results, call result.sendResult with an empty list. In case there are some errors happened, call result.sendResult with null, which will invoke onError(String, Bundle).

The default implementation will invoke onError(String, Bundle).

Parameters
query String: The search query sent from the media browser. It contains keywords separated by space.

extras Bundle: The bundle of service-specific arguments sent from the media browser.

result Result: The MediaBrowserServiceCompat.Result to send the search result.

setSessionToken

added in version 23.2.0
void setSessionToken (MediaSessionCompat.Token token)

Call to set the media session.

This should be called as soon as possible during the service's startup. It may only be called once.

Parameters
token MediaSessionCompat.Token: The token for the service's MediaSessionCompat.

This site uses cookies to store your preferences for site-specific language and display options.

Get the latest Android developer news and tips that will help you find success on Google Play.

* Required Fields

Hooray!

Browse this site in ?

You requested a page in , but your language preference for this site is .

Would you like to change your language preference and browse this site in ? If you want to change your language preference later, use the language menu at the bottom of each page.

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.

Take a one-minute survey?
Help us improve Android tools and documentation.