DocumentProvider — یہ کیا ہے، فراہم کنندہ بنانا اور فائلوں کے ساتھ کام کرنا

DocumentProvider کیا ہے؟

DocumentsProvider ایک Android بنیادی کلاس ہے جو ContentProvider کو بڑھاتی ہے، ایک ایپلیکیشن کو سسٹم SAF انٹرفیس کے ذریعے دوسری ایپلیکیشنز کو اپنی فائلیں فراہم کرنے کی اجازت دیتی ہے۔ فراہم کنندہ ایک ورچوئل فائل سسٹم بناتا ہے جسے صارف دستاویز کے انتخاب کے ڈائیلاگ میں دیکھتا ہے۔

ہر فراہم کنندہ فائلوں کو جڑوں (roots) — اعلیٰ سطحی داخلے کے مقامات میں ترتیب دیتا ہے۔ مثال کے طور پر، Google Drive کی جڑیں «میری ڈرائیو» اور «میرے ساتھ شیئر کردہ» ہیں۔ ایک جڑ کے اندر، فراہم کنندہ دستاویزات کا ایک درخت لوٹاتا ہے، جہاں ہر دستاویز ایک مخصوص MIME قسم، سائز اور تاریخوں والی فائل یا ڈائریکٹری ہے۔

DocumentProvider android.provider پیکیج کا حصہ ہے اور Android 4.4 (API 19) سے دستیاب ہے۔ فراہم کنندہ کلاؤڈ سروسز، پاس ورڈ مینیجرز، نوٹ لینے والی ایپس اور کسی بھی پروگرام کے ذریعے استعمال ہوتا ہے جو فائلوں کو اپنی شکل میں محفوظ کرتا ہے۔

کسٹم DocumentProvider کیسے بنائیں

اپنا خود کا DocumentProvider بنانا DocumentsProvider کلاس کو بڑھانے اور چار لازمی طریقوں کو نافذ کرنے سے شروع ہوتا ہے۔ فراہم کنندہ فائل کے ڈھانچے کی وضاحت کرتا ہے جو فائلیں منتخب کرتے وقت سسٹم 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۔

دوسرا لازمی طریقہ queryChildDocuments ہے، جو ایک مخصوص URI کے ذیلی دستاویزات لوٹاتا ہے۔ یہ طریقہ اس وقت کہا جاتا ہے جب صارف چنندہ میں کوئی ڈائریکٹری کھولتا ہے۔ ہر دستاویز میں کالم ہوتے ہیں: Document.COLUMN_DOCUMENT_ID، COLUMN_DISPLAY_NAME، COLUMN_MIME_TYPE، COLUMN_SIZE اور COLUMN_LAST_MODIFIED۔

DocumentsProvider کے لازمی طریقے

DocumentsProvider کو چار طریقوں کے نفاذ کی ضرورت ہے جو چنندہ کے لیے فائل کا ڈھانچہ بناتے ہیں۔ ان کے بغیر، فراہم کنندہ کام نہیں کرے گا — سسٹم SAF ڈائیلاگ فائلیں ظاہر نہیں کر سکے گا۔

• queryRoots — ذخیرہ میں جڑ کے داخلے کے مقامات لوٹاتا ہے۔ ہر جڑ ایک ID، نام اور آئیکن کے ساتھ کرسر میں ایک قطار سے ظاہر ہوتی ہے۔
• queryDocument — اپنی ID سے ایک دستاویز لوٹاتا ہے۔ کسی مخصوص فائل کے بارے میں معلومات حاصل کرنے کے لیے استعمال ہوتا ہے۔
• queryChildDocuments — مخصوص پیرنٹ ڈائریکٹری URI کے لیے ذیلی دستاویزات لوٹاتا ہے۔
• openDocument — ID سے ایک دستاویز کھولتا ہے اور پڑھنے یا لکھنے کے لیے ParcelFileDescriptor لوٹاتا ہے۔

اضافی طور پر، نئی فائلیں بنانے کے لیے createDocument، حذف کرنے کے لیے deleteDocument اور نام تبدیل کرنے کے لیے renameDocument نافذ کیا جا سکتا ہے۔ ان طریقوں کو جڑ میں FLAG_SUPPORTS_CREATE جھنڈے کی ضرورت ہے۔

AndroidManifest میں فراہم کنندہ کو رجسٹر کرنا

DocumentProvider AndroidManifest.xml میں ایک اضافی انٹینٹ فلٹر اور جھنڈوں کے ساتھ ایک عام ContentProvider کے طور پر رجسٹر ہوتا ہے۔ فراہم کنندہ کو اجازت کے ذریعے براہ راست رسائی سے محفوظ کیا جانا چاہیے — واضح اجازت کے ساتھ 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 قسم کی ایپ ایکسٹینشنز کے ذریعے نافذ کیا جاتا ہے۔

Android DocumentsProvider کے برعکس، iOS UIDocumentPickerViewController کو مقامی فائلوں کے لیے کسٹم فراہم کنندہ بنانے کی ضرورت نہیں ہے — سسٹم چنندہ ڈیفالٹ طور پر iCloud Drive اور مقامی ذخیرہ کو سپورٹ کرتا ہے۔ تیسرے فریق کی کلاؤڈ سروسز Info.plist کلید NSExtensionFileProviderDocumentInterface کے ساتھ Document Provider ایکسٹینشن کے ذریعے رجسٹر ہوتی ہیں۔

بنیادی فرق: Android میں، DocumentProvider کو SAF Intent کے ذریعے فعال طور پر بلایا جاتا ہے اور اسے خود نیویگیشن نافذ کرنی ہوتی ہے۔ iOS میں، UIDocumentPickerViewController ایک بلٹ ان سسٹم فائل براؤزر استعمال کرتا ہے، اور ایکسٹینشن فراہم کنندہ صرف درخواست پر مواد فراہم کرنے کے لیے ذمہ دار ہے۔