Back to index

lightning-sunbird  0.9+nobinonly
CHDownloadProgressDisplay.h
Go to the documentation of this file.
00001 /* ***** BEGIN LICENSE BLOCK *****
00002  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00003  *
00004  * The contents of this file are subject to the Mozilla Public License Version
00005  * 1.1 (the "License"); you may not use this file except in compliance with
00006  * the License. You may obtain a copy of the License at
00007  * http://www.mozilla.org/MPL/
00008  *
00009  * Software distributed under the License is distributed on an "AS IS" basis,
00010  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00011  * for the specific language governing rights and limitations under the
00012  * License.
00013  *
00014  * The Original Code is Chimera code.
00015  *
00016  * The Initial Developer of the Original Code is
00017  * Netscape Communications Corporation.
00018  * Portions created by the Initial Developer are Copyright (C) 2002
00019  * the Initial Developer. All Rights Reserved.
00020  *
00021  * Contributor(s):
00022  *   Simon Fraser <sfraser@netscape.com>
00023  *
00024  * Alternatively, the contents of this file may be used under the terms of
00025  * either the GNU General Public License Version 2 or later (the "GPL"), or
00026  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00027  * in which case the provisions of the GPL or the LGPL are applicable instead
00028  * of those above. If you wish to allow use of your version of this file only
00029  * under the terms of either the GPL or the LGPL, and not to allow others to
00030  * use your version of this file under the terms of the MPL, indicate your
00031  * decision by deleting the provisions above and replace them with the notice
00032  * and other provisions required by the GPL or the LGPL. If you do not delete
00033  * the provisions above, a recipient may use your version of this file under
00034  * the terms of any one of the MPL, the GPL or the LGPL.
00035  *
00036  * ***** END LICENSE BLOCK ***** */
00037 
00038 /*
00039   The classes and protocol in this file allow Cocoa applications to easily
00040   reuse the underlying download implementation, which deals with the complexity
00041   of Gecko's downloading callbacks.
00042   
00043   There are three things here:
00044   
00045   1.  The CHDownloadProgressDisplay protocol.
00046   
00047       This is a formal protocol that needs to be implemented by
00048       a window controller for your progress window. Its methods
00049       will be called by the underlying C++ downloading classes.
00050      
00051   2.  The Obj-C DownloadControllerFactory class.
00052   
00053       This class should be subclassed by an embedder, with an
00054       implementation of 'createDownloadController' that hands back
00055       a new instance of an NSWindowController that implements the
00056       <CHDownloadProgressDisplay> protocol.
00057       
00058       The underlying C++ classes use this factory to create the
00059       progress window controller.
00060   
00061   3.  The CHDownloader C++ class
00062   
00063       This base class exists to hide the complextity of the download
00064       listener classes (which deal with Gecko callbacks) from the
00065       window controller.  Embedders don't need to do anything with it.
00066 
00067   How these classes fit together:
00068   
00069   There are 2 ways in which a download is initiated:
00070   
00071   (i)   File->Save.
00072   
00073         Chimera does a complex dance here in order to get certain
00074         information about the data being downloaded (it needs to
00075         start the download before it can read some optional MIME headers).
00076         
00077         CBrowserView creates an nsIWebBrowserPersist (WBP), and then a
00078         nsHeaderSniffer, which implements nsIWebProgressListener and is set to
00079         observer the WBP. When nsHeaderSniffer hears about the start of the
00080         download, it decides on a file name, and what format to save the data
00081         in. It then cancels the current WPB, makes another one, and does
00082         a CreateInstance of an nsIDownload (making one of our nsDownloadListener
00083         -- aka nsDownloder -- objects), and sets that as the nsIWebProgressListener.
00084         The full download procedes from there.
00085         
00086   (ii)  Click to download (e.g. FTP link)
00087   
00088         This is simpler. The backend (necko) does the CreateInstance of the
00089         nsIDownload, and the download progresses.
00090         
00091   In both cases, creating the nsDownloadListener and calling its Init() method
00092   calls nsDownloder::CreateDownloadDisplay(). The nsDownloder has as a member
00093   variable a DownloadControllerFactory (see above), which got passed to it
00094   via our XPCOM factory for nsIDownload objects. It then uses that DownloadControllerFactory
00095   to get an instance of the download progress window controller, which then
00096   shows the download progress window.
00097   
00098   Simple, eh?
00099   
00100 */
00101 
00102 #import <AppKit/AppKit.h>
00103 
00104 #include "nsISupports.h"
00105 
00106 class CHDownloader;
00107 
00108 // a formal protocol for something that implements progress display
00109 // Embedders can make a window controller that conforms to this
00110 // protocol, and reuse nsDownloadListener to get download UI.
00111 @protocol CHDownloadProgressDisplay
00112 
00113 - (void)onStartDownload:(BOOL)isFileSave;
00114 - (void)onEndDownload;
00115 
00116 - (void)setProgressTo:(long)aCurProgress ofMax:(long)aMaxProgress;
00117 
00118 - (void)setDownloadListener:(CHDownloader*)aDownloader;
00119 - (void)setSourceURL:(NSString*)aSourceURL;
00120 - (void)setDestinationPath:(NSString*)aDestPath;
00121 
00122 @end
00123 
00124 // subclass this, and have your subclass instantiate and return your window
00125 // controller in createDownloadController
00126 @interface DownloadControllerFactory : NSObject
00127 {
00128 }
00129 
00130 - (NSWindowController<CHDownloadProgressDisplay> *)createDownloadController;
00131 
00132 @end
00133 
00134 
00135 // Pure virtual base class for a generic downloader, that the progress UI can talk to.
00136 // It implements nsISupports so that it can be refcounted. This class insulates the
00137 // UI code from having to know too much about the nsIDownloadListener.
00138 // It is responsible for creating the download UI, via the DownloadControllerFactory
00139 // that it owns.
00140 class CHDownloader : public nsISupports
00141 {
00142 public:
00143                   CHDownloader(DownloadControllerFactory* inControllerFactory);
00144     virtual       ~CHDownloader();
00145 
00146     NS_DECL_ISUPPORTS
00147 
00148     virtual void PauseDownload() = 0;
00149     virtual void ResumeDownload() = 0;
00150     virtual void CancelDownload() = 0;
00151     virtual void DownloadDone() = 0;
00152     virtual void DetachDownloadDisplay() = 0;           // tell downloader to forget about its display
00153 
00154     virtual void CreateDownloadDisplay();
00155     
00156 protected:
00157   
00158     PRBool      IsFileSave() { return mIsFileSave; }
00159     void        SetIsFileSave(PRBool inIsFileSave) { mIsFileSave = inIsFileSave; }
00160 
00161 protected:
00162 
00163     DownloadControllerFactory*    mControllerFactory;
00164     id <CHDownloadProgressDisplay>  mDownloadDisplay;   // something that implements the CHDownloadProgressDisplay protocol
00165     PRBool                        mIsFileSave;        // true if we're doing a save, rather than a download
00166 };
00167