Switch the downloads API over to IDL/json_schema_compiler

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;
+  };
+
+  [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.
+    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
+    // <code>name</code> and either <code>value</code> or
+    // <code>binaryValue</code>, restricted to those allowed by XMLHttpRequest.
+    HeaderNameValuePair[]? headers;
+
+    // post body
+    DOMString? body;
+  };
+
+  // 'file': The download's filename is suspicious.
+  // 'url': The download's URL is known to be malicious.
+  // 'content': The downloaded file is known to be malicious.
+  // 'uncommon': The download's URL is not commonly downloaded and could be
+  // dangerous.
+  // 'safe': The download presents no known danger to the user's computer.
+  // These string constants will never change, however the set of DangerTypes
+  // may change.
+  enum DangerType {file, url, content, uncommon, safe};
+
+  // 'in_progress': the download is currently receiving data from the server.
+  // 'interrupted': an error broke the connection with the file host.
+  // 'complete': the download completed successfully.
+  // These string constants will never change, however the set of States may
+  // change.
+  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
+    DOMString url;
+
+    // absolute local path
+    DOMString filename;
+
+    // False if this download is recorded in the history, true if it is not
+    // recorded.
+    boolean incognito;
+
+    // Indication of whether this download is thought to be safe or known to be
+    // suspicious.
+    DangerType danger;
+
+    // true if the user has accepted the download's danger.
+    boolean? dangerAccepted;
+
+    // The file's MIME type.
+    DOMString mime;
+
+    // Number of milliseconds between the unix epoch and when this download
+    // began.
+    long startTime;
+
+    // Number of milliseconds between the unix epoch and when this download
+    // ended.
+    long? endTime;
+
+    // Indicates whether the download is progressing, interrupted, or complete.
+    State state;
+
+    // true if the download has stopped reading data from the host, but kept the
+    // connection open.
+    boolean paused;
+
+    // Number indicating why a download was interrupted.
+    long? error;
+
+    // Number of bytes received so far from the host, without considering file
+    // compression.
+    long bytesReceived;
+
+    // Number of bytes in the whole file, without considering file compression,
+    // or -1 if unknown.
+    long totalBytes;
+
+    // Number of bytes in the whole file post-decompression, or -1 if unknown.
+    long fileSize;
+  };
+
+  [inline_doc] dictionary DownloadQuery {
+    // This space-separated string of search terms that may be grouped using
+    // quotation marks limits results to downloads whose filename or url 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 downloads that started before the given ms since the
+    // epoch.
+    long? startedBefore;
+
+    // Limits results to downloads that started after the given ms since the
+    // epoch.
+    long? startedAfter;
+
+    // Limits results to downloads that ended before the given ms since the
+    // epoch.
+    long? endedBefore;
+
+    // Limits results to downloads that ended after the given ms since the
+    // epoch.
+    long? endedAfter;
+
+    // Limits results to downloads whose totalBytes is greater than the given
+    // integer.
+    long? totalBytesGreater;
+
+    // Limits results to downloads whose totalBytes is less than the given
+    // integer.
+    long? totalBytesLess;
+
+    // Limits results to downloads whose filename matches the given regular
+    // expression.
+    DOMString? filenameRegex;
+
+    // Limits results to downloads whose url matches the given regular
+    // expression.
+    DOMString? urlRegex;
+
+    // Setting this integer limits the number of results. Otherwise, all
+    // matching DownloadItems will be returned.
+    long? limit;
+
+    // Setting this string to a DownloadItem property sorts the DownloadItems
+    // prior to applying the above filters. For example, setting
+    // <code>orderBy='startTime'</code> sorts the DownloadItems by their start
+    // time in ascending order. To specify descending order, prefix
+    // <code>orderBy</code> with a hyphen: '-startTime'.

[asargent_no_longer_on_chrome, 2012/07/02 23:43:48]

From the implemenation, it looks like you allow specifying secondary sort orders
by passing more field names in this string with a space as separator. Did you
intentionally omit that from the documentation here? 

(Also, the idiomatic thing to do with javascript would be to make this parameter
either a single string or array of strings, instead of using an inline separator
character. The way to do this with IDL would be to use a "union type":
http://dev.w3.org/2006/webapi/WebIDL/#idl-union but I don't think we support
that yet. I'm sure we will want to add this eventually, but if happened to want
to take this on in a follow-up CL or something that would be awesome). 

[benjhayden, 2012/07/09 20:18:09]

Filed a bug for myself: http://crbug.com/135636

+    DOMString? orderBy;
+
+    // An identifier that is persistent across browser sessions.
+    long? id;
+
+    // absolute URL
+    DOMString? url;
+
+    // absolute local path
+    DOMString? filename;
+
+    // Indication of whether this download is thought to be safe or known to be
+    // suspicious.
+    DangerType? danger;
+
+    // true if the user has accepted the download's danger.
+    boolean? dangerAccepted;
+
+    // The file's MIME type.
+    DOMString? mime;
+
+    // Number of milliseconds between the unix epoch and when this download
+    // began.
+    long? startTime;
+
+    // Number of milliseconds between the unix epoch and when this download
+    // ended.
+    long? endTime;
+
+    // Indicates whether the download is progressing, interrupted, or complete.
+    State? state;
+
+    // true if the download has stopped reading data from the host, but kept the
+    // connection open.
+    boolean? paused;
+
+    // Number indicating why a download was interrupted.
+    long? error;
+
+    // Number of bytes received so far from the host, without considering file
+    // compression.
+    long? bytesReceived;
+
+    // Number of bytes in the whole file, without considering file compression,
+    // or -1 if unknown.
+    long? totalBytes;
+
+    // Number of bytes in the whole file post-decompression, or -1 if unknown.
+    long? fileSize;
+  };
+
+  [inline_doc] dictionary DownloadStringDiff {
+    DOMString? previous;
+    DOMString? current;
+  };
+
+  [inline_doc] dictionary DownloadLongDiff {
+    long? previous;
+    long? current;
+  };
+
+  [inline_doc] dictionary DownloadBooleanDiff {
+    boolean? previous;
+    boolean? current;
+  };
+
+  // Encapsulates a change in a DownloadItem.
+  [inline_doc] dictionary DownloadDelta {
+    // An identifier that is persistent across browser sessions.
+    long id;
+
+    // Describes a change in a DownloadItem's <code>url</code>.
+    DownloadStringDiff? url;
+
+    // Describes a change in a DownloadItem's <code>filename</code>.
+    DownloadStringDiff? filename;
+
+    // Describes a change in a DownloadItem's <code>danger</code>.
+    DownloadStringDiff? danger;
+
+    // Describes a change in a DownloadItem's <code>dangerAccepted</code>.
+    DownloadBooleanDiff? dangerAccepted;
+
+    // Describes a change in a DownloadItem's <code>mime</code>.
+    DownloadStringDiff? mime;
+
+    // Describes a change in a DownloadItem's <code>startTime</code>.
+    DownloadLongDiff? startTime;
+
+    // Describes a change in a DownloadItem's <code>endTime</code>.
+    DownloadLongDiff? endTime;
+
+    // Describes a change in a DownloadItem's <code>state</code>.
+    DownloadStringDiff? state;
+
+    // Describes a change in a DownloadItem's <code>paused</code>.
+    DownloadBooleanDiff? paused;
+
+    // Describes a change in a DownloadItem's <code>error</code>.
+    DownloadLongDiff? error;
+
+    // Describes a change in a DownloadItem's <code>totalBytes</code>.
+    DownloadLongDiff? totalBytes;
+
+    // Describes a change in a DownloadItem's <code>fileSize</code>.

[asargent_no_longer_on_chrome, 2012/07/02 23:43:48]

Optional suggestion: Repeating the word "DownloadItem" in each of these
descriptions seems verbose. Can you simplify these to just:

// The change in url, if any.
...
// The change in filename, if any.
...

etc.

[benjhayden, 2012/07/09 20:18:09]

Done.

+    DownloadLongDiff? fileSize;
+  };
+
+  [inline_doc] dictionary GetFileIconOptions {
+    // 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);
+
+  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 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 <a
+    // href='extension.html#property-lastError'>chrome.extension.lastError</a>
+    // will contain a descriptive string. The error strings are not guaranteed
+    // to remain backwards compatible between releases. You must not parse it.
+    // |options|: What to download and how.
+    // |callback|: Called with the id of the new DownloadItem.
+    static void download(DownloadOptions options,
+                         optional DownloadCallback callback);
+
+    // Find DownloadItems. Set <code>query</code> to the empty object to get all
+    // DownloadItems. To get a specific DownloadItem, set only the
+    // <code>id</code> field.
+    static void search(DownloadQuery query, SearchCallback callback);
+
+    // Pause the download. If the request was successful the download is in a
+    // paused state. Otherwise <a
+    // href='extension.html#property-lastError'>chrome.extension.lastError</a>
+    // contains an error message. The request will fail if the download is not
+    // active.
+    // |downloadId|: The id of the download to pause.
+    // |callback|: Called when the pause request is completed. 
+    static void pause(long downloadId, optional NullCallback callback);
+
+    // Resume a paused download. If the request was successful the download is
+    // in progress and unpaused. Otherwise <a
+    // href='extension.html#property-lastError'>chrome.extension.lastError</a>
+    // contains an error message. The request will fail if the download is not
+    // active.
+    // |downloadId|: The id of the download to resume.
+    // |callback|: Called when the resume request is completed.
+    static void resume(long downloadId, optional NullCallback callback);
+
+    // Cancel a download. When <code>callback</code> is run, the download is
+    // cancelled, completed, interrupted or doesn't exist anymore.
+    // |downloadId|: The id of the download to cancel.
+    // |callback|: Called when the cancel request is completed.
+    static void cancel(long downloadId, optional NullCallback callback);
+
+    // Retrieve an icon for the specified download. For new downloads, file
+    // icons are available after the onCreated event has been received. The
+    // image returned by this function while a download is in progress may be
+    // different from the image returned after the download is complete. Icon
+    // retrieval is done by querying the underlying operating system or toolkit
+    // depending on the platform. The icon that is returned will therefore
+    // depend on a number of factors including state of the download, platform,
+    // registered file types and visual theme. If a file icon cannot be
+    // determined, <a
+    // href='extension.html#property-lastError'>chrome.extension.lastError</a>
+    // will contain an error message.
+    // |downloadId|: The identifier for the download.
+    // |callback|: A URL to an image that represents the download.
+    static void getFileIcon(long downloadId,
+                            optional GetFileIconOptions options,
+                            GetFileIconCallback callback);
+
+    // Erase matching DownloadItems from history
+    [nodoc] static void erase(DownloadQuery query, optional EraseCallback callback);
+
+    // TODO(benjhayden) Comment.
+    [nodoc] static void setDestination(long downloadId, DOMString relativePath);
+
+    // Prompt the user to either accept or cancel a dangerous download.
+    // <code>acceptDanger()</code> does not automatically accept dangerous
+    // downloads.
+    [nodoc] static void acceptDanger(long downloadId);
+
+    // Show the downloaded file in its folder in a file manager.
+    [nodoc] static void show(long downloadId);
+
+    // Open the downloaded file.
+    [nodoc] static void open(long downloadId);
+
+    // Initiate dragging the file to another application.
+    [nodoc] static void drag(long downloadId);
+  };
+
+  interface Events {
+    // This event fires with the DownloadItem object when a download begins.
+    static void onCreated(DownloadItem downloadItem);
+
+    // Fires with the download id when a download is erased from history.
+    static void onErased(long downloadId);
+
+    // When any of a DownloadItem's properties except <code>bytesReceived</code>
+    // changes, this event fires with the download id and an object containing
+    // the properties that changed.
+    static void onChanged(DownloadDelta downloadDelta);
+  };
+};