DocumentFile

abstract class DocumentFile

kotlin.Any
↳	androidx.documentfile.provider.DocumentFile

Representation of a document backed by either a android.provider.DocumentsProvider or a raw file on disk. This is a utility class designed to emulate the traditional File interface. It offers a simplified view of a tree of documents, but it has substantial overhead. For optimal performance and a richer feature set, use the android.provider.DocumentsContract methods and constants directly.

There are several differences between documents and traditional files:

Documents express their display name and MIME type as separate fields, instead of relying on file extensions. Some documents providers may still choose to append extensions to their display names, but that's an implementation detail.
A single document may appear as the child of multiple directories, so it doesn't inherently know who its parent is. That is, documents don't have a strong notion of path. You can easily traverse a tree of documents from parent to child, but not from child to parent.
Each document has a unique identifier within that provider. This identifier is an opaque implementation detail of the provider, and as such it must not be parsed.

Before using this class, first consider if you really need access to an entire subtree of documents. The principle of least privilege dictates that you should only ask for access to documents you really need. If you only need the user to pick a single file, use Intent#ACTION_OPEN_DOCUMENT or Intent#ACTION_GET_CONTENT. If you want to let the user pick multiple files, add Intent#EXTRA_ALLOW_MULTIPLE. If you only need the user to save a single file, use Intent#ACTION_CREATE_DOCUMENT. If you use these APIs, you can pass the resulting Intent#getData() into fromSingleUri(Context, Uri) to work with that document.

If you really do need full access to an entire subtree of documents, start by launching Intent#ACTION_OPEN_DOCUMENT_TREE to let the user pick a directory. Then pass the resulting Intent#getData() into fromTreeUri(Context, Uri) to start working with the user selected tree.

As you navigate the tree of DocumentFile instances, you can always use getUri() to obtain the Uri representing the underlying document for that object, for use with ContentResolver#openInputStream(Uri), etc.

To simplify your code on devices running android.os.Build.VERSION_CODES#KITKAT or earlier, you can use fromFile(File) which emulates the behavior of a android.provider.DocumentsProvider.

Summary

Public methods
abstract Boolean	`canRead()` Indicates whether the current context is allowed to read from this file.
abstract Long	`length()` Returns the length of this file in bytes.
abstract String?	`getName()` Return the display name of this document.
abstract DocumentFile?	`createFile(@NonNull mimeType: String, @NonNull displayName: String)` Create a new document as a direct child of this directory.
abstract String?	`getType()` Return the MIME type of this document.
abstract Uri	`getUri()` Return a Uri for the underlying document represented by this file.
abstract Boolean	`isFile()` Indicates if this file represents a file.
abstract Boolean	`isVirtual()` Indicates if this file represents a virtual document.
abstract Boolean	`canWrite()` Indicates whether the current context is allowed to write to this file.
abstract Boolean	`isDirectory()` Indicates if this file represents a directory.
abstract Array<DocumentFile!>	`listFiles()` Returns an array of files contained in the directory represented by this file.
abstract Boolean	`renameTo(@NonNull displayName: String)` Renames this file to `displayName`.
open DocumentFile?	`findFile(@NonNull displayName: String)` Search through `listFiles()` for the first document matching the given display name.
open DocumentFile?	`getParentFile()` Return the parent file of this document.
abstract DocumentFile?	`createDirectory(@NonNull displayName: String)` Create a new directory as a direct child of this directory.
abstract Boolean	`exists()` Returns a boolean indicating whether this file can be found.
abstract Long	`lastModified()` Returns the time when this file was last modified, measured in milliseconds since January 1st, 1970, midnight.
abstract Boolean	`delete()` Deletes this file.
open static DocumentFile	`fromFile(@NonNull file: File)` Create a `DocumentFile` representing the filesystem tree rooted at the given `File`.
open static DocumentFile?	`fromSingleUri(@NonNull context: Context, @NonNull singleUri: Uri)` Create a `DocumentFile` representing the single document at the given `Uri`.
open static DocumentFile?	`fromTreeUri(@NonNull context: Context, @NonNull treeUri: Uri)` Create a `DocumentFile` representing the document tree rooted at the given `Uri`.
open static Boolean	`isDocumentUri(@NonNull context: Context, @Nullable uri: Uri?)` Test if given Uri is backed by a `android.provider.DocumentsProvider`.

Public methods

canRead

abstract fun canRead(): Boolean

Indicates whether the current context is allowed to read from this file.

Return
Boolean: `true` if this file can be read, `false` otherwise.

length

abstract fun length(): Long

Returns the length of this file in bytes. Returns 0 if the file does not exist, or if the length is unknown. The result for a directory is not defined.

Return
Long: the number of bytes in this file.

See Also

android.provider.DocumentsContract.Document#COLUMN_SIZE

getName

@Nullable abstract fun getName(): String?

Return the display name of this document.

See Also

android.provider.DocumentsContract.Document#COLUMN_DISPLAY_NAME

createFile

@Nullable abstract fun createFile(@NonNull mimeType: String, @NonNull displayName: String): DocumentFile?

Create a new document as a direct child of this directory.

Parameters
`mimeType`	String: MIME type of new document, such as `image/png` or `audio/flac`
`displayName`	String: name of new document, without any file extension appended; the underlying provider may choose to append the extension

Return
DocumentFile?: file representing newly created document, or null if failed

Exceptions
`UnsupportedOperationException`	when working with a single document created from `fromSingleUri(Context, Uri)`.

See Also

android.provider.DocumentsContract#createDocument(ContentResolver, * Uri, String, String)

getType

@Nullable abstract fun getType(): String?

Return the MIME type of this document.

See Also

android.provider.DocumentsContract.Document#COLUMN_MIME_TYPE

getUri

@NonNull abstract fun getUri(): Uri

Return a Uri for the underlying document represented by this file. This can be used with other platform APIs to manipulate or share the underlying content. You can use isDocumentUri(Context, Uri) to test if the returned Uri is backed by a android.provider.DocumentsProvider.

See Also

Intent#setData(Uri)Intent#setClipData(android.content.ClipData)ContentResolver#openInputStream(Uri)ContentResolver#openOutputStream(Uri)ContentResolver#openFileDescriptor(Uri, String)

isFile

abstract fun isFile(): Boolean

Indicates if this file represents a file.

Return
Boolean: `true` if this file is a file, `false` otherwise.

See Also

android.provider.DocumentsContract.Document#COLUMN_MIME_TYPE

isVirtual

abstract fun isVirtual(): Boolean

Indicates if this file represents a virtual document.

Return
Boolean: `true` if this file is a virtual document.

See Also

android.provider.DocumentsContract.Document#FLAG_VIRTUAL_DOCUMENT

canWrite

abstract fun canWrite(): Boolean

Indicates whether the current context is allowed to write to this file.

Return
Boolean: `true` if this file can be written, `false` otherwise.

See Also

android.provider.DocumentsContract.Document#COLUMN_FLAGSandroid.provider.DocumentsContract.Document#FLAG_SUPPORTS_DELETEandroid.provider.DocumentsContract.Document#FLAG_SUPPORTS_WRITEandroid.provider.DocumentsContract.Document#FLAG_DIR_SUPPORTS_CREATE

isDirectory

abstract fun isDirectory(): Boolean

Indicates if this file represents a directory.

Return
Boolean: `true` if this file is a directory, `false` otherwise.

See Also

android.provider.DocumentsContract.Document#MIME_TYPE_DIR

listFiles

@NonNull abstract fun listFiles(): Array<DocumentFile!>

Returns an array of files contained in the directory represented by this file.

Return
Array<DocumentFile!>: an array of files or `null`.

Exceptions
`UnsupportedOperationException`	when working with a single document created from `fromSingleUri(Context, Uri)`.

See Also

android.provider.DocumentsContract#buildChildDocumentsUriUsingTree(Uri, * String)

renameTo

abstract fun renameTo(@NonNull displayName: String): Boolean

Renames this file to displayName.

Note that this method does not throw IOException on failure. Callers must check the return value.

Some providers may need to create a new document to reflect the rename, potentially with a different MIME type, so getUri() and getType() may change to reflect the rename.

When renaming a directory, children previously enumerated through listFiles() may no longer be valid.

Parameters
`displayName`	String: the new display name.

Return
Boolean: true on success.

Exceptions
`UnsupportedOperationException`	when working with a single document created from `fromSingleUri(Context, Uri)`.

See Also

android.provider.DocumentsContract#renameDocument(ContentResolver, * Uri, String)

findFile

@Nullable open fun findFile(@NonNull displayName: String): DocumentFile?

Search through listFiles() for the first document matching the given display name. Returns null when no matching document is found.

Exceptions
`UnsupportedOperationException`	when working with a single document created from `fromSingleUri(Context, Uri)`.

getParentFile

@Nullable open fun getParentFile(): DocumentFile?

Return the parent file of this document. Only defined inside of the user-selected tree; you can never escape above the top of the tree.

The underlying android.provider.DocumentsProvider only defines a forward mapping from parent to child, so the reverse mapping of child to parent offered here is purely a convenience method, and it may be incorrect if the underlying tree structure changes.

createDirectory

@Nullable abstract fun createDirectory(@NonNull displayName: String): DocumentFile?

Create a new directory as a direct child of this directory.

Parameters
`displayName`	String: name of new directory

Return
DocumentFile?: file representing newly created directory, or null if failed

Exceptions
`UnsupportedOperationException`	when working with a single document created from `fromSingleUri(Context, Uri)`.

See Also

android.provider.DocumentsContract#createDocument(ContentResolver, * Uri, String, String)

exists

abstract fun exists(): Boolean

Returns a boolean indicating whether this file can be found.

Return
Boolean: `true` if this file exists, `false` otherwise.

lastModified

abstract fun lastModified(): Long

Returns the time when this file was last modified, measured in milliseconds since January 1st, 1970, midnight. Returns 0 if the file does not exist, or if the modified time is unknown.

Return
Long: the time when this file was last modified.

See Also

android.provider.DocumentsContract.Document#COLUMN_LAST_MODIFIED

delete

abstract fun delete(): Boolean

Deletes this file.

Note that this method does not throw IOException on failure. Callers must check the return value.

Return
Boolean: `true` if this file was deleted, `false` otherwise.

See Also

android.provider.DocumentsContract#deleteDocument(ContentResolver, * Uri)

fromFile

@NonNull open static fun fromFile(@NonNull file: File): DocumentFile

Create a DocumentFile representing the filesystem tree rooted at the given File. This doesn't give you any additional access to the underlying files beyond what your app already has.

getUri() will return file:// Uris for files explored through this tree.

fromSingleUri

@Nullable open static fun fromSingleUri(@NonNull context: Context, @NonNull singleUri: Uri): DocumentFile?

Create a DocumentFile representing the single document at the given Uri. This is only useful on devices running android.os.Build.VERSION_CODES#KITKAT or later, and will return null when called on earlier platform versions.

Parameters
`singleUri`	Context: the `Intent#getData()` from a successful `Intent#ACTION_OPEN_DOCUMENT` or `Intent#ACTION_CREATE_DOCUMENT` request.

fromTreeUri

@Nullable open static fun fromTreeUri(@NonNull context: Context, @NonNull treeUri: Uri): DocumentFile?

Create a DocumentFile representing the document tree rooted at the given Uri. This is only useful on devices running android.os.Build.VERSION_CODES#LOLLIPOP or later, and will return null when called on earlier platform versions.

Parameters
`treeUri`	Context: the `Intent#getData()` from a successful `Intent#ACTION_OPEN_DOCUMENT_TREE` request.

isDocumentUri

open static fun isDocumentUri(@NonNull context: Context, @Nullable uri: Uri?): Boolean

Test if given Uri is backed by a android.provider.DocumentsProvider.