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

/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* ***** BEGIN LICENSE BLOCK *****
 * Version: NPL 1.1/GPL 2.0/LGPL 2.1
 *
 * The contents of this file are subject to the Netscape Public License
 * Version 1.1 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * http://www.mozilla.org/NPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is mozilla.org code.
 *
 * The Initial Developer of the Original Code is 
 * Netscape Communications Corporation.
 * Portions created by the Initial Developer are Copyright (C) 1998
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *   Blake Ross <blaker@netscape.com> 
 *   Ben Goodger <ben@netscape.com>
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either the GNU General Public License Version 2 or later (the "GPL"), or 
 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the NPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the NPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */

// Keeps track of ongoing downloads, in the form of nsIDownload's. 

#include "nsISupports.idl"

interface nsIDOMWindow;
interface nsIURI;
interface nsILocalFile;
interface nsIDownload;
interface nsIWebBrowserPersist;
interface nsIMIMEInfo;

[scriptable, uuid(9be66cc0-1dd1-11b2-8617-e3a3ed26e3b0)]
interface nsIDownloadManager : nsISupports {

  // Methods called by clients to carry out various managing functions

  /**
  * Creates an nsIDownload and adds it to be managed by the download manager.
  *
  * @param aSource The source (nsIURI) of the download.
  *
  * @param aTarget The local file to which the download is being saved.
  *
  * @param aDisplayName The user-readable description of the download.
  *
  * @param aPersist The "persist" used to transfer the download.  If set,
  *                 the manager will set its listener to the download item
  *                 and use it for cancellation.  If not set, the client
  *                 is expected to set the download item as the listener on
  *                 whatever transfer component is being used, and to
  *                 set an observer on the download item that listens for
  *                 the "oncancel" topic and cancels the download.
  *
  * @return The newly created download item with the passed-in properties.
  */
  
  nsIDownload addDownload(in nsIURI aSource,
                          in nsILocalFile aTarget,
                          in wstring aDisplayName,
                          in nsIMIMEInfo aMIMEInfo,
                          in long long startTime,
                          in nsIWebBrowserPersist aPersist);

  /**
  *  Retrieves an in-progress download managed by the download manager.
  *
  *  @param aPersistentDescriptor The unique identifier used to describe a
  *                               a download, and an attribute of nsILocalFile.
  *                               On Windows and Linux, this is just the path
  *                               of the target, but on Mac this is guaranteed
  *                               to be unique.
  *
  *  @return The download with the specified persistent descriptor.
  */

  nsIDownload getDownload(in string aPersistentDescriptor);

  /**
  * Cancels the download with the specified persistent descriptor if it's
  * currently in progress.  If a "persist" was specified for the download,
  * nsIWebBrowserPersist::CancelSave will be called.  If an observer was set
  * on the nsIDownload, it will be notified with the "oncancel" topic.  Clients
  * that don't provide a "persist" must listen for this topic and cancel the
  * download.
  *
  * @param aPersistentDescriptor The persistent descriptor of the download to
  *                              be cancelled.
  */

  void cancelDownload(in string aPersistentDescriptor);

  /**
  * Removes the download with the specified persistent descriptor if it's not
  * currently in progress.  Whereas cancelDownload simply cancels the transfer
  * but retains information about it, removeDownload removes all knowledge of it.
  *
  * @param aPersistentDescriptor The persistent descriptor of the download to
  *                              be removed.
  */

  void removeDownload(in string aPersistentDescriptor);

  // UI-related methods

  /**
  * Opens the Download Manager front end.
  *
  * @param aParent The parent, or opener, of the front end (optional).
  * @param aDownload A download to pass to the manager window.  Useful
  *                  if, for example, you want the window to select a
  *                  certain download (optional).
  */

  void open(in nsIDOMWindow aParent, in nsIDownload aDownload);

  /**
  * Opens an individual progress dialog displaying progress for the download.
  *
  * @param aPersistentDescriptor The persistent descriptor of the download to
  *                              display progress for.
  *
  * @param aParent The parent, or opener, of the front end (optional).
  */

  void openProgressDialogFor(in string aPersistentDescriptor, in nsIDOMWindow aParent);

  /**
  * Called when the download manager front end is closed.  Useful for
  * third party managers to let us know when they've closed.
  */

  void onClose();
  
  /**
  * Indicate that a batch update (e.g. mass removal) is about to start.
  */

  void startBatchUpdate();
  
  /**
  * Indicate that a batch update is ending.
  */
  
  void endBatchUpdate();
};


%{C++
#define NS_DOWNLOADMANAGER_CONTRACTID "@mozilla.org/download-manager;1"
#define NS_DOWNLOADMANAGER_CLASSNAME "Mozilla Download Manager"
// {EDB0490E-1DD1-11B2-83B8-DBF8D85906A6}
#define NS_DOWNLOADMANAGER_CID \
    { 0xedb0490e, 0x1dd1, 0x11b2, { 0x83, 0xb8, 0xdb, 0xf8, 0xd8, 0x59, 0x06, 0xa6 } }
%}