Function

Summary

Gets the path of a special folder.

Package

system

Signature

get-folder-path what &key create => result

Arguments

what

A keyword.

create

A boolean.

Values

result

A directory pathname naming the path, or nil.

Description

The function get-folder-path obtains the current value for various special folders often used by applications. It is useful because these paths may differ between versions of the operating system. get-folder-path is implemented all platforms, using system APIs on Microsoft Windows, Mac OS X and Android.

On platforms other than Windows, Mac OS X and Android it is a dummy function, which makes a path to a directory inside the user's home directory that looks like <homedir>/get-folder-path/<symbol-name-downcased>. This allows testing code that uses get-folder-path to work in the sense that files can be written and read from these directories.

what indicates the purpose of the special folder. For instance, :common-appdata means the folder containing application data for all users.

The following values of what are recognized on Microsoft Windows and Mac OS X:

:appdata, :documents, :my-documents, :common-appdata, :common-documents and :local-appdata.

:documents is an alias for :my-documents.

The following values are recognized on Microsoft Windows only: :program-files, :programs and :common-programs.

The following values are recognized on Mac OS X only:

:my-library, :my-appsupport, :my-preferences, :my-caches, :my-logs, :common-library, :common-appsupport, :common-preferences, :common-caches, :common-logs, :system-library.

On Mac OS X, :appdata is an alias for :my-appsupport, :common-appdata is an alias for :common-appsupport, and :local-appdata is an alias for :common-appsupport.

If the folder does not exist and create is true, the folder is created. If the folder does not exist and create is false, result is nil. The default value of create is false.

The following values of what are recognized on Android:

:appdata, :local-appdata

Both of these return the same directory. It is the directory which is returned by the getFilesDir on the application context. Note that this is a private directory, not visible to other applications.

:my-documents, :documents

On Android 4.4 and later this returns the "documents" directory in the "public external" directory (the result of calling "android.os.Environment.getExternalStoragePublicDirectory" with the value of android.os.Environment.DIRECTORY_DOCUMENTS). In previous versions it uses the "downloads" directory, because there does not seem to be another useful place for it.

Note: This is used as the home directory on Android, that is what cl:user-homedir-pathname returns.

:alarms, :dcim, :downloads, :movies, :music, :notifications, :pictures, :podcasts, :ringtones

Return the matching directory in the "public external" directory. This is the result of calling "android.os.Environment.getExternalStoragePublicDirectory" with the value of android.os.Environment.DIRECTORY_<symbol-name>, where symbol-name is the symbol name of the keyword), for example android.os.Environment.DIRECTORY_RINGTONES.

:common-appdata

Returns the external storage directory of the application if it is accessible, otherwise returns nil. The external storage directory is the result of calling getExternalFilesDir on the application context with null.

Note that the application will need permission to access the external storage, by having uses-permission android.permission.WRITE_EXTERNAL_STORAGE or android.permission.READ_EXTERNAL_STORAGE in the AndroidManifest.xml file.

Compatibility notes

1. In LispWorks 6.1 and earlier versions, get-folder-path is implemented only on Windows and Mac OS X.
2. In LispWorks 5.0 and previous versions, get-folder-path returns a string.

Example

This form constructs a pathname to a file foo.lisp in the user's documents directory:

(make-pathname 

 :name "foo" 

 :type "lisp" 

 :defaults

 (sys:get-folder-path :my-documents))

See also

get-user-profile-directory