为 Android 创建云媒体提供程序

云媒体提供程序为 Android 照片选择器 提供额外的云媒体内容。当应用使用 ACTION_PICK_IMAGES 或 ACTION_GET_CONTENT 从用户请求媒体文件时，用户可以选择云媒体提供程序提供的照片或视频。云媒体提供程序还可以提供有关相册的信息，用户可以在 Android 照片选择器中浏览这些信息。

开始之前

在开始构建您的云媒体提供程序之前，请考虑以下事项。

资格

Android 正在运行一项试点计划，允许 OEM 提名的应用成为云媒体提供程序。目前，只有 OEM 提名的应用才有资格参加该计划，成为 Android 的云媒体提供程序。每个 OEM 可以提名最多 3 个应用。这些应用获得批准后，将成为安装了这些应用的任何 GMS Android 驱动设备上的云媒体提供程序。

Android 在服务器端维护所有合格云提供程序的列表。每个 OEM 可以使用 可配置覆盖层 选择默认云提供程序。提名的应用必须满足所有技术要求，并通过所有质量测试。要了解有关 OEM 云媒体提供程序试点计划的流程和要求的更多信息，请 填写调查表。

确定是否需要创建云媒体提供程序

云媒体提供商旨在成为应用或服务，作为用户备份和从云端检索照片和视频的主要来源。如果您的应用拥有有用的内容库，但通常不用作照片存储解决方案，您应该考虑创建 文档提供商。

每个配置文件只有一个活动云提供商

每个 Android 个人资料 同时最多只能有一个活动云媒体提供商。用户可以随时从照片选择器设置中删除或更改其选择的云媒体提供商应用。

默认情况下，Android 照片选择器将尝试自动选择云提供商。

• 如果设备上只有一个符合条件的云提供商，则该应用将自动被选中作为当前提供商。

• 如果设备上有多个符合条件的云提供商，并且其中一个与 OEM 选择的默认值匹配，则将选择 OEM 选择的应用。

• 如果设备上有多个符合条件的云提供商，并且没有一个与 OEM 选择的默认值匹配，则不会选择任何应用。

构建您的云媒体提供商

下图说明了 Android 应用、Android 照片选择器、本地设备的 MediaProvider 和 CloudMediaProvider 之间在照片选择会话之前和期间的事件顺序。

1. 系统会初始化用户的首选云提供商，并定期将媒体元数据同步到 Android 照片选择器后端。
2. 当 Android 应用启动照片选择器时，在向用户显示合并的本地或云项目网格之前，照片选择器会与云提供商进行延迟敏感的增量同步，以确保结果尽可能最新。在收到响应或达到截止日期后，照片选择器网格现在将显示所有可访问的照片，将存储在设备上的照片与从云端同步的照片合并。
3. 当用户滚动时，照片选择器会从云媒体提供商获取媒体缩略图以显示在 UI 中。
4. 当用户完成会话并且结果包含云媒体项目时，照片选择器会请求内容的文件描述符，生成 URI，并授予调用应用程序对该文件的访问权限。
5. 应用现在可以打开 URI 并且对媒体内容具有只读访问权限。默认情况下，敏感元数据会被屏蔽。照片选择器利用 FUSE 文件系统来协调 Android 应用和云媒体提供商之间的数据交换。

常见问题

在考虑您的实现时，以下是一些需要牢记的重要事项

避免重复文件

由于 Android 照片选择器无法检查云媒体状态，因此 CloudMediaProvider 需要在光标行中提供 MEDIA_STORE_URI，用于同时存在于云端和本地设备上的任何文件，否则用户将在照片选择器中看到重复文件。

优化预览显示的图像大小

从 onOpenPreview 返回的文件不是完整分辨率的图像，并且必须符合请求的 Size，这一点非常重要。图像太大会导致 UI 加载时间过长，图像太小可能会根据设备屏幕尺寸出现像素化或模糊。

处理正确的方向

如果 onOpenPreview 中返回的缩略图不包含其 EXIF 数据，则应以正确的方向返回它们，以避免缩略图在预览网格中被错误旋转。

防止未经授权的访问

在从 ContentProvider 向调用方返回数据之前，检查 MANAGE_CLOUD_MEDIA_PROVIDERS_PERMISSION。这将防止未经授权的应用访问云数据。

CloudMediaProvider 类

从 android.content.ContentProvider 派生的 CloudMediaProvider 类包含以下示例中显示的方法

abstract class CloudMediaProvider : ContentProvider() {

    @NonNull
    abstract override fun onGetMediaCollectionInfo(@NonNull bundle: Bundle): Bundle

    @NonNull
    override fun onQueryAlbums(@NonNull bundle: Bundle): Cursor = TODO("Implement onQueryAlbums")

    @NonNull
    abstract override fun onQueryDeletedMedia(@NonNull bundle: Bundle): Cursor

    @NonNull
    abstract override fun onQueryMedia(@NonNull bundle: Bundle): Cursor

    @NonNull
    abstract override fun onOpenMedia(
        @NonNull string: String,
        @Nullable bundle: Bundle?,
        @Nullable cancellationSignal: CancellationSignal?
    ): ParcelFileDescriptor

    @NonNull
    abstract override fun onOpenPreview(
        @NonNull string: String,
        @NonNull point: Point,
        @Nullable bundle: Bundle?,
        @Nullable cancellationSignal: CancellationSignal?
    ): AssetFileDescriptor

    @Nullable
    override fun onCreateCloudMediaSurfaceController(
        @NonNull bundle: Bundle,
        @NonNull callback: CloudMediaSurfaceStateChangedCallback
    ): CloudMediaSurfaceController? = null
}

public abstract class CloudMediaProvider extends android.content.ContentProvider {

  @NonNull
  public abstract android.os.Bundle onGetMediaCollectionInfo(@NonNull android.os.Bundle);

  @NonNull
  public android.database.Cursor onQueryAlbums(@NonNull android.os.Bundle);

  @NonNull
  public abstract android.database.Cursor onQueryDeletedMedia(@NonNull android.os.Bundle);

  @NonNull
  public abstract android.database.Cursor onQueryMedia(@NonNull android.os.Bundle);

  @NonNull
  public abstract android.os.ParcelFileDescriptor onOpenMedia(@NonNull String, @Nullable android.os.Bundle, @Nullable android.os.CancellationSignal) throws java.io.FileNotFoundException;

  @NonNull
  public abstract android.content.res.AssetFileDescriptor onOpenPreview(@NonNull String, @NonNull android.graphics.Point, @Nullable android.os.Bundle, @Nullable android.os.CancellationSignal) throws java.io.FileNotFoundException;

  @Nullable
  public android.provider.CloudMediaProvider.CloudMediaSurfaceController onCreateCloudMediaSurfaceController(@NonNull android.os.Bundle, @NonNull android.provider.CloudMediaProvider.CloudMediaSurfaceStateChangedCallback);
}

CloudMediaProviderContract 类

除了主要的 CloudMediaProvider 实现类之外，Android 照片选择器还包含一个 CloudMediaProviderContract 类。此类概述了照片选择器和云媒体提供商之间的互操作性，包括 MediaCollectionInfo（用于同步操作）、预期 Cursor 列和 Bundle 附加信息等方面。

object CloudMediaProviderContract {

    const val EXTRA_ALBUM_ID = "android.provider.extra.ALBUM_ID"
    const val EXTRA_LOOPING_PLAYBACK_ENABLED = "android.provider.extra.LOOPING_PLAYBACK_ENABLED"
    const val EXTRA_MEDIA_COLLECTION_ID = "android.provider.extra.MEDIA_COLLECTION_ID"
    const val EXTRA_PAGE_SIZE = "android.provider.extra.PAGE_SIZE"
    const val EXTRA_PAGE_TOKEN = "android.provider.extra.PAGE_TOKEN"
    const val EXTRA_PREVIEW_THUMBNAIL = "android.provider.extra.PREVIEW_THUMBNAIL"
    const val EXTRA_SURFACE_CONTROLLER_AUDIO_MUTE_ENABLED = "android.provider.extra.SURFACE_CONTROLLER_AUDIO_MUTE_ENABLED"
    const val EXTRA_SYNC_GENERATION = "android.provider.extra.SYNC_GENERATION"
    const val MANAGE_CLOUD_MEDIA_PROVIDERS_PERMISSION = "com.android.providers.media.permission.MANAGE_CLOUD_MEDIA_PROVIDERS"
    const val PROVIDER_INTERFACE = "android.content.action.CLOUD_MEDIA_PROVIDER"

    object MediaColumns {
        const val DATE_TAKEN_MILLIS = "date_taken_millis"
        const val DURATION_MILLIS = "duration_millis"
        const val HEIGHT = "height"
        const val ID = "id"
        const val IS_FAVORITE = "is_favorite"
        const val MEDIA_STORE_URI = "media_store_uri"
        const val MIME_TYPE = "mime_type"
        const val ORIENTATION = "orientation"
        const val SIZE_BYTES = "size_bytes"
        const val STANDARD_MIME_TYPE_EXTENSION = "standard_mime_type_extension"
        const val STANDARD_MIME_TYPE_EXTENSION_ANIMATED_WEBP = 3 // 0x3
        const val STANDARD_MIME_TYPE_EXTENSION_GIF = 1 // 0x1
        const val STANDARD_MIME_TYPE_EXTENSION_MOTION_PHOTO = 2 // 0x2
        const val STANDARD_MIME_TYPE_EXTENSION_NONE = 0 // 0x0
        const val SYNC_GENERATION = "sync_generation"
        const val WIDTH = "width"
    }

    object AlbumColumns {
        const val DATE_TAKEN_MILLIS = "date_taken_millis"
        const val DISPLAY_NAME = "display_name"
        const val ID = "id"
        const val MEDIA_COUNT = "album_media_count"
        const val MEDIA_COVER_ID = "album_media_cover_id"
    }

    object MediaCollectionInfo {
        const val ACCOUNT_CONFIGURATION_INTENT = "account_configuration_intent"
        const val ACCOUNT_NAME = "account_name"
        const val LAST_MEDIA_SYNC_GENERATION = "last_media_sync_generation"
        const val MEDIA_COLLECTION_ID = "media_collection_id"
    }
}

public final class CloudMediaProviderContract {

  public static final String EXTRA_ALBUM_ID = "android.provider.extra.ALBUM_ID";
  public static final String EXTRA_LOOPING_PLAYBACK_ENABLED = "android.provider.extra.LOOPING_PLAYBACK_ENABLED";
  public static final String EXTRA_MEDIA_COLLECTION_ID = "android.provider.extra.MEDIA_COLLECTION_ID";
  public static final String EXTRA_PAGE_SIZE = "android.provider.extra.PAGE_SIZE";
  public static final String EXTRA_PAGE_TOKEN = "android.provider.extra.PAGE_TOKEN";
  public static final String EXTRA_PREVIEW_THUMBNAIL = "android.provider.extra.PREVIEW_THUMBNAIL";
  public static final String EXTRA_SURFACE_CONTROLLER_AUDIO_MUTE_ENABLED = "android.provider.extra.SURFACE_CONTROLLER_AUDIO_MUTE_ENABLED";
  public static final String EXTRA_SYNC_GENERATION = "android.provider.extra.SYNC_GENERATION";
  public static final String MANAGE_CLOUD_MEDIA_PROVIDERS_PERMISSION = "com.android.providers.media.permission.MANAGE_CLOUD_MEDIA_PROVIDERS";
  public static final String PROVIDER_INTERFACE = "android.content.action.CLOUD_MEDIA_PROVIDER";
}

// Columns available for every media item
public static final class CloudMediaProviderContract.MediaColumns {

  public static final String DATE_TAKEN_MILLIS = "date_taken_millis";
  public static final String DURATION_MILLIS = "duration_millis";
  public static final String HEIGHT = "height";
  public static final String ID = "id";
  public static final String IS_FAVORITE = "is_favorite";
  public static final String MEDIA_STORE_URI = "media_store_uri";
  public static final String MIME_TYPE = "mime_type";
  public static final String ORIENTATION = "orientation";
  public static final String SIZE_BYTES = "size_bytes";
  public static final String STANDARD_MIME_TYPE_EXTENSION = "standard_mime_type_extension";
  public static final int STANDARD_MIME_TYPE_EXTENSION_ANIMATED_WEBP = 3; // 0x3
  public static final int STANDARD_MIME_TYPE_EXTENSION_GIF = 1; // 0x1 
  public static final int STANDARD_MIME_TYPE_EXTENSION_MOTION_PHOTO = 2; // 0x2 
  public static final int STANDARD_MIME_TYPE_EXTENSION_NONE = 0; // 0x0 
  public static final String SYNC_GENERATION = "sync_generation";
  public static final String WIDTH = "width";
}

// Columns available for every album item
public static final class CloudMediaProviderContract.AlbumColumns {

  public static final String DATE_TAKEN_MILLIS = "date_taken_millis";
  public static final String DISPLAY_NAME = "display_name";
  public static final String ID = "id";
  public static final String MEDIA_COUNT = "album_media_count";
  public static final String MEDIA_COVER_ID = "album_media_cover_id";
}

// Media Collection metadata that is cached by the OS to compare sync states.
public static final class CloudMediaProviderContract.MediaCollectionInfo {

  public static final String ACCOUNT_CONFIGURATION_INTENT = "account_configuration_intent";
  public static final String ACCOUNT_NAME = "account_name";
  public static final String LAST_MEDIA_SYNC_GENERATION = "last_media_sync_generation";
  public static final String MEDIA_COLLECTION_ID = "media_collection_id";
}

onGetMediaCollectionInfo

操作系统使用 onGetMediaCollectionInfo() 方法来评估其缓存的云媒体项目的有效性，并确定需要与云媒体提供商进行哪些同步。由于操作系统可能会频繁调用此方法，因此 onGetMediaCollectionInfo() 被认为是性能关键的方法；避免进行长时间运行的操作或可能对性能产生负面影响的副作用至关重要。操作系统会缓存来自此方法的先前响应，并将其与后续响应进行比较，以确定适当的操作。

abstract fun onGetMediaCollectionInfo(extras: Bundle): Bundle

@NonNull
public abstract Bundle onGetMediaCollectionInfo(@NonNull Bundle extras);

返回的 MediaCollectionInfo 包含以下常量

• MEDIA_COLLECTION_ID
• LAST_MEDIA_SYNC_GENERATION
• ACCOUNT_NAME
• ACCOUNT_CONFIGURATION_INTENT

onQueryMedia

onQueryMedia() 方法用于填充照片选择器中各种视图的主照片网格。这些调用可能是延迟敏感的，并且可以作为后台主动同步的一部分进行调用，也可以在照片选择器会话中进行调用（需要完整或增量同步状态）。照片选择器用户界面不会无限期地等待响应以显示结果，并且可能会出于用户界面目的而超时这些请求。返回的光标仍将尝试被处理到照片选择器的数据库中，以备将来使用。

此方法返回一个 Cursor，该光标表示媒体集合中的所有媒体项目，可以选择通过提供的附加信息进行过滤，并按 MediaColumns#DATE_TAKEN_MILLIS 的反向时间顺序排序（最新的项目排在最前面）。

返回的 CloudMediaProviderContract 包含以下常量

• EXTRA_ALBUM_ID
• EXTRA_LOOPING_PLAYBACK_ENABLED
• EXTRA_MEDIA_COLLECTION_ID
• EXTRA_PAGE_SIZE
• EXTRA_PAGE_TOKEN
• EXTRA_PREVIEW_THUMBNAIL
• EXTRA_SURFACE_CONTROLLER_AUDIO_MUTE_ENABLED
• EXTRA_SYNC_GENERATION
• MANAGE_CLOUD_MEDIA_PROVIDERS_PERMISSION
• PROVIDER_INTERFACE

云媒体提供商必须将 CloudMediaProviderContract#EXTRA_MEDIA_COLLECTION_ID 设置为返回的 Bundle 的一部分。未设置此参数将导致错误，并使返回的 Cursor 无效。如果云媒体提供商处理了提供的附加信息中的任何过滤器，则必须将该键添加到返回的 Cursor#setExtras 中的 ContentResolver#EXTRA_HONORED_ARGS 中。

onQueryDeletedMedia

onQueryDeletedMedia() 方法用于确保云帐户中的已删除项目从照片选择器用户界面中正确删除。由于这些调用可能会出现潜在的延迟敏感性，因此它们可能会作为以下部分的一部分启动

• 后台主动同步
• 照片选择器会话（需要完整或增量同步状态）

照片选择器的用户界面优先考虑响应式用户体验，并且不会无限期地等待响应。为了保持流畅的交互，可能会发生超时。任何返回的 Cursor 仍将尝试被处理到照片选择器的数据库中，以备将来使用。

此方法返回一个 Cursor，该光标表示当前提供商版本中的整个媒体集合中的所有已删除媒体项目，如 onGetMediaCollectionInfo() 所返回。可以选择通过附加信息过滤这些项目。云媒体提供商必须将 CloudMediaProviderContract#EXTRA_MEDIA_COLLECTION_ID 设置为返回的 Cursor#setExtras 的一部分。未设置此参数将导致错误，并使 Cursor 无效。如果提供商处理了提供的附加信息中的任何过滤器，则必须将该键添加到 ContentResolver#EXTRA_HONORED_ARGS 中。

onQueryAlbums

onQueryAlbums() 方法用于获取云提供商中可用的云相册列表及其关联的元数据。有关更多详细信息，请参阅 CloudMediaProviderContract.AlbumColumns。

此方法返回一个 Cursor，该光标表示媒体集合中的所有相册项目，可以选择通过提供的附加信息进行过滤，并按 AlbumColumns#DATE_TAKEN_MILLIS 的反向时间顺序排序（最新的项目排在最前面）。云媒体提供商必须将 CloudMediaProviderContract#EXTRA_MEDIA_COLLECTION_ID 设置为返回的 Cursor 的一部分。未设置此参数将导致错误，并使返回的 Cursor 无效。如果提供商处理了提供的附加信息中的任何过滤器，则必须将该键添加到返回的 Cursor 中的 ContentResolver#EXTRA_HONORED_ARGS 中。

onOpenMedia

onOpenMedia() 方法应返回由提供的 mediaId 标识的完整大小媒体。如果此方法在将内容下载到设备时阻塞，则应定期检查提供的 CancellationSignal 以中止已放弃的请求。

onOpenPreview

onOpenPreview() 方法应返回提供的 size 的提供的 mediaId 项目的缩略图。缩略图应采用原始的 CloudMediaProviderContract.MediaColumns#MIME_TYPE，并且预期分辨率远低于 onOpenMedia 返回的项目。如果此方法在将内容下载到设备时阻塞，则应定期检查提供的 CancellationSignal 以中止已放弃的请求。

onCreateCloudMediaSurfaceController

onCreateCloudMediaSurfaceController() 方法应返回一个 CloudMediaSurfaceController，用于渲染媒体项目的预览，如果预览渲染不受支持，则返回 null。

CloudMediaSurfaceController 管理在给定的 Surface 实例上渲染媒体项目的预览。此类的方法旨在异步执行，并且不应通过执行任何繁重操作而阻塞。单个 CloudMediaSurfaceController 实例负责渲染与多个表面关联的多个媒体项目。

CloudMediaSurfaceController 支持以下生命周期回调列表

• onConfigChange
• onDestroy
• onMediaPause
• onMediaPlay
• onMediaSeekTo
• onPlayerCreate
• onPlayerRelease
• onSurfaceChanged
• onSurfaceCreated
• onSurfaceDestroyed