chrome.fileSystemProvider
Description: |
Use the chrome.fileSystemProvider API to create file systems,
that can be accessible from the file manager on Chrome OS.
|
Availability: |
Since Chrome 40.
|
Permissions: |
"fileSystemProvider"
|
Important: This API works only on Chrome OS.
Manifest
You must declare the "fileSystemProvider" permission and section in the extension manifest to use the File System Provider API. For example:
{
"name": "My extension",
...
"permissions": [
"fileSystemProvider"
],
...
"file_system_provider_capabilities": {
"configurable": true,
"watchable": false,
"multiple_mounts": true,
"source": "network"
},
...
}
The file_system_provider
section must be declared as follows:
-
configurable
(boolean) - optionalWhether configuring via
onConfigureRequested
is supported. By default:false
. -
multiple_mounts
(boolean) - optionalWhether multiple (more than one) mounted file systems are supported. By default:
false
. -
watchable
(boolean) - optionalWhether setting watchers and notifying about changes is supported. By default:
false
. -
source
(enum of"file"
,"device"
, or"network"
) - requiredSource of data for mounted file systems.
Files app uses above information in order to render related UI elements
approprietly. For example, if configurable
is set to
true, then a menu item for configuring volumes will be rendered.
Similarly, if multiple_mounts
is set to true
, then
Files app will allow to add more than one mount points from the UI. If
watchable
is false
, then a refresh button will be
rendered. Note, that if possible you should add support for watchers, so
changes on the file system can be reflected immediately and automatically.
Overview
File System Provider API allows extensions to support virtual file systems, which are available in the file manager on Chrome OS. Use cases include decompressing archives and accessing files in a cloud service other than Drive.
Mounting file systems
Providing extensions can either provide file system contents from an external source (such as a remote server or a USB device), or using a local file (such as an archive) as its input.
In order to write file systems which are file handlers (source is
"file"
) the provider must be a packaged app, as the
onLaunched
event is not available to extensions.
If the source is network or a device, then the file system should be mounted when onMountRequested event is called.
Source of the file system data | Entry point |
---|---|
"file"
|
Available to packaged apps only. |
"device" or "network"
|
onMountRequested |
Configuring file systems
Provided file systems once mounted can be configured via the onConfigureRequested event. It's especially useful for file systems which provide contents via network in order to set proper credentials. Handling this event is optional.
Life cycle
Provided file systems once mounted are remembered by Chrome and remounted automatically after reboot or restart. Hence, once a file system is mounted by a providing extension, it will stay until either the extension is unloaded, or the extension calls the unmount method.
Summary
Types | |
---|---|
ProviderError | |
OpenFileMode | |
ChangeType | |
CommonActionId | |
EntryMetadata | |
FileSystemInfo | |
Methods | |
mount −
chrome.fileSystemProvider.mount(object options, function callback)
| |
unmount −
chrome.fileSystemProvider.unmount(object options, function callback)
| |
getAll −
chrome.fileSystemProvider.getAll(function callback)
| |
get −
chrome.fileSystemProvider.get(string fileSystemId, function callback)
| |
notify −
chrome.fileSystemProvider.notify(object options, function callback)
| |
Events | |
onUnmountRequested | |
onGetMetadataRequested | |
onGetActionsRequested | |
onReadDirectoryRequested | |
onOpenFileRequested | |
onCloseFileRequested | |
onReadFileRequested | |
onCreateDirectoryRequested | |
onDeleteEntryRequested | |
onCreateFileRequested | |
onCopyEntryRequested | |
onMoveEntryRequested | |
onTruncateRequested | |
onWriteFileRequested | |
onAbortRequested | |
onConfigureRequested | |
onMountRequested | |
onAddWatcherRequested | |
onRemoveWatcherRequested | |
onExecuteActionRequested |
Types
ProviderError
Enum |
---|
"OK" ,
"FAILED" ,
"IN_USE" ,
"EXISTS" ,
"NOT_FOUND" ,
"ACCESS_DENIED" ,
"TOO_MANY_OPENED" ,
"NO_MEMORY" ,
"NO_SPACE" ,
"NOT_A_DIRECTORY" ,
"INVALID_OPERATION" ,
"SECURITY" ,
"ABORT" ,
"NOT_A_FILE" ,
"NOT_EMPTY" ,
"INVALID_URL" ,
or "IO"
|
OpenFileMode
Enum |
---|
"READ" ,
or "WRITE"
|
ChangeType
Enum |
---|
"CHANGED" ,
or "DELETED"
|
CommonActionId
Enum |
---|
"SAVE_FOR_OFFLINE" ,
"OFFLINE_NOT_NECESSARY" ,
or "SHARE"
|
EntryMetadata
properties | ||
---|---|---|
boolean | (optional) isDirectory |
True if it is a directory. Must be provided if requested in |
string | (optional) name |
Name of this entry (not full path name). Must not contain '/'. For root it must be empty. Must be provided if requested in |
double | (optional) size |
File size in bytes. Must be provided if requested in |
Date | (optional) modificationTime |
The last modified time of this entry. Must be provided if requested in |
string | (optional) mimeType |
Mime type for the entry. Always optional, but should be provided if requested in |
string | (optional) thumbnail |
Thumbnail image as a data URI in either PNG, JPEG or WEBP format, at most 32 KB in size. Optional, but can be provided only when explicitly requested by the onGetMetadataRequested event. |
FileSystemInfo
properties | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
string | fileSystemId |
The identifier of the file system. |
|||||||||
string | displayName |
A human-readable name for the file system. |
|||||||||
boolean | writable |
Whether the file system supports operations which may change contents of the file system (such as creating, deleting or writing to files). |
|||||||||
integer | openedFilesLimit |
Since Chrome 42. The maximum number of files that can be opened at once. If 0, then not limited. |
|||||||||
array of object | openedFiles |
Since Chrome 42. List of currently opened files. Properties of each object
|
|||||||||
boolean | (optional) supportsNotifyTag |
Since Chrome 45.
Whether the file system supports the |
|||||||||
array of object | watchers |
Since Chrome 45. List of watchers. Properties of each object
|
Methods
mount
chrome.fileSystemProvider.mount(object options, function callback)
Mounts a file system with the given fileSystemId
and displayName
. displayName
will be shown in the left panel of the Files app. displayName
can contain any characters including '/', but cannot be an empty string. displayName
must be descriptive but doesn't have to be unique. The fileSystemId
must not be an empty string.
Depending on the type of the file system being mounted, the source
option must be set appropriately.
In case of an error, runtime.lastError will be set with a corresponding error code.
Parameters | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
object | options |
|
||||||||||||||||||
function | (optional) callback |
A generic result callback to indicate success or failure. If you specify the callback parameter, it should be a function that looks like this: function() {...};
|
unmount
chrome.fileSystemProvider.unmount(object options, function callback)
Unmounts a file system with the given fileSystemId
. It must be called after onUnmountRequested is invoked. Also, the providing extension can decide to perform unmounting if not requested (eg. in case of lost connection, or a file error).
In case of an error, runtime.lastError will be set with a corresponding error code.
Parameters | |||||
---|---|---|---|---|---|
object | options |
|
|||
function | (optional) callback |
A generic result callback to indicate success or failure. If you specify the callback parameter, it should be a function that looks like this: function() {...};
|
getAll
chrome.fileSystemProvider.getAll(function callback)
Returns all file systems mounted by the extension.
Parameters | |||||
---|---|---|---|---|---|
function | callback |
Callback to receive the result of getAll function. The callback parameter should be a function that looks like this: function(array of FileSystemInfo fileSystems) {...};
|
get
chrome.fileSystemProvider.get(string fileSystemId, function callback)
Since Chrome 42.
Returns information about a file system with the passed fileSystemId
.
Parameters | |||||
---|---|---|---|---|---|
string | fileSystemId | ||||
function | callback |
Callback to receive the result of get function. The callback parameter should be a function that looks like this: function( FileSystemInfo fileSystem) {...};
|
notify
chrome.fileSystemProvider.notify(object options, function callback)
Since Chrome 45.
Notifies about changes in the watched directory at observedPath
in recursive
mode. If the file system is mounted with supportsNofityTag
, then tag
must be provided, and all changes since the last notification always reported, even if the system was shutdown. The last tag can be obtained with getAll.
To use, the file_system_provider.notify
manifest option must be set to true.
Value of tag
can be any string which is unique per call, so it's possible to identify the last registered notification. Eg. if the providing extension starts after a reboot, and the last registered notification's tag is equal to "123", then it should call notify for all changes which happened since the change tagged as "123". It cannot be an empty string.
Not all providers are able to provide a tag, but if the file system has a changelog, then the tag can be eg. a change number, or a revision number.
Note that if a parent directory is removed, then all descendant entries are also removed, and if they are watched, then the API must be notified about the fact. Also, if a directory is renamed, then all descendant entries are in fact removed, as there is no entry under their original paths anymore.
In case of an error, runtime.lastError will be set will a corresponding error code.
Parameters | ||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
object | options |
|
||||||||||||||||||||||||
function | (optional) callback |
A generic result callback to indicate success or failure. If you specify the callback parameter, it should be a function that looks like this: function() {...};
|
Events
onUnmountRequested
Raised when unmounting for the file system with the fileSystemId
identifier is requested. In the response, the unmount API method must be called together with successCallback
. If unmounting is not possible (eg. due to a pending operation), then errorCallback
must be called.
addListener
chrome.fileSystemProvider.onUnmountRequested.addListener(function callback)
Parameters | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
function | callback |
The callback parameter should be a function that looks like this: function(object options, function successCallback, function errorCallback) {...};
|
onGetMetadataRequested
Raised when metadata of a file or a directory at entryPath
is requested. The metadata must be returned with the successCallback
call. In case of an error, errorCallback
must be called.
addListener
chrome.fileSystemProvider.onGetMetadataRequested.addListener(function callback)
Parameters | |||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
function | callback |
The callback parameter should be a function that looks like this: function(object options, function successCallback, function errorCallback) {...};
|
onGetActionsRequested
Since Chrome 48.
Raised when a list of actions for a set of files or directories at entryPaths
is requested. All of the returned actions must be applicable to each entry. If there are no such actions, an empty array should be returned. The actions must be returned with the successCallback
call. In case of an error, errorCallback
must be called.
addListener
chrome.fileSystemProvider.onGetActionsRequested.addListener(function callback)
Parameters | |||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
function | callback |
The callback parameter should be a function that looks like this: function(object options, function successCallback, function errorCallback) {...};
|
onReadDirectoryRequested
Raised when contents of a directory at directoryPath
are requested. The results must be returned in chunks by calling the successCallback
several times. In case of an error, errorCallback
must be called.
addListener
chrome.fileSystemProvider.onReadDirectoryRequested.addListener(function callback)
Parameters | ||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
function | callback |
The callback parameter should be a function that looks like this: function(object options, function successCallback, function errorCallback) {...};
|
onOpenFileRequested
Raised when opening a file at filePath
is requested. If the file does not exist, then the operation must fail. Maximum number of files opened at once can be specified with MountOptions
.
addListener
chrome.fileSystemProvider.onOpenFileRequested.addListener(function callback)
Parameters | ||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
function | callback |
The callback parameter should be a function that looks like this: function(object options, function successCallback, function errorCallback) {...};
|
onCloseFileRequested
Raised when opening a file previously opened with openRequestId
is requested to be closed.
addListener
chrome.fileSystemProvider.onCloseFileRequested.addListener(function callback)
Parameters | |||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
function | callback |
The callback parameter should be a function that looks like this: function(object options, function successCallback, function errorCallback) {...};
|
onReadFileRequested
Raised when reading contents of a file opened previously with openRequestId
is requested. The results must be returned in chunks by calling successCallback
several times. In case of an error, errorCallback
must be called.
addListener
chrome.fileSystemProvider.onReadFileRequested.addListener(function callback)
Parameters | ||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
function | callback |
The callback parameter should be a function that looks like this: function(object options, function successCallback, function errorCallback) {...};
|
onCreateDirectoryRequested
Raised when creating a directory is requested. The operation must fail with the EXISTS error if the target directory already exists. If recursive
is true, then all of the missing directories on the directory path must be created.
addListener
chrome.fileSystemProvider.onCreateDirectoryRequested.addListener(function callback)
Parameters | ||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
function | callback |
The callback parameter should be a function that looks like this: function(object options, function successCallback, function errorCallback) {...};
|
onDeleteEntryRequested
Raised when deleting an entry is requested. If recursive
is true, and the entry is a directory, then all of the entries inside must be recursively deleted as well.
addListener
chrome.fileSystemProvider.onDeleteEntryRequested.addListener(function callback)
Parameters | ||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
function | callback |
The callback parameter should be a function that looks like this: function(object options, function successCallback, function errorCallback) {...};
|
onCreateFileRequested
Raised when creating a file is requested. If the file already exists, then errorCallback
must be called with the "EXISTS"
error code.
addListener
chrome.fileSystemProvider.onCreateFileRequested.addListener(function callback)
Parameters | |||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
function | callback |
The callback parameter should be a function that looks like this: function(object options, function successCallback, function errorCallback) {...};
|
onCopyEntryRequested
Raised when copying an entry (recursively if a directory) is requested. If an error occurs, then errorCallback
must be called.
addListener
chrome.fileSystemProvider.onCopyEntryRequested.addListener(function callback)
Parameters | ||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
function | callback |
The callback parameter should be a function that looks like this: function(object options, function successCallback, function errorCallback) {...};
|
onMoveEntryRequested
Raised when moving an entry (recursively if a directory) is requested. If an error occurs, then errorCallback
must be called.
addListener
chrome.fileSystemProvider.onMoveEntryRequested.addListener(function callback)
Parameters | ||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
function | callback |
The callback parameter should be a function that looks like this: function(object options, function successCallback, function errorCallback) {...};
|
onTruncateRequested
Raised when truncating a file to a desired length is requested. If an error occurs, then errorCallback
must be called.
addListener
chrome.fileSystemProvider.onTruncateRequested.addListener(function callback)
Parameters | ||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
function | callback |
The callback parameter should be a function that looks like this: function(object options, function successCallback, function errorCallback) {...};
|
onWriteFileRequested
Raised when writing contents to a file opened previously with openRequestId
is requested.
addListener
chrome.fileSystemProvider.onWriteFileRequested.addListener(function callback)
Parameters | |||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
function | callback |
The callback parameter should be a function that looks like this: function(object options, function successCallback, function errorCallback) {...};
|
onAbortRequested
Raised when aborting an operation with operationRequestId
is requested. The operation executed with operationRequestId
must be immediately stopped and successCallback
of this abort request executed. If aborting fails, then errorCallback
must be called. Note, that callbacks of the aborted operation must not be called, as they will be ignored. Despite calling errorCallback
, the request may be forcibly aborted.
addListener
chrome.fileSystemProvider.onAbortRequested.addListener(function callback)
Parameters | |||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
function | callback |
The callback parameter should be a function that looks like this: function(object options, function successCallback, function errorCallback) {...};
|
onConfigureRequested
Since Chrome 44.
Raised when showing a configuration dialog for fileSystemId
is requested. If it's handled, the file_system_provider.configurable
manfiest option must be set to true.
addListener
chrome.fileSystemProvider.onConfigureRequested.addListener(function callback)
Parameters | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
function | callback |
The callback parameter should be a function that looks like this: function(object options, function successCallback, function errorCallback) {...};
|
onMountRequested
Since Chrome 44.
Raised when showing a dialog for mounting a new file system is requested. If the extension/app is a file handler, then this event shouldn't be handled. Instead app.runtime.onLaunched
should be handled in order to mount new file systems when a file is opened. For multiple mounts, the file_system_provider.multiple_mounts
manifest option must be set to true.
addListener
chrome.fileSystemProvider.onMountRequested.addListener(function callback)
Parameters | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
function | callback |
The callback parameter should be a function that looks like this: function(function successCallback, function errorCallback) {...};
|
onAddWatcherRequested
Since Chrome 45.
Raised when setting a new directory watcher is requested. If an error occurs, then errorCallback
must be called.
addListener
chrome.fileSystemProvider.onAddWatcherRequested.addListener(function callback)
Parameters | ||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
function | callback |
The callback parameter should be a function that looks like this: function(object options, function successCallback, function errorCallback) {...};
|
onRemoveWatcherRequested
Since Chrome 45.
Raised when the watcher should be removed. If an error occurs, then errorCallback
must be called.
addListener
chrome.fileSystemProvider.onRemoveWatcherRequested.addListener(function callback)
Parameters | ||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
function | callback |
The callback parameter should be a function that looks like this: function(object options, function successCallback, function errorCallback) {...};
|
onExecuteActionRequested
Since Chrome 48.
Raised when executing an action for a set of files or directories is\ requested. After the action is completed, successCallback
must be called. On error, errorCallback
must be called.
addListener
chrome.fileSystemProvider.onExecuteActionRequested.addListener(function callback)
Parameters | ||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
function | callback |
The callback parameter should be a function that looks like this: function(object options, function successCallback, function errorCallback) {...};
|