Download manager. Not part of build.

xpfe/components/download-manager/public/nsIDownloadItem.idl

@@ -38,14 +38,13 @@
 
 
  /*
-  * nsIDownloadItem acts as a "master listener" for the ongoing transfer.  It implements nsIWebProgressListener,
-  * If clients provide a persist object, the item will automatically be set as the persist's listener. Otherwise,
-  * clients should set this themselves on whatever download mechanism they're using.
-  * nsIDownloadItem's listener impl will forward progress notifications onto three possible
-  * listeners: the internal listener (an nsIDownloadProgressListener, used to update
-  * the main download manager UI), the properties listener (used to update the download manager
-  * properties dialog), and an optional listener set by the client via nsIDownloadItem's |listener|
-  * attribute (used to update client UI).
+  * nsIDownloadItem implements nsIWebProgressListener and acts as a "master
+  * listener" for the ongoing transfer. If clients provide a persist object,
+  * the item will automatically be set as the persist's listener. Otherwise,
+  * clients should set this themselves on whatever download mechanism they're
+  * using.  Clients may have their own UI for a download as well, in which case
+  * they may set the listener attribute.  nsIDownloadItem will forward
+  * notifications to that listener.
   */
   
 #include "nsIWebProgressListener.idl"
@@ -60,49 +59,48 @@ interface nsIDownloadItem : nsIWebProgressListener {
     
     /**
      * prettyName
-     * The user-readable description of a download
+     * The user-readable description of the download.
      */
     attribute wstring prettyName;
     
     /**
      * source
-     * The source of a download
+     * The source of the download.
      */
     attribute nsIURI source;
     
     /**
      * target
-     * The local file where the download is being saved
+     * The local file where the download is being saved.
      */
     attribute nsILocalFile target;
     
     /**
      * percentComplete
-     * The percentage complete of an item
+     * The percentage of completion of the download.
      */
     readonly attribute PRInt32 percentComplete;
 
     /**
      * startTime
-     * The time a download was started; necessary for more accurate
-     * measurements 
+     * The time a download was started; necessary for more accurate measurements.
      */
     readonly attribute long long startTime;
 
     /**
      * listener
-     * Optional; downloading information is
-     * passed to this listener and used to update client UI
+     * Optional; downloading information is passed to this listener and used to
+     * update client UI.
      */
     attribute nsIWebProgressListener listener;
    
     /**
      * persist
      * Optional. If set, it will be used for cancellation, and the download item
-     * will be set as its listener.  If not, observer should be set to listen and
-     * respond accordingly to topics like oncancel, and the client promises to set
-     * the download item (which implements nsIWebProgressListener) as the listener for
-     * whatever transfer component being used.
+     * will be set as its listener.  If not, |observer| should be set to listen
+     * and respond accordingly to topics like oncancel, and the client promises
+     * to set the download item as the listener for whatever transfer component
+     * being used.
      */
 
     attribute nsIWebBrowserPersist persist;
@@ -114,6 +112,7 @@ interface nsIDownloadItem : nsIWebProgressListener {
      */
 
     attribute nsIObserver observer;
+
 };
 
 %{C++

xpfe/components/download-manager/public/nsIDownloadManager.idl

@@ -37,6 +37,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+// Keeps track of ongoing downloads, in the form of nsIDownloadItems. 
+
 #include "nsISupports.idl"
 #include "nsIWebProgressListener.idl"
 
@@ -96,7 +98,7 @@ interface nsIDownloadManager : nsISupports {
 
   /**
   * onClose
-  * Called when the download manager UI is closed.  Useful for
+  * Called when the download manager front end is closed.  Useful for
   * third party managers to let us know when they've closed.
   */
   void onClose();

xpfe/components/download-manager/public/nsIDownloadProgressListener.idl

@@ -37,11 +37,11 @@
  * ***** END LICENSE BLOCK ***** */
 
 /* A minimally extended progress listener used by download manager
- * to update its default UI.  See nsIWebProgressListener for documentation,
- * and use its constants.  This isn't pretty, but the alternative is having
- * this extend nsIWebProgressListener and adding an |item| attribute, which
- * would mean a separate nsIDownloadProgressListener for every nsIDownloadItem,
- * which is a waste...
+ * to update its default UI.  This is implemented in nsDownloadProgressListener.js.
+ * See nsIWebProgressListener for documentation, and use its constants.  This isn't
+ * too pretty, but the alternative is having this extend nsIWebProgressListener and
+ * adding an |item| attribute, which would mean a separate nsIDownloadProgressListener
+ * for every nsIDownloadItem, which is a waste...
  */
 
 #include "nsISupports.idl"
@@ -54,10 +54,14 @@ interface nsIDOMDocument;
 
 [scriptable, uuid(09cddbea-1dd2-11b2-aa15-c41ffea19d79)]
 interface nsIDownloadProgressListener : nsISupports {
+
+ /**
+  * document
+  * The document of the download manager frontend.
+  */
   
   attribute nsIDOMDocument document;
 
-
   void onStateChange(in nsIWebProgress aWebProgress,
                      in nsIRequest aRequest,
                      in long aStateFlags,

xpfe/components/download-manager/src/nsDownloadManager.cpp

@@ -54,6 +54,7 @@
 
 /* Outstanding issues/todo:
  * 1. Using the target path as an identifier is not sufficient because it's not unique on mac.
+ * 2. Implement pause/resume
  */
   
 static NS_DEFINE_CID(kRDFServiceCID, NS_RDFSERVICE_CID);
@@ -139,7 +140,7 @@ nsDownloadManager::Init()
 }
 
 nsresult
-nsDownloadManager::NotifyDownloadEnded(const char* aKey)
+nsDownloadManager::DownloadFinished(const char* aKey)
 {
   nsCStringKey key(aKey);
   if (mCurrDownloadItems->Exists(&key)) {
@@ -261,7 +262,7 @@ nsDownloadManager::AssertProgressInfo()
     nsCStringKey key(id);
     if (mCurrDownloadItems->Exists(&key)) {
       nsIDownloadItem* item = NS_STATIC_CAST(nsIDownloadItem*, mCurrDownloadItems->Get(&key));
-      if (!item) continue; // must be a finished download; don't need to update ui
+      if (!item) continue; // must be a finished download; don't need to update info
 
       // update percentage
       item->GetPercentComplete(&percentComplete);
@@ -365,6 +366,7 @@ nsDownloadManager::AddDownload(nsIDownloadItem* aDownloadItem)
   rv = remote->Flush();
   if (NS_FAILED(rv)) return rv;
   
+  // if a persist object was specified, set the download item as the progress listener
   nsCOMPtr<nsIWebBrowserPersist> persist;
   aDownloadItem->GetPersist(getter_AddRefs(persist));
   if (persist) {
@@ -438,13 +440,14 @@ nsDownloadManager::RemoveDownload(const char* aKey)
 
   PRInt32 itemIndex;
   downloads->IndexOf(res, &itemIndex);
-  if (itemIndex > 0) {
-    nsCOMPtr<nsIRDFNode> node;
-    rv = downloads->RemoveElementAt(itemIndex, PR_TRUE, getter_AddRefs(node));
-    if (NS_FAILED(rv)) return rv;
-    return Flush(); // necessary?
-  }
-  return rv;
+  if (itemIndex <= 0)
+    return NS_ERROR_FAILURE;
+  
+  nsCOMPtr<nsIRDFNode> node;
+  rv = downloads->RemoveElementAt(itemIndex, PR_TRUE, getter_AddRefs(node));
+  if (NS_FAILED(rv)) return rv;
+
+  return Flush(); // necessary?
 }  
 
 NS_IMETHODIMP
@@ -495,7 +498,7 @@ nsDownloadManager::OpenProgressDialogFor(const char* aKey, nsIDOMWindow* aParent
   // start time...
   PRInt64 startTime = 0;
   item->GetStartTime(&startTime);
-  if (startTime)
+  if (startTime) // possible not to have a start time yet if the dialog was requested immediately
     dialog->SetStartTime(startTime);
   
   // source...
@@ -894,12 +897,12 @@ DownloadItem::OnStateChange(nsIWebProgress* aWebProgress,
 {
   if (aStateFlags & STATE_START) {
     mStartTime = PR_Now();
-    mRequest = aRequest;
+    mRequest = aRequest; // used for pause/resume
   }
-  else if (aStateFlags & STATE_STOP) {    
+  else if (aStateFlags & STATE_STOP) {
     char* path;
     mTarget->GetPath(&path);
-    mDownloadManager->NotifyDownloadEnded(path);
+    mDownloadManager->DownloadFinished(path);
   }
 
   if (mListener)

xpfe/components/download-manager/src/nsDownloadManager.h

@@ -45,7 +45,6 @@
 #include "nsIDownloadItem.h"
 #include "nsIRDFDataSource.h"
 #include "nsIRDFRemoteDataSource.h"
-#include "nsIRDFContainer.h"
 #include "nsIRDFService.h"
 #include "nsIDOMDocument.h"
 #include "nsIDOMEventListener.h"
@@ -80,7 +79,7 @@ protected:
   nsresult GetProfileDownloadsFileURL(char** aDownloadsFileURL);
   nsresult GetInternalListener(nsIDownloadProgressListener** aInternalListener);
   nsresult AssertProgressInfo();
-  nsresult NotifyDownloadEnded(const char* aTargetPath);
+  nsresult DownloadFinished(const char* aTargetPath);
   PRBool MustUpdateUI() { if (mDocument) return PR_TRUE; return PR_FALSE; }
 
 private:
@@ -108,6 +107,7 @@ protected:
   nsresult SetDownloadManager(nsDownloadManager* aDownloadManager);
   nsresult SetDialogListener(nsIWebProgressListener* aInternalListener);
   nsresult GetDialogListener(nsIWebProgressListener** aInternalListener);
+
 private:
   nsIRDFResource* mDownloadItem;
   nsIRDFDataSource* mDataSource;