SysDirExternalStorage (Function)

ONLINE HELP
WINDEV, WEBDEV AND WINDEV MOBILE

Version:

Home | Sign in | English

Windows management functions

System functions

SysDirExternalStorage

Presentation

Example

Existence and availability

Managing the files and their location

See also

SysDirExternalStorage (Function)

In french: SysRepStockageExterne

Returns the path of directory that will be used to store files in the external storage space of Android device.

Starting with Android 11, new restrictions appear for the locations accessible to applications. For more details on authorized locations, consult Android 11: Changes in the behavior of applications.

Example

// Enregistrement d'une photo dans le répertoire de l'application
// sur l'espace de stockage externe primaire de l'application
sPhoto est une chaîne = VidéoLanceAppli(viCaptureImage)
SI sPhoto <> "" _ET_ SysEtatStockageExterne(1) = sseDisponible ALORS
fCopieFichier(sPhoto, SysRepStockageExterne(1, sseAppPhoto))
FIN

Syntax

<Result> = SysDirExternalStorage(<Subscript> , <Type>)

<Result>: Character string

Path of specified directory.
Empty string ("") if an error occurred.

<Subscript>: entier

Subscript of external storage space to use (if the device includes several external storage spaces).
Remark: SysNbExternalStorage returns the number of external storage spaces found on the device.

<Type>: Integer constant

Path of directory for which the path on the external storage is searched. This parameter can correspond to one of the following constants:
sseAppDocument Directory of application documents.
sseAppFile Directory of files specific to the application.
sseAppMusic Directory of musical files of application.
sseAppPhoto Directory of application photos.
sseAppDownload Directory of files downloaded by the application.
sseAppVideo Directory of application videos.
ssePublic Root directory of external storage space.
ssePublicDocument Directory of shared documents.
ssePublicMusic Directory of shared musical files.
ssePublicPhoto Directory of shared photos.
ssePublicDownload Directory of shared downloaded files.
ssePublicVideo Directory of shared videos.

Remarks

Existence and availability

The directory corresponding to the path returned by SysDirExternalStorage may not exist. You must check its existence with fDirExist and/or create it with fMakeDir.
Before accessing a directory located in the external storage area of the device, it is recommended to test its availability with the SysStatusExternalStorage function.

Managing the files and their location

The application files that must not be shared with other applications must be stored in the application directory on the internal storage space of application. The path of the different subdirectories can be known with the functions fCurrentDir, fExeDir, fDataDir and fCacheDir.
When uninstalling the application, the files that group the following characteristics will be automatically deleted by the system:
- The files found in the application directory on the external storage space
- the files corresponding to the sseAppFile, sseAppMusic, sseAppVideo, sseAppPhoto, seeAppDownload and sseAppDocument constants.
The shared files of the external storage space correspondin to the ssePublic, ssePublicVideo, ssePublicMusic , ssePublicPhoto, ssePublicDocument and ssePublicDownload constants are regularly scanned by the system to be listed. Then, the photos for example are displayed in the albums of the device. These files will not be deleted when uninstalling the application.
The files found on the external storage space are accessible in read/write by all the applications.
From Android 4.4 (KitKat), if the external storage space corresponds to moveable memory (SDCard), the applications can create, modify or delete files in their own directory only (directories corresponding to the sseAppXXX constants). The other files found in the external storage space are accessible in read-only.
Starting with Android 10, an application must only access files in application directories. Any attempt to access files outside of these directories (in read or write mode) may fail.. It is recommended not to use ssePublicxxx constants to avoid errors.
Remark: For Android applications used under Android 10 and generated with WINDEV Mobile, the operation is unchanged (if you use the patch 118661 or the version 250Update 4 of WINDEV Mobile).
When the application is used on a device that runs Android 11, new restrictions appear:
- applications can no longer read or write files to the external storage outside of:
  - public directories such as "Documents", "Download", "Images", etc.: use SysDirExternalStorage with ssePublicXXX constants.
  - app-specific directories: use SysDirExternalStorage with sseAppXXX constants.
- in public directories, applications can only access (read or write) files they have created.
  Remark: if the application is uninstalled and then reinstalled, it will no longer have access to files created by the version previously installed in the public directories of the external storage.

Component: wd260android.jar