android_document_fetcher

A highly optimized Flutter plugin for retrieving documents directly from the Android MediaStore without opening a file picker.

Unlike traditional file picker plugins that require user interaction, Android Document Fetcher lets you query the device's storage programmatically. Heavy MediaStore queries are executed on native Android background threads, ensuring smooth Flutter UI performance even when scanning thousands of files.

---

✨ Features

• ⚡ Fast & Efficient – Native background-thread execution keeps your UI responsive.
• 📄 Pagination – Fetch documents in chunks using limit and offset.
• 🗂️ Sorting – Sort by file name, last modified date, or file size.
• 🔍 MIME Type Filtering – Retrieve only the document types you need (PDF, DOCX, TXT, etc.).
• 🤖 Native Android Implementation – Uses the Android MediaStore API for maximum performance.
• 💙 Flutter Friendly – Simple asynchronous API with Dart models.

---

Platform Support

Platform	Supported
Android	✅
iOS	❌
Web	❌
Windows	❌
macOS	❌
Linux	❌

Note: This plugin is Android-only because it relies on the Android MediaStore API.

---

Installation

Add the package to your pubspec.yaml:

dependencies:
  android_document_fetcher: latest_version

Then run:

flutter pub get

---

Android Setup

1. Add Storage Permissions

Add the required permissions to your application's android/app/src/main/AndroidManifest.xml file.

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>

<!-- Android 13+ -->
<uses-permission android:name="android.permission.READ_MEDIA_DOCUMENTS"/>

Important

This plugin does not request permissions automatically. Your application is responsible for requesting and managing runtime permissions before using the plugin.

---

2. Request Runtime Permission

You can use packages such as permission_handler before calling the plugin.

Usage

Import the package:

import 'package:android_document_fetcher/android_document_fetcher.dart';

Create an instance:

final fetcher = AndroidDocumentFetcher();

Fetch documents:

try {
  final documents = await fetcher.getDocuments(
    limit: 50,
    offset: 0,
    sortBy: DocumentSortColumn.date,
    sortOrder: SortOrder.desc,
  );

  for (final document in documents) {
    print(document.name);
    print(document.size);
    print(document.dateModified);
  }
} catch (e) {
  print(e);
}

---

Pagination

Retrieve documents in smaller batches.

final documents = await fetcher.getDocuments(
  limit: 100,
  offset: 200,
);

---

Sorting

Sort documents by different columns.

final documents = await fetcher.getDocuments(
  sortBy: DocumentSortColumn.name,
  sortOrder: SortOrder.asc,
);

Available sort columns include:

• DocumentSortColumn.name
• DocumentSortColumn.date
• DocumentSortColumn.size

Sort orders:

• SortOrder.asc
• SortOrder.desc

---

MIME Type Filtering

Retrieve only specific document types.

final pdfsAndWords = await fetcher.getDocuments(
  typeFilters: [
    DocumentType.pdf,
    DocumentType.word,
    DocumentType.plainText,
  ],
);

---

Error Handling

The plugin throws descriptive exceptions when something goes wrong.

Error Code	Description
PERMISSION_DENIED	Storage permission has not been granted.
QUERY_ERROR	MediaStore failed to execute the query.

Example:

try {
  final documents = await fetcher.getDocuments();
} catch (e) {
  print('Error: $e');
}

---

Performance

This plugin is designed for high-performance document retrieval.

• Native Android implementation
• Background thread execution
• Efficient MediaStore queries
• Supports pagination for reduced memory usage
• Suitable for libraries containing thousands of documents

---

Contributing

Contributions, bug reports, and feature requests are welcome.

If you encounter an issue or have an idea for improvement, please open an issue or submit a pull request.

---

License

This project is licensed under the MIT License. See the LICENSE file for details.