1 // Copyright 2013 The Chromium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
5 // fileBrowserPrivate API.
6 // This is a private API used by the file browser of ChromeOS.
7 [platforms=("chromeos"),
8 implemented_in="chrome/browser/chromeos/extensions/file_manager/file_browser_private_api_functions.h"]
9 namespace fileBrowserPrivate {
10 // Type of the mounted volume.
11 enum VolumeType { drive, downloads, removable, archive, cloud_device };
13 // Device type. Available if this is removable volume.
14 enum DeviceType { usb, sd, optical, mobile, unknown };
16 // Additional data about mount, for example, that the filesystem is not
18 enum MountCondition { unknown, unsupported };
20 // Is the event raised for mounting or unmounting.
21 enum MountCompletedEventType { mount, unmount };
23 // Event type that tells listeners if mount was successful or an error
24 // occurred. It also specifies the error.
25 enum MountCompletedStatus {
29 error_invalid_argument,
31 error_path_already_mounted,
32 error_path_not_mounted,
33 error_directory_creation_failed,
34 error_invalid_mount_options,
35 error_invalid_unmount_options,
36 error_insufficient_permissions,
37 error_mount_program_not_found,
38 error_mount_program_failed,
39 error_invalid_device_path,
40 error_unknown_filesystem,
41 error_unsuported_filesystem,
42 error_invalid_archive,
47 // File transfer progress state.
48 enum TransferState { started, in_progress, completed, failed };
50 // Defines file transfer direction.
51 enum TransferType { upload, download };
53 // The type of the progress event.
54 enum CopyProgressStatusType {
55 // "begin_copy_entry" is fired for each entry (file or directory) before
56 // starting the copy operation.
59 // "end_copy_entry" is fired for each entry (file or directory) after ending
60 // the copy operation.
63 // "progress" is fired periodically to report progress of a file copy (not
67 // "success" is fired after all entries are copied.
70 // "error" is fired when an error occurs.
74 // Specifies type of event that is raised.
75 enum FileWatchEventType { changed, error };
77 // The type of entry that is needed. Default to ALL.
78 enum SearchType { EXCLUDE_DIRECTORIES, SHARED_WITH_ME, OFFLINE, ALL };
81 enum ZoomOperationType { in, out, reset };
84 enum DeviceEventType {
87 // If the device is disabled by preference, the disabled event is published
88 // instead of the added event.
90 // Device is added, but scan for the device is canceled. The event is
91 // published after the added event.
103 // Drive sync error type.
104 // Keep it synced with DriveSyncErrorType in operation_observer.h.
105 enum DriveSyncErrorType {
106 // Request to delete a file without permission.
107 delete_without_permission,
108 // Google Drive is temporarily unavailable.
110 // Miscellaneous errors other than listed above.
114 // Result of task execution.
116 // The task execution succeeded and a new window/tab was opened.
118 // The task execution succeeded and the message was sent to the proper
121 // The task execution failed.
123 // No URL is specified.
127 // A file task represents an action that the file manager can perform over the
128 // currently selected files. See
129 // chrome/browser/chromeos/extensions/file_manager/file_tasks.h for details
130 // about how file tasks are handled.
131 dictionary FileTask {
132 // The unique identifier of the task.
135 // Task title (ex. App name).
138 // Task icon url (from chrome://extension-icon/...)
141 // True if this task is a default task for the selected files.
145 // Drive file properties.
146 dictionary DriveEntryProperties {
147 // URL to the Drive thumbnail image for this file.
148 DOMString? thumbnailUrl;
150 // Width, if the entry is an image.
153 // Height, if the entry is an image.
156 // Rotation in clockwise degrees, if the entry is an image.
159 // True if the file is pinned in Drive cache.
162 // True if the file is present in Drive cache.
165 // True if the file is hosted on a Drive server instead of local.
168 // URL to the custom icon for this file.
169 DOMString? customIconUrl;
171 // Drive MIME type for this file.
172 DOMString? contentMimeType;
174 // True if the entry is labeled as shared-with-me.
175 boolean? sharedWithMe;
177 // True if the entry is labeled as shared (either from me to others or to me
182 // Information about total and remaining size on the mount point.
183 dictionary MountPointSizeStats {
184 // Approximate total available size on the mount point.
187 // Approximate remaining available size on the mount point.
188 double remainingSize;
191 // Information about a profile.
192 dictionary ProfileInfo {
193 // Profile ID. This is currently e-mail address of the profile.
196 // The name of the profile for display purpose.
197 DOMString displayName;
199 // True if the profile is the one running the current file manager instance.
200 // TODO(hirono): Remove the property because of the design change of
201 // multi-profile suuport.
202 boolean isCurrentProfile;
204 // Data URI of profile image;
208 // Mounted disk volume metadata.
209 dictionary VolumeMetadata {
210 // ID of the disk volume.
213 // Description of the profile where the volume belongs.
214 // TODO(hirono): Remove the property because of the design change of
215 // multi-profile suuport.
218 // Disk volume mount point path.
221 // The path to the mounted device, archive file or network resource.
222 DOMString? sourcePath;
224 // Type of the mounted volume.
225 VolumeType volumeType;
227 // Device type. Available if this is removable volume.
228 DeviceType? deviceType;
230 // Path to identify the device. This is consistent with DeviceEvent's
232 DOMString? devicePath;
234 // Label of the device.
235 DOMString? deviceLabel;
237 // Whether the device is parent or not (i.e. sdb rather than sdb1).
238 boolean? isParentDevice;
240 // Flag that specifies if volume is mounted in read-only mode.
243 // Additional data about mount, for example, that the filesystem is not
245 MountCondition? mountCondition;
248 // Payload data for mount event.
249 dictionary MountCompletedEvent {
250 // Is the event raised for mounting or unmounting.
251 MountCompletedEventType eventType;
253 // Event type that tells listeners if mount was successful or an error
254 // occurred. It also specifies the error.
255 MountCompletedStatus status;
257 // Metadata of the mounted volume.
258 VolumeMetadata volumeMetadata;
260 // Whether it is remount or not.
261 boolean isRemounting;
264 // Payload data for file transfer status updates.
265 dictionary FileTransferStatus {
266 // URL of file that is being transfered.
269 // File transfer progress state.
270 TransferState transferState;
272 // Defines file transfer direction.
273 TransferType transferType;
275 // Approximated completed portion of the transfer operation.
278 // Approximated total size of transfer operation.
282 // Error during the drive sync.
283 dictionary DriveSyncErrorEvent {
285 DriveSyncErrorType type;
287 // File URL of the entry that the error happens to.
291 // Payload data for copy status progress updates.
292 dictionary CopyProgressStatus {
293 // The type of the progress event.
294 CopyProgressStatusType type;
296 // URL for the entry currently being copied. This field is particularly useful
297 // when a directory copy is initiated with startCopy(). The field tells what
298 // file/directory in that directory is now being copied.
299 DOMString? sourceUrl;
301 // URL for the entry currently being created. This field is particularly
302 // useful when a directory copy is initiated with startCopy(). The field tells
303 // what file/directory in that directory is being created. Available only for
304 // end_copy_entry and success.
305 DOMString? destinationUrl;
307 // Number of processed bytes for the file currently being copied. Available
308 // only for "progress" event. To show the progress bar, a caller needs to
309 // pre-compute the size of files being copied for the file (not directory).
312 // FileError's code of the error. Available only for ERROR event.
316 // Payload data for file transfer cancel response.
317 dictionary FileTransferCancelStatus {
318 // URL of file that is being transfered.
321 // True if ongoing transfer operation was found and canceled.
325 // Directory change notification details.
326 dictionary FileWatchEvent {
327 // Specifies type of event that is raised.
328 FileWatchEventType eventType;
330 // An Entry object which represents a changed directory. The conversion into a
331 // kind of FileEntry object is done in
332 // file_browser_handler_custom_bindings.cc. For filesystem API's Entry
334 // href='http://www.w3.org/TR/file-system-api/#the-entry-interface'>The Entry
336 [instanceOf=Entry] object entry;
339 dictionary Preferences {
340 boolean driveEnabled;
341 boolean cellularDisabled;
342 boolean hostedFilesDisabled;
343 boolean use24hourClock;
344 boolean allowRedeemOffers;
347 dictionary PreferencesChange {
348 boolean? cellularDisabled;
349 boolean? hostedFilesDisabled;
352 dictionary SearchParams {
356 // ID of the search feed that should be fetched next. Value passed here should
357 // be gotten from previous searchDrive call. It can be empty for the initial
362 dictionary SearchMetadataParams {
363 // Search query. It can be empty. Any filename matches to an empty query.
366 // The type of entry that is needed. Default to ALL.
369 // Maximum number of results.
373 // Entry and Drive-related properties representing a search result.
374 dictionary SearchResult {
375 // A dictionary object which represents a Drive file. This will be converted
376 // into a kind of FileEntry object. See
377 // file_browser_handler_custom_bindings.cc for details. For filesystem API's
378 // Entry interface, see <a
379 // href='http://www.w3.org/TR/file-system-api/#the-entry-interface'>The Entry
381 [instanceOf=Entry] object entry;
383 // The base name of a Drive file that matched the search query. The matched
384 // sub strings are highlighted with <b> element. Meta characters are escaped
386 DOMString highlightedBaseName;
389 dictionary DriveConnectionState {
392 // Reasons of offline.
396 // Device event dispatched to listeners of onDeviceChaged. See also
397 // DeviceEventType to know when the event dispatched.
398 dictionary DeviceEvent {
399 // Event type of the device event.
400 DeviceEventType type;
401 // Device path to identify the device.
402 DOMString devicePath;
405 // Callback that does not take arguments.
406 callback SimpleCallback = void();
408 // |result| Result of the task execution.
409 callback ExecuteTaskCallback = void(TaskResult result);
411 // |tasks| The list of matched file URL patterns for this task.
412 callback GetFileTasksCallback = void(FileTask[] tasks);
414 // |result| Hash containing the string assets.
415 callback GetStringsCallback = void(object result);
417 // |success| True when file watch is successfully added.
418 callback AddFileWatchCallback = void(optional boolean success);
420 // |success| True when file watch is successfully removed.
421 callback RemoveFileWatchCallback = void(optional boolean success);
423 // |fileSystem| A DOMFileSystem instance for local file system access. null if
424 // |the caller has no appropriate permissions.
425 callback RequestFileSystemCallback = void(optional object fileSystem);
427 // |fileProperties| A dictionary containing properties of the requested entry.
428 callback GetDriveEntryPropertiesCallback =
429 void(DriveEntryProperties fileProperties);
431 // |localFilePaths| An array of the local file paths for the requested files,
432 // one entry for each file in fileUrls.
433 callback GetDriveFilesCallback = void(DOMString[] localFilePaths);
435 // |sourcePath| Source path of the mount.
436 callback AddMountCallback = void(DOMString sourcePath);
438 // |volumeMetadataList| The list of VolumeMetadata representing mounted volumes.
439 callback GetVolumeMetadataListCallback =
440 void(VolumeMetadata[] volumeMetadataList);
442 // |fileTransferCancelStatuses| The list of FileTransferCancelStatus.
443 callback CancelFileTransfersCallback =
444 void(FileTransferCancelStatus[] fileTransferCancelStatuses);
446 // |copyId| ID of the copy task. Can be used to identify the progress, and to
448 callback StartCopyCallback = void(long copyId);
450 // |sizeStats| Name/value pairs of size stats. Will be undefined if stats could
451 // not be determined.
452 callback GetSizeStatsCallback = void(optional MountPointSizeStats sizeStats);
454 callback GetPreferencesCallback = void(Preferences result);
457 // |nextFeed| ID of the feed that contains next chunk of the search result.
458 // Should be sent to the next searchDrive request to perform
459 // incremental search.
460 callback SearchDriveCallback =
461 void([instanceOf=Entry] object[] entries, DOMString nextFeed);
463 callback SearchDriveMetadataCallback = void(SearchResult[] results);
465 callback ZipSelectionCallback = void(optional boolean success);
467 callback GetDriveConnectionStateCallback = void(DriveConnectionState result);
469 // |result| true if the length is in the valid range, false otherwise.
470 callback ValidatePathNameLengthCallback = void(boolean result);
472 // |accessToken| OAuth2 access token, or an empty string if failed to fetch.
473 callback RequestAccessTokenCallback = void(DOMString accessToken);
475 // |accessToken| OAuth2 access token, or an empty string if failed to fetch.
476 callback RequestWebStoreAccessTokenCallback = void(DOMString accessToken);
478 // |shareUrl| Share Url for the sharing dialog.
479 callback GetShareUrlCallback = void(DOMString shareUrl);
481 // |profiles| List of profile information.
482 // |runningProfile| ID of the profile that runs the application instance.
483 // |showingProfile| ID of the profile that shows the application window.
484 callback GetProfilesCallback = void(ProfileInfo[] profiles,
485 DOMString runningProfile,
486 DOMString displayProfile);
488 interface Functions {
489 // Logout the current user for navigating to the re-authentication screen for
490 // the Google account.
491 static void logoutUserForReauthentication();
493 // Cancels file selection.
494 static void cancelDialog();
496 // Executes file browser task over selected files.
497 // |taskId| The unique identifier of task to execute.
498 // |fileUrls| Array of file URLs
500 static void executeTask(DOMString taskId,
501 DOMString[] fileUrls,
502 optional ExecuteTaskCallback callback);
504 // Sets the default task for the supplied MIME types and suffixes of the
505 // supplied file URLs. Lists of MIME types and URLs may contain duplicates.
506 // |taskId| The unique identifier of task to mark as default.
507 // |fileUrls| Array of selected file URLs to extract suffixes from.
508 // |mimeTypes| Array of selected file MIME types.
510 static void setDefaultTask(DOMString taskId,
511 DOMString[] fileUrls,
512 optional DOMString[] mimeTypes,
513 optional SimpleCallback callback);
515 // Gets the list of tasks that can be performed over selected files.
516 // |fileUrls| Array of selected file URLs
517 // |mimeTypes| Array of selected file MIME types
519 static void getFileTasks(DOMString[] fileUrls,
520 DOMString[] mimeTypes,
521 GetFileTasksCallback callback);
523 // Gets localized strings and initialization data.
525 static void getStrings(GetStringsCallback callback);
528 // |fileUrl| URL of file to watch
530 static void addFileWatch(DOMString fileUrl, AddFileWatchCallback callback);
532 // Removes file watch.
533 // |fileUrl| URL of watched file to remove
535 static void removeFileWatch(DOMString fileUrl,
536 RemoveFileWatchCallback callback);
538 // Requests access to a file system volume.
539 // |volumeId| The ID of the file system volume to request. The volume ID is
540 // delivered to JavaScript as part of VolumeMetadata. By specifying
541 // "compatible", this function behaves in the compatible mode, where the
542 // returned FileSystem object gives access to all file system volumes such
543 // as Downloads folder and removal media like SD cards (i.e. all volumes
544 // are provided inside the single FileSystem object). In the new
545 // "per-volume FileSystem object model" crbug.com/322305, a separate
546 // FileSystem object is created for each volume. "compatible" parameter
547 // will be removed once Files.app is switched to the per-volume FileSystem
550 static void requestFileSystem(DOMString volumeId,
551 RequestFileSystemCallback callback);
553 // Selects multiple files.
554 // |selectedPaths| Array of selected paths
555 // |shouldReturnLocalPath| true if paths need to be resolved to local paths.
557 static void selectFiles(DOMString[] selectedPaths,
558 boolean shouldReturnLocalPath,
559 SimpleCallback callback);
562 // |selectedPath| A selected path
563 // |index| Index of Filter
564 // |forOpening| true if paths are selected for opening. false if for saving.
565 // |shouldReturnLocalPath| true if paths need to be resolved to local paths.
567 static void selectFile(DOMString selectedPath,
570 boolean shouldReturnLocalPath,
571 SimpleCallback callback);
573 // Requests Drive file properties for a file.
574 // |fileUrl| URL of a file
576 static void getDriveEntryProperties(DOMString fileUrl,
577 GetDriveEntryPropertiesCallback callback);
579 // Pins/unpins a Drive file in the cache.
580 // |fileUrl| URL of a file to pin/unpin.
581 // |pin| Pass true to pin the file.
582 // |callback| Completion callback. $ref:runtime.lastError will be set if there
584 static void pinDriveFile(DOMString fileUrl,
586 optional SimpleCallback callback);
589 // |fileUrls| Array of Drive file URLs to get.
591 static void getDriveFiles(DOMString[] fileUrls,
592 GetDriveFilesCallback callback);
594 // Mount a resource or a file.
595 // |source| Mount point source. For compressed files it is relative file path
596 // within external file system
598 static void addMount(DOMString source, AddMountCallback callback);
600 // Unmounts a mounted resource.
601 // |volumeId| An ID of the volume.
602 static void removeMount(DOMString volumeId);
604 // Get the list of mounted volumes.
606 static void getVolumeMetadataList(GetVolumeMetadataListCallback callback);
608 // Cancels ongoing file transfers for selected files.
609 // |fileUrls| Array of files for which ongoing transfer should be canceled.
611 static void cancelFileTransfers(DOMString[] fileUrls,
612 CancelFileTransfersCallback callback);
614 // Starts to copy an entry. If the source is a directory, the copy is done
616 // |sourceUrl| URL of the source entry to be copied.
617 // |parent| URL of the destination directory.
618 // |newName| Name of the new entry. It shouldn't contain '/'.
619 // |callback| Completion callback.
620 static void startCopy(DOMString sourceUrl,
623 StartCopyCallback callback);
625 // Cancels the running copy task.
626 // |copyId| ID of the copy task to be cancelled.
627 // |callback| Completion callback of the cancel.
628 static void cancelCopy(long copyId, optional SimpleCallback callback);
630 // Retrieves total and remaining size of a mount point.
631 // |volumeId| ID of the volume to be checked.
633 static void getSizeStats(DOMString volumeId, GetSizeStatsCallback callback);
635 // Formats a mounted volume.
636 // |volumeId| ID of the volume to be formatted.
637 static void formatVolume(DOMString volumeId);
639 // Retrieves file manager preferences.
641 static void getPreferences(GetPreferencesCallback callback);
643 // Sets file manager preferences.
645 static void setPreferences(PreferencesChange changeInfo);
647 // Performs drive content search.
650 static void searchDrive(SearchParams searchParams,
651 SearchDriveCallback callback);
653 // Performs drive metadata search.
656 static void searchDriveMetadata(SearchMetadataParams searchParams,
657 SearchDriveMetadataCallback callback);
659 // Create a zip file for the selected files.
660 // |dirURL| URL of the directory containing the selected files.
661 // |selectionUrls| URLs of the selected files. The files must be under the
662 // directory specified by dirURL.
663 // |destName| Name of the destination zip file. The zip file will be created
664 // under the directory specified by dirURL.
666 static void zipSelection(DOMString dirURL,
667 DOMString[] selectionUrls,
669 optional ZipSelectionCallback callback);
671 // Retrieves the state of the current drive connection.
673 static void getDriveConnectionState(GetDriveConnectionStateCallback callback);
675 // Checks whether the path name length fits in the limit of the filesystem.
676 // |parent_directory_url| The URL of the parent directory entry.
677 // |name| The name of the file.
678 // |callback| Called back when the check is finished.
679 static void validatePathNameLength(DOMString parent_directory_url,
681 ValidatePathNameLengthCallback callback);
683 // Changes the zoom factor of the Files.app.
684 // |operation| Zooming mode.
685 static void zoom(ZoomOperationType operation);
687 // Requests a Drive API OAuth2 access token.
688 // |refresh| Whether the token should be refetched instead of using the cached
691 static void requestAccessToken(boolean refresh,
692 RequestAccessTokenCallback callback);
694 // Requests a Webstore API OAuth2 access token.
696 static void requestWebStoreAccessToken(
697 RequestWebStoreAccessTokenCallback callback);
699 // Requests a share dialog url for the specified file.
700 // |url| Url for the file.
702 static void getShareUrl(DOMString url, GetShareUrlCallback callback);
704 // Requests to install a webstore item.
705 // |item_id| The id of the item to install.
707 static void installWebstoreItem(DOMString item_id,
708 SimpleCallback callback);
710 // Obtains a list of profiles that are logged-in.
711 static void getProfiles(GetProfilesCallback callback);
713 // Moves the window to other user's desktop.
714 static void visitDesktop(DOMString profileId,
715 optional SimpleCallback callback);
719 static void onMountCompleted(MountCompletedEvent event);
721 static void onFileTransfersUpdated(FileTransferStatus[] event);
723 static void onCopyProgress(long copyId, CopyProgressStatus status);
725 static void onDirectoryChanged(FileWatchEvent event);
727 static void onPreferencesChanged();
729 static void onDriveConnectionStatusChanged();
731 static void onDeviceChanged(DeviceEvent event);
733 static void onDriveSyncError(DriveSyncErrorEvent event);
735 // Dispatched when a profile is added.
736 static void onProfileAdded();
738 // Dispatched when any window moves another desktop.
739 // TODO(hirono): Add information which window is moved.
740 static void onDesktopChanged();