DocumentProvider — とは何か、プロバイダーの作成とファイル操作

DocumentProviderとは？

DocumentsProvider は、ContentProviderを拡張するAndroidの基本クラスであり、アプリケーションがシステムSAFインターフェースを介して他のアプリケーションにファイルを提供できるようにします。プロバイダーは、ユーザーがドキュメント選択ダイアログで表示する仮想ファイルシステムを作成します。

各プロバイダーはファイルを ルート（roots） — トップレベルのエントリポイントに整理します。たとえば、Google Driveには“マイドライブ”と“共有アイテム”というルートがあります。ルート内で、プロバイダーはドキュメントのツリーを返します。各ドキュメントは、特定のMIMEタイプ、サイズ、日付を持つファイルまたはディレクトリです。

DocumentProviderは android.provider パッケージの一部であり、Android 4.4（API 19）以降で利用可能です。このプロバイダーは、クラウドサービス、パスワードマネージャー、メモ帳アプリ、およびファイルを独自の形式で保存するプログラムで使用されています。

カスタムDocumentProviderの作成方法

独自の DocumentProviderを作成するには、DocumentsProviderクラスを拡張し、4つの必須メソッドを実装します。プロバイダーは、ファイル選択時にシステムSAFピッカーに表示されるファイル構造を定義します。

最初のメソッドは queryRoots で、Root.COLUMN_ROOT_ID、Root.COLUMN_TITLE、Root.COLUMN_SUMMARY、Root.COLUMN_FLAGSのカラムを持つカーソルを返します。各ルートはフラグをサポートできます：FLAG_SUPPORTS_CREATE、FLAG_SUPPORTS_SEARCH、FLAG_SUPPORTS_IS_CHILD。

2番目の必須メソッドは queryChildDocuments で、指定されたURIの子ドキュメントを返します。このメソッドは、ユーザーがピッカーでディレクトリを開いたときに呼び出されます。各ドキュメントには、Document.COLUMN_DOCUMENT_ID、COLUMN_DISPLAY_NAME、COLUMN_MIME_TYPE、COLUMN_SIZE、COLUMN_LAST_MODIFIEDのカラムが含まれます。

DocumentsProviderの必須メソッド

DocumentsProvider は、ピッカーのファイル構造を形成する4つのメソッドの実装を必要とします。これらがないと、プロバイダーは機能しません — システムSAFダイアログはファイルを表示できません。

• queryRoots — ストレージへのルートエントリポイントを返します。各ルートは、ID、名前、アイコンを持つカーソルの行で表されます。
• queryDocument — IDによって単一のドキュメントを返します。特定のファイルに関する情報を取得するために使用されます。
• queryChildDocuments — 指定された親ディレクトリURIの子ドキュメントを返します。
• openDocument — IDによってドキュメントを開き、読み取りまたは書き込み用のParcelFileDescriptorを返します。

さらに、新しいファイルを作成する createDocument、削除する deleteDocument、名前を変更する renameDocument を実装できます。これらのメソッドには、ルートにFLAG_SUPPORTS_CREATEフラグが必要です。

AndroidManifestへのプロバイダー登録

DocumentProvider は、追加のインテントフィルターとフラグを持つ通常のContentProviderとしてAndroidManifest.xmlに登録されます。プロバイダーはパーミッションによる直接アクセスから保護する必要があります — 明示的なパーミッションで android:exported="true" を使用することをお勧めします。

<provider
    android:name=".provider.CustomDocumentProvider"
    android:authorities="com.example.app.documents"
    android:exported="true"
    android:grantUriPermissions="true"
    android:permission="android.permission.MANAGE_DOCUMENTS">
    <intent-filter>
        <action
            android:name="android.content.action.DOCUMENTS_PROVIDER" />
    </intent-filter>
    <meta-data
        android:name="android.content.documents.roots"
        android:resource="@xml/file_paths" />
</provider>

grantUriPermissions フラグは、SAFが呼び出し元アプリケーションに一時的にアクセス権を委任できるようにします。authorities属性は一意である必要があります — 通常は .documents サフィックス付きのパッケージ名が使用されます。ルートを設定するためのXMLリソースを持つメタデータを指定することも推奨されます。

コード例：DocumentsProviderの実装

DocumentsProvider の実装には、openDocumentメソッドからParcelFileDescriptorを返す必要があります。ローカルファイルにはParcelFileDescriptor.openを使用し、クラウドファイルにはストリーミング用にPipeを使用したParcelFileDescriptor.openを使用します。コードはアクセスエラーやファイル欠落を処理する必要があります。

class CustomDocumentProvider : DocumentsProvider() {

    override fun queryRoots(): Cursor {
        val matrix = MatrixCursor(Root.COLUMNS)
        matrix.newRow().add(Root.COLUMN_ROOT_ID, "local")
            .add(Root.COLUMN_TITLE, "My Files")
            .add(Root.COLUMN_SUMMARY, "Local documents")
            .add(Root.COLUMN_FLAGS, Root.FLAG_SUPPORTS_CREATE)
        return matrix
    }

    override fun openDocument(
        documentId: String, flags: Int, cursor: CancellationSignal?
    ): ParcelFileDescriptor {
        val file = File(context.filesDir, documentId)
        val accessMode = ParcelFileDescriptor.parseMode(flags)
        return ParcelFileDescriptor.open(file, accessMode)
    }
}

仮想ドキュメントの処理

DocumentProviderは 仮想ファイル — ディスク上に個別のファイルとして存在しないドキュメントを返すことができます。たとえば、データベースのメモを仮想PDFとして提供できます。これには FLAG_VIRTUAL_DOCUMENT フラグ付きのMIMEタイプを使用し、openDocumentは送信前にデータを要求された形式に変換します。

iOSのDocumentProvider：UIDocumentPickerViewController

iOS にも同様のメカニズム — UIDocumentPickerViewControllerがあり、統一されたファイル選択インターフェースを提供します。ただし、iOSではドキュメントプロバイダーは UIDocumentPickerDelegate とDocument Providerタイプのアプリ拡張機能（App Extensions）を介して実装されます。

AndroidのDocumentsProviderとは異なり、iOSのUIDocumentPickerViewControllerはローカルファイル用のカスタムプロバイダーを作成する必要はありません — システムピッカーはデフォルトでiCloud Driveとローカルストレージをサポートしています。サードパーティのクラウドサービスは、Info.plistキーNSExtensionFileProviderDocumentInterfaceを持つ Document Provider拡張機能 を介して登録されます。

主な違い：Androidでは、DocumentProviderはSAF Intentを介して アクティブに呼び出され、自身でナビゲーションを実装する必要があります。iOSでは、UIDocumentPickerViewControllerは組み込みのシステムファイルブラウザを使用し、拡張プロバイダーはリクエストに応じてコンテンツを提供するのみです。