Move chrome.downloads out of experimental to dev

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 {
+  [nodoc] dictionary HeaderNameValuePair {
+    // Name of the HTTP header.
+    DOMString name;
+
+    // Value of the HTTP header.
+    DOMString value;
+  };
+
+  [nodoc] 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.
+    [legalValues=(GET, POST)] DOMString? method;

[asargent_no_longer_on_chrome, 2012/06/12 19:08:16]

we can use enums for string values, just not integer/float/etc.

So this should probably be:

enum Method { GET, POST };

[nodoc] dictionary DownloadOptions {
  ...
  Method method;
  ...
};

[benjhayden, 2012/06/12 20:15:42]

Done.

+
+    // 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.
+    [inline_doc] 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;
+  };
+
+  [nodoc] 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'.
+    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;
+  };
+
+  [nodoc] dictionary DownloadStringDiff {
+    DOMString? previous;
+    DOMString? current;
+  };
+
+  [nodoc] dictionary DownloadLongDiff {
+    long? previous;
+    long? current;
+  };
+
+  [nodoc] dictionary DownloadBooleanDiff {
+    boolean? previous;
+    boolean? current;
+  };
+
+  // Encapsulates a change in a DownloadItem.
+  [nodoc] dictionary DownloadDelta {
+    // An identifier that is persistent across browser sessions.
+    long id;
+
+    // Describes a change in a DownloadItem's <code>url</code>.
+    [inline_doc] DownloadStringDiff? url;
+
+    // Describes a change in a DownloadItem's <code>filename</code>.
+    [inline_doc] DownloadStringDiff? filename;
+
+    // Describes a change in a DownloadItem's <code>danger</code>.
+    [inline_doc] DownloadStringDiff? danger;
+
+    // Describes a change in a DownloadItem's <code>dangerAccepted</code>.
+    [inline_doc] DownloadBooleanDiff? dangerAccepted;
+
+    // Describes a change in a DownloadItem's <code>mime</code>.
+    [inline_doc] DownloadStringDiff? mime;
+
+    // Describes a change in a DownloadItem's <code>startTime</code>.
+    [inline_doc] DownloadLongDiff? startTime;
+
+    // Describes a change in a DownloadItem's <code>endTime</code>.
+    [inline_doc] DownloadLongDiff? endTime;
+
+    // Describes a change in a DownloadItem's <code>state</code>.
+    [inline_doc] DownloadStringDiff? state;
+
+    // Describes a change in a DownloadItem's <code>paused</code>.
+    [inline_doc] DownloadBooleanDiff? paused;
+
+    // Describes a change in a DownloadItem's <code>error</code>.
+    [inline_doc] DownloadLongDiff? error;
+
+    // Describes a change in a DownloadItem's <code>totalBytes</code>.
+    [inline_doc] DownloadLongDiff? totalBytes;
+
+    // Describes a change in a DownloadItem's <code>fileSize</code>.
+    [inline_doc] DownloadLongDiff? fileSize;

[asargent_no_longer_on_chrome, 2012/06/12 19:08:16]

General comment:

It seems weird that we need to use use [inline_doc] so many places - should we
switch to having that be the default, and you have to explicitly opt-out of it?

I guess I don't really understand what inline_doc means and why some
parameters/properties have are annotated with it and others aren't.

[benjhayden, 2012/06/12 20:15:42]

See https://www/~benjhayden/no_crawl/downloads_docs/downloads.html

inline_doc moves documentation of properties from the Types section to wherever
the type is used (either another Type in the Types section, or somewhere in the
Methods or Events sections) so that readers don't need to bounce around the page
and mentally compose types. It also looks much less scary to see 3 Types instead
of 11.
Generally, I use inline_doc for types that are only used in one place or types
that only make sense in the context of their containers.
inline_doc might be unnecessary or less necessary if IDL supported inline
dictionary definition like C's inline structs.

+  };
+
+  [nodoc] 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([inline_doc] 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([inline_doc] 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,
+                            [inline_doc] optional GetFileIconOptions options,

[asargent_no_longer_on_chrome, 2012/06/12 19:08:16]

It seems kind of weird that the options paramter here is marked inline_doc, but
the GetFileIconOptions type is marked as nodoc. 

[benjhayden, 2012/06/12 20:15:42]

A "move" operation is composed of a "copy" operation and a "delete" operation.
inline_doc doesn't "move" the doc, it just copies it. The nodoc is the "delete"
operation that completes the "move".
Without [nodoc] on GetFileIconOptions, the type would be documented both in the
getFileIcon() method and in the Types section.

+                            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([inline_doc] DownloadDelta downloadDelta);
+  };
+};