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.
+
+// <p>The downloads API allows you to programmatically initiate, monitor,
+// manipulate, and search for downloads.</p>
+//
+// <h2 id='manifest'>Manifest</h2>
+//
+// <p> You must declare the 'downloads' permission in the <a
+// href='manifest.html'>extension manifest</a> to use this API, along with <a
+// href='manifest.html#permissions'>host permissions</a> for any hosts that you
+// may pass to <a href='#method-download'>download()</a>.</p>
+//
+// <pre>{
+//   'name': 'My extension',<br>
+//   ...<br>
+// <b>  'permissions': [<br>
+//     'downloads',<br>
+//     '*://*.google.com'<br>
+//   ]</b>,<br>
+//   ...<br>
+// }</pre>
+//
+// <p>If the URL's hostname is not specified in the permissions, then <a
+// href='#method-download'>download()</a> will call its callback with a null
+// <code>downloadId</code> and set the <a
+// href='extension.html#property-lastError'>chrome.extensions.lastError</a>
+// object to indicate that the extension does not have permission to access that
+// hostname.</p>
+//
+// <h2 id='examples'>Examples</h2>
+//
+// <p>You can find simple examples of using the downloads module in the <a
+// href='http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/api/downloads/'>examples/api/downloads</a>
+// directory. For other examples and for help in viewing the source code, see <a
+// href='samples.html'>Samples</a>.</p>

[not at google - send to devlin, 2012/06/04 04:16:49]

I don't think that this is a desirable change.  Dealing with a code comment is
much more awkward than dealing with plain HTML... for example, syntax
highlighting doesn't work in editors.  Browsers can't open this file to preview
it.  You need to modify an IDL file to modify documentation, so it will be
harder to cherry-pick changes into releases.

Another data point: we're currently in the process of re-writing how
documentation works anyway.  Ping me if you want the design doc, but basically
it will remove needing to generate anything at all.

So if all this buys is needing to change only 1 file rather than 2, I'd rather
we didn't do it.

[benjhayden, 2012/06/04 20:33:15]

If you have a link handy, I'm curious, otherwise don't spend too much time
writing it up.
Done.

+
+[permissions=downloads] namespace downloads {
+  dictionary HeaderNameValuePair {
+    // Name of the HTTP header.
+    DOMString name;
+
+    // Value of the HTTP header if it can be represented by UTF-8.
+    DOMString? value;
+
+    // Value of the HTTP header if it cannot be represented by UTF-8, stored as
+    // individual byte values.
+    long[]? binaryValue;
+  };
+
+  enum HttpMethod {GET, POST};
+
+  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;
+  };
+
+  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;
+  };
+
+  // Encapsulates a change in a string DownloadItem field.
+  dictionary DownloadStringDiff {
+    DOMString? previous;
+    DOMString? current;
+  };
+
+  // Encapsulates a change in a long DownloadItem field.
+  dictionary DownloadLongDiff {
+    long? previous;
+    long? current;
+  };
+
+  // Encapsulates a change in a boolean DownloadItem field.
+  dictionary DownloadBooleanDiff {
+    boolean? previous;
+    boolean? current;
+  };
+
+  // Encapsulates a change in a DownloadItem.
+  dictionary DownloadDelta {
+    // An identifier that is persistent across browser sessions.
+    long id;
+    DownloadStringDiff? url;
+    DownloadStringDiff? filename;
+    DownloadStringDiff? danger;
+    DownloadBooleanDiff? dangerAccepted;
+    DownloadStringDiff? mime;
+    DownloadLongDiff? startTime;
+    DownloadLongDiff? endTime;
+    DownloadStringDiff? state;
+    DownloadBooleanDiff? paused;
+    DownloadLongDiff? error;
+    DownloadLongDiff? bytesReceived;
+    DownloadLongDiff? totalBytes;
+    DownloadLongDiff? fileSize;
+  };
+
+  enum IconSize {SMALL = 16, LARGE = 32};
+
+  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.
+    IconSize? 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);
+  };
+};