Expose final download URL (actual url after redirects) in the extension API.

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.
 
 // Use the <code>chrome.downloads</code> API to programmatically initiate,
 // monitor, manipulate, and search for downloads.
 [permissions=downloads]
 namespace downloads {
   [inline_doc] dictionary HeaderNameValuePair {
     // Name of the HTTP header.
@@ skipping 116 matching lines @@
   //     <dt>complete</dt>
   //     <dd>The download completed successfully.</dd>
   // </dl>
   enum State {in_progress, interrupted, complete};
 
   // The state of the process of downloading a file.
   dictionary DownloadItem {
     // An identifier that is persistent across browser sessions.
     long id;
 
-    // Absolute URL.
+    // The absolute URL that this download initiated from, before any
+    // redirects.
     DOMString url;
 
+    // The absolute URL that this download is being made from, after all
+    // redirects.
+    DOMString finalUrl;
+
     // Absolute URL.
     DOMString referrer;
 
     // Absolute local path.
     DOMString filename;
 
     // False if this download is recorded in the history, true if it is not
     // recorded.
     boolean incognito;
 
@@ skipping 69 matching lines @@
     DOMString? byExtensionId;
 
     // The localized name of the extension that initiated this download if this
     // download was initiated by an extension. May change if the extension
     // changes its name or if the user changes their locale.
     DOMString? byExtensionName;
   };
 
   [inline_doc] dictionary DownloadQuery {
     // This array of search terms limits results to $(ref:DownloadItem) whose
-    // <code>filename</code> or <code>url</code> contain all of the search terms
-    // that do not begin with a dash '-' and none of the search terms that do
-    // begin with a dash.
+    // <code>filename</code> or <code>url</code> or <code>finalUrl</code>
+    // contain all of the search terms that do not begin with a dash '-' and
+    // none of the search terms that do begin with a dash.
     DOMString[]? query;
 
     // Limits results to $(ref:DownloadItem) that
     // started before the given ms since the epoch.
     DOMString? startedBefore;
 
     // Limits results to $(ref:DownloadItem) that
     // started after the given ms since the epoch.
     DOMString? startedAfter;
 
@@ skipping 14 matching lines @@
     double? totalBytesLess;
 
     // Limits results to $(ref:DownloadItem) whose
     // <code>filename</code> matches the given regular expression.
     DOMString? filenameRegex;
 
     // Limits results to $(ref:DownloadItem) whose
     // <code>url</code> matches the given regular expression.
     DOMString? urlRegex;
 
+    // Limits results to $(ref:DownloadItem) whose
+    // <code>finalUrl</code> matches the given regular expression.
+    DOMString? finalUrlRegex;
+
     // The maximum number of matching $(ref:DownloadItem) returned. Defaults to
     // 1000. Set to 0 in order to return all matching $(ref:DownloadItem). See
     // $(ref:search) for how to page through results.
     long? limit;
 
     // Set elements of this array to $(ref:DownloadItem) properties in order to
     // sort search results. For example, setting
     // <code>orderBy=['startTime']</code> sorts the $(ref:DownloadItem) by their
     // start time in ascending order. To specify descending order, prefix with a
     // hyphen: '-startTime'.
     DOMString[]? orderBy;
 
     // The <code>id</code> of the $(ref:DownloadItem) to query.
     long? id;
 
-    // Absolute URL.
+    // The absolute URL that this download initiated from, before any
+    // redirects.
     DOMString? url;
 
+    // The absolute URL that this download is being made from, after all
+    // redirects.
+    DOMString? finalUrl;
+
     // Absolute local path.
     DOMString? filename;
 
     // Indication of whether this download is thought to be safe or known to be
     // suspicious.
     DangerType? danger;
 
     // The file's MIME type.
     DOMString? mime;
 
@@ skipping 42 matching lines @@
     boolean? previous;
     boolean? current;
   };
 
   // Encapsulates a change in a DownloadItem.
   [inline_doc] dictionary DownloadDelta {
     // The <code>id</code> of the $(ref:DownloadItem)
     // that changed.
     long id;
 
-    // The change in <code>url</code>, if any.
+    // The <code>url</code> of download, only if previously unknown.
     StringDelta? url;
 
+    // The <code>finalUrl</code> of download, only if previously unknown.
+    StringDelta? finalUrl;
+
     // The change in <code>filename</code>, if any.
     StringDelta? filename;
 
     // The change in <code>danger</code>, if any.
     StringDelta? danger;
 
-    // The change in <code>mime</code>, if any.
+    // The <code>mime</code> of download, only if previously unknown.
     StringDelta? mime;
 
-    // The change in <code>startTime</code>, if any.
+    // The <code>startTime</code> of download, only if previously unknown.
     StringDelta? startTime;
 
     // The change in <code>endTime</code>, if any.
     StringDelta? endTime;
 
     // The change in <code>state</code>, if any.
     StringDelta? state;
 
     // The change in <code>canResume</code>, if any.
     BooleanDelta? canResume;
@@ skipping 147 matching lines @@
 
     // 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> and <code>estimatedEndTime</code> changes,
     // this event fires with the <code>downloadId</code> and an object
-    // containing the properties that changed.
+    // containing the properties that changed. This event can contain all
+    // previously unreported download item data, it will be fired in two cases:
+    // for downloads that already existed before event listener was added or
+    // for dangerous download that was accepted and is not temporary anymore.
+    // Those are the only cases where fields <code>url</code>,
+    // <code>finalUrl</code>, <code>mime</code> and <code>startTime</code> can
+    // appear in download delta, those properties cannot change after download
+    // item creation. Download delta fields in such cases will contain only
+    // current value.

[asanka, 2016/07/07 19:28:31]

Let's not document this behavior; it's a bug and should be fixed at some point
(could you file a bug?).

Even if the bug were not not be fixed, the behavior changes depending on whether
there was some other extension listening for the affected events (i.e. if there
was another extension listening, then the new extension that adds a listener
will not see any of the additional fields.)

[mharanczyk, 2016/07/08 10:10:54]

Reverted download delta documentation back to original. Created crbug.com/626626

     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
     // <code>suggestion</code> 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
     // <code>suggestion</code> 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, pass <code>filename</code> to
     // $(ref:download) instead.
     [maxListeners=1] static void onDeterminingFilename(
         DownloadItem downloadItem, SuggestFilenameCallback suggest);
   };
 };