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 — भंडारण में रूट प्रवेश बिंदु लौटाता है। प्रत्येक रूट आईडी, नाम और आइकन के साथ कर्सर में एक पंक्ति द्वारा दर्शाया जाता है।
• queryDocument — अपनी आईडी द्वारा एक दस्तावेज़ लौटाता है। किसी विशिष्ट फ़ाइल के बारे में जानकारी प्राप्त करने के लिए उपयोग किया जाता है।
• queryChildDocuments — निर्दिष्ट पैरेंट निर्देशिका URI के लिए चाइल्ड दस्तावेज़ लौटाता है।
• openDocument — आईडी द्वारा दस्तावेज़ खोलता है और पढ़ने या लिखने के लिए 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 संसाधन के साथ meta-data निर्दिष्ट करने की भी अनुशंसा की जाती है।

कोड उदाहरण: 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 एक अंतर्निहित सिस्टम फ़ाइल ब्राउज़र का उपयोग करता है, और एक्सटेंशन प्रदाता केवल अनुरोध पर सामग्री प्रदान करने के लिए जिम्मेदार है।