Paylaşılan depolama alanındaki dokümanlara ve diğer dosyalara erişme

Uygulamanız, Android 4.4 (API düzeyi 19) ve sonraki sürümleri çalıştıran cihazlarda Depolama Erişim Çerçevesi'ni kullanarak harici depolama birimleri ve bulut tabanlı depolama dahil olmak üzere bir doküman sağlayıcısıyla etkileşim kurabilir. Bu çerçeve, kullanıcıların bir belge sağlayıcısı seçmek ve uygulamanızın oluşturması, açması veya değiştirmesi için belirli dokümanları ve diğer dosyaları seçmek üzere sistem seçiciyle etkileşimde bulunmalarına olanak tanır.

Uygulamanızın erişebileceği dosyaları veya dizinleri seçmekte kullanıcı rol oynadığından bu mekanizma, herhangi bir sistem izni gerektirmez ve kullanıcı denetimi ile gizlilik geliştirilir. Ayrıca, uygulamaya özel bir dizinin ve medya mağazasının dışında depolanan bu dosyalar, uygulamanız kaldırıldıktan sonra cihazda kalır.

Çerçevenin kullanılması aşağıdaki adımları içerir:

1. Bir uygulama, depolama alanıyla ilgili işlem içeren bir niyet çağırır. Bu işlem, çerçevenin kullanıma sunduğu belirli bir kullanım alanına karşılık gelir.
2. Kullanıcı, bir sistem seçici görür. Bu seçici, kullanıcının doküman sağlayıcısına göz atmasına ve depolamayla ilgili işlemin gerçekleştirileceği konumu veya dokümanı belirlemesine olanak tanır.
3. Uygulama, kullanıcının seçtiği konumu veya belgeyi temsil eden bir URI'ye okuma ve yazma erişimi kazanır. Uygulama, bu URI'yı kullanarak seçilen konumda işlem gerçekleştirebilir.

Not: Uygulamanız medya dosyalarına erişiyorsa fotoğraflara ve videolara erişmek için rahat bir arayüz sağlayan fotoğraf seçiciyi kullanabilirsiniz.

Android 9 (API düzeyi 28) veya önceki sürümleri çalıştıran cihazlarda medya dosyasına erişimi desteklemek için READ_EXTERNAL_STORAGE iznini beyan edin ve maxSdkVersion özelliğini 28 olarak ayarlayın.

Bu kılavuzda, çerçevenin dosyalar ve diğer belgelerle çalışmak için desteklediği farklı kullanım alanları açıklanmaktadır. Ayrıca, kullanıcı tarafından seçilen konumda işlemlerin nasıl yapılacağı da açıklanmaktadır.

Dokümanlara ve diğer dosyalara erişim için kullanım alanları

Depolama Erişim Çerçevesi, dosyalara ve diğer belgelere erişmek için aşağıdaki kullanım alanlarını destekler.

Yeni dosya oluşturma

ACTION_CREATE_DOCUMENT Amaç işlemi, kullanıcıların bir dosyayı belirli bir konuma kaydetmesine olanak tanır.

Bir dokümanı veya dosyayı açma

ACTION_OPEN_DOCUMENT Amaç işlemi, kullanıcıların açmak için belirli bir dokümanı veya dosyayı seçmesine olanak tanır.

Dizin içeriğine erişim izni verme

Android 5.0 (API düzeyi 21) ve sonraki sürümlerde bulunan ACTION_OPEN_DOCUMENT_TREE intent işlemi, kullanıcıların belirli bir dizini seçmesine olanak tanıyarak uygulamanızın o dizindeki tüm dosyalara ve alt dizinlere erişmesine izin verir.

Aşağıdaki bölümlerde, her bir kullanım alanının nasıl yapılandırılacağı konusunda yol gösterici bilgiler sunulmaktadır.

Yeni dosya oluşturma

Sistem dosya seçiciyi yüklemek ve kullanıcının dosya içeriğinin yazılacağı konumu seçmesine izin vermek için ACTION_CREATE_DOCUMENT amaç işlemini kullanın. Bu işlem, diğer işletim sistemlerinin kullandığı "farklı kaydet" iletişim kutularında kullanılan işleme benzerdir.

Not: ACTION_CREATE_DOCUMENT, mevcut bir dosyanın üzerine yazamaz. Uygulamanız aynı adla bir dosya kaydetmeye çalışırsa sistem, dosya adının sonuna parantez içinde bir sayı ekler.

Örneğin, uygulamanız confirmation.pdf adında bir dosyayı zaten bu ada sahip bir dosyanın bulunduğu bir dizine kaydetmeye çalışırsa sistem yeni dosyayı confirmation(1).pdf adıyla kaydeder.

Niyeti yapılandırırken dosyanın adını ve MIME türünü belirtin ve isteğe bağlı olarak, ekstra EXTRA_INITIAL_URI niyetini kullanarak dosya seçicinin ilk yüklendiğinde görüntülemesi gereken dosya veya dizinin URI'sını belirtin.

Aşağıdaki kod snippet'i, dosya oluşturma amacının nasıl oluşturulacağını ve çağrılacağını göstermektedir:

Kotlin

// Request code for creating a PDF document.
const val CREATE_FILE = 1

private fun createFile(pickerInitialUri: Uri) {
    val intent = Intent(Intent.ACTION_CREATE_DOCUMENT).apply {
        addCategory(Intent.CATEGORY_OPENABLE)
        type = "application/pdf"
        putExtra(Intent.EXTRA_TITLE, "invoice.pdf")

        // Optionally, specify a URI for the directory that should be opened in
        // the system file picker before your app creates the document.
        putExtra(DocumentsContract.EXTRA_INITIAL_URI, pickerInitialUri)
    }
    startActivityForResult(intent, CREATE_FILE)
}

Java

// Request code for creating a PDF document.
private static final int CREATE_FILE = 1;

private void createFile(Uri pickerInitialUri) {
    Intent intent = new Intent(Intent.ACTION_CREATE_DOCUMENT);
    intent.addCategory(Intent.CATEGORY_OPENABLE);
    intent.setType("application/pdf");
    intent.putExtra(Intent.EXTRA_TITLE, "invoice.pdf");

    // Optionally, specify a URI for the directory that should be opened in
    // the system file picker when your app creates the document.
    intent.putExtra(DocumentsContract.EXTRA_INITIAL_URI, pickerInitialUri);

    startActivityForResult(intent, CREATE_FILE);
}

Dosya aç

Uygulamanızda, kullanıcıların benzerleriyle paylaşmak veya başka dokümanlara aktarmak isteyebilecekleri verileri girdikleri depolama birimi olarak dokümanları kullanabilirsiniz. Bir kullanıcının üretkenlik dokümanını veya EPUB dosyası olarak kaydedilmiş bir kitabı açmasını örnek olarak verebiliriz.

Bu gibi durumlarda, sistemin dosya seçici uygulamasını açan ACTION_OPEN_DOCUMENT amacını çağırarak kullanıcının açılacak dosyayı seçmesine izin verin. Yalnızca uygulamanızın desteklediği dosya türlerini göstermek için bir MIME türü belirtin. Ayrıca, isteğe bağlı olarak EXTRA_INITIAL_URI ekstra niyetini kullanarak dosya seçicinin dosya ilk kez yüklendiğinde görüntülemesi gereken URI'sini de belirtebilirsiniz.

Aşağıdaki kod snippet'inde, bir PDF dokümanını açma amacının nasıl oluşturulacağı ve çağrılacağı gösterilmektedir:

Kotlin

// Request code for selecting a PDF document.
const val PICK_PDF_FILE = 2

fun openFile(pickerInitialUri: Uri) {
    val intent = Intent(Intent.ACTION_OPEN_DOCUMENT).apply {
        addCategory(Intent.CATEGORY_OPENABLE)
        type = "application/pdf"

        // Optionally, specify a URI for the file that should appear in the
        // system file picker when it loads.
        putExtra(DocumentsContract.EXTRA_INITIAL_URI, pickerInitialUri)
    }

    startActivityForResult(intent, PICK_PDF_FILE)
}

Java

// Request code for selecting a PDF document.
private static final int PICK_PDF_FILE = 2;

private void openFile(Uri pickerInitialUri) {
    Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT);
    intent.addCategory(Intent.CATEGORY_OPENABLE);
    intent.setType("application/pdf");

    // Optionally, specify a URI for the file that should appear in the
    // system file picker when it loads.
    intent.putExtra(DocumentsContract.EXTRA_INITIAL_URI, pickerInitialUri);

    startActivityForResult(intent, PICK_PDF_FILE);
}

Erişim kısıtlamaları

Android 11 (API düzeyi 30) ve sonraki sürümlerde, kullanıcının aşağıdaki dizinlerden dosyaları seçmesini istemek için ACTION_OPEN_DOCUMENT intent işlemini kullanamazsınız:

• Android/data/ dizini ve tüm alt dizinler.
• Android/obb/ dizini ve tüm alt dizinler.

Dizin içeriğine erişim izni verme

Not: Bu bölümde açıklanan intent işlemi, Android 5.0 (API düzeyi 21) ve sonraki sürümlerde kullanılabilir.

Dosya yönetimi ve medya oluşturma uygulamaları genellikle bir dizin hiyerarşisindeki dosya gruplarını yönetir. Uygulamanızda bu özelliği sağlamak için ACTION_OPEN_DOCUMENT_TREE intent işlemini kullanın. Bu işlem, kullanıcının Android 11'den (API düzeyi 30) başlayan bazı istisnalarla birlikte tüm dizin ağacına erişim izni vermesine olanak tanır. Böylece uygulamanız, seçilen dizindeki ve bu dizinin alt dizinlerindeki herhangi bir dosyaya erişebilir.

ACTION_OPEN_DOCUMENT_TREE kullanıldığında uygulamanız yalnızca kullanıcının seçtiği dizindeki dosyalara erişim elde eder. Kullanıcı tarafından seçilen bu dizinin dışında bulunan diğer uygulamaların dosyalarına erişiminiz yok. Kullanıcı tarafından kontrol edilen bu erişim, kullanıcıların uygulamanızla tam olarak hangi içeriği paylaşmak istediklerini seçmelerine olanak tanır.

İsteğe bağlı olarak, EXTRA_INITIAL_URI ekstra niyetini kullanarak dosya seçicinin ilk yüklendiğinde görüntülemesi gereken dizin URI'sini belirtebilirsiniz.

Aşağıdaki kod snippet'i, bir dizin açma amacının nasıl oluşturulacağını ve çağrılacağını gösterir:

Kotlin

fun openDirectory(pickerInitialUri: Uri) {
    // Choose a directory using the system's file picker.
    val intent = Intent(Intent.ACTION_OPEN_DOCUMENT_TREE).apply {
        // Optionally, specify a URI for the directory that should be opened in
        // the system file picker when it loads.
        putExtra(DocumentsContract.EXTRA_INITIAL_URI, pickerInitialUri)
    }

    startActivityForResult(intent, your-request-code)
}

Java

public void openDirectory(Uri uriToLoad) {
    // Choose a directory using the system's file picker.
    Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT_TREE);

    // Optionally, specify a URI for the directory that should be opened in
    // the system file picker when it loads.
    intent.putExtra(DocumentsContract.EXTRA_INITIAL_URI, uriToLoad);

    startActivityForResult(intent, your-request-code);
}

Dikkat: ACTION_OPEN_DOCUMENT_TREE kullanarak erişilen dizinde çok sayıda dosyayı tekrarlamanız durumunda uygulamanızın performansı düşebilir.

Erişim kısıtlamaları

Android 11 (API düzeyi 30) ve sonraki sürümlerde, aşağıdaki dizinlere erişim istemek için ACTION_OPEN_DOCUMENT_TREE intent işlemini kullanamazsınız:

• Dahili depolama biriminin kök dizini.
• Kartın emüle edilmiş veya çıkarılabilir olmasına bakılmaksızın, cihaz üreticisinin güvenilir olarak kabul ettiği her bir SD kart biriminin kök dizini. Güvenilir bir birim, uygulamaların çoğu zaman başarıyla erişebildiği hacimdir.
• Download dizini.

Ayrıca, Android 11 (API düzeyi 30) ve sonraki sürümlerde, kullanıcının aşağıdaki dizinlerden dosya seçmesini istemek için ACTION_OPEN_DOCUMENT_TREE intent işlemini kullanamazsınız:

• Android/data/ dizini ve tüm alt dizinler.
• Android/obb/ dizini ve tüm alt dizinler.

Seçilen konumda işlem gerçekleştirme

Kullanıcı, sistemin dosya seçiciyi kullanarak bir dosya veya dizin seçtikten sonra, seçilen öğenin URI'sini onActivityResult() içinde aşağıdaki kodu kullanarak alabilirsiniz:

Kotlin

override fun onActivityResult(
        requestCode: Int, resultCode: Int, resultData: Intent?) {
    if (requestCode == your-request-code
            && resultCode == Activity.RESULT_OK) {
        // The result data contains a URI for the document or directory that
        // the user selected.
        resultData?.data?.also { uri ->
            // Perform operations on the document using its URI.
        }
    }
}

Java

@Override
public void onActivityResult(int requestCode, int resultCode,
        Intent resultData) {
    if (requestCode == your-request-code
            && resultCode == Activity.RESULT_OK) {
        // The result data contains a URI for the document or directory that
        // the user selected.
        Uri uri = null;
        if (resultData != null) {
            uri = resultData.getData();
            // Perform operations on the document using its URI.
        }
    }
}

Seçili öğenin URI'sına referans alarak öğe üzerinde çeşitli işlemler gerçekleştirilebilir. Örneğin, öğenin meta verilerine erişebilir, öğeyi yerinde düzenleyebilir ve silebilirsiniz.

Aşağıdaki bölümlerde, kullanıcının seçtiği dosyalarda nasıl işlem yapılacağı gösterilmektedir.

Bir sağlayıcının desteklediği işlemleri belirleme

Farklı içerik sağlayıcıları, belgeler üzerinde farklı işlemlerin gerçekleştirilmesine (dokümanı kopyalama veya küçük resmini görüntüleme gibi) olanak tanır. Belirli bir sağlayıcının hangi işlemleri desteklediğini belirlemek için Document.COLUMN_FLAGS değerini kontrol edin. Bu durumda uygulamanızın kullanıcı arayüzünde yalnızca sağlayıcının desteklediği seçenekler gösterilebilir.

İzinleri koru

Uygulamanız okuma veya yazma için bir dosya açtığında sistem, uygulamanıza o dosya için bir URI izni verir. Bu izin, kullanıcının cihazı yeniden başlatılana kadar geçerli olur. Ancak uygulamanızın bir resim düzenleme uygulaması olduğunu ve kullanıcıların en son düzenledikleri 5 resme doğrudan uygulamanızdan erişebilmelerini istediğinizi varsayalım. Kullanıcının cihazı yeniden başlatılmışsa, dosyaları bulmak için kullanıcıyı sistem seçiciye geri göndermeniz gerekir.

Cihaz yeniden başlatıldığında dosyalara erişimi korumak ve daha iyi bir kullanıcı deneyimi oluşturmak için uygulamanız, aşağıdaki kod snippet'inde gösterildiği gibi sistemin sunduğu kalıcı URI izni iznini "alabilir":

Kotlin

val contentResolver = applicationContext.contentResolver

val takeFlags: Int = Intent.FLAG_GRANT_READ_URI_PERMISSION or
        Intent.FLAG_GRANT_WRITE_URI_PERMISSION
// Check for the freshest data.
contentResolver.takePersistableUriPermission(uri, takeFlags)

Java

final int takeFlags = intent.getFlags()
            & (Intent.FLAG_GRANT_READ_URI_PERMISSION
            | Intent.FLAG_GRANT_WRITE_URI_PERMISSION);
// Check for the freshest data.
getContentResolver().takePersistableUriPermission(uri, takeFlags);

Dikkat: İlgili belge taşınırsa veya silinirse takePersistableUriPermission() çağrısı yaptıktan sonra bile uygulamanız URI'ye erişimi korumaz. Bu durumlarda, URI'ye yeniden erişim kazanmak için tekrar izin istemeniz gerekir.

Doküman meta verilerini inceleme

Bir dokümanın URI'sına sahip olduğunuzda dokümanın meta verilerine erişebilirsiniz. Bu snippet, URI tarafından belirtilen bir belgenin meta verilerini alır ve günlüğe kaydeder:

Kotlin

val contentResolver = applicationContext.contentResolver

fun dumpImageMetaData(uri: Uri) {

    // The query, because it only applies to a single document, returns only
    // one row. There's no need to filter, sort, or select fields,
    // because we want all fields for one document.
    val cursor: Cursor? = contentResolver.query(
            uri, null, null, null, null, null)

    cursor?.use {
        // moveToFirst() returns false if the cursor has 0 rows. Very handy for
        // "if there's anything to look at, look at it" conditionals.
        if (it.moveToFirst()) {

            // Note it's called "Display Name". This is
            // provider-specific, and might not necessarily be the file name.
            val displayName: String =
                    it.getString(it.getColumnIndex(OpenableColumns.DISPLAY_NAME))
            Log.i(TAG, "Display Name: $displayName")

            val sizeIndex: Int = it.getColumnIndex(OpenableColumns.SIZE)
            // If the size is unknown, the value stored is null. But because an
            // int can't be null, the behavior is implementation-specific,
            // and unpredictable. So as
            // a rule, check if it's null before assigning to an int. This will
            // happen often: The storage API allows for remote files, whose
            // size might not be locally known.
            val size: String = if (!it.isNull(sizeIndex)) {
                // Technically the column stores an int, but cursor.getString()
                // will do the conversion automatically.
                it.getString(sizeIndex)
            } else {
                "Unknown"
            }
            Log.i(TAG, "Size: $size")
        }
    }
}

Java

public void dumpImageMetaData(Uri uri) {

    // The query, because it only applies to a single document, returns only
    // one row. There's no need to filter, sort, or select fields,
    // because we want all fields for one document.
    Cursor cursor = getActivity().getContentResolver()
            .query(uri, null, null, null, null, null);

    try {
        // moveToFirst() returns false if the cursor has 0 rows. Very handy for
        // "if there's anything to look at, look at it" conditionals.
        if (cursor != null && cursor.moveToFirst()) {

            // Note it's called "Display Name". This is
            // provider-specific, and might not necessarily be the file name.
            String displayName = cursor.getString(
                    cursor.getColumnIndex(OpenableColumns.DISPLAY_NAME));
            Log.i(TAG, "Display Name: " + displayName);

            int sizeIndex = cursor.getColumnIndex(OpenableColumns.SIZE);
            // If the size is unknown, the value stored is null. But because an
            // int can't be null, the behavior is implementation-specific,
            // and unpredictable. So as
            // a rule, check if it's null before assigning to an int. This will
            // happen often: The storage API allows for remote files, whose
            // size might not be locally known.
            String size = null;
            if (!cursor.isNull(sizeIndex)) {
                // Technically the column stores an int, but cursor.getString()
                // will do the conversion automatically.
                size = cursor.getString(sizeIndex);
            } else {
                size = "Unknown";
            }
            Log.i(TAG, "Size: " + size);
        }
    } finally {
        cursor.close();
    }
}

Bir doküman açın

Bir dokümanın URI'sına referans vererek dokümanı daha fazla işlenmesi için açabilirsiniz. Bu bölümde, bit eşlem ve giriş akışı açmaya ilişkin örnekler gösterilmektedir.

Bit eşlem

Aşağıdaki kod snippet'inde, Bitmap dosyasının URI'si belirtilerek nasıl açılacağı gösterilmektedir:

Kotlin

val contentResolver = applicationContext.contentResolver

@Throws(IOException::class)
private fun getBitmapFromUri(uri: Uri): Bitmap {
    val parcelFileDescriptor: ParcelFileDescriptor =
            contentResolver.openFileDescriptor(uri, "r")
    val fileDescriptor: FileDescriptor = parcelFileDescriptor.fileDescriptor
    val image: Bitmap = BitmapFactory.decodeFileDescriptor(fileDescriptor)
    parcelFileDescriptor.close()
    return image
}

Java

private Bitmap getBitmapFromUri(Uri uri) throws IOException {
    ParcelFileDescriptor parcelFileDescriptor =
            getContentResolver().openFileDescriptor(uri, "r");
    FileDescriptor fileDescriptor = parcelFileDescriptor.getFileDescriptor();
    Bitmap image = BitmapFactory.decodeFileDescriptor(fileDescriptor);
    parcelFileDescriptor.close();
    return image;
}

Not: Bu işlemi kullanıcı arayüzü iş parçacığında değil, arka plan iş parçacığında tamamlamanız gerekir.

Bit eşlemi açtıktan sonra ImageView içinde görüntüleyebilirsiniz.

Giriş akışı

Aşağıdaki kod snippet'i, URI'sına sahip bir InputStream nesnesinin nasıl açılacağını göstermektedir. Bu snippet'te, dosyanın satırları bir dizeye okunmaktadır:

Kotlin

val contentResolver = applicationContext.contentResolver

@Throws(IOException::class)
private fun readTextFromUri(uri: Uri): String {
    val stringBuilder = StringBuilder()
    contentResolver.openInputStream(uri)?.use { inputStream ->
        BufferedReader(InputStreamReader(inputStream)).use { reader ->
            var line: String? = reader.readLine()
            while (line != null) {
                stringBuilder.append(line)
                line = reader.readLine()
            }
        }
    }
    return stringBuilder.toString()
}

Java

private String readTextFromUri(Uri uri) throws IOException {
    StringBuilder stringBuilder = new StringBuilder();
    try (InputStream inputStream =
            getContentResolver().openInputStream(uri);
            BufferedReader reader = new BufferedReader(
            new InputStreamReader(Objects.requireNonNull(inputStream)))) {
        String line;
        while ((line = reader.readLine()) != null) {
            stringBuilder.append(line);
        }
    }
    return stringBuilder.toString();
}

Doküman düzenleme

Yerinde bir metin dokümanını düzenlemek için Depolama Erişim Çerçevesi'ni kullanabilirsiniz.

Not: DocumentFile sınıfının canWrite() yöntemi, uygulamanızın bir dokümanı düzenleyebileceği anlamına gelmez. Bunun nedeni, Document.COLUMN_FLAGS FLAG_SUPPORTS_DELETE veya FLAG_SUPPORTS_WRITE değerini içeriyorsa bu yöntemin true değerini döndürmesidir. Uygulamanızın belirli bir dokümanı düzenleyip düzenleyemeyeceğini belirlemek için doğrudan FLAG_SUPPORTS_WRITE değerini sorgulayın.

Aşağıdaki kod snippet'i, belirtilen URI tarafından temsil edilen belge içeriğinin üzerine yazar:

Kotlin

val contentResolver = applicationContext.contentResolver

private fun alterDocument(uri: Uri) {
    try {
        contentResolver.openFileDescriptor(uri, "w")?.use {
            FileOutputStream(it.fileDescriptor).use {
                it.write(
                    ("Overwritten at ${System.currentTimeMillis()}\n")
                        .toByteArray()
                )
            }
        }
    } catch (e: FileNotFoundException) {
        e.printStackTrace()
    } catch (e: IOException) {
        e.printStackTrace()
    }
}

Java

private void alterDocument(Uri uri) {
    try {
        ParcelFileDescriptor pfd = getActivity().getContentResolver().
                openFileDescriptor(uri, "w");
        FileOutputStream fileOutputStream =
                new FileOutputStream(pfd.getFileDescriptor());
        fileOutputStream.write(("Overwritten at " + System.currentTimeMillis() +
                "\n").getBytes());
        // Let the document provider know you're done by closing the stream.
        fileOutputStream.close();
        pfd.close();
    } catch (FileNotFoundException e) {
        e.printStackTrace();
    } catch (IOException e) {
        e.printStackTrace();
    }
}

Doküman silme

Bir dokümanın URI'sına sahipseniz ve dokümanın Document.COLUMN_FLAGS içeriği SUPPORTS_DELETE içeriyorsa dokümanı silebilirsiniz. Örneğin:

Kotlin

DocumentsContract.deleteDocument(applicationContext.contentResolver, uri)

Java

DocumentsContract.deleteDocument(applicationContext.contentResolver, uri);

Eşdeğer bir medya URI'si al

getMediaUri() yöntemi, belirtilen belge sağlayıcı URI'sına eşdeğer bir medya mağazası URI'si sağlar. 2 URI aynı temel öğeye işaret eder. Medya mağazası URI'sini kullanarak paylaşılan depolama alanından medya dosyalarına daha kolay erişebilirsiniz.

Not: Bu yöntem herhangi bir yeni izin vermez. Uygulamanız, belirli bir belge sağlayıcı URI'sine erişmek için gerekli izinlere (ör. dokümanı açma) sahip olmalıdır.

getMediaUri() yöntemi ExternalStorageProvider URI'larını destekler. Bu yöntem, Android 12 (API düzeyi 31) ve sonraki sürümlerde MediaDocumentsProvider URI'lerini de destekler.

Sanal dosya açma

Android 7.0 (API düzeyi 25) ve daha yeni sürümlerde uygulamanız, Depolama Erişim Çerçevesi'nin sunduğu sanal dosyalardan yararlanabilir. Sanal dosyalarda ikili gösterim bulunmasa da uygulamanız, dosyaları farklı bir dosya türüne zorlayarak veya ACTION_VIEW intent işlemini kullanarak bu dosyaları görüntüleyerek açabilir.

Sanal dosyaları açmak için istemci uygulamanızın bunları işleyecek özel bir mantık içermesi gerekir. Dosyanın bayt gösterimini almak istiyorsanız (örneğin, dosyayı önizlemek için) doküman sağlayıcıdan alternatif bir MIME türü istemeniz gerekir.

Not: Bir uygulama openInputStream() yöntemini kullanarak sanal bir dosyayı doğrudan açamayacağından, ACTION_OPEN_DOCUMENT veya ACTION_OPEN_DOCUMENT_TREE işlemini içeren amaç oluştururken CATEGORY_OPENABLE kategorisini kullanmayın.

Kullanıcı bir seçim yaptıktan sonra, aşağıdaki kod snippet'inde gösterildiği gibi, dosyanın sanal olup olmadığını belirlemek için sonuç verilerindeki URI'yı kullanın:

Kotlin

private fun isVirtualFile(uri: Uri): Boolean {
    if (!DocumentsContract.isDocumentUri(this, uri)) {
        return false
    }

    val cursor: Cursor? = contentResolver.query(
            uri,
            arrayOf(DocumentsContract.Document.COLUMN_FLAGS),
            null,
            null,
            null
    )

    val flags: Int = cursor?.use {
        if (cursor.moveToFirst()) {
            cursor.getInt(0)
        } else {
            0
        }
    } ?: 0

    return flags and DocumentsContract.Document.FLAG_VIRTUAL_DOCUMENT != 0
}

Java

private boolean isVirtualFile(Uri uri) {
    if (!DocumentsContract.isDocumentUri(this, uri)) {
        return false;
    }

    Cursor cursor = getContentResolver().query(
        uri,
        new String[] { DocumentsContract.Document.COLUMN_FLAGS },
        null, null, null);

    int flags = 0;
    if (cursor.moveToFirst()) {
        flags = cursor.getInt(0);
    }
    cursor.close();

    return (flags & DocumentsContract.Document.FLAG_VIRTUAL_DOCUMENT) != 0;
}

Dokümanın sanal bir dosya olduğunu doğruladıktan sonra, dosyayı "image/png" gibi alternatif bir MIME türüne zorlayabilirsiniz. Aşağıdaki kod snippet'i, sanal bir dosyanın resim olarak temsil edilip edilemeyeceğinin nasıl kontrol edileceğini ve uygunsa sanal dosyadan giriş akışı aldığını gösterir:

Kotlin

@Throws(IOException::class)
private fun getInputStreamForVirtualFile(
        uri: Uri, mimeTypeFilter: String): InputStream {

    val openableMimeTypes: Array<String>? =
            contentResolver.getStreamTypes(uri, mimeTypeFilter)

    return if (openableMimeTypes?.isNotEmpty() == true) {
        contentResolver
                .openTypedAssetFileDescriptor(uri, openableMimeTypes[0], null)
                .createInputStream()
    } else {
        throw FileNotFoundException()
    }
}

Java

private InputStream getInputStreamForVirtualFile(Uri uri, String mimeTypeFilter)
    throws IOException {

    ContentResolver resolver = getContentResolver();

    String[] openableMimeTypes = resolver.getStreamTypes(uri, mimeTypeFilter);

    if (openableMimeTypes == null ||
        openableMimeTypes.length < 1) {
        throw new FileNotFoundException();
    }

    return resolver
        .openTypedAssetFileDescriptor(uri, openableMimeTypes[0], null)
        .createInputStream();
}

Ek kaynaklar

Belgeleri ve diğer dosyaları depolama ve bunlara erişme hakkında daha fazla bilgi için aşağıdaki kaynaklara başvurun.

Sana Özel

• ActionOpenDocument sayfasına GitHub'dan erişebilirsiniz.
• ActionOpenDocumentTree (GitHub'da).

Videolar

• Kısıtlı Depolama için hazırlanma (Android Dev Summit '19)