belongs to Maven artifact com.android.support:documentfile:28.0.0-alpha1
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 |
static
DocumentFile
|
fromFile(File file)
Create a |
static
DocumentFile
|
fromSingleUri(Context context, Uri singleUri)
Create a |
static
DocumentFile
|
fromTreeUri(Context context, Uri treeUri)
Create a |
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
|
|