added in version 22.1.0
belongs to Maven artifact com.android.support:documentfile:28.0.0-alpha1

Summary: Methods | Inherited Methods | [Expand All]

DocumentFile

public abstract class DocumentFile
extends Object

java.lang.Object
↳	android.support.v4.provider.DocumentFile

Representation of a document backed by either a 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 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 ACTION_OPEN_DOCUMENT or ACTION_GET_CONTENT. If you want to let the user pick multiple files, add EXTRA_ALLOW_MULTIPLE. If you only need the user to save a single file, use ACTION_CREATE_DOCUMENT. If you use these APIs, you can pass the resulting 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 ACTION_OPEN_DOCUMENT_TREE to let the user pick a directory. Then pass the resulting 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 openInputStream(Uri), etc.

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

See also:

Summary

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

Inherited methods

From class


  
    java.lang.Object

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

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

Parameters
`context`	`Context`
`treeUri`	`Uri`: the `getData()` from a successful `ACTION_OPEN_DOCUMENT_TREE` request.

DocumentFile

Summary

Public methods

Inherited methods

Public methods

canRead

canWrite

createDirectory

createFile

delete

exists

findFile

fromFile

fromSingleUri

fromTreeUri

getName

getParentFile

getType

getUri

isDirectory

isDocumentUri

isFile

isVirtual

lastModified

length

listFiles

renameTo

Classes