MediaBrowserCompat
public final class MediaBrowserCompat
Browses media content offered by a MediaBrowserServiceCompat.
The app targeting API level 30 or higher must include a <queries> element in their manifest to connect to a media browser service in another app. See the following example and this guide for more information.
<!-- As an intent action --> <intent> <action android:name="android.media.browse.MediaBrowserService" /> </intent> <!-- Or, as a package name --> <package android:name="package_name_of_the_other_app" />
This object is not thread-safe. All calls should happen on the thread on which the browser was constructed. All callback methods will be called from the thread on which the browser was constructed.
Summary
Nested types |
|---|
public class MediaBrowserCompat.ConnectionCallbackCallbacks for connection related events. |
public abstract class MediaBrowserCompat.CustomActionCallbackCallback for receiving the result of |
public abstract class MediaBrowserCompat.ItemCallbackCallback for receiving the result of |
public class MediaBrowserCompat.MediaItem implements ParcelableA class with information on a single media item for use in browsing/searching media. |
public abstract class MediaBrowserCompat.SearchCallbackCallback for receiving the result of |
public abstract class MediaBrowserCompat.SubscriptionCallbackCallbacks for subscription related events. |
Constants |
|
|---|---|
static final String |
CUSTOM_ACTION_DOWNLOAD = "android.support.v4.media.action.DOWNLOAD"Predefined custom action to ask the connected service to download a specific |
static final String |
CUSTOM_ACTION_REMOVE_DOWNLOADED_FILE = "android.support.v4.media.action.REMOVE_DOWNLOADED_FILE"Predefined custom action to ask the connected service to remove the downloaded file of |
static final String |
EXTRA_DOWNLOAD_PROGRESS = "android.media.browse.extra.DOWNLOAD_PROGRESS"Used as a float extra field to denote the current progress during download. |
static final String |
EXTRA_MEDIA_ID = "android.media.browse.extra.MEDIA_ID"Used as a string extra field to denote the target |
static final String |
EXTRA_PAGE = "android.media.browse.extra.PAGE"Used as an int extra field to denote the page number to subscribe. |
static final String |
EXTRA_PAGE_SIZE = "android.media.browse.extra.PAGE_SIZE"Used as an int extra field to denote the number of media items in a page. |
Public constructors |
|---|
MediaBrowserCompat(Creates a media browser for the specified media browse service. |
Public methods |
|
|---|---|
void |
connect()Connects to the media browse service. |
void |
Disconnects from the media browse service. |
@Nullable Bundle |
Gets any extras for the media service. |
void |
getItem(Retrieves a specific |
@NonNull String |
getRoot()Gets the root id. |
@NonNull ComponentName |
Gets the service component that the media browser is connected to. |
@NonNull MediaSessionCompat.Token |
Gets the media session token associated with the media browser. |
boolean |
Returns whether the browser is connected to the service. |
void |
Searches |
void |
sendCustomAction(Sends a custom action to the connected service. |
void |
subscribe(Queries for information about the media items that are contained within the specified id and subscribes to receive updates when they change. |
void |
subscribe(Queries with service-specific arguments for information about the media items that are contained within the specified id and subscribes to receive updates when they change. |
void |
unsubscribe(@NonNull String parentId)Unsubscribes for changes to the children of the specified media id. |
void |
unsubscribe(Unsubscribes for changes to the children of the specified media id. |
Constants
CUSTOM_ACTION_DOWNLOAD
public static final String CUSTOM_ACTION_DOWNLOAD = "android.support.v4.media.action.DOWNLOAD"
Predefined custom action to ask the connected service to download a specific MediaItem for offline playback. The id of the media item must be passed in an extra bundle. The download progress might be delivered to the browser via onProgressUpdate.
CUSTOM_ACTION_REMOVE_DOWNLOADED_FILE
public static final String CUSTOM_ACTION_REMOVE_DOWNLOADED_FILE = "android.support.v4.media.action.REMOVE_DOWNLOADED_FILE"
Predefined custom action to ask the connected service to remove the downloaded file of MediaItem by the download action. The id of the media item must be passed in an extra bundle.
| See also | |
|---|---|
EXTRA_MEDIA_ID |
|
CUSTOM_ACTION_DOWNLOAD |
EXTRA_DOWNLOAD_PROGRESS
public static final String EXTRA_DOWNLOAD_PROGRESS = "android.media.browse.extra.DOWNLOAD_PROGRESS"
Used as a float extra field to denote the current progress during download. The value of this field must be a float number within [0.0, 1.0].
| See also | |
|---|---|
CUSTOM_ACTION_DOWNLOAD |
|
onProgressUpdate |
EXTRA_MEDIA_ID
public static final String EXTRA_MEDIA_ID = "android.media.browse.extra.MEDIA_ID"
Used as a string extra field to denote the target MediaItem.
EXTRA_PAGE
public static final String EXTRA_PAGE = "android.media.browse.extra.PAGE"
Used as an int extra field to denote the page number to subscribe. The value of EXTRA_PAGE should be greater than or equal to 0.
EXTRA_PAGE_SIZE
public static final String EXTRA_PAGE_SIZE = "android.media.browse.extra.PAGE_SIZE"
Used as an int extra field to denote the number of media items in a page. The value of EXTRA_PAGE_SIZE should be greater than or equal to 1.
Public constructors
MediaBrowserCompat
public MediaBrowserCompat(
Context context,
ComponentName serviceComponent,
MediaBrowserCompat.ConnectionCallback callback,
Bundle rootHints
)
Creates a media browser for the specified media browse service.
| Parameters | |
|---|---|
Context context |
The context. |
ComponentName serviceComponent |
The component name of the media browse service. |
MediaBrowserCompat.ConnectionCallback callback |
The connection callback. |
Bundle rootHints |
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. |
| See also | |
|---|---|
EXTRA_RECENT |
|
EXTRA_OFFLINE |
|
EXTRA_SUGGESTED |
Public methods
connect
public void connect()
Connects to the media browse service. Internally, it binds to the service.
The connection callback specified in the constructor will be invoked when the connection completes or fails.
disconnect
public void disconnect()
Disconnects from the media browse service. After this, no more callbacks will be received.
getExtras
public @Nullable Bundle getExtras()
Gets any extras for the media service.
| Throws | |
|---|---|
java.lang.IllegalStateException |
if not connected. |
getItem
public void getItem(
@NonNull String mediaId,
@NonNull MediaBrowserCompat.ItemCallback cb
)
Retrieves a specific MediaItem from the connected service. Not all services may support this, so falling back to subscribing to the parent's id should be used when unavailable.
| Parameters | |
|---|---|
@NonNull String mediaId |
The id of the item to retrieve. |
@NonNull MediaBrowserCompat.ItemCallback cb |
The callback to receive the result on. |
getRoot
public @NonNull String getRoot()
Gets the root id.
Note that the root id may become invalid or change when when the browser is disconnected.
| Throws | |
|---|---|
java.lang.IllegalStateException |
if not connected. |
getServiceComponent
public @NonNull ComponentName getServiceComponent()
Gets the service component that the media browser is connected to.
getSessionToken
public @NonNull MediaSessionCompat.Token getSessionToken()
Gets the media session token associated with the media browser.
Note that the session token may become invalid or change when when the browser is disconnected.
| Returns | |
|---|---|
@NonNull MediaSessionCompat.Token |
The session token for the browser, never null. |
| Throws | |
|---|---|
java.lang.IllegalStateException |
if not connected. |
isConnected
public boolean isConnected()
Returns whether the browser is connected to the service.
search
public void search(
@NonNull String query,
Bundle extras,
@NonNull MediaBrowserCompat.SearchCallback callback
)
Searches media items from the connected service. Not all services may support this, and onError will be called if not implemented.
| Parameters | |
|---|---|
@NonNull String query |
The search query that contains keywords separated by space. Should not be an empty string. |
Bundle extras |
The bundle of service-specific arguments to send to the media browser service. The contents of this bundle may affect the search result. |
@NonNull MediaBrowserCompat.SearchCallback callback |
The callback to receive the search result. Must be non-null. |
| Throws | |
|---|---|
java.lang.IllegalStateException |
if the browser is not connected to the media browser service. |
sendCustomAction
public void sendCustomAction(
@NonNull String action,
Bundle extras,
@Nullable MediaBrowserCompat.CustomActionCallback callback
)
Sends a custom action to the connected service. If the service doesn't support the given action, onError will be called.
| Parameters | |
|---|---|
@NonNull String action |
The custom action that will be sent to the connected service. Should not be an empty string. |
Bundle extras |
The bundle of service-specific arguments to send to the media browser service. |
@Nullable MediaBrowserCompat.CustomActionCallback callback |
The callback to receive the result of the custom action. |
subscribe
public void subscribe(
@NonNull String parentId,
@NonNull MediaBrowserCompat.SubscriptionCallback callback
)
Queries for information about the media items that are contained within the specified id and subscribes to receive updates when they change.
The list of subscriptions is maintained even when not connected and is restored after the reconnection. It is ok to subscribe while not connected but the results will not be returned until the connection completes.
If the id is already subscribed with a different callback then the new callback will replace the previous one and the child data will be reloaded.
| Parameters | |
|---|---|
@NonNull String parentId |
The id of the parent media item whose list of children will be subscribed. |
@NonNull MediaBrowserCompat.SubscriptionCallback callback |
The callback to receive the list of children. |
subscribe
public void subscribe(
@NonNull String parentId,
@NonNull Bundle options,
@NonNull MediaBrowserCompat.SubscriptionCallback callback
)
Queries with service-specific arguments for information about the media items that are contained within the specified id and subscribes to receive updates when they change.
The list of subscriptions is maintained even when not connected and is restored after the reconnection. It is ok to subscribe while not connected but the results will not be returned until the connection completes.
If the id is already subscribed with a different callback then the new callback will replace the previous one and the child data will be reloaded.
| Parameters | |
|---|---|
@NonNull String parentId |
The id of the parent media item whose list of children will be subscribed. |
@NonNull Bundle options |
A bundle of service-specific arguments to send to the media browse service. The contents of this bundle may affect the information returned when browsing. |
@NonNull MediaBrowserCompat.SubscriptionCallback callback |
The callback to receive the list of children. |
unsubscribe
public void unsubscribe(@NonNull String parentId)
Unsubscribes for changes to the children of the specified media id.
The query callback will no longer be invoked for results associated with this id once this method returns.
unsubscribe
public void unsubscribe(
@NonNull String parentId,
@NonNull MediaBrowserCompat.SubscriptionCallback callback
)
Unsubscribes for changes to the children of the specified media id.
The query callback will no longer be invoked for results associated with this id once this method returns.
| Parameters | |
|---|---|
@NonNull String parentId |
The id of the parent media item whose list of children will be unsubscribed. |
@NonNull MediaBrowserCompat.SubscriptionCallback callback |
A callback sent to the media browse service to subscribe. |