DocumentProvider — این چیست، ایجاد ارائه‌دهنده و کار با فایل‌ها

DocumentProvider چیست؟

DocumentsProvider — یک کلاس پایه Android است که از ContentProvider ارث‌بری می‌کند و به برنامه اجازه می‌دهد فایل‌های خود را از طریق رابط سیستم SAF به سایر برنامه‌ها ارائه دهد. ارائه‌دهنده یک سیستم فایل مجازی ایجاد می‌کند که کاربر در دیالوگ انتخاب اسناد می‌بیند.

هر ارائه‌دهنده فایل‌ها را در ریشه‌ها (roots) — نقاط ورود سطح بالا — سازماندهی می‌کند. به عنوان مثال، Google Drive دارای ریشه‌های «دیسک من» و «به اشتراک گذاشته شده با من» است. در داخل ریشه، ارائه‌دهنده یک درخت سند برمی‌گرداند که هر سند یک فایل یا دایرکتوری با نوع MIME، اندازه و تاریخ‌های مشخص است.

DocumentProvider بخشی از بسته android.provider است و از Android 4.4 (API 19) در دسترس است. ارائه‌دهنده توسط سرویس‌های ابری، مدیران رمز عبور، برنامه‌های یادداشت و هر برنامه‌ای که فایل‌ها را در قالب خود ذخیره می‌کند، استفاده می‌شود.

ایجاد DocumentProvider سفارشی

ایجاد DocumentProvider خودتان با ارث‌بری از کلاس DocumentsProvider و پیاده‌سازی چهار متد اجباری آغاز می‌شود. ارائه‌دهنده ساختار فایلی را تعیین می‌کند که در انتخابگر سیستم SAF هنگام انتخاب فایل‌ها نمایش داده می‌شود.

اولین متد — queryRoots که یک کursor با ستون‌های Root.COLUMN_ROOT_ID، Root.COLUMN_TITLE، Root.COLUMN_SUMMARY و Root.COLUMN_FLAGS برمی‌گرداند. هر ریشه می‌تواند پرچم‌های FLAG_SUPPORTS_CREATE، FLAG_SUPPORTS_SEARCH و FLAG_SUPPORTS_IS_CHILD را پشتیبانی کند.

دومین متد اجباری — queryChildDocuments که اسناد فرزند URI مشخص شده را برمی‌گرداند. این متد زمانی فراخوانی می‌شود که کاربر یک دایرکتوری را در انتخابگر باز می‌کند. هر سند شامل ستون‌های Document.COLUMN_DOCUMENT_ID، COLUMN_DISPLAY_NAME، COLUMN_MIME_TYPE، COLUMN_SIZE و COLUMN_LAST_MODIFIED است.

متدهای اجباری DocumentsProvider

DocumentsProvider نیاز به پیاده‌سازی چهار متد دارد که ساختار فایل را برای انتخابگر تشکیل می‌دهند. بدون آنها ارائه‌دهنده کار نخواهد کرد — دیالوگ سیستم SAF نمی‌تواند فایل‌ها را نمایش دهد.

• queryRoots — نقاط ورود ریشه به ذخیره‌ساز را برمی‌گرداند. هر ریشه با یک ردیف در کursor با ID، نام و آیکون نمایش داده می‌شود.
• queryDocument — یک سند را با ID آن برمی‌گرداند. برای دریافت اطلاعات درباره یک فایل خاص استفاده می‌شود.
• queryChildDocuments — اسناد فرزند را برای URI دایرکتوری والد مشخص شده برمی‌گرداند.
• openDocument — سند را با ID باز می‌کند و ParcelFileDescriptor را برای خواندن یا نوشتن برمی‌گرداند.

علاوه بر این می‌توان createDocument برای ایجاد فایل‌های جدید، deleteDocument برای حذف و renameDocument برای تغییر نام پیاده‌سازی کرد. این متدها به پرچم FLAG_SUPPORTS_CREATE در ریشه نیاز دارند.

ثبت ارائه‌دهنده در AndroidManifest

DocumentProvider در AndroidManifest.xml به عنوان یک ContentProvider معمولی با intent-filter اضافی و پرچم‌ها ثبت می‌شود. ارائه‌دهنده باید از دسترسی مستقیم از طریق permission محافظت شود — توصیه می‌شود از android:exported="true" با 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>

پرچم grantUriPermissions به SAF اجازه می‌دهد به طور موقت حقوق دسترسی را به برنامه فراخوان‌کننده واگذار کند. ویژگی authorities باید منحصر‌به‌فرد باشد — معمولاً از نام بسته با پسوند .documents استفاده می‌شود. توصیه می‌شود همچنین meta-data با منبع XML برای پیکربندی ریشه‌ها مشخص شود.

نمونه کد: پیاده‌سازی DocumentsProvider

پیاده‌سازی DocumentsProvider نیاز به بازگرداندن ParcelFileDescriptor از متد openDocument دارد. برای فایل‌های محلی از ParcelFileDescriptor.open و برای فایل‌های ابری از ParcelFileDescriptor.open با Pipe برای انتقال جریانی استفاده می‌شود. کد باید خطاهای دسترسی و عدم وجود فایل را مدیریت کند.

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 مجازی نمایش داده شود. برای این کار از نوع MIME با پرچم FLAG_VIRTUAL_DOCUMENT استفاده می‌شود و openDocument داده‌ها را قبل از ارسال به فرمت مورد نیاز تبدیل می‌کند.

DocumentProvider در iOS: UIDocumentPickerViewController

iOS دارای مکانیزم مشابهی است — UIDocumentPickerViewController که همچنین یک رابط انتخاب فایل یکپارچه ارائه می‌دهد. با این حال در iOS، ارائه‌دهنده اسناد از طریق UIDocumentPickerDelegate و افزونه‌های برنامه (App Extensions) با نوع Document Provider پیاده‌سازی می‌شود.

برخلاف Android DocumentsProvider، iOS UIDocumentPickerViewController نیازی به ایجاد یک ارائه‌دهنده سفارشی برای فایل‌های محلی ندارد — انتخابگر سیستم به طور پیش‌فرض از iCloud Drive و ذخیره‌ساز محلی پشتیبانی می‌کند. سرویس‌های ابری شخص ثالث از طریق Document Provider extension با کلید Info.plist NSExtensionFileProviderDocumentInterface ثبت می‌شوند.

تفاوت اصلی: در Android، DocumentProvider به طور فعال فراخوانی می‌شود از طریق SAF Intent و باید خود پیمایش را پیاده‌سازی کند. در iOS، UIDocumentPickerViewController از مرورگر فایل سیستم داخلی استفاده می‌کند و افزونه ارائه‌دهنده فقط مسئول ارائه محتوا در صورت درخواست است.