CloudMediaProvider
public
abstract
class
CloudMediaProvider
extends ContentProvider
java.lang.Object | ||
↳ | android.content.ContentProvider | |
↳ | android.provider.CloudMediaProvider |
Base class for a cloud media provider. A cloud media provider offers read-only access to durable media files, specifically photos and videos stored on a local disk, or files in a cloud storage service. To create a cloud media provider, extend this class, implement the abstract methods, and add it to your manifest like this:
<manifest> ... <application> ... <provider android:name="com.example.MyCloudProvider" android:authorities="com.example.mycloudprovider" android:exported="true" android:permission="com.android.providers.media.permission.MANAGE_CLOUD_MEDIA_PROVIDERS" <intent-filter> <action android:name="android.content.action.CLOUD_MEDIA_PROVIDER" /> </intent-filter> </provider> ... </application> </manifest>
When defining your provider, you must protect it with the
CloudMediaProviderContract#MANAGE_CLOUD_MEDIA_PROVIDERS_PERMISSION
, which is a permission
only the system can obtain, trying to define an unprotected CloudMediaProvider
will
result in a SecurityException
.
Applications cannot use a cloud media provider directly; they must go through
MediaStore#ACTION_PICK_IMAGES
which requires a user to actively navigate and select
media items. When a user selects a media item through that UI, the system issues narrow URI
permission grants to the requesting application.
Media items
A media item must be an openable stream (with a specific MIME type). Media items can belong to zero or more albums. Albums cannot contain other albums.
Each item under a provider is uniquely referenced by its media or album id, which must not
change which must be unique across all collection IDs as returned by
onGetMediaCollectionInfo(Bundle)
.
See also:
Summary
Nested classes | |
---|---|
class |
CloudMediaProvider.CloudMediaSurfaceController
Manages rendering the preview of media items on given instances of |
class |
CloudMediaProvider.CloudMediaSurfaceStateChangedCallback
This class is used by |
Inherited constants |
---|
Public constructors | |
---|---|
CloudMediaProvider()
|
Public methods | |
---|---|
final
void
|
attachInfo(Context context, ProviderInfo info)
Implementation is provided by the parent class. |
final
Bundle
|
call(String method, String arg, Bundle extras)
Implementation is provided by the parent class. |
final
Uri
|
canonicalize(Uri uri)
Implementation is provided by the parent class. |
final
int
|
delete(Uri uri, String selection, String[] selectionArgs)
Implementation is provided by the parent class. |
final
String
|
getType(Uri uri)
Implementation is provided by the parent class. |
final
Uri
|
insert(Uri uri, ContentValues values)
Implementation is provided by the parent class. |
CloudMediaProvider.CloudMediaSurfaceController
|
onCreateCloudMediaSurfaceController(Bundle config, CloudMediaProvider.CloudMediaSurfaceStateChangedCallback callback)
Returns a |
abstract
Bundle
|
onGetMediaCollectionInfo(Bundle extras)
Returns metadata about the media collection itself. |
abstract
ParcelFileDescriptor
|
onOpenMedia(String mediaId, Bundle extras, CancellationSignal signal)
Returns the full size media item identified by |
abstract
AssetFileDescriptor
|
onOpenPreview(String mediaId, Point size, Bundle extras, CancellationSignal signal)
Returns a thumbnail of The cloud media provider should strictly return thumbnail in the original
|
Cursor
|
onQueryAlbums(Bundle extras)
Returns a cursor representing all album items in the media collection optionally filtered
by |
abstract
Cursor
|
onQueryDeletedMedia(Bundle extras)
Returns a |
abstract
Cursor
|
onQueryMedia(Bundle extras)
Returns a cursor representing all media items in the media collection optionally filtered by
|
final
ParcelFileDescriptor
|
openFile(Uri uri, String mode, CancellationSignal signal)
Implementation is provided by the parent class. |
final
ParcelFileDescriptor
|
openFile(Uri uri, String mode)
Implementation is provided by the parent class. |
final
AssetFileDescriptor
|
openTypedAssetFile(Uri uri, String mimeTypeFilter, Bundle opts)
Implementation is provided by the parent class. |
final
AssetFileDescriptor
|
openTypedAssetFile(Uri uri, String mimeTypeFilter, Bundle opts, CancellationSignal signal)
Implementation is provided by the parent class. |
final
Cursor
|
query(Uri uri, String[] projection, Bundle queryArgs, CancellationSignal cancellationSignal)
Implementation is provided by the parent class. |
final
Cursor
|
query(Uri uri, String[] projection, String selection, String[] selectionArgs, String sortOrder)
Implementation is provided by the parent class. |
final
Cursor
|
query(Uri uri, String[] projection, String selection, String[] selectionArgs, String sortOrder, CancellationSignal cancellationSignal)
Implementation is provided by the parent class. |
final
int
|
update(Uri uri, ContentValues values, String selection, String[] selectionArgs)
Implementation is provided by the parent class. |
Inherited methods | |
---|---|
Public constructors
Public methods
attachInfo
public final void attachInfo (Context context, ProviderInfo info)
Implementation is provided by the parent class. Cannot be overridden.
Parameters | |
---|---|
context |
Context : This value cannot be null . |
info |
ProviderInfo : This value cannot be null . |
call
public final Bundle call (String method, String arg, Bundle extras)
Implementation is provided by the parent class. Cannot be overridden.
Parameters | |
---|---|
method |
String : This value cannot be null . |
arg |
String : This value may be null . |
extras |
Bundle : This value may be null . |
Returns | |
---|---|
Bundle |
This value cannot be null . |
canonicalize
public final Uri canonicalize (Uri uri)
Implementation is provided by the parent class. Throws by default, and cannot be overridden.
Parameters | |
---|---|
uri |
Uri : This value cannot be null . |
Returns | |
---|---|
Uri |
This value cannot be null . |
delete
public final int delete (Uri uri, String selection, String[] selectionArgs)
Implementation is provided by the parent class. Throws by default, and cannot be overridden.
Parameters | |
---|---|
uri |
Uri : This value cannot be null . |
selection |
String : This value may be null . |
selectionArgs |
String : This value may be null . |
Returns | |
---|---|
int |
The number of rows affected. |
getType
public final String getType (Uri uri)
Implementation is provided by the parent class. Throws by default, and cannot be overridden.
Parameters | |
---|---|
uri |
Uri : This value cannot be null . |
Returns | |
---|---|
String |
This value cannot be null . |
insert
public final Uri insert (Uri uri, ContentValues values)
Implementation is provided by the parent class. Throws by default, and cannot be overridden.
Parameters | |
---|---|
uri |
Uri : This value cannot be null . |
values |
ContentValues : This value cannot be null . |
Returns | |
---|---|
Uri |
This value cannot be null . |
onCreateCloudMediaSurfaceController
public CloudMediaProvider.CloudMediaSurfaceController onCreateCloudMediaSurfaceController (Bundle config, CloudMediaProvider.CloudMediaSurfaceStateChangedCallback callback)
Returns a CloudMediaSurfaceController
used for rendering the preview of media items,
or null if preview rendering is not supported.
Parameters | |
---|---|
config |
Bundle : containing configuration parameters for CloudMediaSurfaceController
null . |
callback |
CloudMediaProvider.CloudMediaSurfaceStateChangedCallback : CloudMediaSurfaceStateChangedCallback to send state updates for
Surface to picker launched via MediaStore#ACTION_PICK_IMAGES
This value cannot be null . |
Returns | |
---|---|
CloudMediaProvider.CloudMediaSurfaceController |
onGetMediaCollectionInfo
public abstract Bundle onGetMediaCollectionInfo (Bundle extras)
Returns metadata about the media collection itself.
This is useful for the OS to determine if its cache of media items in the collection is
still valid and if a full or incremental sync is required with onQueryMedia(Bundle)
.
This method might be called by the OS frequently and is performance critical, hence it should avoid long running operations.
If the provider handled any filters in extras
, it must add the key to the
ContentResolver#EXTRA_HONORED_ARGS
as part of the returned Bundle
.
Parameters | |
---|---|
extras |
Bundle : containing keys to filter result:
This value cannot be null . |
onOpenMedia
public abstract ParcelFileDescriptor onOpenMedia (String mediaId, Bundle extras, CancellationSignal signal)
Returns the full size media item identified by mediaId
.
If you block while downloading content, you should periodically check
CancellationSignal#isCanceled()
to abort abandoned open requests.
Parameters | |
---|---|
mediaId |
String : the media item to return
This value cannot be null . |
extras |
Bundle : to modify the way the fd is opened, there's none at the moment, but some
might be implemented in the future
This value may be null . |
signal |
CancellationSignal : used by the OS to signal if the request should be cancelled
This value may be null . |
Returns | |
---|---|
ParcelFileDescriptor |
read-only file descriptor for accessing the media file
This value cannot be null . |
Throws | |
---|---|
FileNotFoundException |
onOpenPreview
public abstract AssetFileDescriptor onOpenPreview (String mediaId, Point size, Bundle extras, CancellationSignal signal)
Returns a thumbnail of size
for a media item identified by mediaId
The cloud media provider should strictly return thumbnail in the original
CloudMediaProviderContract.MediaColumns#MIME_TYPE
of the item.
This is expected to be a much lower resolution version than the item returned by
onOpenMedia(String, Bundle, CancellationSignal)
.
If you block while downloading content, you should periodically check
CancellationSignal#isCanceled()
to abort abandoned open requests.
Parameters | |
---|---|
mediaId |
String : the media item to return
This value cannot be null . |
size |
Point : the dimensions of the thumbnail to return. The returned file descriptor doesn't
have to match the size precisely because the OS will adjust the dimensions before
usage. Implementations can return close approximations especially if the approximation is
already locally on the device and doesn't require downloading from the cloud.
This value cannot be null . |
extras |
Bundle : to modify the way the fd is opened, e.g. for video files we may request a
thumbnail image instead of a video with
CloudMediaProviderContract#EXTRA_PREVIEW_THUMBNAIL
This value may be null . |
signal |
CancellationSignal : used by the OS to signal if the request should be cancelled
This value may be null . |
Returns | |
---|---|
AssetFileDescriptor |
read-only file descriptor for accessing the thumbnail for the media file
This value cannot be null . |
Throws | |
---|---|
FileNotFoundException |
onQueryAlbums
public Cursor onQueryAlbums (Bundle extras)
Returns a cursor representing all album items in the media collection optionally filtered
by extras
and sorted in reverse chronological order of
CloudMediaProviderContract.AlbumColumns#DATE_TAKEN_MILLIS
, i.e. most recent items
first.
The cloud media provider must set the
CloudMediaProviderContract#EXTRA_MEDIA_COLLECTION_ID
as part of the returned
Cursor#setExtras
Bundle
. Not setting this is an error and invalidates the
returned Cursor
.
If the provider handled any filters in extras
, it must add the key to
the ContentResolver#EXTRA_HONORED_ARGS
as part of the returned
Cursor#setExtras
Bundle
.
Parameters | |
---|---|
extras |
Bundle : containing keys to filter album items:
null . |
Returns | |
---|---|
Cursor |
cursor representing album items containing all
CloudMediaProviderContract.AlbumColumns columns
This value cannot be null . |
onQueryDeletedMedia
public abstract Cursor onQueryDeletedMedia (Bundle extras)
Returns a Cursor
representing all deleted media items in the entire media collection
within the current provider version as returned by onGetMediaCollectionInfo(Bundle)
. These
items can be optionally filtered by extras
.
The cloud media provider must set the
CloudMediaProviderContract#EXTRA_MEDIA_COLLECTION_ID
as part of the returned
Cursor#setExtras
Bundle
. Not setting this is an error and invalidates the
returned Cursor
.
If the provider handled any filters in extras
, it must add the key to
the ContentResolver#EXTRA_HONORED_ARGS
as part of the returned
Cursor#setExtras
Bundle
.
Parameters | |
---|---|
extras |
Bundle : containing keys to filter deleted media items:
This value cannot be null . |
Returns | |
---|---|
Cursor |
cursor representing deleted media items containing just the
CloudMediaProviderContract.MediaColumns#ID column
This value cannot be null . |
onQueryMedia
public abstract Cursor onQueryMedia (Bundle extras)
Returns a cursor representing all media items in the media collection optionally filtered by
extras
and sorted in reverse chronological order of
CloudMediaProviderContract.MediaColumns#DATE_TAKEN_MILLIS
, i.e. most recent items
first.
The cloud media provider must set the
CloudMediaProviderContract#EXTRA_MEDIA_COLLECTION_ID
as part of the returned
Cursor#setExtras
Bundle
. Not setting this is an error and invalidates the
returned Cursor
.
If the cloud media provider handled any filters in extras
, it must add the key to
the ContentResolver#EXTRA_HONORED_ARGS
as part of the returned
Cursor#setExtras
Bundle
.
Parameters | |
---|---|
extras |
Bundle : containing keys to filter media items:
null . |
Returns | |
---|---|
Cursor |
cursor representing media items containing all
CloudMediaProviderContract.MediaColumns columns
This value cannot be null . |
openFile
public final ParcelFileDescriptor openFile (Uri uri, String mode, CancellationSignal signal)
Implementation is provided by the parent class. Cannot be overridden.
Parameters | |
---|---|
uri |
Uri : This value cannot be null . |
mode |
String : This value cannot be null . |
signal |
CancellationSignal : This value may be null . |
Returns | |
---|---|
ParcelFileDescriptor |
This value cannot be null . |
Throws | |
---|---|
FileNotFoundException |
openFile
public final ParcelFileDescriptor openFile (Uri uri, String mode)
Implementation is provided by the parent class. Cannot be overridden.
Parameters | |
---|---|
uri |
Uri : This value cannot be null . |
mode |
String : This value cannot be null . |
Returns | |
---|---|
ParcelFileDescriptor |
This value cannot be null . |
Throws | |
---|---|
FileNotFoundException |
openTypedAssetFile
public final AssetFileDescriptor openTypedAssetFile (Uri uri, String mimeTypeFilter, Bundle opts)
Implementation is provided by the parent class. Cannot be overridden.
Parameters | |
---|---|
uri |
Uri : This value cannot be null . |
mimeTypeFilter |
String : This value cannot be null . |
opts |
Bundle : This value may be null . |
Returns | |
---|---|
AssetFileDescriptor |
This value cannot be null . |
Throws | |
---|---|
FileNotFoundException |
openTypedAssetFile
public final AssetFileDescriptor openTypedAssetFile (Uri uri, String mimeTypeFilter, Bundle opts, CancellationSignal signal)
Implementation is provided by the parent class. Cannot be overridden.
Parameters | |
---|---|
uri |
Uri : This value cannot be null . |
mimeTypeFilter |
String : This value cannot be null . |
opts |
Bundle : This value may be null . |
signal |
CancellationSignal : This value may be null . |
Returns | |
---|---|
AssetFileDescriptor |
This value cannot be null . |
Throws | |
---|---|
FileNotFoundException |
query
public final Cursor query (Uri uri, String[] projection, Bundle queryArgs, CancellationSignal cancellationSignal)
Implementation is provided by the parent class. Cannot be overridden.
Parameters | |
---|---|
uri |
Uri : This value cannot be null . |
projection |
String : This value may be null . |
queryArgs |
Bundle : This value may be null . |
cancellationSignal |
CancellationSignal : This value may be null . |
Returns | |
---|---|
Cursor |
This value cannot be null . |
query
public final Cursor query (Uri uri, String[] projection, String selection, String[] selectionArgs, String sortOrder)
Implementation is provided by the parent class. Throws by default, and cannot be overridden.
Parameters | |
---|---|
uri |
Uri : This value cannot be null . |
projection |
String : This value may be null . |
selection |
String : This value may be null . |
selectionArgs |
String : This value may be null . |
sortOrder |
String : This value may be null . |
Returns | |
---|---|
Cursor |
This value cannot be null . |
query
public final Cursor query (Uri uri, String[] projection, String selection, String[] selectionArgs, String sortOrder, CancellationSignal cancellationSignal)
Implementation is provided by the parent class. Throws by default, and cannot be overridden.
Parameters | |
---|---|
uri |
Uri : This value cannot be null . |
projection |
String : This value may be null . |
selection |
String : This value may be null . |
selectionArgs |
String : This value may be null . |
sortOrder |
String : This value may be null . |
cancellationSignal |
CancellationSignal : This value may be null . |
Returns | |
---|---|
Cursor |
This value cannot be null . |
update
public final int update (Uri uri, ContentValues values, String selection, String[] selectionArgs)
Implementation is provided by the parent class. Throws by default, and cannot be overridden.
Parameters | |
---|---|
uri |
Uri : This value cannot be null . |
values |
ContentValues : This value cannot be null . |
selection |
String : This value may be null . |
selectionArgs |
String : This value may be null . |
Returns | |
---|---|
int |
the number of rows affected. |
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2024-06-18 UTC.