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 خارجی (external) به حافظه مشترک اشاره دارد، داخلی (internal) — به فایل‌های رسانه‌ای سیستم. استفاده از 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 به عنوان deprecated علامت‌گذاری شده است و توسعه‌دهندگان باید از طریق باز کردن InputStream بر اساس URI کار کنند.

مجوزهای کار با MediaStore

MediaStore نیاز به مجوزهای صریح دارد که بسته به نسخه Android متفاوت است. قبل از Android 13 از مجوز واحد READ_EXTERNAL_STORAGE استفاده می‌شد. از Android 13 (API 33)، Google مجوزهای دقیق برای هر نوع رسانه معرفی کرد.

نوشتن در MediaStore نیز برای Android 9 و پایین‌تر نیاز به WRITE_EXTERNAL_STORAGE دارد. از Android 10، برنامه می‌تواند فایل‌های خود را بدون مجوزهای اضافی در MediaStore بنویسد — سیستم هنگام درج رکورد از طریق ContentResolver.insert به طور خودکار دسترسی را فراهم می‌کند.

درخواست مجوزها در زمان اجرا

مجوزهای MediaStore از طریق مکانیزم استاندارد ActivityResultContracts.RequestMultiplePermissions درخواست می‌شوند. کاربر ممکن است درخواست را رد کند و برنامه باید این سناریو را به درستی مدیریت کند. توصیه می‌شود قبل از هر دسترسی به MediaStore وجود مجوز را از طریق ContextCompat.checkSelfPermission بررسی کنید.

نمونه کد: خواندن و نوشتن از طریق 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 برای انتخاب اسناد دلخواه از طریق انتخاب‌گر سیستم استفاده می‌شود.