Docs:Android: Add docs notes about support for content Uris

Add some details about the support of Qt apis (QFile, QDir, QFileInfo)
for Android content uris.

Fixes: QTBUG-99664
Task-number: QTBUG-98974
Change-Id: I4b884623702ccad116d47049e34ccddfe21f83ca
Reviewed-by: Nicholas Bennett <nicholas.bennett@qt.io>
(cherry picked from commit a0ca5f433fdc45e97e461ece2d9839eebd3c7ea0)
Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>
This commit is contained in:
Nicholas Bennett 2022-10-05 15:51:25 +03:00 committed by Assam Boudjelthia
parent 481f1e1a75
commit 7253f6cac0
5 changed files with 59 additions and 0 deletions

View File

@ -82,6 +82,36 @@
\title Android: Keeping your app responsive
*/
/*!
\externalpage https://developer.android.com/training/data-storage/shared/documents-files
\title Android: Access documents and other files from shared storage
*/
/*!
\externalpage https://developer.android.com/reference/androidx/documentfile/provider/DocumentFile#getParentFile()
\title Android: DocumentFile.getParentFile()
*/
/*!
\externalpage https://developer.android.com/guide/topics/providers/content-provider-basics#ContentURIs
\title Android: Content URIs
*/
/*!
\externalpage https://developer.android.com/training/data-storage#scoped-storage
\title Android: Scoped storage
*/
/*!
\externalpage https://developer.android.com/training/data-storage/use-cases
\title Android: storage best practices
*/
/*!
\externalpage https://developer.android.com/reference/android/provider/MediaStore
\title Android: MediaStore
*/
/*!
\externalpage https://cmake.org/cmake/help/latest/module/GNUInstallDirs.html
\title GNUInstallDirs

View File

@ -0,0 +1,13 @@
On Android, some limitations apply when dealing with
\l {Android: Content URIs}{content URIs}:
\list
\li Access permissions might be needed by prompting the user through the
\l QFileDialog which implements
\l {Access documents and other files from shared storage}{Android's native file picker}.
\li Aim to follow the \l {Android: Scoped storage}{Scoped storage} guidelines,
such as using app specific directories instead of other public external directories.
For more information, also see
\l {Android: storage best practices}{storage best practices}.
\li Due to the design of Qt APIs (e.g. QFile), it's not possible to fully
integrate the latter APIs with Android's \l {Android: MediaStore}{MediaStore} APIs.
\endlist

View File

@ -507,6 +507,10 @@ inline void QDirPrivate::initFileEngine()
\snippet qdir-listfiles/main.cpp 0
\section1 Platform Specific Issues
\include android-content-uri-limitations.qdocinc
\sa QFileInfo, QFile, QFileDialog, QCoreApplication::applicationDirPath(), {Find Files Example}
*/
@ -990,6 +994,9 @@ bool QDir::cd(const QString &dirName)
otherwise returns \c false. Note that the logical cdUp() operation is
not performed if the new directory does not exist.
\note On Android, this is not supported for content URIs. For more information,
see \l {Android: DocumentFile.getParentFile()}{DocumentFile.getParentFile()}.
\sa cd(), isReadable(), exists(), path()
*/
bool QDir::cdUp()

View File

@ -192,6 +192,8 @@ QAbstractFileEngine *QFilePrivate::engine() const
function mostly useless for NTFS volumes. It may still be of use for USB
sticks that use VFAT file systems. POSIX ACLs are not manipulated, either.
\include android-content-uri-limitations.qdocinc
\sa QTextStream, QDataStream, QFileInfo, QDir, {The Qt Resource System}
*/
@ -857,6 +859,9 @@ QFile::copy(const QString &fileName, const QString &newName)
will try to create a new file before opening it. The file will be
created with mode 0666 masked by the umask on POSIX systems, and
with permissions inherited from the parent directory on Windows.
On Android, it's expected to have access permission to the parent
of the file name, otherwise, it won't be possible to create this
non-existing file.
\sa QIODevice::OpenMode, setFileName()
*/

View File

@ -290,6 +290,10 @@ QDateTime &QFileInfoPrivate::getFileTime(QAbstractFileEngine::FileTime request)
If you want to make sure that all information is read from the
file system, use stat().
\section1 Platform Specific Issues
\include android-content-uri-limitations.qdocinc
\sa QDir, QFile
*/