[platforms=("chromeos"),
implemented_in="chrome/browser/chromeos/extensions/file_system_provider/file_system_provider_api.h"]
namespace fileSystemProvider {
- // Callback to receive the result of mount() function.
- // <code>fileSystemID</code> will be a unique ID for the file system just
- // mounted. The ID is used to distinguish multiple file systems mounted
- // from a single File System Provider.
- callback MountCallback = void(long fileSystemId,
- [nodoc, instanceOf=DOMError] object error);
+ // Error codes used by providing extensions in response to requests as well
+ // as in case of errors when calling methods of the API. For success, <code>
+ // OK</code> must be used.
+ enum ProviderError {
+ 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,
+ IO
+ };
+
+ // Mode of opening a file. Used by <code>onOpenFileRequested</code>.
+ enum OpenFileMode {
+ READ,
+ WRITE
+ };
+
+ // Type of a change detected on the observed directory.
+ enum ChangeType {
+ CHANGED,
+ DELETED
+ };
+
+ // Represents metadata of a file or a directory.
+ dictionary EntryMetadata {
+ // True if it is a directory.
+ boolean isDirectory;
+
+ // Name of this entry (not full path name).
+ DOMString name;
+
+ // File size in bytes.
+ double size;
+
+ // The last modified time of this entry.
+ [instanceOf=Date] object modificationTime;
+
+ // Mime type for the entry.
+ DOMString? mimeType;
+
+ // 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 <code>onGetMetadataRequested</code> event.
+ DOMString? thumbnail;
+ };
+
+ // Represents a watcher.
+ dictionary Watcher {
+ // The path of the entry being observed.
+ DOMString entryPath;
+
+ // Whether watching should include all child entries recursively. It can be
+ // true for directories only.
+ boolean recursive;
+
+ // Tag used by the last notification for the watcher.
+ DOMString? lastTag;
+ };
+
+ // Represents a mounted file system.
+ dictionary FileSystemInfo {
+ // The identifier of the file system.
+ DOMString fileSystemId;
+
+ // A human-readable name for the file system.
+ DOMString displayName;
+
+ // Whether the file system supports operations which may change contents
+ // of the file system (such as creating, deleting or writing to files).
+ boolean writable;
+
+ // Whether the file system supports the <code>tag</code> field for observing
+ // directories.
+ [nodoc] boolean? supportsNotifyTag;
+
+ // List of watchers.
+ [nodoc] Watcher[] watchers;
+ };
+
+ // Options for the <code>mount()</code> method.
+ dictionary MountOptions {
+ // The string indentifier of the file system. Must be unique per each
+ // extension.
+ DOMString fileSystemId;
+
+ // A human-readable name for the file system.
+ DOMString displayName;
+
+ // Whether the file system supports operations which may change contents
+ // of the file system (such as creating, deleting or writing to files).
+ boolean? writable;
+
+ // Whether the file system supports the <code>tag</code> field for observed
+ // directories. Required in order to enable the internal cache.
+ [nodoc] boolean? supportsNotifyTag;
+ };
+
+ // Options for the <code>unmount()</code> method.
+ dictionary UnmountOptions {
+ // The identifier of the file system to be unmounted.
+ DOMString fileSystemId;
+ };
+
+ // Options for the <code>onUnmountRequested()</code> event.
+ dictionary UnmountRequestedOptions {
+ // The identifier of the file system to be unmounted.
+ DOMString fileSystemId;
+ long requestId;
+ };
+
+ // Options for the <code>onGetMetadataRequested()</code> event.
+ dictionary GetMetadataRequestedOptions {
+ // The identifier of the file system related to this operation.
+ DOMString fileSystemId;
+
+ // The unique identifier of this request.
+ long requestId;
+
+ // The path of the entry to fetch metadata about.
+ DOMString entryPath;
+
+ // Set to <code>true</code> if the thumbnail is requested.
+ boolean thumbnail;
+ };
+
+ // Options for the <code>onReadDirectoryRequested()</code> event.
+ dictionary ReadDirectoryRequestedOptions {
+ // The identifier of the file system related to this operation.
+ DOMString fileSystemId;
+
+ // The unique identifier of this request.
+ long requestId;
+
+ // The path of the directory which contents are requested.
+ DOMString directoryPath;
+ };
+
+ // Options for the <code>onOpenFileRequested()</code> event.
+ dictionary OpenFileRequestedOptions {
+ // The identifier of the file system related to this operation.
+ DOMString fileSystemId;
+
+ // A request ID which will be used by consecutive read/write and close
+ // requests.
+ long requestId;
+
+ // The path of the file to be opened.
+ DOMString filePath;
+
+ // Whether the file will be used for reading or writing.
+ OpenFileMode mode;
+ };
+
+ // Options for the <code>onCloseFileRequested()</code> event.
+ dictionary CloseFileRequestedOptions {
+ // The identifier of the file system related to this operation.
+ DOMString fileSystemId;
+
+ // The unique identifier of this request.
+ long requestId;
+
+ // A request ID used to open the file.
+ long openRequestId;
+ };
+
+ // Options for the <code>onReadFileRequested()</code> event.
+ dictionary ReadFileRequestedOptions {
+ // The identifier of the file system related to this operation.
+ DOMString fileSystemId;
+
+ // The unique identifier of this request.
+ long requestId;
+
+ // A request ID used to open the file.
+ long openRequestId;
+
+ // Position in the file (in bytes) to start reading from.
+ double offset;
+
+ // Number of bytes to be returned.
+ double length;
+ };
+
+ // Options for the <code>onCreateDirectoryRequested()</code> event.
+ dictionary CreateDirectoryRequestedOptions {
+ // The identifier of the file system related to this operation.
+ DOMString fileSystemId;
+
+ // The unique identifier of this request.
+ long requestId;
+
+ // The path of the directory to be created.
+ DOMString directoryPath;
+
+ // Whether the operation is recursive (for directories only).
+ boolean recursive;
+ };
+
+ // Options for the <code>onDeleteEntryRequested()</code> event.
+ dictionary DeleteEntryRequestedOptions {
+ // The identifier of the file system related to this operation.
+ DOMString fileSystemId;
+
+ // The unique identifier of this request.
+ long requestId;
+
+ // The path of the entry to be deleted.
+ DOMString entryPath;
+
+ // Whether the operation is recursive (for directories only).
+ boolean recursive;
+ };
+
+ // Options for the <code>onCreateFileRequested()</code> event.
+ dictionary CreateFileRequestedOptions {
+ // The identifier of the file system related to this operation.
+ DOMString fileSystemId;
+
+ // The unique identifier of this request.
+ long requestId;
+
+ // The path of the file to be created.
+ DOMString filePath;
+ };
+
+ // Options for the <code>onCopyEntryRequested()</code> event.
+ dictionary CopyEntryRequestedOptions {
+ // The identifier of the file system related to this operation.
+ DOMString fileSystemId;
+
+ // The unique identifier of this request.
+ long requestId;
- // Callback to handle an error raised from the browser.
- [nocompile] callback ErrorCallback = void([instanceOf=DOMError] object error);
+ // The source path of the entry to be copied.
+ DOMString sourcePath;
+
+ // The destination path for the copy operation.
+ DOMString targetPath;
+ };
+
+ // Options for the <code>onMoveEntryRequested()</code> event.
+ dictionary MoveEntryRequestedOptions {
+ // The identifier of the file system related to this operation.
+ DOMString fileSystemId;
+
+ // The unique identifier of this request.
+ long requestId;
+
+ // The source path of the entry to be moved into a new place.
+ DOMString sourcePath;
+
+ // The destination path for the copy operation.
+ DOMString targetPath;
+ };
+
+ // Options for the <code>onTruncateRequested()</code> event.
+ dictionary TruncateRequestedOptions {
+ // The identifier of the file system related to this operation.
+ DOMString fileSystemId;
+
+ // The unique identifier of this request.
+ long requestId;
+
+ // The path of the file to be truncated.
+ DOMString filePath;
+
+ // Number of bytes to be retained after the operation completes.
+ double length;
+ };
+
+ // Options for the <code>onWriteFileRequested()</code> event.
+ dictionary WriteFileRequestedOptions {
+ // The identifier of the file system related to this operation.
+ DOMString fileSystemId;
+
+ // The unique identifier of this request.
+ long requestId;
+
+ // A request ID used to open the file.
+ long openRequestId;
+
+ // Position in the file (in bytes) to start writing the bytes from.
+ double offset;
+
+ // Buffer of bytes to be written to the file.
+ ArrayBuffer data;
+ };
+
+ // Options for the <code>onAbortRequested()</code> event.
+ dictionary AbortRequestedOptions {
+ // The identifier of the file system related to this operation.
+ DOMString fileSystemId;
+
+ // The unique identifier of this request.
+ long requestId;
+
+ // An ID of the request to be aborted.
+ long operationRequestId;
+ };
+
+ // Options for the <code>onAddWatcherRequested()</code> event.
+ dictionary AddWatcherRequestedOptions {
+ // The identifier of the file system related to this operation.
+ DOMString fileSystemId;
+
+ // The unique identifier of this request.
+ long requestId;
+
+ // The path of the entry to be observed.
+ DOMString entryPath;
+
+ // Whether observing should include all child entries recursively. It can be
+ // true for directories only.
+ boolean recursive;
+ };
+
+ // Options for the <code>onRemoveWatcherRequested()</code> event.
+ dictionary RemoveWatcherRequestedOptions {
+ // The identifier of the file system related to this operation.
+ DOMString fileSystemId;
+
+ // The unique identifier of this request.
+ long requestId;
+
+ // The path of the watched entry.
+ DOMString entryPath;
+
+ // Mode of the watcher.
+ boolean recursive;
+ };
+
+ // Information about a change happened to an entry within the observed
+ // directory (including the entry itself).
+ dictionary Change {
+ // The path of the changed entry.
+ DOMString entryPath;
+
+ // The type of the change which happened to the entry.
+ ChangeType changeType;
+ };
+
+ // Options for the <code>Notify()</code> method.
+ dictionary NotifyOptions {
+ // The identifier of the file system related to this change.
+ DOMString fileSystemId;
+
+ // The path of the observed entry.
+ DOMString observedPath;
+
+ // Mode of the observed entry.
+ boolean recursive;
+
+ // The type of the change which happened to the observed entry. If it is
+ // DELETED, then the observed entry will be automatically removed from the
+ // list of observed entries.
+ ChangeType changeType;
+
+ // List of changes to entries within the observed directory (including the
+ // entry itself)
+ Change[]? changes;
+
+ // Tag for the notification. Required if the file system was mounted with
+ // the <code>supportsNotifyTag</code> option. Note, that this flag is
+ // necessary to provide notifications about changes which changed even
+ // when the system was shutdown.
+ DOMString? tag;
+ };
+
+ // Callback to receive the result of getAll() function.
+ callback GetAllCallback = void(FileSystemInfo[] fileSystems);
+
+ // Callback to be called by the providing extension in case of a success.
+ [nocompile] callback ProviderSuccessCallback = void();
+
+ // Callback to be called by the providing extension in case of an error.
+ [nocompile] callback ProviderErrorCallback = void(ProviderError error);
+
+ // Success callback for the <code>onGetMetadataRequested</code> event.
+ [nocompile] callback MetadataCallback = void(
+ EntryMetadata metadata);
+
+ // Success callback for the <code>onReadDirectoryRequested</code> event. If
+ // more entries will be returned, then <code>hasMore</code> must be true, and
+ // it has to be called again with additional entries. If no more entries are
+ // available, then <code>hasMore</code> must be set to false.
+ [nocompile] callback EntriesCallback = void(
+ EntryMetadata[] entries, boolean hasMore);
+
+ // Success callback for the <code>onReadFileRequested</code> event. If more
+ // data will be returned, then <code>hasMore</code> must be true, and it
+ // has to be called again with additional entries. If no more data is
+ // available, then <code>hasMore</code> must be set to false.
+ [nocompile] callback FileDataCallback = void(
+ ArrayBuffer data, boolean hasMore);
+
+ // A generic result callback to indicate success or failure.
+ callback ResultCallback = void();
interface Functions {
- // Mounts a file system with the given <code>displayName</code>.
- // <code>displayName</code> will be shown in the left panel of
- // Files.app. <code>displayName</code> can contain any characters
+ // Mounts a file system with the given <code>fileSystemId</code> and <code>
+ // displayName</code>. <code>displayName</code> will be shown in the left
+ // panel of Files.app. <code>displayName</code> can contain any characters
// including '/', but cannot be an empty string. <code>displayName</code>
- // should be descritive but doesn't have to be unique. Duplicate display
- // names are uniquified by adding suffix like "(1)" in the Files.app UI.
- static void mount(DOMString displayName,
- MountCallback successCallback,
- [nocompile] ErrorCallback errorCallback);
+ // must be descriptive but doesn't have to be unique. The <code>fileSystemId
+ // </code> must not be an empty string.
+ //
+ // In case of an error, <code>chrome.runtime.lastError</code> will be set
+ // will a corresponding error code.
+ static void mount(MountOptions options,
+ optional ResultCallback callback);
+
+ // Unmounts a file system with the given <code>fileSystemId</code>. It
+ // must be called after <code>onUnmountRequested</code> 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, <code>chrome.runtime.lastError</code> will be set
+ // will a corresponding error code.
+ static void unmount(UnmountOptions options,
+ optional ResultCallback callback);
+
+ // Returns all file systems mounted by the extension.
+ static void getAll(GetAllCallback callback);
+
+ // Notifies about changes in the watched directory at <code>
+ // observedPath</code> in <code>recursive</code mode. If the file system is
+ // mounted with <code>supportsNofityTag</code>, then <code>tag</code> 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 <code>
+ // getAll()</code>. Note, that <code>tag</code> is required in order to
+ // enable the internal cache.
+ //
+ // Value of <code>tag</code> 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, <code>chrome.runtime.lastError</code> will be set
+ // will a corresponding error code.
+ [nodoc] static void notify(NotifyOptions options,
+ optional ResultCallback callback);
+ };
+
+ interface Events {
+ // Raised when unmounting for the file system with the <code>fileSystemId
+ // </code> identifier is requested. In the response, the <code>unmount
+ // </code> API method must be called together with <code>successCallback
+ // </code>. If unmounting is not possible (eg. due to a pending operation),
+ // then <code>errorCallback</code> must be called.
+ [maxListeners=1] static void onUnmountRequested(
+ UnmountRequestedOptions options,
+ ProviderSuccessCallback successCallback,
+ ProviderErrorCallback errorCallback);
+
+ // Raised when metadata of a file or a directory at <code>entryPath</code>
+ // is requested. The metadata must be returned with the <code>
+ // successCallback</code> call. In case of an error, <code>errorCallback
+ // </code> must be called.
+ [maxListeners=1] static void onGetMetadataRequested(
+ GetMetadataRequestedOptions options,
+ MetadataCallback successCallback,
+ ProviderErrorCallback errorCallback);
+
+ // Raised when contents of a directory at <code>directoryPath</code> are
+ // requested. The results must be returned in chunks by calling the <code>
+ // successCallback</code> several times. In case of an error, <code>
+ // errorCallback</code> must be called.
+ [maxListeners=1] static void onReadDirectoryRequested(
+ ReadDirectoryRequestedOptions options,
+ EntriesCallback successCallback,
+ ProviderErrorCallback errorCallback);
+
+ // Raised when opening a file at <code>filePath</code> is requested. If the
+ // file does not exist, then the operation must fail.
+ [maxListeners=1] static void onOpenFileRequested(
+ OpenFileRequestedOptions options,
+ ProviderSuccessCallback successCallback,
+ ProviderErrorCallback errorCallback);
+
+ // Raised when opening a file previously opened with <code>openRequestId
+ // </code> is requested to be closed.
+ [maxListeners=1] static void onCloseFileRequested(
+ CloseFileRequestedOptions options,
+ ProviderSuccessCallback successCallback,
+ ProviderErrorCallback errorCallback);
+
+ // Raised when reading contents of a file opened previously with <code>
+ // openRequestId</code> is requested. The results must be returned in
+ // chunks by calling <code>successCallback</code> several times. In case of
+ // an error, <code>errorCallback</code> must be called.
+ [maxListeners=1] static void onReadFileRequested(
+ ReadFileRequestedOptions options,
+ FileDataCallback successCallback,
+ ProviderErrorCallback errorCallback);
+
+ // Raised when creating a directory is requested. The operation must fail
+ // with the EXISTS error if the target directory already exists.
+ // If <code>recursive</code> is true, then all of the missing directories
+ // on the directory path must be created.
+ [maxListeners=1] static void onCreateDirectoryRequested(
+ CreateDirectoryRequestedOptions options,
+ ProviderSuccessCallback successCallback,
+ ProviderErrorCallback errorCallback);
+
+ // Raised when deleting an entry is requested. If <code>recursive</code> is
+ // true, and the entry is a directory, then all of the entries inside
+ // must be recursively deleted as well.
+ [maxListeners=1] static void onDeleteEntryRequested(
+ DeleteEntryRequestedOptions options,
+ ProviderSuccessCallback successCallback,
+ ProviderErrorCallback errorCallback);
+
+ // Raised when creating a file is requested. If the file already exists,
+ // then <code>errorCallback</code> must be called with the <code>EXISTS
+ // </code> error code.
+ [maxListeners=1] static void onCreateFileRequested(
+ CreateFileRequestedOptions options,
+ ProviderSuccessCallback successCallback,
+ ProviderErrorCallback errorCallback);
+
+ // Raised when copying an entry (recursively if a directory) is requested.
+ // If an error occurs, then <code>errorCallback</code> must be called.
+ [maxListeners=1] static void onCopyEntryRequested(
+ CopyEntryRequestedOptions options,
+ ProviderSuccessCallback successCallback,
+ ProviderErrorCallback errorCallback);
+
+ // Raised when moving an entry (recursively if a directory) is requested.
+ // If an error occurs, then <code>errorCallback</code> must be called.
+ [maxListeners=1] static void onMoveEntryRequested(
+ MoveEntryRequestedOptions options,
+ ProviderSuccessCallback successCallback,
+ ProviderErrorCallback errorCallback);
+
+ // Raised when truncating a file to a desired length is requested.
+ // If an error occurs, then <code>errorCallback</code> must be called.
+ [maxListeners=1] static void onTruncateRequested(
+ TruncateRequestedOptions options,
+ ProviderSuccessCallback successCallback,
+ ProviderErrorCallback errorCallback);
+
+ // Raised when writing contents to a file opened previously with <code>
+ // openRequestId</code> is requested.
+ [maxListeners=1] static void onWriteFileRequested(
+ WriteFileRequestedOptions options,
+ ProviderSuccessCallback successCallback,
+ ProviderErrorCallback errorCallback);
+
+ // Raised when aborting an operation with <code>operationRequestId</code>
+ // is requested. The operation executed with <code>operationRequestId</code>
+ // must be immediately stopped and <code>successCallback</code> of this
+ // abort request executed. If aborting fails, then <code>errorCallback
+ // </code> must be called. Note, that callbacks of the aborted operation
+ // must not be called, as they will be ignored. Despite calling <code>
+ // errorCallback</code>, the request may be forcibly aborted.
+ [maxListeners=1] static void onAbortRequested(
+ AbortRequestedOptions options,
+ ProviderSuccessCallback successCallback,
+ ProviderErrorCallback errorCallback);
+
+ // Raised when setting a new directory watcher is requested. If an error
+ // occurs, then <code>errorCallback</code> must be called.
+ [maxListeners=1, nodoc] static void onAddWatcherRequested(
+ AddWatcherRequestedOptions options,
+ ProviderSuccessCallback successCallback,
+ ProviderErrorCallback errorCallback);
+
+ // Raised when the watcher should be removed. If an error occurs, then
+ // <code>errorCallback</code> must be called.
+ [maxListeners=1, nodoc] static void onRemoveWatcherRequested(
+ RemoveWatcherRequestedOptions options,
+ ProviderSuccessCallback successCallback,
+ ProviderErrorCallback errorCallback);
};
};
+