Merge pull request #5959 from electron/download-item-interrupt

Add more bindings to DownloadItem

atom/browser/api/atom_api_download_item.cc

@@ -25,6 +25,9 @@ struct Converter<content::DownloadItem::DownloadState> {
                                    content::DownloadItem::DownloadState state) {
     std::string download_state;
     switch (state) {
+      case content::DownloadItem::IN_PROGRESS:
+        download_state = "progressing";
+        break;
       case content::DownloadItem::COMPLETE:
         download_state = "completed";
         break;
@@ -85,7 +88,7 @@ void DownloadItem::OnDownloadUpdated(content::DownloadItem* item) {
     // Destroy the item once item is downloaded.
     base::MessageLoop::current()->PostTask(FROM_HERE, GetDestroyClosure());
   } else {
-    Emit("updated");
+    Emit("updated", item->GetState());
   }
 }
 
@@ -99,10 +102,18 @@ void DownloadItem::Pause() {
   download_item_->Pause();
 }
 
+bool DownloadItem::IsPaused() const {
+  return download_item_->IsPaused();
+}
+
 void DownloadItem::Resume() {
   download_item_->Resume();
 }
 
+bool DownloadItem::CanResume() const {
+  return download_item_->CanResume();
+}
+
 void DownloadItem::Cancel() {
   download_item_->Cancel(true);
   download_item_->Remove();
@@ -141,6 +152,14 @@ const GURL& DownloadItem::GetURL() const {
   return download_item_->GetURL();
 }
 
+content::DownloadItem::DownloadState DownloadItem::GetState() const {
+  return download_item_->GetState();
+}
+
+bool DownloadItem::IsDone() const {
+  return download_item_->IsDone();
+}
+
 void DownloadItem::SetSavePath(const base::FilePath& path) {
   save_path_ = path;
 }
@@ -155,7 +174,9 @@ void DownloadItem::BuildPrototype(v8::Isolate* isolate,
   mate::ObjectTemplateBuilder(isolate, prototype)
       .MakeDestroyable()
       .SetMethod("pause", &DownloadItem::Pause)
+      .SetMethod("isPaused", &DownloadItem::IsPaused)
       .SetMethod("resume", &DownloadItem::Resume)
+      .SetMethod("canResume", &DownloadItem::CanResume)
       .SetMethod("cancel", &DownloadItem::Cancel)
       .SetMethod("getReceivedBytes", &DownloadItem::GetReceivedBytes)
       .SetMethod("getTotalBytes", &DownloadItem::GetTotalBytes)
@@ -164,6 +185,8 @@ void DownloadItem::BuildPrototype(v8::Isolate* isolate,
       .SetMethod("getFilename", &DownloadItem::GetFilename)
       .SetMethod("getContentDisposition", &DownloadItem::GetContentDisposition)
       .SetMethod("getURL", &DownloadItem::GetURL)
+      .SetMethod("getState", &DownloadItem::GetState)
+      .SetMethod("isDone", &DownloadItem::IsDone)
       .SetMethod("setSavePath", &DownloadItem::SetSavePath)
       .SetMethod("getSavePath", &DownloadItem::GetSavePath);
 }

atom/browser/api/atom_api_download_item.h

@@ -27,7 +27,9 @@ class DownloadItem : public mate::TrackableObject<DownloadItem>,
                              v8::Local<v8::ObjectTemplate> prototype);
 
   void Pause();
+  bool IsPaused() const;
   void Resume();
+  bool CanResume() const;
   void Cancel();
   int64_t GetReceivedBytes() const;
   int64_t GetTotalBytes() const;
@@ -36,6 +38,8 @@ class DownloadItem : public mate::TrackableObject<DownloadItem>,
   std::string GetFilename() const;
   std::string GetContentDisposition() const;
   const GURL& GetURL() const;
+  content::DownloadItem::DownloadState GetState() const;
+  bool IsDone() const;
   void SetSavePath(const base::FilePath& path);
   base::FilePath GetSavePath() const;
 

docs/api/download-item.md

@@ -2,49 +2,70 @@
 
 > Control file downloads from remote sources.
 
-`DownloadItem` is an EventEmitter that represents a download item in Electron.
-It is used in `will-download` event of `Session` module, and allows users to
+`DownloadItem` is an `EventEmitter` that represents a download item in Electron.
+It is used in `will-download` event of `Session` class, and allows users to
 control the download item.
 
 ```javascript
 // In the main process.
 win.webContents.session.on('will-download', (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', () => {
-    console.log('Received bytes: ' + item.getReceivedBytes());
-  });
-  item.on('done', (e, state) => {
-    if (state === 'completed') {
-      console.log('Download successfully');
-    } else {
-      console.log('Download is cancelled or interrupted that can\'t be resumed');
+  item.setSavePath('/tmp/save.pdf')
+
+  item.on('updated', (event, state) => {
+    if (state === 'interrupted') {
+      console.log('Download is interrupted but can be resumed')
+    } else if (state === 'progressing') {
+      if (item.isPaused()) {
+        console.log('Download is paused')
+      } else {
+        console.log(`Received bytes: ${item.getReceivedBytes()}`)
+      }
     }
-  });
-});
+  })
+  item.once('done', (event, state) => {
+    if (state === 'completed') {
+      console.log('Download successfully')
+    } else {
+      console.log(`Download failed: ${state}`)
+    }
+  })
+})
 ```
 
 ## Events
 
 ### Event: 'updated'
 
-Emits when the `downloadItem` gets updated.
-
-### Event: 'done'
+Returns:
 
 * `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
+Emitted when the download has been updated and is not done.
+
+The `state` can be one of following:
+
+* `progressing` - The download is in-progress.
+* `interrupted` - The download has interrupted and can be resumed.
+
+### Event: 'done'
+
+Returns:
+
+* `event` Event
+* `state` String
+
+Emitted when the download is in a terminal state. This includes a completed
 download, a cancelled download(via `downloadItem.cancel()`), and interrupted
 download that can't be resumed.
 
+The `state` can be one of following:
+
+* `completed` - The download completed successfully.
+* `cancelled` - The download has been cancelled.
+* `interrupted` - The download has interrupted and can not resume.
+
 ## Methods
 
 The `downloadItem` object has the following methods:
@@ -61,10 +82,18 @@ routine to determine the save path(Usually prompts a save dialog).
 
 Pauses the download.
 
+### `downloadItem.isPaused()`
+
+Returns whether the download is paused.
+
 ### `downloadItem.resume()`
 
 Resumes the download that has been paused.
 
+### `downloadItem.canResume()`
+
+Resumes whether the download can resume.
+
 ### `downloadItem.cancel()`
 
 Cancels the download operation.
@@ -102,3 +131,14 @@ Returns a `Integer` represents the received bytes of the download item.
 
 Returns a `String` represents the Content-Disposition field from the response
 header.
+
+### `downloadItem.getState()`
+
+Returns current state as `String`.
+
+Possible values are:
+
+* `progressing` - The download is in-progress.
+* `completed` - The download completed successfully.
+* `cancelled` - The download has been cancelled.
+* `interrupted` - The download has interrupted.