DocumentProvider — τι είναι, δημιουργία παρόχου και εργασία με αρχεία

Τι είναι το DocumentProvider;

DocumentsProvider — είναι μια βασική κλάση Android που κληρονομεί το ContentProvider και επιτρέπει σε μια εφαρμογή να παρέχει τα αρχεία της σε άλλες εφαρμογές μέσω της διεπαφής συστήματος SAF. Ο πάροχος δημιουργεί ένα εικονικό σύστημα αρχείων που βλέπει ο χρήστης στο παράθυρο επιλογής εγγράφων.

Κάθε πάροχος οργανώνει αρχεία σε ρίζες (roots) — σημεία εισόδου ανώτατου επιπέδου. Για παράδειγμα, το Google Drive έχει ρίζες “Ο δίσκος μου” και “Διαμοιρασμένα με μένα”. Μέσα στη ρίζα, ο πάροχος επιστρέφει ένα δέντρο εγγράφων, όπου κάθε έγγραφο είναι ένα αρχείο ή κατάλογος με συγκεκριμένο τύπο MIME, μέγεθος και ημερομηνίες.

Το DocumentProvider αποτελεί μέρος του πακέτου android.provider και είναι διαθέσιμο από Android 4.4 (API 19). Ο πάροχος χρησιμοποιείται από υπηρεσίες cloud, διαχειριστές κωδικών πρόσβασης, εφαρμογές σημειώσεων και όλα τα προγράμματα που αποθηκεύουν αρχεία σε δική τους μορφή.

Πώς να δημιουργήσετε προσαρμοσμένο DocumentProvider

Δημιουργία του δικού σας DocumentProvider ξεκινά με κληρονομιά της κλάσης DocumentsProvider και υλοποίηση τεσσάρων υποχρεωτικών μεθόδων. Ο πάροχος καθορίζει τη δομή αρχείων που εμφανίζεται στον επιλογέα συστήματος SAF κατά την επιλογή αρχείων.

Η πρώτη μέθοδος — queryRoots, η οποία επιστρέφει έναν cursor με τις στήλες 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 — επιστρέφει τα ριζικά σημεία εισόδου στον αποθηκευτικό χώρο. Κάθε ρίζα αντιπροσωπεύεται από μια γραμμή στον cursor με 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, για αρχεία cloud — 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 και την τοπική αποθήκευση. Υπηρεσίες cloud τρίτων καταχωρούνται μέσω Document Provider extension με το κλειδί Info.plist NSExtensionFileProviderDocumentInterface.

Η κύρια διαφορά: στο Android, το DocumentProvider καλείται ενεργά μέσω SAF Intent και πρέπει να υλοποιήσει μόνο του την πλοήγηση. Στο iOS, το UIDocumentPickerViewController χρησιμοποιεί τον ενσωματωμένο περιηγητή αρχείων συστήματος και η επέκταση παρόχου είναι υπεύθυνη μόνο για την παροχή περιεχομένου κατόπιν αιτήματος.