Add events for configuring and adding new providers to FSP API.

chrome/common/extensions/api/file_system_provider.idl

 // Copyright 2013 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 // Use the <code>chrome.fileSystemProvider</code> API to create file systems,
 // that can be accessible from the file manager on Chrome OS.
 [implemented_in="chrome/browser/chromeos/extensions/file_system_provider/file_system_provider_api.h"]
 namespace fileSystemProvider {
   // 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>
@@ skipping 26 matching lines @@
 
   // Type of a change detected on the observed directory.
   enum ChangeType {
     CHANGED,
     DELETED
   };
 
   // Source of the file system data.
   enum FileSystemSource {
     // The file system is handling a file, eg. an archive file obtained via the
-    // <code>OnLaunched</code> event and the <code>file_handlers</code> manifest
+    // <code>onLaunched</code> event and the <code>file_handlers</code> manifest
     // entry.
     FILE,
 
     // The file system contents are fetched from an external device, such as a
     // USB device, but not via <code>file_handlers</code>.
     DEVICE,
 
     // The file system is network based. The contents are obtained from another
     // server or local network. Eg. cloud services.
     NETWORK
@@ skipping 106 matching lines @@
   // 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;
+
+    // The unique identifier of this request.
     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;
@@ skipping 241 matching lines @@
     // 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;
   };
 
+  // Options for the <code>onConfigureRequested()</code> event.
+  dictionary ConfigureRequestedOptions {
+    // The identifier of the file system to be configured.
+    DOMString fileSystemId;
+
+    // The unique identifier of this request.
+    long requestId;
+  };
+
   // Callback to receive the result of getAll() function.
   callback GetAllCallback = void(FileSystemInfo[] fileSystems);
 
   // Callback to receive the result of get() function.
   callback GetCallback = void(FileSystemInfo fileSystem);
 
   // 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.
@@ skipping 195 matching lines @@
     // 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 showing a configuration dialog for <code>fileSystemId</code>
+    // is requested. If it's not supported, then this event must not be handled.
+    [maxListeners=1] static void onConfigureRequested(

[benwells, 2015/04/16 00:29:35]

Should this be nodoc until the implementation is real?

[mtomasz, 2015/04/16 01:07:28]

This is going to be shipped in M44. I can add [nodoc], but there is already
updated documentation in fileBrowserPrivate.html which refers to these methods.
I could revert that documentation changes and add [nodoc] if you prefer.

[benwells, 2015/04/16 01:15:32]

Having documentation for new things that work is fine, as the documentation
should make it clear that the new thing is only available in whatever release it
comes in. As these functions are currently unimplemented / half implemented
(that's my understanding) they shouldn't be documented anywhere. If they are,
some poor developer will think the API is ready on dev channel and try to use
it.

Does that make sense?

[mtomasz, 2015/04/16 01:24:16]

Makes sense. I reverted the documentation and added nodoc.

+        ConfigureRequestedOptions options,
+        ProviderSuccessCallback successCallback,
+        ProviderErrorCallback errorCallback);
+
+    // 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 <code>onLaunched</code> should be handled in order to
+    // mount new file systems when a file is opened.
+    [maxListeners=1] static void onMountRequested(
+        ProviderSuccessCallback successCallback,

[benwells, 2015/04/16 00:29:36]

What about options? I'd have thought providing options to this (e.g. url for a
web based file system) makes sense.

[mtomasz, 2015/04/16 01:07:28]

It's responsibility of the providing extension to ask user for details such as
urls, credentials, ports, captchas, etc. As the options are different for each
providing extension, we decided to put the responsibility to show the UI on
providing extensions, rather than to try to create some general purpose dialog
on the File System Provider API implementation side.

In most cases, for onMountRequest providing extensions will show a dialog for
credentials/urls and whatever is required to make a mount. onConfigureRequested
will show the same dialog but with prefilled fields for already mounted file
system.

+        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);
   };
 };