Android Dev Summit, October 23-24: two days of technical content, directly from the Android team. Sign-up for livestream updates.

MediaBrowserServiceCompat

abstract class MediaBrowserServiceCompat : Service
kotlin.Any
   ↳ android.content.Context
   ↳ android.content.ContextWrapper
   ↳ android.app.Service
   ↳ androidx.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>
  

Summary

Nested classes

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

open

Completion handler for asynchronous callback methods in MediaBrowserServiceCompat.

Constants

static String

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

Public constructors

Base class for media browse services.

Public methods

open Unit
dump(fd: FileDescriptor!, writer: PrintWriter!, args: Array<String!>!)

Bundle!

Gets the root hints sent from the currently connected MediaBrowserCompat.

MediaSessionManager.RemoteUserInfo

Gets the browser information who sent the current request.

open MediaSessionCompat.Token?

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

open Unit
notifyChildrenChanged(@NonNull parentId: String)

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

open Unit
notifyChildrenChanged(@NonNull parentId: String, @NonNull options: Bundle)

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

open IBinder!
onBind(intent: Intent!)

open Unit

open Unit
onCustomAction(@NonNull action: String, extras: Bundle!, @NonNull result: MediaBrowserServiceCompat.Result<Bundle!>)

Called to request a custom action to this service.

abstract MediaBrowserServiceCompat.BrowserRoot?
onGetRoot(@NonNull clientPackageName: String, clientUid: Int, @Nullable rootHints: Bundle?)

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

abstract Unit

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

open Unit
onLoadChildren(@NonNull parentId: String, @NonNull result: MediaBrowserServiceCompat.Result<MutableList<MediaBrowserCompat.MediaItem!>!>, @NonNull options: Bundle)

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

open Unit

Called to get information about a specific media item.

open Unit

Called to get the search result.

open Unit

Call to set the media session.

Constants

SERVICE_INTERFACE

static val SERVICE_INTERFACE: String

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

Value: "android.media.browse.MediaBrowserService"

Public constructors

<init>

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>
  

Public methods

dump

open fun dump(fd: FileDescriptor!, writer: PrintWriter!, args: Array<String!>!): Unit

getBrowserRootHints

fun getBrowserRootHints(): Bundle!

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 android.media.browse.MediaBrowser and running on API 23 or lower.

Exceptions
IllegalStateException If this method is called outside of onLoadChildren, onLoadItem or onSearch.

getCurrentBrowserInfo

@NonNull fun getCurrentBrowserInfo(): MediaSessionManager.RemoteUserInfo

Gets the browser information who sent the current request.

Exceptions
IllegalStateException If this method is called outside of onGetRoot or onLoadChildren or onLoadItem.

getSessionToken

@Nullable open fun getSessionToken(): MediaSessionCompat.Token?

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

notifyChildrenChanged

open fun notifyChildrenChanged(@NonNull parentId: String): Unit

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

open fun notifyChildrenChanged(@NonNull parentId: String, @NonNull options: Bundle): Unit

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 String: 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

open fun onBind(intent: Intent!): IBinder!

onCreate

open fun onCreate(): Unit

onCustomAction

open fun onCustomAction(@NonNull action: String, extras: Bundle!, @NonNull result: MediaBrowserServiceCompat.Result<Bundle!>): Unit

Called to request a custom action to this service.

Implementations must call either Result#sendResult or Result#sendError. If the requested custom action will be an expensive operation Result#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 Result#sendProgressUpdate to send an interim update to the requester.

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

Parameters
action String: The custom action sent from the media browser.
extras String: The bundle of service-specific arguments sent from the media browser.
result String: The Result to send the result of the requested custom action.

onGetRoot

@Nullable abstract fun onGetRoot(@NonNull clientPackageName: String, clientUid: Int, @Nullable rootHints: Bundle?): MediaBrowserServiceCompat.BrowserRoot?

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 String: The uid of the application which is requesting access to browse media.
rootHints String: 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.
Return
MediaBrowserServiceCompat.BrowserRoot?: The BrowserRoot for accessing this app's content or null.

onLoadChildren

abstract fun onLoadChildren(@NonNull parentId: String, @NonNull result: MediaBrowserServiceCompat.Result<MutableList<MediaBrowserCompat.MediaItem!>!>): Unit

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 Result#sendResult with an empty list. When the given parentId is invalid, implementations must call result.sendResult with null, which will invoke MediaBrowserCompat.SubscriptionCallback#onError.

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

onLoadChildren

open fun onLoadChildren(@NonNull parentId: String, @NonNull result: MediaBrowserServiceCompat.Result<MutableList<MediaBrowserCompat.MediaItem!>!>, @NonNull options: Bundle): Unit

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 Result#sendResult with an empty list. When the given parentId is invalid, implementations must call result.sendResult with null, which will invoke MediaBrowserCompat.SubscriptionCallback#onError.

Parameters
parentId String: The id of the parent media item whose children are to be queried.
result String: The Result to send the list of children to.
options String: 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

open fun onLoadItem(itemId: String!, @NonNull result: MediaBrowserServiceCompat.Result<MediaBrowserCompat.MediaItem!>): Unit

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 MediaBrowserCompat.ItemCallback#onError.

Parameters
itemId String!: The id for the specific MediaBrowserCompat.MediaItem.
result String!: The Result to send the item to, or null if the id is invalid.

onSearch

open fun onSearch(@NonNull query: String, extras: Bundle!, @NonNull result: MediaBrowserServiceCompat.Result<MutableList<MediaBrowserCompat.MediaItem!>!>): Unit

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 .

The default implementation will invoke MediaBrowserCompat.SearchCallback#onError.

Parameters
query String: The search query sent from the media browser. It contains keywords separated by space.
extras String: The bundle of service-specific arguments sent from the media browser.
result String: The Result to send the search result.

setSessionToken

open fun setSessionToken(token: MediaSessionCompat.Token!): Unit

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.