Merge pull request #2840 from atom/download-item

Add more download supports in Electron

atom/browser/api/atom_api_download_item.cc

@@ -0,0 +1,201 @@
+// Copyright (c) 2015 GitHub, Inc.
+// Use of this source code is governed by the MIT license that can be
+// found in the LICENSE file.
+
+#include "atom/browser/api/atom_api_download_item.h"
+
+#include <map>
+
+#include "atom/common/native_mate_converters/callback.h"
+#include "atom/common/native_mate_converters/file_path_converter.h"
+#include "atom/common/native_mate_converters/gurl_converter.h"
+#include "atom/common/node_includes.h"
+#include "base/memory/linked_ptr.h"
+#include "base/strings/utf_string_conversions.h"
+#include "native_mate/dictionary.h"
+#include "net/base/filename_util.h"
+
+namespace mate {
+
+template<>
+struct Converter<content::DownloadItem::DownloadState> {
+  static v8::Local<v8::Value> ToV8(v8::Isolate* isolate,
+                                   content::DownloadItem::DownloadState state) {
+    std::string download_state;
+    switch (state) {
+      case content::DownloadItem::COMPLETE:
+        download_state = "completed";
+        break;
+      case content::DownloadItem::CANCELLED:
+        download_state = "cancelled";
+        break;
+      case content::DownloadItem::INTERRUPTED:
+        download_state = "interrputed";
+        break;
+      default:
+        break;
+    }
+    return ConvertToV8(isolate, download_state);
+  }
+};
+
+}  // namespace mate
+
+namespace atom {
+
+namespace api {
+
+namespace {
+// The wrapDownloadItem funtion which is implemented in JavaScript
+using WrapDownloadItemCallback = base::Callback<void(v8::Local<v8::Value>)>;
+WrapDownloadItemCallback g_wrap_download_item;
+
+char kDownloadItemSavePathKey[] = "DownloadItemSavePathKey";
+
+std::map<uint32, linked_ptr<v8::Global<v8::Value>>> g_download_item_objects;
+}  // namespace
+
+DownloadItem::SavePathData::SavePathData(const base::FilePath& path) :
+  path_(path) {
+}
+
+const base::FilePath& DownloadItem::SavePathData::path() {
+  return path_;
+}
+
+DownloadItem::DownloadItem(content::DownloadItem* download_item) :
+    download_item_(download_item) {
+  download_item_->AddObserver(this);
+}
+
+DownloadItem::~DownloadItem() {
+  Destroy();
+}
+
+void DownloadItem::Destroy() {
+  if (download_item_) {
+    download_item_->RemoveObserver(this);
+    auto iter = g_download_item_objects.find(download_item_->GetId());
+    if (iter != g_download_item_objects.end())
+      g_download_item_objects.erase(iter);
+    download_item_ = nullptr;
+  }
+}
+
+bool DownloadItem::IsDestroyed() const {
+  return download_item_ == nullptr;
+}
+
+void DownloadItem::OnDownloadUpdated(content::DownloadItem* item) {
+  download_item_->IsDone() ? Emit("done", item->GetState()) : Emit("updated");
+}
+
+void DownloadItem::OnDownloadDestroyed(content::DownloadItem* download) {
+  Destroy();
+}
+
+int64 DownloadItem::GetReceivedBytes() {
+  return download_item_->GetReceivedBytes();
+}
+
+int64 DownloadItem::GetTotalBytes() {
+  return download_item_->GetTotalBytes();
+}
+
+const GURL& DownloadItem::GetUrl() {
+  return download_item_->GetURL();
+}
+
+std::string DownloadItem::GetMimeType() {
+  return download_item_->GetMimeType();
+}
+
+bool DownloadItem::HasUserGesture() {
+  return download_item_->HasUserGesture();
+}
+
+std::string DownloadItem::GetFilename() {
+  return base::UTF16ToUTF8(net::GenerateFileName(GetUrl(),
+                           GetContentDisposition(),
+                           std::string(),
+                           download_item_->GetSuggestedFilename(),
+                           GetMimeType(),
+                           std::string()).LossyDisplayName());
+}
+
+std::string DownloadItem::GetContentDisposition() {
+  return download_item_->GetContentDisposition();
+}
+
+void DownloadItem::SetSavePath(const base::FilePath& path) {
+  download_item_->SetUserData(UserDataKey(), new SavePathData(path));
+}
+
+void DownloadItem::Pause() {
+  download_item_->Pause();
+}
+
+void DownloadItem::Resume() {
+  download_item_->Resume();
+}
+
+void DownloadItem::Cancel() {
+  download_item_->Cancel(true);
+}
+
+mate::ObjectTemplateBuilder DownloadItem::GetObjectTemplateBuilder(
+    v8::Isolate* isolate) {
+  return mate::ObjectTemplateBuilder(isolate)
+      .SetMethod("pause", &DownloadItem::Pause)
+      .SetMethod("resume", &DownloadItem::Resume)
+      .SetMethod("cancel", &DownloadItem::Cancel)
+      .SetMethod("getReceivedBytes", &DownloadItem::GetReceivedBytes)
+      .SetMethod("getTotalBytes", &DownloadItem::GetTotalBytes)
+      .SetMethod("getUrl", &DownloadItem::GetUrl)
+      .SetMethod("getMimeType", &DownloadItem::GetMimeType)
+      .SetMethod("hasUserGesture", &DownloadItem::HasUserGesture)
+      .SetMethod("getFilename", &DownloadItem::GetFilename)
+      .SetMethod("getContentDisposition", &DownloadItem::GetContentDisposition)
+      .SetMethod("setSavePath", &DownloadItem::SetSavePath);
+}
+
+void SetWrapDownloadItem(const WrapDownloadItemCallback& callback) {
+  g_wrap_download_item = callback;
+}
+
+void ClearWrapDownloadItem() {
+  g_wrap_download_item.Reset();
+}
+
+// static
+mate::Handle<DownloadItem> DownloadItem::Create(
+    v8::Isolate* isolate, content::DownloadItem* item) {
+  auto handle = mate::CreateHandle(isolate, new DownloadItem(item));
+  g_wrap_download_item.Run(handle.ToV8());
+  g_download_item_objects[item->GetId()] = make_linked_ptr(
+      new v8::Global<v8::Value>(isolate, handle.ToV8()));
+  return handle;
+}
+
+// static
+void* DownloadItem::UserDataKey() {
+  return &kDownloadItemSavePathKey;
+}
+
+}  // namespace api
+
+}  // namespace atom
+
+namespace {
+
+void Initialize(v8::Local<v8::Object> exports, v8::Local<v8::Value> unused,
+                v8::Local<v8::Context> context, void* priv) {
+  v8::Isolate* isolate = context->GetIsolate();
+  mate::Dictionary dict(isolate, exports);
+  dict.SetMethod("_setWrapDownloadItem", &atom::api::SetWrapDownloadItem);
+  dict.SetMethod("_clearWrapDownloadItem", &atom::api::ClearWrapDownloadItem);
+}
+
+}  // namespace
+
+NODE_MODULE_CONTEXT_AWARE_BUILTIN(atom_browser_download_item, Initialize);

atom/browser/api/atom_api_download_item.h

@@ -0,0 +1,72 @@
+// Copyright (c) 2015 GitHub, Inc.
+// Use of this source code is governed by the MIT license that can be
+// found in the LICENSE file.
+
+#ifndef ATOM_BROWSER_API_ATOM_API_DOWNLOAD_ITEM_H_
+#define ATOM_BROWSER_API_ATOM_API_DOWNLOAD_ITEM_H_
+
+#include <string>
+
+#include "atom/browser/api/trackable_object.h"
+#include "base/files/file_path.h"
+#include "content/public/browser/download_item.h"
+#include "native_mate/handle.h"
+#include "url/gurl.h"
+
+namespace atom {
+
+namespace api {
+
+class DownloadItem : public mate::EventEmitter,
+                     public content::DownloadItem::Observer {
+ public:
+  class SavePathData : public base::SupportsUserData::Data {
+   public:
+    explicit SavePathData(const base::FilePath& path);
+    const base::FilePath& path();
+   private:
+    base::FilePath path_;
+  };
+
+  static mate::Handle<DownloadItem> Create(v8::Isolate* isolate,
+                                           content::DownloadItem* item);
+  static void* UserDataKey();
+
+ protected:
+  explicit DownloadItem(content::DownloadItem* download_item);
+  ~DownloadItem();
+
+  // Override content::DownloadItem::Observer methods
+  void OnDownloadUpdated(content::DownloadItem* download) override;
+  void OnDownloadDestroyed(content::DownloadItem* download) override;
+
+  void Pause();
+  void Resume();
+  void Cancel();
+  int64 GetReceivedBytes();
+  int64 GetTotalBytes();
+  std::string GetMimeType();
+  bool HasUserGesture();
+  std::string GetFilename();
+  std::string GetContentDisposition();
+  const GURL& GetUrl();
+  void SetSavePath(const base::FilePath& path);
+
+ private:
+  // mate::Wrappable:
+  mate::ObjectTemplateBuilder GetObjectTemplateBuilder(
+      v8::Isolate* isolate) override;
+  bool IsDestroyed() const override;
+
+  void Destroy();
+
+  content::DownloadItem* download_item_;
+
+  DISALLOW_COPY_AND_ASSIGN(DownloadItem);
+};
+
+}  // namespace api
+
+}  // namespace atom
+
+#endif  // ATOM_BROWSER_API_ATOM_API_DOWNLOAD_ITEM_H_

atom/browser/api/atom_api_session.cc

@@ -8,6 +8,7 @@
 #include <vector>
 
 #include "atom/browser/api/atom_api_cookies.h"
+#include "atom/browser/api/atom_api_download_item.h"
 #include "atom/browser/atom_browser_context.h"
 #include "atom/browser/api/atom_api_web_contents.h"
 #include "atom/common/native_mate_converters/callback.h"
@@ -101,19 +102,6 @@ struct Converter<ClearStorageDataOptions> {
   }
 };
 
-template<>
-struct Converter<content::DownloadItem*> {
-  static v8::Local<v8::Value> ToV8(v8::Isolate* isolate,
-                                   content::DownloadItem* val) {
-    mate::Dictionary dict(isolate, v8::Object::New(isolate));
-    dict.Set("url", val->GetURL());
-    dict.Set("filename", val->GetSuggestedFilename());
-    dict.Set("mimeType", val->GetMimeType());
-    dict.Set("hasUserGesture", val->HasUserGesture());
-    return dict.GetHandle();
-  }
-};
-
 }  // namespace mate
 
 namespace atom {
@@ -245,11 +233,12 @@ Session::~Session() {
 }
 
 void Session::OnDownloadCreated(content::DownloadManager* manager,
-                                    content::DownloadItem* item) {
+                                content::DownloadItem* item) {
   auto web_contents = item->GetWebContents();
-  bool prevent_default = Emit("will-download", item,
+  bool prevent_default = Emit(
-                              api::WebContents::CreateFrom(isolate(),
+      "will-download",
-                                                           web_contents));
+      DownloadItem::Create(isolate(), item),
+      api::WebContents::CreateFrom(isolate(), web_contents));
   if (prevent_default) {
     item->Cancel(true);
     item->Remove();

atom/browser/api/lib/app.coffee

@@ -2,6 +2,7 @@ EventEmitter = require('events').EventEmitter
 
 bindings = process.atomBinding 'app'
 sessionBindings = process.atomBinding 'session'
+downloadItemBindings = process.atomBinding 'download_item'
 
 app = bindings.app
 app.__proto__ = EventEmitter.prototype
@@ -10,6 +11,15 @@ wrapSession = (session) ->
   # session is an Event Emitter.
   session.__proto__ = EventEmitter.prototype
 
+wrapDownloadItem = (download_item) ->
+  # download_item is an Event Emitter.
+  download_item.__proto__ = EventEmitter.prototype
+  # Be compatible with old APIs.
+  download_item.url = download_item.getUrl()
+  download_item.filename = download_item.getFilename()
+  download_item.mimeType = download_item.getMimeType()
+  download_item.hasUserGesture = download_item.hasUserGesture()
+
 app.setApplicationMenu = (menu) ->
   require('menu').setApplicationMenu menu
 
@@ -51,5 +61,8 @@ app.on 'activate', (event, hasVisibleWindows) -> @emit 'activate-with-no-open-wi
 sessionBindings._setWrapSession wrapSession
 process.once 'exit', sessionBindings._clearWrapSession
 
+downloadItemBindings._setWrapDownloadItem wrapDownloadItem
+process.once 'exit', downloadItemBindings._clearWrapDownloadItem
+
 # Only one App object pemitted.
 module.exports = app

atom/browser/atom_download_manager_delegate.cc

@@ -6,6 +6,7 @@
 
 #include <string>
 
+#include "atom/browser/api/atom_api_download_item.h"
 #include "atom/browser/atom_browser_context.h"
 #include "atom/browser/native_window.h"
 #include "atom/browser/ui/file_dialog.h"
@@ -73,18 +74,19 @@ void AtomDownloadManagerDelegate::OnDownloadPathGenerated(
   if (relay)
     window = relay->window.get();
 
-  file_dialog::Filters filters;
   base::FilePath path;
-  if (!file_dialog::ShowSaveDialog(window, item->GetURL().spec(), default_path,
+  if (file_dialog::ShowSaveDialog(window, item->GetURL().spec(), default_path,
-                                   filters, &path)) {
+                                  file_dialog::Filters(), &path)) {
-    return;
+    // Remember the last selected download directory.
+    AtomBrowserContext* browser_context = static_cast<AtomBrowserContext*>(
+        download_manager_->GetBrowserContext());
+    browser_context->prefs()->SetFilePath(prefs::kDownloadDefaultDirectory,
+                                          path.DirName());
   }
 
-  // Remeber the last selected download directory.
+  // Running the DownloadTargetCallback with an empty FilePath signals that the
-  AtomBrowserContext* browser_context = static_cast<AtomBrowserContext*>(
+  // download should be cancelled.
-      download_manager_->GetBrowserContext());
+  // If user cancels the file save dialog, run the callback with empty FilePath.
-  browser_context->prefs()->SetFilePath(prefs::kDownloadDefaultDirectory,
-                                        path.DirName());
   callback.Run(path,
                content::DownloadItem::TARGET_DISPOSITION_PROMPT,
                content::DOWNLOAD_DANGER_TYPE_NOT_DANGEROUS, path);
@@ -100,6 +102,25 @@ bool AtomDownloadManagerDelegate::DetermineDownloadTarget(
     const content::DownloadTargetCallback& callback) {
   DCHECK_CURRENTLY_ON(content::BrowserThread::UI);
 
+  if (!download->GetForcedFilePath().empty()) {
+    callback.Run(download->GetForcedFilePath(),
+                 content::DownloadItem::TARGET_DISPOSITION_OVERWRITE,
+                 content::DOWNLOAD_DANGER_TYPE_NOT_DANGEROUS,
+                 download->GetForcedFilePath());
+    return true;
+  }
+  base::SupportsUserData::Data* save_path = download->GetUserData(
+      atom::api::DownloadItem::UserDataKey());
+  if (save_path) {
+    const base::FilePath& default_download_path =
+        static_cast<api::DownloadItem::SavePathData*>(save_path)->path();
+    callback.Run(default_download_path,
+                 content::DownloadItem::TARGET_DISPOSITION_OVERWRITE,
+                 content::DOWNLOAD_DANGER_TYPE_NOT_DANGEROUS,
+                 default_download_path);
+    return true;
+  }
+
   AtomBrowserContext* browser_context = static_cast<AtomBrowserContext*>(
       download_manager_->GetBrowserContext());
   base::FilePath default_download_path = browser_context->prefs()->GetFilePath(
@@ -110,14 +131,6 @@ bool AtomDownloadManagerDelegate::DetermineDownloadTarget(
     default_download_path = path.Append(FILE_PATH_LITERAL("Downloads"));
   }
 
-  if (!download->GetForcedFilePath().empty()) {
-    callback.Run(download->GetForcedFilePath(),
-                 content::DownloadItem::TARGET_DISPOSITION_OVERWRITE,
-                 content::DOWNLOAD_DANGER_TYPE_NOT_DANGEROUS,
-                 download->GetForcedFilePath());
-    return true;
-  }
-
   CreateDownloadPathCallback download_path_callback =
       base::Bind(&AtomDownloadManagerDelegate::OnDownloadPathGenerated,
                  weak_ptr_factory_.GetWeakPtr(),

atom/common/node_bindings.cc

@@ -34,6 +34,7 @@ REFERENCE_MODULE(atom_browser_app);
 REFERENCE_MODULE(atom_browser_auto_updater);
 REFERENCE_MODULE(atom_browser_content_tracing);
 REFERENCE_MODULE(atom_browser_dialog);
+REFERENCE_MODULE(atom_browser_download_item);
 REFERENCE_MODULE(atom_browser_menu);
 REFERENCE_MODULE(atom_browser_power_monitor);
 REFERENCE_MODULE(atom_browser_power_save_blocker);

docs/api/download-item.md

@@ -0,0 +1,101 @@
+# DownloadItem
+
+`DownloadItem` is an EventEmitter represents a download item in Electron. It
+is used in `will-download` event of `Session` module, and allows users to
+control the download item.
+
+```javascript
+// In the main process.
+win.webContents.session.on('will-download', function(event, item, webContents) {
+  // Set the save path, making Electron not to prompt a save dialog.
+  item.setSavePath('/tmp/save.pdf');
+  console.log(item.getMimeType());
+  console.log(item.getFilename());
+  console.log(item.getTotalBytes());
+  item.on('updated', function() {
+    console.log('Received bytes: ' + item.getReceivedBytes());
+  });
+  item.on('done', function(e, state) {
+    if (state == "completed") {
+      console.log("Download successfully");
+    } else {
+      console.log("Download is cancelled or interrupted that can't be resumed");
+    }
+  });
+```
+
+## Events
+
+### Event: 'updated'
+
+Emits when the `downloadItem` gets updated.
+
+### Event: 'done'
+
+* `event` Event
+* `state` String
+  * `completed` - The download completed successfully.
+  * `cancelled` - The download has been cancelled.
+  * `interrupted` - An error broke the connection with the file server.
+
+Emits when the download is in a terminal state. This includes a completed
+download, a cancelled download(via `downloadItem.cancel()`), and interrputed
+download that can't be resumed.
+
+## Methods
+
+The `downloadItem` object has the following methods:
+
+### `downloadItem.setSavePath(path)`
+
+* `path` String - Set the save file path of the download item.
+
+The API is only available in session's `will-download` callback function.
+If user doesn't set the save path via the API, Electron will use the original
+routine to determine the save path(Usually prompts a save dialog).
+
+### `downloadItem.pause()`
+
+Pauses the download.
+
+### `downloadItem.resume()`
+
+Resumes the download that has been paused.
+
+### `downloadItem.cancel()`
+
+Cancels the download operation.
+
+### `downloadItem.getURL()`
+
+Returns a `String` represents the origin url where the item is downloaded from.
+
+### `downloadItem.getMimeType()`
+
+Returns a `String` represents the mime type.
+
+### `downloadItem.hasUserGesture()`
+
+Returns a `Boolean` indicates whether the download has user gesture.
+
+### `downloadItem.getFilename()`
+
+Returns a `String` represents the file name of the download item.
+
+**Note:** The file name is not always the same as the actual one saved in local
+disk. If user changes the file name in a prompted download saving dialog, the
+actual name of saved file will be different.
+
+### `downloadItem.getTotalBytes()`
+
+Returns a `Integer` represents the total size in bytes of the download item.
+If the size is unknown, it returns 0.
+
+### `downloadItem.getReceivedBytes()`
+
+Returns a `Integer` represents the received bytes of the download item.
+
+### `downloadItem.getContentDisposition()`
+
+Returns a `String` represents the Content-Disposition field from the response
+header.

docs/api/session.md

@@ -18,11 +18,7 @@ var session = win.webContents.session
 ### Event: 'will-download'
 
 * `event` Event
-* `item` Object
+* `item` [DownloadItem](download-item.md)
-  * `url` String
-  * `filename` String
-  * `mimeType` String
-  * `hasUserGesture` Boolean
 * `webContents` [WebContents](web-contents.md)
 
 Fired when Electron is about to download `item` in `webContents`.
@@ -32,7 +28,7 @@ Calling `event.preventDefault()` will cancel the download.
 ```javascript
 session.on('will-download', function(event, item, webContents) {
   event.preventDefault();
-  require('request')(item.url, function(data) {
+  require('request')(item.getURL(), function(data) {
     require('fs').writeFileSync('/somewhere', data);
   });
 });

filenames.gypi

@@ -71,6 +71,8 @@
       'atom/browser/api/atom_api_content_tracing.cc',
       'atom/browser/api/atom_api_cookies.cc',
       'atom/browser/api/atom_api_cookies.h',
+      'atom/browser/api/atom_api_download_item.cc',
+      'atom/browser/api/atom_api_download_item.h',
       'atom/browser/api/atom_api_dialog.cc',
       'atom/browser/api/atom_api_global_shortcut.cc',
       'atom/browser/api/atom_api_global_shortcut.h',

spec/api-session-spec.coffee

@@ -2,6 +2,7 @@ assert = require 'assert'
 remote = require 'remote'
 http   = require 'http'
 path   = require 'path'
+fs     = require 'fs'
 app    = remote.require 'app'
 BrowserWindow = remote.require 'browser-window'
 
@@ -72,3 +73,51 @@ describe 'session module', ->
           quotas: ['persistent'],
         w.webContents.session.clearStorageData options, ->
           w.webContents.send 'getcount'
+
+  describe 'DownloadItem', ->
+    # A 5 MB mock pdf.
+    mockPDF = new Buffer 1024 * 1024 * 5
+    contentDisposition = 'inline; filename="mock.pdf"'
+    ipc = require 'ipc'
+    downloadFilePath = path.join fixtures, 'mock.pdf'
+    downloadServer = http.createServer (req, res) ->
+      res.writeHead 200, {
+        'Content-Length': mockPDF.length,
+        'Content-Type': 'application/pdf',
+        'Content-Disposition': contentDisposition
+      }
+      res.end mockPDF
+      downloadServer.close()
+
+    it 'can download successfully', (done) ->
+      downloadServer.listen 0, '127.0.0.1', ->
+        {port} = downloadServer.address()
+        ipc.sendSync 'set-download-option', false
+        w.loadUrl "#{url}:#{port}"
+        ipc.once 'download-done', (state, url, mimeType, receivedBytes,
+            totalBytes, disposition, filename) ->
+          assert.equal state, 'completed'
+          assert.equal filename, 'mock.pdf'
+          assert.equal url, "http://127.0.0.1:#{port}/"
+          assert.equal mimeType, 'application/pdf'
+          assert.equal receivedBytes, mockPDF.length
+          assert.equal totalBytes, mockPDF.length
+          assert.equal disposition, contentDisposition
+          assert fs.existsSync downloadFilePath
+          fs.unlinkSync downloadFilePath
+          done()
+
+    it 'can cancel download', (done) ->
+      downloadServer.listen 0, '127.0.0.1', ->
+        {port} = downloadServer.address()
+        ipc.sendSync 'set-download-option', true
+        w.loadUrl "#{url}:#{port}/"
+        ipc.once 'download-done', (state, url, mimeType, receivedBytes,
+            totalBytes, disposition, filename) ->
+          assert.equal state, 'cancelled'
+          assert.equal filename, 'mock.pdf'
+          assert.equal mimeType, 'application/pdf'
+          assert.equal receivedBytes, 0
+          assert.equal totalBytes, mockPDF.length
+          assert.equal disposition, contentDisposition
+          done()

spec/static/main.js

@@ -1,6 +1,7 @@
 var app = require('app');
 var ipc = require('ipc');
 var dialog = require('dialog');
+var path = require('path');
 var BrowserWindow = require('browser-window');
 
 var window = null;
@@ -73,4 +74,27 @@ app.on('ready', function() {
     });
     if (chosen == 0) window.destroy();
   });
+
+  // For session's download test, listen 'will-download' event in browser, and
+  // reply the result to renderer for verifying
+  var downloadFilePath = path.join(__dirname, '..', 'fixtures', 'mock.pdf');
+  require('ipc').on('set-download-option', function(event, need_cancel) {
+    window.webContents.session.once('will-download',
+        function(e, item, webContents) {
+          item.setSavePath(downloadFilePath);
+          item.on('done', function(e, state) {
+            window.webContents.send('download-done',
+                                    state,
+                                    item.getUrl(),
+                                    item.getMimeType(),
+                                    item.getReceivedBytes(),
+                                    item.getTotalBytes(),
+                                    item.getContentDisposition(),
+                                    item.getFilename());
+          });
+          if (need_cancel)
+            item.cancel();
+        });
+    event.returnValue = "done";
+  });
 });