לגשת לקובצי מדיה מנפח אחסון משותף

כדי לספק חוויית משתמש עשירה יותר, אפליקציות רבות מאפשרות למשתמשים להוסיף תוכן ולגשת למדיה שזמינה בנפח אחסון חיצוני. המסגרת מספק אינדקס אופטימלי לאוספים של מדיה, שנקרא חנות המדיה, שמאפשר למשתמשים לאחזר ולעדכן את קובצי המדיה האלה בקלות רבה יותר. באופן שווה לאחר הסרת האפליקציה, הקבצים האלה נשארים במכשיר של המשתמש.

הערה: אם האפליקציה שלך עובדת עם קובצי מדיה שמספקים ערך למשתמש בלבד בתוך האפליקציה, מומלץ לאחסן אותם בספריות ספציפיות לאפליקציה אחסון חיצוני.

בורר התמונות

כחלופה לשימוש בחנות המדיה, הכלי לבחירת תמונות ב-Android מספק למשתמשים דרך מובנית ובטוחה לבחור קובצי מדיה בלי להעניק לאפליקציה גישה לכל ספריית המדיה שלהם. התכונה הזו זמינה רק במכשירים נתמכים. מידע נוסף זמין במדריך בנושא הכלי לבחירת תמונות.

חנות מדיה

כדי לבצע אינטראקציה עם ההפשטה של חנות המדיה, צריך להשתמש אובייקט ContentResolver שאתם אחזור מההקשר של האפליקציה:

KotlinJava

val projection = arrayOf(media-database-columns-to-retrieve)
val selection = sql-where-clause-with-placeholder-variables
val selectionArgs = values-of-placeholder-variables
val sortOrder = sql-order-by-clause

applicationContext.contentResolver.query(
    MediaStore.media-type.Media.EXTERNAL_CONTENT_URI,
    projection,
    selection,
    selectionArgs,
    sortOrder
)?.use { cursor ->
    while (cursor.moveToNext()) {
        // Use an ID column from the projection to get
        // a URI representing the media item itself.
    }
}

String[] projection = new String[] {
        media-database-columns-to-retrieve
};
String selection = sql-where-clause-with-placeholder-variables;
String[] selectionArgs = new String[] {
        values-of-placeholder-variables
};
String sortOrder = sql-order-by-clause;

Cursor cursor = getApplicationContext().getContentResolver().query(
    MediaStore.media-type.Media.EXTERNAL_CONTENT_URI,
    projection,
    selection,
    selectionArgs,
    sortOrder
);

while (cursor.moveToNext()) {
    // Use an ID column from the projection to get
    // a URI representing the media item itself.
}

המערכת סורקת באופן אוטומטי נפח אחסון של אחסון חיצוני ומוסיפה קובצי מדיה לאוספים הבאים, המוגדרים היטב:

• תמונות, כולל תמונות וצילומי מסך, שנשמרות בספריות DCIM/ ו-Pictures/. המערכת מוסיפה את הקבצים האלה טבלה MediaStore.Images.
• סרטונים, שמאוחסנים בספריות DCIM/,‏ Movies/ ו-Pictures/. המערכת מוסיפה את הקבצים האלה לטבלה MediaStore.Video.
• קובצי אודיו, שמאוחסנים בתיקיות Alarms/,‏ Audiobooks/,‏ Music/,‏ Notifications/,‏ Podcasts/ ו-Ringtones/. בנוסף, המערכת מזהה פלייליסטים של אודיו שנמצאים בMusic/ או Movies/ וגם הקלטות קוליות שנמצאות בRecordings/ המערכת מוסיפה את הקבצים האלה טבלה MediaStore.Audio. הספרייה Recordings/ לא זמינה ב-Android 11 (רמת API 30) נמוכה יותר.
• קבצים שהורדו, שמאוחסנים בספרייה Download/. במצב מופעל מכשירים עם Android 10 (API ברמה 29) ואילך, הקבצים האלה מאוחסנים MediaStore.Downloads טבלה. הטבלה הזו לא זמינה ב-Android 9 (רמת API 28) ובגרסאות קודמות.

חנות המדיה כוללת גם אוסף בשם MediaStore.Files התוכן שלו תלוי אם האפליקציה משתמשת באחסון מוגבל, שזמין באפליקציות שמטרגטות את Android מגרסה 10 ואילך.

• אם האחסון המוגבל מופעל, באוסף יוצגו רק התמונות, הסרטונים וקובצי האודיו שנוצרו על ידי האפליקציה. רוב המפתחים לא צריכים להשתמש MediaStore.Files כדי להציג קובצי מדיה מאפליקציות אחרות, אבל אם יש לך דרישה ספציפית לעשות זאת, ניתן להצהיר על READ_EXTERNAL_STORAGE הרשאה. עם זאת, מומלץ להשתמש ב-MediaStore ממשקי ה-API כדי לפתוח קבצים שלא נוצרו על ידי האפליקציה.
• אם נפח האחסון בהיקף לא זמין או שלא נמצא בשימוש, באוסף יוצגו כל הנתונים סוגים שונים של קובצי מדיה.

בקשה להרשאות הנדרשות

לפני שמבצעים פעולות בקובצי מדיה, חשוב לוודא שהאפליקציה הצהירה על ההרשאות הדרושות לה כדי לגשת לקובצי המדיה האלה. עם זאת, חשוב להיזהר שלא להצהיר על הרשאות שהאפליקציה לא צריכה או לא משתמשת בהן.

הרשאות אחסון

היכולת של האפליקציה לגשת לאחסון תלויה בשאלה אם היא ניגשת רק את קובצי המדיה שלו או קבצים שנוצרו על ידי אפליקציות אחרות.

גישה לקובצי המדיה שלכם

במכשירים עם Android 10 ואילך, אין צורך הרשאות הקשורות לאחסון לגשת לקובצי מדיה ולשנות אותם האפליקציה שלך היא הבעלים, כולל קבצים בMediaStore.Downloads האוסף 'עדכונים'. לדוגמה, אם אתם מפתחים אפליקציית מצלמה, אתם לא צריכים לבקש הרשאות שקשורות לאחסון כדי לגשת לתמונות שהיא מצלמת, כי התמונות שאתם כותבים לאחסון המדיה הן בבעלות האפליקציה.

גישה לקבצי מדיה של אפליקציות אחרות

כדי לגשת לקובצי מדיה שנוצרו על ידי אפליקציות אחרות, צריך להצהיר על בהרשאות המתאימות הקשורות לאחסון, והקבצים חייבים להיות ממוקמים באחד אוספי המדיה הבאים:

• MediaStore.Images
• MediaStore.Video
• MediaStore.Audio

כל עוד אפשר לראות קובץ באמצעות השאילתות MediaStore.Images,‏ MediaStore.Video או MediaStore.Audio, אפשר לראות אותו גם באמצעות השאילתה MediaStore.Files.

קטע הקוד הבא מראה איך להצהיר על נפח האחסון המתאים הרשאות:

<!-- Required only if your app needs to access images or photos
     that other apps created. -->
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />

<!-- Required only if your app needs to access videos
     that other apps created. -->
<uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />

<!-- Required only if your app needs to access audio files
     that other apps created. -->
<uses-permission android:name="android.permission.READ_MEDIA_AUDIO" />

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

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"
                 android:maxSdkVersion="29" />

הערה: אם מבקשים גם את ההרשאה READ_MEDIA_IMAGES וגם את ההרשאה READ_MEDIA_VIDEO באותו זמן, המערכת מציגה תיבת דו-שיח אחת עם בקשה להרשאת זמן ריצה שמזכירה את שתי ההרשאות.

נדרשות הרשאות נוספות לאפליקציות שפועלות במכשירים מדור קודם

אם האפליקציה משמשת במכשיר עם Android מגרסה 9 ומטה, או אם האפליקציה שלך ביטלה באופן זמני את ההסכמה להיקף אחסון, צריך לבקש את READ_EXTERNAL_STORAGE הרשאת גישה לכל קובץ מדיה. אם אתם רוצים לשנות קובצי מדיה, עליכם לבקש גם את ההרשאה WRITE_EXTERNAL_STORAGE.

נדרשת מסגרת גישה לאחסון כדי לגשת לאפליקציות אחרות הורדות

אם האפליקציה שלכם רוצה לגשת לקובץ באוסף MediaStore.Downloads שלא נוצר על ידה, עליכם להשתמש במסגרת Storage Access Framework. למידה מידע נוסף על אופן השימוש במסגרת הזו, ראו גישה למסמכים ולקבצים אחרים מתוך נפח אחסון משותף.

הרשאת מיקום של מדיה

אם האפליקציה מטרגטת את Android 10 (רמת API 29) ואילך וצריכים כדי לאחזר מטא-נתונים לא מצונזרים של תצוגת EXIF מתמונות, צריך להצהיר על ACCESS_MEDIA_LOCATION במניפסט של האפליקציה, ואז יש לבקש את ההרשאה הזו בזמן הריצה.

אזהרה: מאחר שמבקשים את ההרשאה ACCESS_MEDIA_LOCATION בזמן הריצה, אין ערובה לאפליקציה תהיה גישה למטא-נתונים של EXIF ללא צנזור מתמונות. כדי לקבל גישה למידע הזה, האפליקציה שלכם צריכה לקבל הסכמה מפורשת מהמשתמשים.

חיפוש עדכונים לחנות המדיה

כדי לגשת לקובצי מדיה בצורה אמינה יותר, במיוחד אם האפליקציה שלך שומרת מזהי URI או נתונים מחנות המדיה, בדיקה אם הגרסה של חנות המדיה השתנתה בהשוואה למועד שבו סנכרנת את נתוני המדיה שלך בפעם האחרונה. כדי לבצע את הבדיקה הזו לעדכונים, צריך להפעיל את הפונקציה getVersion(). הגרסה שתוחזר היא מחרוזת ייחודית שמשתנה בכל פעם שמתבצע שינוי משמעותי במאגר המדיה. אם הגרסה שהוחזרה שונה מהגרסה האחרונה שסונכרנה של האפליקציה, לסרוק מחדש ולסנכרן מחדש את מטמון המדיה של האפליקציה.

צריך לבצע את הבדיקה הזו בזמן ההפעלה של תהליך האפליקציה. אין צורך לבדוק את הגרסה בכל פעם ששולחים שאילתה לחנות המדיה.

אל תניחו פרטי יישום כלשהם בנוגע למספר הגרסה.

הערה: מספר הגרסה של חנות המדיה לא משתנה כתוצאה מציד האפליקציה משתנה, למשל כשאפליקציה מוסיפה קובץ מדיה. יש שיטה נפרדת שתעזור לכם לזהות עדכונים בקובצי מדיה.

שליחת שאילתה לאוסף מדיה

כדי למצוא מדיה שעומדת בקבוצה מסוימת של תנאים, כמו משך זמן באורך 5 דקות ומעלה, או במשפט בחירה דמוי-SQL שדומה ל מוצגת בקטע הקוד הבא:

KotlinJava

// Need the READ_EXTERNAL_STORAGE permission if accessing video files that your
// app didn't create.

// Container for information about each video.
data class Video(val uri: Uri,
    val name: String,
    val duration: Int,
    val size: Int
)
val videoList = mutableListOf<Video>()

val collection =
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
        MediaStore.Video.Media.getContentUri(
            MediaStore.VOLUME_EXTERNAL
        )
    } else {
        MediaStore.Video.Media.EXTERNAL_CONTENT_URI
    }

val projection = arrayOf(
    MediaStore.Video.Media._ID,
    MediaStore.Video.Media.DISPLAY_NAME,
    MediaStore.Video.Media.DURATION,
    MediaStore.Video.Media.SIZE
)

// Show only videos that are at least 5 minutes in duration.
val selection = "${MediaStore.Video.Media.DURATION} >= ?"
val selectionArgs = arrayOf(
    TimeUnit.MILLISECONDS.convert(5, TimeUnit.MINUTES).toString()
)

// Display videos in alphabetical order based on their display name.
val sortOrder = "${MediaStore.Video.Media.DISPLAY_NAME} ASC"

val query = ContentResolver.query(
    collection,
    projection,
    selection,
    selectionArgs,
    sortOrder
)
query?.use { cursor ->
    // Cache column indices.
    val idColumn = cursor.getColumnIndexOrThrow(MediaStore.Video.Media._ID)
    val nameColumn =
            cursor.getColumnIndexOrThrow(MediaStore.Video.Media.DISPLAY_NAME)
    val durationColumn =
            cursor.getColumnIndexOrThrow(MediaStore.Video.Media.DURATION)
    val sizeColumn = cursor.getColumnIndexOrThrow(MediaStore.Video.Media.SIZE)

    while (cursor.moveToNext()) {
        // Get values of columns for a given video.
        val id = cursor.getLong(idColumn)
        val name = cursor.getString(nameColumn)
        val duration = cursor.getInt(durationColumn)
        val size = cursor.getInt(sizeColumn)

        val contentUri: Uri = ContentUris.withAppendedId(
            MediaStore.Video.Media.EXTERNAL_CONTENT_URI,
            id
        )

        // Stores column values and the contentUri in a local object
        // that represents the media file.
        videoList += Video(contentUri, name, duration, size)
    }
}

// Need the READ_EXTERNAL_STORAGE permission if accessing video files that your
// app didn't create.

// Container for information about each video.
class Video {
    private final Uri uri;
    private final String name;
    private final int duration;
    private final int size;

    public Video(Uri uri, String name, int duration, int size) {
        this.uri = uri;
        this.name = name;
        this.duration = duration;
        this.size = size;
    }
}
List<Video> videoList = new ArrayList<Video>();

Uri collection;
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
    collection = MediaStore.Video.Media.getContentUri(MediaStore.VOLUME_EXTERNAL);
} else {
    collection = MediaStore.Video.Media.EXTERNAL_CONTENT_URI;
}

String[] projection = new String[] {
    MediaStore.Video.Media._ID,
    MediaStore.Video.Media.DISPLAY_NAME,
    MediaStore.Video.Media.DURATION,
    MediaStore.Video.Media.SIZE
};
String selection = MediaStore.Video.Media.DURATION +
        " >= ?";
String[] selectionArgs = new String[] {
    String.valueOf(TimeUnit.MILLISECONDS.convert(5, TimeUnit.MINUTES));
};
String sortOrder = MediaStore.Video.Media.DISPLAY_NAME + " ASC";

try (Cursor cursor = getApplicationContext().getContentResolver().query(
    collection,
    projection,
    selection,
    selectionArgs,
    sortOrder
)) {
    // Cache column indices.
    int idColumn = cursor.getColumnIndexOrThrow(MediaStore.Video.Media._ID);
    int nameColumn =
            cursor.getColumnIndexOrThrow(MediaStore.Video.Media.DISPLAY_NAME);
    int durationColumn =
            cursor.getColumnIndexOrThrow(MediaStore.Video.Media.DURATION);
    int sizeColumn = cursor.getColumnIndexOrThrow(MediaStore.Video.Media.SIZE);

    while (cursor.moveToNext()) {
        // Get values of columns for a given video.
        long id = cursor.getLong(idColumn);
        String name = cursor.getString(nameColumn);
        int duration = cursor.getInt(durationColumn);
        int size = cursor.getInt(sizeColumn);

        Uri contentUri = ContentUris.withAppendedId(
                MediaStore.Video.Media.EXTERNAL_CONTENT_URI, id);

        // Stores column values and the contentUri in a local object
        // that represents the media file.
        videoList.add(new Video(contentUri, name, duration, size));
    }
}

כשמבצעים שאילתה באפליקציה, חשוב לזכור:

• הפעלת השיטה query() בשרשור של עובדים.
• שומרים את האינדקסים של העמודות במטמון כדי שלא תצטרכו לקרוא להם getColumnIndexOrThrow() בכל פעם שמעבדים שורה מתוצאת השאילתה.
• יש לצרף את המזהה ל-URI של התוכן כפי שמוצג בדוגמה הזו.
• במכשירים עם Android 10 ואילך נדרשת עמודה שמות שמוגדרים ממשק ה-API של MediaStore. אם ספרייה תלויה באפליקציה מצפה לשם עמודה שלא מוגדר ב-API, כמו "MimeType", צריך להשתמש ב-CursorWrapper כדי לתרגם באופן דינמי את שם העמודה בתהליך של האפליקציה.

טעינת תמונות ממוזערות של קבצים

אם האפליקציה מציגה כמה קובצי מדיה ומבקשת מהמשתמש לבחור אחד מהקבצים האלה, יעיל יותר לטעון גרסאות מקדימות – או תמונות ממוזערות – של הקבצים במקום את הקבצים עצמם.

כדי לטעון את התמונה הממוזערת של קובץ מדיה נתון, משתמשים ב- loadThumbnail() ולהעביר את גודל התמונה הממוזערת שרוצים לטעון, כפי שמוצג את קטע הקוד הבא:

KotlinJava

// Load thumbnail of a specific media item.
val thumbnail: Bitmap =
        applicationContext.contentResolver.loadThumbnail(
        content-uri, Size(640, 480), null)

// Load thumbnail of a specific media item.
Bitmap thumbnail =
        getApplicationContext().getContentResolver().loadThumbnail(
        content-uri, new Size(640, 480), null);

פתיחת קובץ מדיה

הלוגיקה הספציפית שבה משתמשים לפתיחת קובץ מדיה משתנה תוכן מדיה מיוצג בצורה הטובה ביותר כמתאר קובץ, כזרם קבצים נתיב קובץ ישיר.

מתאר קובץ

כדי לפתוח קובץ מדיה באמצעות מתאר קובץ, צריך להשתמש בלוגיקה דומה לזו שמוצגת את קטע הקוד הבא:

KotlinJava

// Open a specific media item using ParcelFileDescriptor.
val resolver = applicationContext.contentResolver

// "rw" for read-and-write.
// "rwt" for truncating or overwriting existing file contents.
val readOnlyMode = "r"
resolver.openFileDescriptor(content-uri, readOnlyMode).use { pfd ->
    // Perform operations on "pfd".
}

// Open a specific media item using ParcelFileDescriptor.
ContentResolver resolver = getApplicationContext()
        .getContentResolver();

// "rw" for read-and-write.
// "rwt" for truncating or overwriting existing file contents.
String readOnlyMode = "r";
try (ParcelFileDescriptor pfd =
        resolver.openFileDescriptor(content-uri, readOnlyMode)) {
    // Perform operations on "pfd".
} catch (IOException e) {
    e.printStackTrace();
}

העברת קבצים בסטרימינג

כדי לפתוח קובץ מדיה באמצעות העברת קבצים, צריך להשתמש בלוגיקה דומה לזו שמוצגת את קטע הקוד הבא:

KotlinJava

// Open a specific media item using InputStream.
val resolver = applicationContext.contentResolver
resolver.openInputStream(content-uri).use { stream ->
    // Perform operations on "stream".
}

// Open a specific media item using InputStream.
ContentResolver resolver = getApplicationContext()
        .getContentResolver();
try (InputStream stream = resolver.openInputStream(content-uri)) {
    // Perform operations on "stream".
}

נתיבי קבצים ישירים

כדי לעזור לאפליקציה לפעול בצורה חלקה יותר עם ספריות מדיה של צד שלישי, ב-Android 11 ואילך (רמת API 30 ואילך) אפשר להשתמש בממשקי API אחרים מלבד ה-API MediaStore כדי לגשת לקובצי מדיה מאחסון שיתופי. אפשר במקום זאת לגשת ישירות לקובצי מדיה באמצעות אחד מממשקי ה-API הבאים:

• ה-API של File
• ספריות מקוריות, כמו fopen()

אם אין לכם הרשאות שקשורות לאחסון, אפשר לגשת לקבצים ספרייה ספציפית לאפליקציה וגם מדיה קבצים שמשויכים לאפליקציה שלכם באמצעות ה-API של File.

אם האפליקציה מנסה לגשת לקובץ באמצעות ה-API File ואין לה את ההרשאות הנדרשות, מתרחשת הודעת השגיאה FileNotFoundException.

כדי לגשת לקבצים אחרים באחסון השיתופי במכשיר עם Android 10 (רמת API 29), מומלץ לבטל באופן זמני את ההסכמה לאחסון מוגבל על ידי הגדרת requestLegacyExternalStorage לערך true בקובץ המניפסט של האפליקציה. כדי לגשת לקובצי מדיה באמצעות שיטות נייטיב ב-Android 10, צריך גם לבקש READ_EXTERNAL_STORAGE הרשאה.

שיקולים בגישה לתוכן מדיה

כשאתם ניגשים לתוכן מדיה, חשוב לזכור את השיקולים שמפורטים בקטעים הבאים.

נתונים בקובץ שמור

אם האפליקציה שומרת במטמון מזהי URI או נתונים מחנות המדיה, כדאי לבדוק מדי פעם אם יש עדכונים בחנות המדיה. הבדיקה הזו מאפשרת לנתונים שנשמרו במטמון בצד האפליקציה להישאר מסונכרנים עם הנתונים של הספק בצד המערכת.

ביצועים

כשמבצעים קריאות עוקבות של קובצי מדיה באמצעות נתיבי קבצים ישירים, לביצוע השוואה MediaStore API.

כשמבצעים קריאה וכתיבה אקראיות של קובצי מדיה באמצעות נתיבי קבצים ישירים, עם זאת, התהליך עשוי להיות איטי עד פי שניים. במצבים כאלה, מומלץ להשתמש במקום זאת ב-API של MediaStore.

העמודה DATA

כשאתם ניגשים לקובץ מדיה קיים, אתם יכולים להשתמש בערך של העמודה DATA בלוגיקה שלכם. הסיבה לכך היא שלערך הזה יש נתיב קובץ תקין. עם זאת, אל תניחו שהקובץ תמיד זמין. חשוב להיות מוכנים לטפל בכל שגיאת קלט/פלט (I/O) שמתרחשת בקובץ.

לעומת זאת, כדי ליצור או לעדכן קובץ מדיה, אין להשתמש בערך של העמודה DATA. במקום זאת, השתמשו בערכים DISPLAY_NAME וגם RELATIVE_PATH עמודות.

נפחי אחסון

אפליקציות שמטרגטות את Android מגרסה 10 ואילך יכולות לגשת לשם הייחודי שהמערכת מקצה לכל נפח אחסון חיצוני. מערכת השמות הזו עוזרת לארגן את התוכן ולהוסיף אותו לאינדקס ביעילות, ומאפשרת לכם לקבוע איפה יישמרו קובצי מדיה חדשים.

חשוב במיוחד לזכור את הכרכים הבאים:

• VOLUME_EXTERNAL עוצמת הקול מספקת תצוגה של כל נפחי האחסון המשותפים במכשיר. אפשר לקרוא את התוכן של האוסף הסינתטי הזה, אבל אי אפשר לשנות את התוכן.
• VOLUME_EXTERNAL_PRIMARY מייצג את נפח האחסון המשותף הראשי במכשיר. אפשר לקרוא ולשנות את התוכן של הכרך הזה.

אפשר לחפש כרכים אחרים בטלפון MediaStore.getExternalVolumeNames()

KotlinJava

val volumeNames: Set<String> = MediaStore.getExternalVolumeNames(context)
val firstVolumeName = volumeNames.iterator().next()

Set<String> volumeNames = MediaStore.getExternalVolumeNames(context);
String firstVolumeName = volumeNames.iterator().next();

המיקום שבו צולם המדיה

חלק מהתמונות והסרטונים מכילים פרטי מיקום במטא-נתונים שלהם, שמציג את המקום שבו צולמה התמונה או את המקום שבו הסרטון צולם מוקלטת.

האופן שבו תקבלו גישה לפרטי המיקום האלה באפליקציה תלוי אם אתם צריכים גישה לפרטי המיקום של תמונה או של סרטון.

תצלומים

אם האפליקציה משתמשת באחסון מוגבל, המערכת מסתירה את פרטי המיקום כברירת מחדל. כדי לגשת למידע הזה:

1. מבקשים את ACCESS_MEDIA_LOCATION במניפסט של האפליקציה.

2. מהאובייקט MediaStore צריך לקבל את הבייטים המדויקים של התמונה באמצעות שיחות setRequireOriginal() ולהעביר את ה-URI של התמונה, כפי שמוצג בקטע הקוד הבא:

   KotlinJava

   val photoUri: Uri = Uri.withAppendedPath(
           MediaStore.Images.Media.EXTERNAL_CONTENT_URI,
           cursor.getString(idColumnIndex)
   )
   
   // Get location data using the Exifinterface library.
   // Exception occurs if ACCESS_MEDIA_LOCATION permission isn't granted.
   photoUri = MediaStore.setRequireOriginal(photoUri)
   contentResolver.openInputStream(photoUri)?.use { stream ->
       ExifInterface(stream).run {
           // If lat/long is null, fall back to the coordinates (0, 0).
           val latLong = latLong ?: doubleArrayOf(0.0, 0.0)
       }
   }

   Uri photoUri = Uri.withAppendedPath(
           MediaStore.Images.Media.EXTERNAL_CONTENT_URI,
           cursor.getString(idColumnIndex));
   
   final double[] latLong;
   
   // Get location data using the Exifinterface library.
   // Exception occurs if ACCESS_MEDIA_LOCATION permission isn't granted.
   photoUri = MediaStore.setRequireOriginal(photoUri);
   InputStream stream = getContentResolver().openInputStream(photoUri);
   if (stream != null) {
       ExifInterface exifInterface = new ExifInterface(stream);
       double[] returnedLatLong = exifInterface.getLatLong();
   
       // If lat/long is null, fall back to the coordinates (0, 0).
       latLong = returnedLatLong != null ? returnedLatLong : new double[2];
   
       // Don't reuse the stream associated with
       // the instance of "ExifInterface".
       stream.close();
   } else {
       // Failed to load the stream, so return the coordinates (0, 0).
       latLong = new double[2];
   }

סרטונים

כדי לגשת לפרטי מיקום במטא-נתונים של סרטון, צריך להשתמש ברכיב MediaMetadataRetriever class, כפי שמוצג בקטע הקוד הבא. האפליקציה לא צריכה לבקש הרשאות נוספות כדי להשתמש בכיתה הזו.

KotlinJava

val retriever = MediaMetadataRetriever()
val context = applicationContext

// Find the videos that are stored on a device by querying the video collection.
val query = ContentResolver.query(
    collection,
    projection,
    selection,
    selectionArgs,
    sortOrder
)
query?.use { cursor ->
    val idColumn = cursor.getColumnIndexOrThrow(MediaStore.Video.Media._ID)
    while (cursor.moveToNext()) {
        val id = cursor.getLong(idColumn)
        val videoUri: Uri = ContentUris.withAppendedId(
            MediaStore.Video.Media.EXTERNAL_CONTENT_URI,
            id
        )
        extractVideoLocationInfo(videoUri)
    }
}

private fun extractVideoLocationInfo(videoUri: Uri) {
    try {
        retriever.setDataSource(context, videoUri)
    } catch (e: RuntimeException) {
        Log.e(APP_TAG, "Cannot retrieve video file", e)
    }
    // Metadata uses a standardized format.
    val locationMetadata: String? =
            retriever.extractMetadata(MediaMetadataRetriever.METADATA_KEY_LOCATION)
}

MediaMetadataRetriever retriever = new MediaMetadataRetriever();
Context context = getApplicationContext();

// Find the videos that are stored on a device by querying the video collection.
try (Cursor cursor = context.getContentResolver().query(
    collection,
    projection,
    selection,
    selectionArgs,
    sortOrder
)) {
    int idColumn = cursor.getColumnIndexOrThrow(MediaStore.Video.Media._ID);
    while (cursor.moveToNext()) {
        long id = cursor.getLong(idColumn);
        Uri videoUri = ContentUris.withAppendedId(
                MediaStore.Video.Media.EXTERNAL_CONTENT_URI, id);
        extractVideoLocationInfo(videoUri);
    }
}

private void extractVideoLocationInfo(Uri videoUri) {
    try {
        retriever.setDataSource(context, videoUri);
    } catch (RuntimeException e) {
        Log.e(APP_TAG, "Cannot retrieve video file", e);
    }
    // Metadata uses a standardized format.
    String locationMetadata = retriever.extractMetadata(
            MediaMetadataRetriever.METADATA_KEY_LOCATION);
}

שיתוף

חלק מהאפליקציות מאפשרות למשתמשים לשתף קובצי מדיה זה עם זה. לדוגמה, רשתות חברתיות אפליקציות מדיה מאפשרות למשתמשים לשתף תמונות וסרטונים עם חברים.

כדי לשתף קובצי מדיה, יש להשתמש ב-URI של content://, בהתאם להמלצה במדריך אל יצירת ספק תוכן.

ייחוס של קובצי מדיה באפליקציה

כשאחסון מוגבל מופעל באפליקציה שמטרגטת את Android מגרסה 10 ואילך, המערכת משייכת אפליקציה לכל קובץ מדיה. כך המערכת קובעת לאילו קבצים לאפליקציה תהיה גישה אם היא לא ביקשה הרשאות אחסון. אפשר לשייך כל קובץ רק לאפליקציה אחת. לכן, אם האפליקציה יוצרת קובץ מדיה שמאוחסן באוסף התמונות, הסרטונים או קובצי האודיו, לאפליקציה יש גישה לקובץ.

עם זאת, אם המשתמש מסיר את האפליקציה ומתקין אותו מחדש, צריך לבקש READ_EXTERNAL_STORAGE כדי לגשת לקבצים שהאפליקציה שלכם יצרה במקור. הבקשה להרשאה נדרשת כי המערכת מתייחסת לקובץ כקשור לגרסה הקודמת של האפליקציה, ולא לגרסה החדשה שהותקנה.

הוספת פריט

כדי להוסיף פריט מדיה לאוסף קיים, משתמשים בקוד דומה לקוד הבא. קטע הקוד הזה ניגש לנפח VOLUME_EXTERNAL_PRIMARY במכשירים עם Android מגרסה 10 ואילך. הסיבה לכך היא שבמכשירים האלה אפשר לשנות את התוכן של נפח אחסון רק אם הוא נפח האחסון הראשי, כפי שמתואר בקטע נפחי אחסון.

KotlinJava

// Add a specific media item.
val resolver = applicationContext.contentResolver

// Find all audio files on the primary external storage device.
val audioCollection =
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
        MediaStore.Audio.Media.getContentUri(
            MediaStore.VOLUME_EXTERNAL_PRIMARY
        )
    } else {
        MediaStore.Audio.Media.EXTERNAL_CONTENT_URI
    }

// Publish a new song.
val newSongDetails = ContentValues().apply {
    put(MediaStore.Audio.Media.DISPLAY_NAME, "My Song.mp3")
}

// Keep a handle to the new song's URI in case you need to modify it
// later.
val myFavoriteSongUri = resolver
        .insert(audioCollection, newSongDetails)

// Add a specific media item.
ContentResolver resolver = getApplicationContext()
        .getContentResolver();

// Find all audio files on the primary external storage device.
Uri audioCollection;
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
    audioCollection = MediaStore.Audio.Media
            .getContentUri(MediaStore.VOLUME_EXTERNAL_PRIMARY);
} else {
    audioCollection = MediaStore.Audio.Media.EXTERNAL_CONTENT_URI;
}

// Publish a new song.
ContentValues newSongDetails = new ContentValues();
newSongDetails.put(MediaStore.Audio.Media.DISPLAY_NAME,
        "My Song.mp3");

// Keep a handle to the new song's URI in case you need to modify it
// later.
Uri myFavoriteSongUri = resolver
        .insert(audioCollection, newSongDetails);

החלפת מצב המתנה של קובצי מדיה

אם האפליקציה מבצעת פעולות שעשויות לגזול זמן רב, כמו כתיבה קובצי מדיה, כדאי לקבל גישה בלעדית לקובץ בזמן שהוא עבר עיבוד. במכשירים עם Android מגרסה 10 ואילך, האפליקציה יכולה: לקבל את הגישה הבלעדית הזאת באמצעות הגדרת הערך של IS_PENDING סימון ל-1. רק האפליקציה שלך יכולה לראות את הקובץ עד שהאפליקציה תשנה את הערך של IS_PENDING חזרה ל-0.

קטע הקוד הבא מבוסס על קטע הקוד הקודם. קטע הקוד הזה מראה איך משתמשים בדגל IS_PENDING כששומרים שיר ארוך בספרייה התואמת לאוסף MediaStore.Audio:

KotlinJava

// Add a media item that other apps don't see until the item is
// fully written to the media store.
val resolver = applicationContext.contentResolver

// Find all audio files on the primary external storage device.
val audioCollection =
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
        MediaStore.Audio.Media.getContentUri(
            MediaStore.VOLUME_EXTERNAL_PRIMARY
        )
    } else {
        MediaStore.Audio.Media.EXTERNAL_CONTENT_URI
    }

val songDetails = ContentValues().apply {
    put(MediaStore.Audio.Media.DISPLAY_NAME, "My Workout Playlist.mp3")
    put(MediaStore.Audio.Media.IS_PENDING, 1)
}

val songContentUri = resolver.insert(audioCollection, songDetails)

// "w" for write.
resolver.openFileDescriptor(songContentUri, "w", null).use { pfd ->
    // Write data into the pending audio file.
}

// Now that you're finished, release the "pending" status and let other apps
// play the audio track.
songDetails.clear()
songDetails.put(MediaStore.Audio.Media.IS_PENDING, 0)
resolver.update(songContentUri, songDetails, null, null)

// Add a media item that other apps don't see until the item is
// fully written to the media store.
ContentResolver resolver = getApplicationContext()
        .getContentResolver();

// Find all audio files on the primary external storage device.
Uri audioCollection;
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
    audioCollection = MediaStore.Audio.Media
            .getContentUri(MediaStore.VOLUME_EXTERNAL_PRIMARY);
} else {
    audioCollection = MediaStore.Audio.Media.EXTERNAL_CONTENT_URI;
}

ContentValues songDetails = new ContentValues();
songDetails.put(MediaStore.Audio.Media.DISPLAY_NAME,
        "My Workout Playlist.mp3");
songDetails.put(MediaStore.Audio.Media.IS_PENDING, 1);

Uri songContentUri = resolver
        .insert(audioCollection, songDetails);

// "w" for write.
try (ParcelFileDescriptor pfd =
        resolver.openFileDescriptor(songContentUri, "w", null)) {
    // Write data into the pending audio file.
}

// Now that you're finished, release the "pending" status and let other apps
// play the audio track.
songDetails.clear();
songDetails.put(MediaStore.Audio.Media.IS_PENDING, 0);
resolver.update(songContentUri, songDetails, null, null);

הוספת רמז למיקום הקובץ

כשהאפליקציה שומרת מדיה במכשיר עם Android 10, עד ברירת המחדל של המדיה מאורגנת לפי הסוג שלה. לדוגמה, כברירת מחדל קובצי תמונות חדשים ממוקמים בספרייה Environment.DIRECTORY_PICTURES, שמתאימה לאוסף MediaStore.Images.

אם האפליקציה מזהה מיקום ספציפי שבו אפשר לאחסן קבצים, למשל בתור אלבום תמונות בשם Pictures/MyVacationPictures, אפשר להגדיר MediaColumns.RELATIVE_PATH כדי לספק למערכת רמז למיקום האחסון של הקבצים החדשים שנכתבו.

הערה: למרות שניתן לאחסן קבצים לשימוש כללי בשני סוגי האפליקציות התיקייה Documents/ או התיקייה Download/, כולל קבצים שאינם קובצי מדיה, עדיף להשתמש ב-Storage Access Framework בתרחישים לדוגמה כאלה.

עדכון פריט

כדי לעדכן קובץ מדיה שבבעלות האפליקציה, משתמשים בקוד דומה לקוד הבא:

KotlinJava

// Updates an existing media item.
val mediaId = // MediaStore.Audio.Media._ID of item to update.
val resolver = applicationContext.contentResolver

// When performing a single item update, prefer using the ID.
val selection = "${MediaStore.Audio.Media._ID} = ?"

// By using selection + args you protect against improper escaping of // values.
val selectionArgs = arrayOf(mediaId.toString())

// Update an existing song.
val updatedSongDetails = ContentValues().apply {
    put(MediaStore.Audio.Media.DISPLAY_NAME, "My Favorite Song.mp3")
}

// Use the individual song's URI to represent the collection that's
// updated.
val numSongsUpdated = resolver.update(
        myFavoriteSongUri,
        updatedSongDetails,
        selection,
        selectionArgs)

// Updates an existing media item.
long mediaId = // MediaStore.Audio.Media._ID of item to update.
ContentResolver resolver = getApplicationContext()
        .getContentResolver();

// When performing a single item update, prefer using the ID.
String selection = MediaStore.Audio.Media._ID + " = ?";

// By using selection + args you protect against improper escaping of
// values. Here, "song" is an in-memory object that caches the song's
// information.
String[] selectionArgs = new String[] { getId().toString() };

// Update an existing song.
ContentValues updatedSongDetails = new ContentValues();
updatedSongDetails.put(MediaStore.Audio.Media.DISPLAY_NAME,
        "My Favorite Song.mp3");

// Use the individual song's URI to represent the collection that's
// updated.
int numSongsUpdated = resolver.update(
        myFavoriteSongUri,
        updatedSongDetails,
        selection,
        selectionArgs);

אם האחסון המוגבל לא זמין או לא מופעל, התהליך שמתואר בקטע הקוד הקודם פועל גם לגבי קבצים שהאפליקציה לא הבעלים שלהם.

הערה: אפשר להעביר קבצים בדיסק במהלך קריאה ל-update() על ידי שינוי הערך של MediaColumns.RELATIVE_PATH או של MediaColumns.DISPLAY_NAME.

עדכון בקוד המקורי

כדי לכתוב קובצי מדיה באמצעות ספריות נייטיב, מעבירים את ממתאר קובץ משויך מקוד מבוסס Java או מקוד מבוסס Kotlin את הקוד המקורי.

קטע הקוד הבא מראה איך מעבירים את מתאר הקובץ של אובייקט מדיה לקוד האפליקציה:

KotlinJava

val contentUri: Uri = ContentUris.withAppendedId(
        MediaStore.Audio.Media.EXTERNAL_CONTENT_URI,
        cursor.getLong(BaseColumns._ID))
val fileOpenMode = "r"
val parcelFd = resolver.openFileDescriptor(contentUri, fileOpenMode)
val fd = parcelFd?.detachFd()
// Pass the integer value "fd" into your native code. Remember to call
// close(2) on the file descriptor when you're done using it.

Uri contentUri = ContentUris.withAppendedId(
        MediaStore.Audio.Media.EXTERNAL_CONTENT_URI,
        cursor.getLong(Integer.parseInt(BaseColumns._ID)));
String fileOpenMode = "r";
ParcelFileDescriptor parcelFd =
        resolver.openFileDescriptor(contentUri, fileOpenMode);
if (parcelFd != null) {
    int fd = parcelFd.detachFd();
    // Pass the integer value "fd" into your native code. Remember to call
    // close(2) on the file descriptor when you're done using it.
}

עדכון קובצי מדיה של אפליקציות אחרות

אם האפליקציה שלכם משתמשת באחסון מוגבל, בדרך כלל היא לא יכולה לעדכן קובץ מדיה שאפליקציה אחרת הוסיפה למאגר המדיה.

עם זאת, אפשר לקבל את הסכמת המשתמשים לשינוי הקובץ RecoverableSecurityException שהפלטפורמה זורקת. לאחר מכן תוכלו לבקש מהמשתמש להעניק לאפליקציה הרשאת כתיבה לפריט הספציפי הזה, כפי שמתואר בקטע הקוד הבא:

KotlinJava

// Apply a grayscale filter to the image at the given content URI.
try {
    // "w" for write.
    contentResolver.openFileDescriptor(image-content-uri, "w")?.use {
        setGrayscaleFilter(it)
    }
} catch (securityException: SecurityException) {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
        val recoverableSecurityException = securityException as?
            RecoverableSecurityException ?:
            throw RuntimeException(securityException.message, securityException)

        val intentSender =
            recoverableSecurityException.userAction.actionIntent.intentSender
        intentSender?.let {
            startIntentSenderForResult(intentSender, image-request-code,
                    null, 0, 0, 0, null)
        }
    } else {
        throw RuntimeException(securityException.message, securityException)
    }
}

try {
    // "w" for write.
    ParcelFileDescriptor imageFd = getContentResolver()
            .openFileDescriptor(image-content-uri, "w");
    setGrayscaleFilter(imageFd);
} catch (SecurityException securityException) {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
        RecoverableSecurityException recoverableSecurityException;
        if (securityException instanceof RecoverableSecurityException) {
            recoverableSecurityException =
                    (RecoverableSecurityException)securityException;
        } else {
            throw new RuntimeException(
                    securityException.getMessage(), securityException);
        }
        IntentSender intentSender =recoverableSecurityException.getUserAction()
                .getActionIntent().getIntentSender();
        startIntentSenderForResult(intentSender, image-request-code,
                null, 0, 0, 0, null);
    } else {
        throw new RuntimeException(
                securityException.getMessage(), securityException);
    }
}

צריך להשלים את התהליך הזה בכל פעם שהאפליקציה צריכה לשנות קובץ מדיה שהיא לא יצרה.

לחלופין, אם האפליקציה פועלת ב-Android 11 ואילך, אפשר משתמשים יכולים לתת לאפליקציה גישת כתיבה לקבוצה של קובצי מדיה. משתמשים ב createWriteRequest() שיטה זו, כפי שמתואר בקטע על ניהול קבוצות של מדיה קבצים.

אם לאפליקציה שלכם יש תרחיש אחר לדוגמה שלא נכלל בנפח האחסון בהיקף, ציינו בקשה להוספת תכונה וגם להפסיק באופן זמני את השימוש בהיקף אחסון.

הסרת פריט

כדי להסיר מחנות המדיה פריט שאין לאפליקציה יותר צורך בו, משתמשים בלוגיקה שדומה לזו שמוצגת בקטע הקוד הבא:

KotlinJava

// Remove a specific media item.
val resolver = applicationContext.contentResolver

// URI of the image to remove.
val imageUri = "..."

// WHERE clause.
val selection = "..."
val selectionArgs = "..."

// Perform the actual removal.
val numImagesRemoved = resolver.delete(
        imageUri,
        selection,
        selectionArgs)

// Remove a specific media item.
ContentResolver resolver = getApplicationContext()
        getContentResolver();

// URI of the image to remove.
Uri imageUri = "...";

// WHERE clause.
String selection = "...";
String[] selectionArgs = "...";

// Perform the actual removal.
int numImagesRemoved = resolver.delete(
        imageUri,
        selection,
        selectionArgs);

אם נפח האחסון בהיקף לא זמין או לא מופעל, אפשר להשתמש את קטע הקוד להסרת קבצים שבבעלות אפליקציות אחרות. אם נפח האחסון בהיקף מופעל, עם זאת, צריך להשיג RecoverableSecurityException לכל קובץ האפליקציה שלך רוצה להסיר, כפי שמתואר בקטע עדכון מדיה פריטים.

אם האפליקציה שלכם פועלת ב-Android מגרסה 11 ואילך, תוכלו לאפשר למשתמשים לבחור קבוצה של קובצי מדיה להסרה. שימוש בcreateTrashRequest() או createDeleteRequest() שיטה זו, כפי שמתואר בקטע על ניהול קבוצות של מדיה קבצים.

אם יש לאפליקציה שלכם תרחיש לדוגמה נוסף שלא מכוסה על ידי נפח האחסון הייעודי לאפליקציות, שלחו בקשה להוספת תכונה וביטלו את ההשתתפות בנפח האחסון הייעודי לאפליקציות באופן זמני.

זיהוי עדכונים לקובצי מדיה

יכול להיות שהאפליקציה שלכם תצטרך לזהות נפחי אחסון שמכילים קובצי מדיה שאפליקציות הוסיפו או שינו, בהשוואה לנקודת זמן קודמת. כדי לזהות את השינויים האלה בצורה מהימנה ככל האפשר, מעבירים את נפח האחסון הרצוי אל getGeneration(). כל עוד הגרסה של חנות המדיה לא משתנה, ערך ההחזרה של השיטה הזו עולה באופן מונוטוני עם הזמן.

באופן ספציפי, המדד getGeneration() מבוסס יותר מהתאריכים בעמודות מדיה, כמו DATE_ADDED ו-DATE_MODIFIED. הסיבה לכך היא שערכים של עמודות מדיה יכולים להשתנות כשאפליקציה קוראת ל-setLastModified() או כשהמשתמש משנה את שעון המערכת.

שימו לב: לפני שמסתמכים על הערך של getGeneration(), צריך לבדוק אם יש עדכונים בחנות המדיה. אם הגרסה של חנות המדיה השתנתה, לבצע מעבר סנכרון מלא.

ניהול קבוצות של קובצי מדיה

ב-Android 11 ואילך, אפשר לבקש מהמשתמש לבחור קבוצה של קובצי מדיה, ואז לעדכן את קובצי המדיה האלה בפעולה אחת. האלה השיטות האלה מספקות עקביות טובה יותר בין מכשירים, והשיטות מקלות על התהליך למשתמשים לנהל את אוספי המדיה שלהם.

השיטות שמספקות את הפונקציונליות של 'עדכון באצווה' כוללות את השיטות הבאות:

createWriteRequest()

עליך לבקש מהמשתמש להעניק לאפליקציה שלך גישת כתיבה לקבוצה שצוינה של קובצי מדיה.

createFavoriteRequest()

לבקש מהמשתמש לסמן את קובצי המדיה שצוינו כחלק מקובצי המדיה 'מועדפים' במדיה במכשיר. כל אפליקציה שיש לה גישת קריאה לקובץ הזה יכולה לראות שהמשתמש סימן את הקובץ כ'מועדף'.

createTrashRequest()

מבקשים מהמשתמש להעביר את קובצי המדיה שצוינו לאשפה של המכשיר. הפריטים שבאשפה נמחקים לתמיד אחרי פרק זמן מוגדר מראש.

הערה: אם האפליקציה היא אפליקציית הגלריה שהותקנה מראש על ידי ה-OEM במכשיר, אתם יכולים להציב הקבצים באשפה בלי להציג תיבת דו-שיח. כדי לעשות את זה, צריך להגדיר IS_TRASHED ישירות אל 1.

createDeleteRequest()

שליחת בקשה מהמשתמש למחוק באופן סופי את קובצי המדיה שצוינו מיד, מבלי להעביר אותם לאשפה לפני כן.

לאחר קריאה לכל אחת מהשיטות האלה, המערכת יוצרת אובייקט PendingIntent. אחרי האפליקציה מפעיל את הכוונה הזו, המשתמשים רואים תיבת דו-שיח עם בקשה להסכמתם לאפליקציה כדי לעדכן או למחוק את קובצי המדיה שצוינו.

לדוגמה, כך המבנה של קריאה ל-createWriteRequest():

KotlinJava

val urisToModify = /* A collection of content URIs to modify. */
val editPendingIntent = MediaStore.createWriteRequest(contentResolver,
        urisToModify)

// Launch a system prompt requesting user permission for the operation.
startIntentSenderForResult(editPendingIntent.intentSender, EDIT_REQUEST_CODE,
    null, 0, 0, 0)

List<Uri> urisToModify = /* A collection of content URIs to modify. */
PendingIntent editPendingIntent = MediaStore.createWriteRequest(contentResolver,
                  urisToModify);

// Launch a system prompt requesting user permission for the operation.
startIntentSenderForResult(editPendingIntent.getIntentSender(),
    EDIT_REQUEST_CODE, null, 0, 0, 0);

בודקים את התשובה של המשתמש. אם המשתמש הביע הסכמה, ממשיכים בפעולה של המדיה. אחרת, צריך להסביר למשתמש למה נדרשת לאפליקציה ההרשאה:

KotlinJava

override fun onActivityResult(requestCode: Int, resultCode: Int,
                 data: Intent?) {
    ...
    when (requestCode) {
        EDIT_REQUEST_CODE ->
            if (resultCode == Activity.RESULT_OK) {
                /* Edit request granted; proceed. */
            } else {
                /* Edit request not granted; explain to the user. */
            }
    }
}

@Override
protected void onActivityResult(int requestCode, int resultCode,
                   @Nullable Intent data) {
    ...
    if (requestCode == EDIT_REQUEST_CODE) {
        if (resultCode == Activity.RESULT_OK) {
            /* Edit request granted; proceed. */
        } else {
            /* Edit request not granted; explain to the user. */
        }
    }
}

אפשר להשתמש באותו דפוס כללי עם createFavoriteRequest() createTrashRequest(), וגם createDeleteRequest().

הרשאה לניהול מדיה

משתמשים עשויים לסמוך על אפליקציה מסוימת לניהול מדיה, למשל לבצע עריכות תכופות של קובצי מדיה. אם האפליקציה מטרגטת Android מגרסה 11 ואילך ולא אפליקציית הגלריה של המכשיר, תצטרכו להציג למשתמש תיבת דו-שיח לאישור בכל פעם שהאפליקציה שלכם מנסה לשנות או למחוק קובץ.

אם האפליקציה מטרגטת את Android 12 (רמת API 31) ואילך, אפשר לבקש מעניקים לאפליקציה גישה להרשאה מיוחדת לניהול מדיה. ההרשאה הזו מאפשרת לאפליקציה לבצע את הפעולות הבאות בלי לבקש מהמשתמש אישור לכל פעולה:

• שינוי קבצים באמצעות createWriteRequest()
• העברת קבצים לאשפה ומחוץ לה, באמצעות createTrashRequest()
• למחוק קבצים באמצעות createDeleteRequest().

כדי לעשות זאת, מבצעים את השלבים הבאים:

1. מגדירים את ההרשאה MANAGE_MEDIA ואת ההרשאה READ_EXTERNAL_STORAGE בקובץ המניפסט של האפליקציה.

   כדי לקרוא ל-createWriteRequest() בלי להציג תיבת דו-שיח לאישור, צריך להצהיר גם על ההרשאה ACCESS_MEDIA_LOCATION.

2. באפליקציה, מציגים למשתמש ממשק משתמש עם הסבר למה כדאי לתת לאפליקציה גישה לניהול מדיה.

3. מפעילים את ACTION_REQUEST_MANAGE_MEDIA פעולת Intent. הפעולה הזו תעביר את המשתמשים למסך האפליקציות לניהול מדיה ב- הגדרות המערכת. מכאן המשתמשים יכולים להעניק לאפליקציה המיוחדת גישה.

תרחישים לדוגמה שמחייבים חלופה לחנות המדיה

אם האפליקציה שלכם ממלאת בעיקר את אחד מהתפקידים הבאים, כדאי לשקול אלטרנטיביים לממשקי ה-API של MediaStore.

עבודה עם סוגים אחרים של קבצים

אם האפליקציה פועלת עם מסמכים וקבצים שלא מכילים רק מדיה תוכן, למשל קבצים עם סיומת קובץ EPUB או PDF, יש להשתמש ב פעולת Intent מסוג ACTION_OPEN_DOCUMENT, כפי שמתואר במדריך לאחסון וגישה למסמכים .

שיתוף קבצים באפליקציות נלוות

במקרים שבהם אתם מספקים חבילת אפליקציות נלוות, כמו אפליקציית הודעות ואפליקציית פרופיל, מגדירים שיתוף קבצים באמצעות מזהי URI מסוג content://. אנחנו ממליצים גם על תהליך העבודה הזה כאמצעי לאבטחה בפועל.

מקורות מידע נוספים

למידע נוסף על אחסון מדיה ועל גישה אליה, אפשר לעיין במקורות המידע הבאים:

דוגמיות

• MediaStore, זמין ב-GitHub

סרטונים

• הכנה לקראת Scoped Storage (Android Dev Summit 2019)