downloads

Interact with the browser's download manager. You can use this module to download files, cancel, pause, resume downloads, and show downloaded files in the file manager.

To use this API you need to have the "downloads" permission.

Types

downloads.FilenameConflictAction

downloads.InterruptReason

downloads.DangerType

downloads.State

downloads.DownloadItem

downloads.StringDelta

downloads.DoubleDelta

downloads.BooleanDelta

downloads.DownloadTime

downloads.DownloadQuery

Functions

downloads.download()

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 filename and saveAs are specified, then the Save As dialog will be displayed, pre-populated with the specified filename. If the download started successfully, callback will be called with the new DownloadItem's downloadId. If there was an error starting the download, then callback will be called with downloadId=undefined and runtime.lastError will contain a descriptive string. The error strings are not guaranteed to remain backwards compatible between releases. You must not parse it.

downloads.search()

Find DownloadItems. Set query to the empty object to get all DownloadItems. To get a specific DownloadItem, set only the id field.

downloads.pause()

Pause the download. If the request was successful the download is in a paused state. Otherwise runtime.lastError contains an error message. The request will fail if the download is not active.

downloads.resume()

Resume a paused download. If the request was successful the download is in progress and unpaused. Otherwise runtime.lastError contains an error message. The request will fail if the download is not active.

downloads.cancel()

Cancel a download. When callback is run, the download is cancelled, completed, interrupted or doesn't exist anymore.

downloads.getFileIcon()

Retrieve an icon for the specified download. For new downloads, file icons are available after the downloads.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, runtime.lastError will contain an error message.

downloads.open()

Open the downloaded file.

downloads.show()

Show the downloaded file in its folder in a file manager.

downloads.showDefaultFolder()

downloads.erase()

Erase matching DownloadItems from history

downloads.removeFile()

downloads.acceptDanger()

Prompt the user to either accept or cancel a dangerous download. acceptDanger() does not automatically accept dangerous downloads.

downloads.drag()

Initiate dragging the file to another application.

downloads.setShelfEnabled()

Events

downloads.onCreated

This event fires with the DownloadItem object when a download begins.

downloads.onErased

Fires with the downloadId when a download is erased from history.

downloads.onChanged

When any of a DownloadItem's properties except bytesReceived changes, this event fires with the downloadId and an object containing the properties that changed.

Browser compatibility

Chrome incompatibilities

• Firefox does not support:
  • pause()
  • getFileIcon()
  • resume()
  • show()
  • removeFile()
  • cancel()
  • drag()
  • erase()
  • acceptDanger()
  • showDefaultFolder()
  • setShelfEnabled()
  • open()
  • onCreated
  • onErased

// Copyright 2015 The Chromium Authors. All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are
// met:
//
//    * Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
//    * Redistributions in binary form must reproduce the above
// copyright notice, this list of conditions and the following disclaimer
// in the documentation and/or other materials provided with the
// distribution.
//    * Neither the name of Google Inc. nor the names of its
// contributors may be used to endorse or promote products derived from
// this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.