MediaStore API: ما هو، الإمكانيات والعمل مع ملفات الوسائط المشتركة

ما هو MediaStore API؟

MediaStore API هو موفر محتوى النظام على منصة Android مصمم لفهرسة وتخزين وتوفير الوصول إلى ملفات الوسائط للجهاز. API جزء من Android SDK ومتاحة منذ API Level 1.

يعمل MediaStore من خلال قاعدة بيانات وسائط موحدة تقوم بمسح الجهاز تلقائياً وجمع بيانات وصفية لجميع ملفات الوسائط. قاعدة البيانات يتم تحديثها بواسطة النظام عند إضافة الملفات أو تعديلها أو حذفها، لذلك تتلقى التطبيقات دائماً معلومات محدثة دون مسح يدوي.

الجداول الرئيسية لـ MediaStore هي: Images (الصور)، Video (الفيديو)، Audio (الصوت) و Files (الملفات العامة). يحتوي كل جدول على أعمدة مع بيانات وصفية: الاسم وتاريخ الإنشاء والحجم ونوع MIME وإحداثيات GPS وسمات أخرى.

تطور MediaStore في إصدارات Android

قبل Android 10، كان المطورون يستخدمون READ_EXTERNAL_STORAGE للوصول إلى جميع ملفات الجهاز. Android 10 (API 29) قدم Scoped Storage: أصبحت التطبيقات قادرة على الوصول فقط إلى ملفاتها الخاصة وعبر MediaStore. شدد Android 11 السياسة، مما منع المسار المباشر إلى الدلائل المشتركة تماماً.

بدءاً من Android 13 (API 33)، استبدلت Google READ_EXTERNAL_STORAGE بأذونات دقيقة: READ_MEDIA_IMAGES وREAD_MEDIA_VIDEO وREAD_MEDIA_AUDIO. يتيح هذا للمستخدمين منح الوصول فقط إلى أنواع محددة من الوسائط دون كشف التخزين بأكمله.

كيف يعمل MediaStore: الهندسة المعمارية وقاعدة بيانات الوسائط

MediaStore مبني على بنية موفر المحتوى: يصل إليه كل تطبيق من خلال ContentResolver وUri. ماسح الوسائط النظامي — MediaScannerConnection — يقوم بفهرسة جميع ملفات الجهاز تلقائياً أثناء التشغيل أو الاتصال عبر USB أو إعادة التشغيل.

يتم تخزين قاعدة بيانات الوسائط في قاعدة بيانات النظام وتحتوي على سجلات لكل ملف وسائط. تختلف الأعمدة حسب النوع: الصور بها ORIENTATION و DATE_TAKEN، والفيديو به DURATION، والملفات الصوتية بها ARTIST و ALBUM. يمكن للمطورين تنفيذ استعلامات شبيهة بـ SQL باستخدام query مع projection و selection للتصفية.

val projection = arrayOf(
    MediaStore.Images.Media._ID,
    MediaStore.Images.Media.DISPLAY_NAME,
    MediaStore.Images.Media.DATE_ADDED
)

val cursor = contentResolver.query(
    MediaStore.Images.Media.EXTERNAL_CONTENT_URI,
    projection,
    null,
    null,
    MediaStore.Images.Media.DATE_ADDED + " DESC"
)

cursor?.use {
    while (moveToNext()) {
        val name = getString(getColumnIndexOrThrow(MediaStore.Images.Media.DISPLAY_NAME))
    }
}

Content URI ومعناها

يتم تحديد كل ملف وسائط بواسطة Content URI مثل content://media/external/images/media/1234. يشير URI الخارجي إلى التخزين المشترك، بينما يشير الداخلي إلى ملفات وسائط النظام. استخدام URI بدلاً من مسارات الملفات هو ميزة رئيسية لـ MediaStore: لا يحتاج التطبيق إلى الوصول إلى نظام الملفات ويعمل من خلال موفر محتوى آمن.

أنواع ملفات الوسائط في MediaStore

MediaStore يدعم أربعة أنواع رئيسية من الوسائط، لكل منها جدول خاص بها ومجموعة بيانات وصفية. يختار المطورون الجدول المناسب حسب نوع المحتوى الذي يعمل معه التطبيق.

• MediaStore.Images — الصور ولقطات الشاشة والرسومات. الأعمدة: BUCKET_DISPLAY_NAME، IS_PRIVATE، LATITUDE، LONGITUDE.
• MediaStore.Video — تسجيلات الفيديو والأفلام. الأعمدة: DURATION، RESOLUTION، IS_DRM.
• MediaStore.Audio — المقاطع الموسيقية والملفات الصوتية. الأعمدة: ARTIST، ALBUM، COMPOSER، TRACK.
• MediaStore.Files — المستندات والملفات الأخرى. متاح منذ Android 10 للوصول المشترك.

بالإضافة إلى الأعمدة القياسية، يحتوي كل جدول على حقول النظام: _ID، DATA (قديم)، SIZE، MIME_TYPE، DATE_ADDED، DATE_MODIFIED. منذ Android 10، تم وضع علامة على حقل DATA على أنه قديم، ويجب على المطورين العمل من خلال فتح InputStream عبر URI.

أذونات العمل مع MediaStore

MediaStore يتطلب أذونات صريحة، تختلف حسب إصدار Android. قبل Android 13، كان يُستخدم الإذن الواحد READ_EXTERNAL_STORAGE. بدءاً من Android 13 (API 33)، قدمت Google أذونات دقيقة لكل نوع وسائط.

تتطلب الكتابة إلى MediaStore أيضاً WRITE_EXTERNAL_STORAGE لنظام Android 9 والإصدارات الأقدم. بدءاً من Android 10، يمكن للتطبيق كتابة ملفاته الخاصة إلى MediaStore دون أذونات إضافية — يمنح النظام الوصول تلقائياً عند إدراج سجل عبر ContentResolver.insert.

طلب الأذونات في وقت التشغيل

يتم طلب أذونات MediaStore من خلال الآلية القياسية ActivityResultContracts.RequestMultiplePermissions. قد يرفض المستخدم الطلب، ويجب على التطبيق معالجة هذا السيناريو بشكل صحيح. يُوصى بالتحقق من الإذن عبر ContextCompat.checkSelfPermission قبل كل وصول إلى MediaStore.

أمثلة الكود: القراءة والكتابة عبر MediaStore

MediaStore يسمح ليس فقط بالقراءة ولكن أيضاً بكتابة ملفات الوسائط. لكتابة صورة أو فيديو، يستخدم المطور ContentResolver.insert ويفتح OutputStream للـ URI المُعاد. يقوم النظام تلقائياً بإضافة الملف إلى قاعدة بيانات الوسائط وفهرسته.

val values = ContentValues().apply {
    put(MediaStore.Images.Media.DISPLAY_NAME, "photo_2025.jpg")
    put(MediaStore.Images.Media.MIME_TYPE, "image/jpeg")
    put(MediaStore.Images.Media.RELATIVE_PATH, "Pictures/MyApp")
}

val uri = contentResolver?.insert(
    MediaStore.Images.Media.EXTERNAL_CONTENT_URI, values
)

uri?.let {
    val outputStream = contentResolver?.openOutputStream(it)
    outputStream?.use { stream ->
        // كتابة البايتات إلى التدفق
    }
}

حذف ملفات الوسائط عبر MediaStore

يتم الحذف باستخدام ContentResolver.delete مع URI للملف. يتحقق النظام من حقوق الوصول: إذا كان الملف ينتمي إلى التطبيق الحالي، يتم الحذف دون أذونات إضافية. لملفات التطبيقات الأخرى على Android 10+، يلزم تأكيد المستخدم عبر حوار النظام.

MediaStore مقابل الوصول المباشر إلى الملفات

MediaStore API يختلف جوهرياً عن الوصول المباشر إلى الملفات عبر File API. بدلاً من مسارات الملفات، تُستخدم Content URI، وبدلاً من عمليات الملفات، تُستخدم طرق ContentResolver. يوفر هذا ثلاث مزايا رئيسية: الأمان والفهرسة التلقائية والواجهة الموحدة.

الوصول المباشر إلى الملفات مقيد على Android 10+ للدلائل المشتركة. يبقى MediaStore الطريقة الوحيدة لقراءة الوسائط من Pictures وDCIM وMovies وMusic وDownload. للملفات الخاصة بالتطبيق (app-specific storage)، يُحتفظ بالوصول المباشر — وهي المجلدات في Android/data وAndroid/media.

الاختيار بين MediaStore والوصول المباشر يعتمد على نوع المحتوى. MediaStore إلزامي لملفات الوسائط المشتركة التي يمكن للتطبيقات الأخرى الوصول إليها. File API المباشر مناسب للملفات الداخلية للتطبيق وذاكرة التخزين المؤقت. يُستخدم Storage Access Framework لاختيار المستندات العشوائية من خلال منتقي النظام.