DocumentProvider — ano ito, paggawa ng tagapagbigay at pagtatrabaho sa mga file

Ano ang DocumentProvider?

DocumentsProvider — ay isang base na klase ng Android na nagmamana ng ContentProvider at nagpapahintulot sa isang app na ibigay ang mga file nito sa ibang mga app sa pamamagitan ng interface ng system ng SAF. Ang tagapagbigay ay lumilikha ng isang virtual na file system na nakikita ng gumagamit sa dialog ng pagpili ng dokumento.

Bawat tagapagbigay ay nag-aayos ng mga file sa mga root (roots) — mga entry point sa pinakamataas na antas. Halimbawa, ang Google Drive ay may mga root na "Aking Disk" at "Ibinahagi sa Akin". Sa loob ng root, ang tagapagbigay ay nagbabalik ng isang puno ng dokumento, kung saan ang bawat dokumento ay isang file o direktoryo na may tiyak na uri ng MIME, laki, at mga petsa.

Ang DocumentProvider ay bahagi ng paketeng android.provider at magagamit mula noong Android 4.4 (API 19). Ang tagapagbigay ay ginagamit ng mga serbisyo sa cloud, tagapamahala ng password, mga app ng tala, at lahat ng programa na nag-iimbak ng mga file sa kanilang sariling format.

Paano Gumawa ng Custom na DocumentProvider

Paggawa ng iyong sariling DocumentProvider ay nagsisimula sa pagmamana ng klase ng DocumentsProvider at pagpapatupad ng apat na sapilitang pamamaraan. Tinutukoy ng tagapagbigay ang istruktura ng file na ipinapakita sa system picker ng SAF kapag pumipili ng mga file.

Ang unang pamamaraan — queryRoots, na nagbabalik ng cursor na may mga column na Root.COLUMN_ROOT_ID, Root.COLUMN_TITLE, Root.COLUMN_SUMMARY at Root.COLUMN_FLAGS. Bawat root ay maaaring sumuporta sa mga flag: FLAG_SUPPORTS_CREATE, FLAG_SUPPORTS_SEARCH at FLAG_SUPPORTS_IS_CHILD.

Ang pangalawang sapilitang pamamaraan — queryChildDocuments, na nagbabalik ng mga child document ng tinukoy na URI. Ang pamamaraang ito ay tinatawag kapag binuksan ng gumagamit ang isang direktoryo sa picker. Bawat dokumento ay naglalaman ng mga column: Document.COLUMN_DOCUMENT_ID, COLUMN_DISPLAY_NAME, COLUMN_MIME_TYPE, COLUMN_SIZE at COLUMN_LAST_MODIFIED.

Mga Sapilitang Pamamaraan ng DocumentsProvider

DocumentsProvider ay nangangailangan ng pagpapatupad ng apat na pamamaraan na bumubuo sa istruktura ng file para sa picker. Kung wala ang mga ito, hindi gagana ang tagapagbigay — ang system dialog ng SAF ay hindi makapagpapakita ng mga file.

• queryRoots — nagbabalik ng mga root entry point sa imbakan. Bawat root ay kinakatawan ng isang hilera sa cursor na may ID, pangalan, at icon.
• queryDocument — nagbabalik ng isang dokumento ayon sa ID nito. Ginagamit upang makakuha ng impormasyon tungkol sa isang partikular na file.
• queryChildDocuments — nagbabalik ng mga child document para sa tinukoy na URI ng parent directory.
• openDocument — binubuksan ang dokumento ayon sa ID at nagbabalik ng ParcelFileDescriptor para sa pagbasa o pagsulat.

Dagdag pa, maaaring ipatupad ang createDocument para sa paggawa ng mga bagong file, deleteDocument para sa pagbura at renameDocument para sa pagpapalit ng pangalan. Ang mga pamamaraang ito ay nangangailangan ng flag na FLAG_SUPPORTS_CREATE sa root.

Pagrerehistro ng Tagapagbigay sa AndroidManifest

DocumentProvider ay nirerehistro sa AndroidManifest.xml bilang isang ordinaryong ContentProvider na may karagdagang intent-filter at mga flag. Ang tagapagbigay ay dapat protektahan mula sa direktang pag-access sa pamamagitan ng permission — inirerekomenda ang paggamit ng android:exported="true" na may tahasang permission.

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

Ang flag na grantUriPermissions ay nagpapahintulot sa SAF na pansamantalang italaga ang mga karapatan sa pag-access sa tumatawag na app. Ang atributong authorities ay dapat na natatangi — karaniwang ginagamit ang pangalan ng package na may suffix na .documents. Inirerekomenda din na tukuyin ang meta-data na may XML resource para sa pagsasaayos ng mga root.

Halimbawa ng Kodigo: Pagpapatupad ng DocumentsProvider

Pagpapatupad ng DocumentsProvider ay nangangailangan ng pagbabalik ng ParcelFileDescriptor mula sa pamamaraang openDocument. Para sa mga lokal na file, ginagamit ang ParcelFileDescriptor.open; para sa mga cloud file — ParcelFileDescriptor.open na may Pipe para sa streaming transmission. Ang kodigo ay dapat humawak ng mga error sa pag-access at kawalan ng file.

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)
    }
}

Paghawak ng mga Virtual na Dokumento

Ang DocumentProvider ay maaaring magbalik ng mga virtual na file — mga dokumento na hindi umiiral bilang hiwalay na mga file sa disk. Halimbawa, ang isang tala mula sa database ay maaaring iharap bilang isang virtual na PDF. Para dito, ginagamit ang uri ng MIME na may flag na FLAG_VIRTUAL_DOCUMENT, at ang openDocument ay nagko-convert ng data sa hinihinging format bago ipadala.

DocumentProvider sa iOS: UIDocumentPickerViewController

iOS ay may katulad na mekanismo — UIDocumentPickerViewController, na nagbibigay din ng pinag-isang interface ng pagpili ng file. Gayunpaman sa iOS, ang tagapagbigay ng dokumento ay ipinapatupad sa pamamagitan ng UIDocumentPickerDelegate at mga extension ng app (App Extensions) na may uri ng Document Provider.

Hindi tulad ng Android DocumentsProvider, ang iOS UIDocumentPickerViewController ay hindi nangangailangan ng paggawa ng custom na tagapagbigay para sa mga lokal na file — ang system picker ay sumusuporta sa iCloud Drive at lokal na imbakan bilang default. Ang mga third-party na serbisyo sa cloud ay nagrerehistro sa pamamagitan ng Document Provider extension na may Info.plist key na NSExtensionFileProviderDocumentInterface.

Ang pangunahing pagkakaiba: sa Android, ang DocumentProvider ay aktibong tinatawag sa pamamagitan ng SAF Intent at dapat mismo magpatupad ng nabigasyon. Sa iOS, ang UIDocumentPickerViewController ay gumagamit ng built-in na system file browser, at ang extension ng tagapagbigay ay responsable lamang sa pagbibigay ng nilalaman kapag hiniling.