| 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:
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.
| Public Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
Indicates whether the current context is allowed to read from this file.
| |||||||||||
Indicates whether the current context is allowed to write to this file.
| |||||||||||
Create a new directory as a direct child of this directory.
| |||||||||||
Create a new document as a direct child of this directory.
| |||||||||||
Deletes this file.
| |||||||||||
Returns a boolean indicating whether this file can be found.
| |||||||||||
Search through
listFiles() for the first document matching the
given display name.
| |||||||||||
Create a
DocumentFile representing the filesystem tree rooted at
the given Uri.
| |||||||||||
Create a
DocumentFile representing the single document at the
given Uri.
| |||||||||||
Create a
DocumentFile representing the document tree rooted at
the given Uri.
| |||||||||||
Return the display name of this document.
| |||||||||||
Return the parent file of this document.
| |||||||||||
Return the MIME type of this document.
| |||||||||||
Return a Uri for the underlying document represented by this file.
| |||||||||||
Indicates if this file represents a directory.
| |||||||||||
Test if given Uri is backed by a
DocumentsProvider.
| |||||||||||
Indicates if this file represents a file.
| |||||||||||
Returns the time when this file was last modified, measured in
milliseconds since January 1st, 1970, midnight.
| |||||||||||
Returns the length of this file in bytes.
| |||||||||||
Returns an array of files contained in the directory represented by this
file.
| |||||||||||
Renames this file to
displayName.
| |||||||||||
|
[Expand]
Inherited Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
| |||||||||||
Indicates whether the current context is allowed to read from this file.
Developers
true if this file can be read, false otherwise.
Indicates whether the current context is allowed to write to this file.
true if this file can be written, false
otherwise.Create a new directory as a direct child of this directory.
| displayName | name of new directory |
|---|
| UnsupportedOperationException | when working with a single document
created from fromSingleUri(Context, Uri). |
|---|
Create a new document as a direct child of this directory.
| mimeType | MIME type of new document, such as image/png or
audio/flac |
|---|---|
| displayName | name of new document, without any file extension appended; the underlying provider may choose to append the extension |
| UnsupportedOperationException | when working with a single document
created from fromSingleUri(Context, Uri). |
|---|
Deletes this file.
Note that this method does not throw IOException on
failure. Callers must check the return value.
true if this file was deleted, false otherwise.Returns a boolean indicating whether this file can be found.
true if this file exists, false otherwise.
Search through listFiles() for the first document matching the
given display name. Returns null when no matching document is
found.
| UnsupportedOperationException | when working with a single document
created from fromSingleUri(Context, Uri).
|
|---|
Create a DocumentFile representing the filesystem tree rooted at
the given Uri. 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.
Create a DocumentFile representing the single document at the
given Uri. This is only useful on devices running
KITKAT or later, and will return
null when called on earlier platform versions.
| singleUri | the getData() from a successful
ACTION_OPEN_DOCUMENT or
ACTION_CREATE_DOCUMENT request.
|
|---|
Create a DocumentFile representing the document tree rooted at
the given Uri. This is only useful on devices running
LOLLIPOP or later, and will return
null when called on earlier platform versions.
| treeUri | the getData() from a successful
ACTION_OPEN_DOCUMENT_TREE request.
|
|---|
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 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.
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
DocumentsProvider.
Indicates if this file represents a directory.
true if this file is a directory, false
otherwise.Test if given Uri is backed by a
DocumentsProvider.
Indicates if this file represents a file.
true if this file is a file, false otherwise.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.
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.
Returns an array of files contained in the directory represented by this file.
null.| UnsupportedOperationException | when working with a single document
created from fromSingleUri(Context, Uri). |
|---|
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.
| displayName | the new display name. |
|---|
| UnsupportedOperationException | when working with a single document
created from fromSingleUri(Context, Uri). |
|---|