Implement chrome.downloads.onDeterminingFilename()

chrome/common/extensions/api/downloads.idl

 // Copyright (c) 2012 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.
 
 [permissions=downloads]
 namespace downloads {
   [inline_doc] dictionary HeaderNameValuePair {
     // Name of the HTTP header.
     DOMString name;
 
     // Value of the HTTP header.
     DOMString value;
   };
 
+  // $ref:onDeterminingFilename listeners may pass a $ref:FilenameSuggestion
+  // object to <code>suggest()</code> in order to override a download's target
+  // filename.
+  dictionary FilenameSuggestion {
+    // The $ref:DownloadItem's new target $ref:DownloadItem.filename, as a path
+    // relative to the user's default Downloads directory, possibly containing
+    // subdirectories. Absolute paths, empty paths, and paths containing
+    // back-references ".." will be ignored.
+    DOMString filename;
+
+    // Whether to overwrite any existing files.
+    boolean? overwrite;
+  };
+
   [inline_doc] enum HttpMethod {GET, POST};
 
   [inline_doc] dictionary DownloadOptions {
     // The URL to download.
     DOMString url;
 
     // A file path relative to the Downloads directory to contain the downloaded
-    // file.
+    // file. See $ref:onDeterminingFilename for how to dynamically suggest a
+    // filename after the file's MIME type and a tentative filename have been
+    // determined.
     DOMString? filename;
 
     // Use a file-chooser to allow the user to select a filename.
     boolean? saveAs;
 
     // The HTTP method to use if the URL uses the HTTP[S] protocol.
     HttpMethod? method;
 
     // Extra HTTP headers to send with the request if the URL uses the HTTP[s]
     // protocol. Each header is represented as a dictionary containing the keys
@@ skipping 273 matching lines @@
     // The size of the icon.  The returned icon will be square with dimensions
     // size * size pixels.  The default size for the icon is 32x32 pixels.
     [legalValues=(16,32)] long? size;
   };
 
   callback DownloadCallback = void(long downloadId);
   callback SearchCallback = void(DownloadItem[] results);
   callback EraseCallback = void(long[] erasedIds);
   callback NullCallback = void();
   callback GetFileIconCallback = void(optional DOMString iconURL);
+  callback SuggestFilenameCallback = void(
+    optional FilenameSuggestion suggestion);
 
   interface Functions {
     // Download a URL. If the URL uses the HTTP[S] protocol, then the request
     // will include all cookies currently set for its hostname. If both
     // <code>filename</code> and <code>saveAs</code> are specified, then the
     // Save As dialog will be displayed, pre-populated with the specified
     // <code>filename</code>. If the download started successfully,
     // <code>callback</code> will be called with the new $ref:DownloadItem's
     // <code>downloadId</code>. If there was an error starting the download,
     // then <code>callback</code> will be called with
-    // <code>downloadId=undefined</code> and
-    // $ref:runtime.lastError
-    // will contain a descriptive string. The error strings are not guaranteed
-    // to remain backwards compatible between releases. You must not parse it.
+    // <code>downloadId=undefined</code> and $ref:runtime.lastError will contain
+    // a descriptive string. The error strings are not guaranteed to remain
+    // backwards compatible between releases. Extensions must not parse it.
     // |options|: What to download and how.
     // |callback|: Called with the id of the new $ref:DownloadItem.
     static void download(DownloadOptions options,
                          optional DownloadCallback callback);
 
     // Find $ref:DownloadItem. Set
     // <code>query</code> to the empty object to get all
     // $ref:DownloadItem. To get a specific
     // $ref:DownloadItem, set only the <code>id</code>
     // field.
@@ skipping 49 matching lines @@
 
     // Show the downloaded file in its folder in a file manager.
     // |downloadId|: The identifier for the downloaded file.
     static void show(long downloadId);
 
     // Erase matching $ref:DownloadItem from history. An $ref:onErased event
     // will fire for each $ref:DownloadItem that matches <code>query</code>,
     // then <code>callback</code> will be called.
     static void erase(DownloadQuery query, optional EraseCallback callback);
 
-    // TODO(benjhayden) Comment.
-    [nodoc] static void setDestination(long downloadId, DOMString relativePath);
-
     // Prompt the user to accept a dangerous download. Does not automatically
     // accept dangerous downloads. If the download is accepted, then an
     // $ref:onChanged event will fire, otherwise nothing will happen.  When all
     // the data is fetched into a temporary file and either the download is not
     // dangerous or the danger has been accepted, then the temporary file is
     // renamed to the target filename, the |state| changes to 'complete', and
     // $ref:onChanged fires.
     // |downloadId|: The identifier for the $ref:DownloadItem.
     static void acceptDanger(long downloadId);
 
     // Initiate dragging the downloaded file to another application.
     static void drag(long downloadId);
   };
 
   interface Events {
     // This event fires with the $ref:DownloadItem
     // object when a download begins.
     static void onCreated(DownloadItem downloadItem);
 
     // Fires with the <code>downloadId</code> when a download is erased from
     // history.
     // |downloadId|: The <code>id</code> of the $ref:DownloadItem that was erased.
     static void onErased(long downloadId);
 
     // When any of a $ref:DownloadItem's properties
     // except <code>bytesReceived</code> changes, this event fires with the
     // <code>downloadId</code> and an object containing the properties that changed.
     static void onChanged(DownloadDelta downloadDelta);
+
+    // During the filename determination process, extensions will be given the
+    // opportunity to override the target $ref:DownloadItem.filename. Each
+    // extension may not register more than one listener for this event. Each
+    // listener must call <code>suggest</code> exactly once, either
+    // synchronously or asynchronously. If the listener calls
+    // <code>suggest</code> asynchronously, then it must return
+    // <code>true</code>. If the listener neither calls <code>suggest</code>
+    // synchronously nor returns <code>true</code>, then <code>suggest</code>
+    // will be called automatically. The $ref:DownloadItem will not complete
+    // until all listeners have called <code>suggest</code>. Listeners may call
+    // <code>suggest</code> without any arguments in order to allow the download
+    // to use <code>downloadItem.filename</code> for its filename, or pass a
+    // $ref:FilenameSuggestion object to <code>suggest</code> in order to
+    // override the target filename. If more than one extension overrides the
+    // filename, then the last extension installed whose listener passes a
+    // $ref:FilenameSuggestion object to <code>suggest</code> wins. In order to
+    // avoid confusion regarding which extension will win, users should not
+    // install extensions that may conflict. If the download is initiated by
+    // $ref:download and the target filename is known before the MIME type and
+    // tentative filename have been determined, use
+    // $ref:DownloadOptions.filename instead.
+    [maxListeners=1] static void onDeterminingFilename(
+        DownloadItem downloadItem, SuggestFilenameCallback suggest);
   };
 };