Provides access to a document on Android devices. More...

#include "juce_AndroidDocument.h"

Classes
struct	NativeInfo

class	Pimpl

struct	Utils

Public Member Functions
	AndroidDocument ()
	Create a null document.

	AndroidDocument (const AndroidDocument &)

	AndroidDocument (AndroidDocument &&) noexcept

AndroidDocument &	operator= (const AndroidDocument &)

AndroidDocument &	operator= (AndroidDocument &&) noexcept

bool	operator== (const AndroidDocument &) const
	True if the URLs of the two documents match.

bool	operator!= (const AndroidDocument &) const
	False if the URLs of the two documents match.

bool	deleteDocument () const
	Attempts to delete this document, and returns true on success.

bool	renameTo (const String &newDisplayName)
	Renames the document, and returns true on success.

AndroidDocument	createChildDocumentWithTypeAndName (const String &type, const String &name) const
	Attempts to create a new nested document with a particular type and name.

AndroidDocument	createChildDirectory (const String &name) const
	Attempts to create a new nested directory with a particular name.

bool	hasValue () const
	True if this object actually refers to a document.

	operator bool () const
	Like hasValue(), but allows declaring AndroidDocument instances directly in 'if' statements.

std::unique_ptr< InputStream >	createInputStream () const
	Creates a stream for reading from this document.

std::unique_ptr< OutputStream >	createOutputStream () const
	Creates a stream for writing to this document.

URL	getUrl () const
	Returns the content URL describing this document.

AndroidDocumentInfo	getInfo () const
	Fetches information about this document.

AndroidDocument	copyDocumentToParentDocument (const AndroidDocument &target) const
	Experimental: Attempts to copy this document to a new parent, and returns an AndroidDocument representing the copy.

bool	moveDocumentFromParentToParent (const AndroidDocument &currentParent, const AndroidDocument &newParent)
	Experimental: Attempts to move this document from one parent to another, and returns true on success.

NativeInfo	getNativeInfo () const

Static Public Member Functions
static AndroidDocument	fromFile (const File &filePath)
	Create an AndroidDocument representing a file or directory at a particular path.

static AndroidDocument	fromDocument (const URL &documentUrl)
	Create an AndroidDocument representing a single document.

static AndroidDocument	fromTree (const URL &treeUrl)
	Create an AndroidDocument representing the root of a tree of files.

Detailed Description

Provides access to a document on Android devices.

In this context, a 'document' may be a file or a directory.

The main purpose of this class is to provide access to files in shared storage on Android. On newer Android versions, such files cannot be accessed directly by a file path, and must instead be read and modified using a new URI-based DocumentsContract API.

Example use-cases:

After showing the system open dialog to allow the user to open a file, pass the FileChooser's URL result to AndroidDocument::fromDocument. Then, you can use getInfo() to retrieve information about the file, and createInputStream to read from the file. Other functions allow moving, copying, and deleting the file.
Similarly to the 'open' use-case, you may use createOutputStream to write to a file, normally located using the system save dialog.
To allow reading or writing to a tree of files in shared storage, you can show the system open dialog in 'selects directories' mode, and pass the resulting URL to AndroidDocument::fromTree. Then, you can iterate the files in the directory, query them, and create new files. This is a good way to store multiple files that the user can access from other apps, and that will be persistent after uninstalling and reinstalling your app.

Note that you probably do not need this class if your app only needs to access files in its own internal sandbox. juce::File instances should work as expected in that case.

AndroidDocument is a bit like the DocumentFile class from the androidx extension library, in that it represents a single document, and is implemented using DocumentsContract functions.

@tags{Core}

Definition at line 241 of file juce_AndroidDocument.h.

Class Documentation

◆ juce::AndroidDocument::NativeInfo

struct juce::AndroidDocument::NativeInfo

Definition at line 33 of file juce_AndroidDocument_android.cpp.

Constructor & Destructor Documentation

◆ AndroidDocument()

juce::AndroidDocument::AndroidDocument ( const AndroidDocument & other )

Definition at line 875 of file juce_AndroidDocument_android.cpp.

Member Function Documentation

◆ copyDocumentToParentDocument()

AndroidDocument juce::AndroidDocument::copyDocumentToParentDocument ( const AndroidDocument & target ) const

Experimental: Attempts to copy this document to a new parent, and returns an AndroidDocument representing the copy.

On failure, the returned AndroidDocument may be invalid, and will return false from hasValue().

This function may fail if the document doesn't allow copying, and when using URI-based documents on devices with API level 23 or lower. On failure, the returned AndroidDocument will return false from hasValue(). In testing, copying was not supported on the Android emulator for API 24, 30, or 31, so there's a good chance this function won't work on real devices.

See also: AndroidDocumentInfo::canCopy

Definition at line 908 of file juce_AndroidDocument_android.cpp.

◆ createChildDirectory()

AndroidDocument juce::AndroidDocument::createChildDirectory ( const String & name ) const

Attempts to create a new nested directory with a particular name.

On failure, the returned AndroidDocument may be invalid, and will return false from hasValue().

Definition at line 921 of file juce_AndroidDocument_android.cpp.

◆ createChildDocumentWithTypeAndName()

AndroidDocument juce::AndroidDocument::createChildDocumentWithTypeAndName	(	const String &	type,
		const String &	name
	)		const

Attempts to create a new nested document with a particular type and name.

The type should be a standard MIME type string, e.g. "image/png", "text/plain".

The file name doesn't need to contain an extension, as this information is passed via the type argument. If this document is File-based rather than URL-based, then an appropriate file extension will be chosen based on the MIME type.

On failure, the returned AndroidDocument may be invalid, and will return false from hasValue().

Definition at line 914 of file juce_AndroidDocument_android.cpp.

◆ createInputStream()

std::unique_ptr< InputStream > juce::AndroidDocument::createInputStream ( ) const

Creates a stream for reading from this document.

Definition at line 939 of file juce_AndroidDocument_android.cpp.

◆ createOutputStream()

std::unique_ptr< OutputStream > juce::AndroidDocument::createOutputStream ( ) const

Creates a stream for writing to this document.

Definition at line 945 of file juce_AndroidDocument_android.cpp.

◆ deleteDocument()

bool juce::AndroidDocument::deleteDocument ( ) const

Attempts to delete this document, and returns true on success.

Definition at line 893 of file juce_AndroidDocument_android.cpp.

◆ fromDocument()

AndroidDocument juce::AndroidDocument::fromDocument ( const URL & documentUrl )

static

Create an AndroidDocument representing a single document.

The argument should be a URL representing a document. Such URLs are returned by the system file-picker when it is not in folder-selection mode. If you pass a tree URL, this function will fail.

This function may fail on Android devices with API level 18 or lower, and on non-Android platforms. If this function fails, hasValue() will return false on the returned document. If calling this function fails, you may want to retry creating an AndroidDocument with fromFile(), passing the result of URL::getLocalFile().

Definition at line 815 of file juce_AndroidDocument_android.cpp.

◆ fromFile()

AndroidDocument juce::AndroidDocument::fromFile ( const File & filePath )

static

Create an AndroidDocument representing a file or directory at a particular path.

This is provided for use on older API versions (lower than 19), or on other platforms, so that the same AndroidDocument API can be used regardless of the runtime platform version.

If the runtime platform version is 19 or higher, and you wish to work with a URI obtained from a native file picker, use fromDocument() or fromTree() instead.

If this function fails, hasValue() will return false on the returned document.

Definition at line 799 of file juce_AndroidDocument_android.cpp.

◆ fromTree()

AndroidDocument juce::AndroidDocument::fromTree ( const URL & treeUrl )

static

Create an AndroidDocument representing the root of a tree of files.

The argument should be a URL representing a tree. Such URLs are returned by the system file-picker when it is in folder-selection mode. If you pass a URL referring to a document inside a tree, this will return a document referring to the root of the tree. If you pass a URL referring to a single file, this will fail.

When targeting platform version 30 or later, access to the filesystem via file paths is heavily restricted, and access to shared storage must use a new URI-based system instead. At time of writing, apps uploaded to the Play Store must target API 30 or higher. If you want read/write access to a shared folder, you must:

Use a native FileChooser in canSelectDirectories mode, to allow the user to select a folder that your app can access. Your app will only have access to the contents of this directory; it cannot escape to the filesystem root. The system will not allow the user to grant access to certain locations, including filesystem roots and the Download folder.
Pass the URI that the user selected to fromTree(), and use the resulting AndroidDocument to read/write to the file system.

This function may fail on Android devices with API level 20 or lower, and on non-Android platforms. If this function fails, hasValue() will return false on the returned document.

Definition at line 841 of file juce_AndroidDocument_android.cpp.

◆ getInfo()

AndroidDocumentInfo juce::AndroidDocument::getInfo ( ) const

Fetches information about this document.

Definition at line 957 of file juce_AndroidDocument_android.cpp.

◆ getNativeInfo()

AndroidDocument::NativeInfo juce::AndroidDocument::getNativeInfo ( ) const

Definition at line 973 of file juce_AndroidDocument_android.cpp.

◆ getUrl()

URL juce::AndroidDocument::getUrl ( ) const

Returns the content URL describing this document.

Definition at line 951 of file juce_AndroidDocument_android.cpp.

◆ hasValue()

bool juce::AndroidDocument::hasValue ( ) const

True if this object actually refers to a document.

If this function returns false, you must not call any function on this instance other than the special member functions to copy, move, and/or destruct the instance.

Definition at line 344 of file juce_AndroidDocument.h.

◆ moveDocumentFromParentToParent()

bool juce::AndroidDocument::moveDocumentFromParentToParent	(	const AndroidDocument &	currentParent,
		const AndroidDocument &	newParent
	)

Experimental: Attempts to move this document from one parent to another, and returns true on success.

This may cause the document's URI and metadata to change, so ensure to invalidate any cached information about the document (URLs, AndroidDocumentInfo instances) after calling this function.

This function may fail if the document doesn't allow moving, and when using URI-based documents on devices with API level 23 or lower.

Definition at line 926 of file juce_AndroidDocument_android.cpp.

◆ operator bool()

juce::AndroidDocument::operator bool ( ) const

explicit

Like hasValue(), but allows declaring AndroidDocument instances directly in 'if' statements.

Definition at line 347 of file juce_AndroidDocument.h.

◆ operator!=()

bool juce::AndroidDocument::operator!= ( const AndroidDocument & other ) const

False if the URLs of the two documents match.

Definition at line 968 of file juce_AndroidDocument_android.cpp.

◆ operator=()

AndroidDocument & juce::AndroidDocument::operator= ( const AndroidDocument & other )

Definition at line 883 of file juce_AndroidDocument_android.cpp.

◆ operator==()

bool juce::AndroidDocument::operator== ( const AndroidDocument & other ) const

True if the URLs of the two documents match.

Definition at line 963 of file juce_AndroidDocument_android.cpp.

◆ renameTo()

bool juce::AndroidDocument::renameTo ( const String & newDisplayName )

Renames the document, and returns true on success.

This may cause the document's URI and metadata to change, so ensure to invalidate any cached information about the document (URLs, AndroidDocumentInfo instances) after calling this function.

Definition at line 895 of file juce_AndroidDocument_android.cpp.

The documentation for this class was generated from the following files:

juce_core/files/juce_AndroidDocument.h
juce_core/native/juce_AndroidDocument_android.cpp

Classes

Public Member Functions

Static Public Member Functions

Detailed Description

Class Documentation

◆ juce::AndroidDocument::NativeInfo

Constructor & Destructor Documentation

◆ AndroidDocument()

Member Function Documentation

◆ copyDocumentToParentDocument()

◆ createChildDirectory()

◆ createChildDocumentWithTypeAndName()

◆ createInputStream()

◆ createOutputStream()

◆ deleteDocument()

◆ fromDocument()

◆ fromFile()

◆ fromTree()

◆ getInfo()

◆ getNativeInfo()

◆ getUrl()

◆ hasValue()

◆ moveDocumentFromParentToParent()

◆ operator bool()

◆ operator!=()

◆ operator=()

◆ operator==()

◆ renameTo()