uriloader/base/nsITransfer.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsIWebProgressListener2.idl"
   7
   8 interface nsIArray;
   9 interface nsIURI;
  10 interface nsICancelable;
  11 interface nsIMIMEInfo;
  12 interface nsIFile;
  13 interface nsIReferrerInfo;
  14 interface nsIHttpChannel;
  15 webidl BrowsingContext;
  16
  17 [scriptable, uuid(37ec75d3-97ad-4da8-afaa-eabe5b4afd73)]
  18 interface nsITransfer : nsIWebProgressListener2 {
  19
  20     const unsigned long DOWNLOAD_ACCEPTABLE = 0;
  21     const unsigned long DOWNLOAD_FORBIDDEN = 1;
  22     const unsigned long DOWNLOAD_POTENTIALLY_UNSAFE = 2;
  23
  24     /**
  25      * Initializes the transfer with certain properties.  This function must
  26      * be called prior to accessing any properties on this interface.
  27      *
  28      * @param aSource The source URI of the transfer. Must not be null.
  29      *
  30      * @param aSourceOriginalURI The original URI of the transfer in case
  31      *                           aSource is a blob URL. Can be null.
  32      *
  33      * @param aTarget The target URI of the transfer. Must not be null.
  34      *
  35      * @param aDisplayName The user-readable description of the transfer.
  36      *                     Can be empty.
  37      *
  38      * @param aMIMEInfo The MIME info associated with the target,
  39      *                  including MIME type and helper app when appropriate.
  40      *                  This parameter is optional.
  41      *
  42      * @param startTime Time when the download started (ie, when the first
  43      *                  response from the server was received)
  44      *                  XXX presumably wbp and exthandler do this differently
  45      *
  46      * @param aTempFile The location of a temporary file; i.e. a file in which
  47      *                  the received data will be stored, but which is not
  48      *                  equal to the target file. (will be moved to the real
  49      *                  target by the caller, when the download is finished)
  50      *                  May be null.
  51      *
  52      * @param aCancelable An object that can be used to abort the download.
  53      *                    Must not be null.
  54      *                    Implementations are expected to hold a strong
  55      *                    reference to this object until the download is
  56      *                    finished, at which point they should release the
  57      *                    reference.
  58      *
  59      * @param aIsPrivate Used to determine the privacy status of the new transfer.
  60      *                   If true, indicates that the transfer was initiated from
  61      *                   a source that desires privacy.
  62      *
  63      * @param aDownloadClassification Indicates wheter the download is unwanted,
  64      *                                should be considered dangerous or insecure.
  65      *
  66      * @param aReferrerInfo The Referrer this download is started with
  67      *
  68      * @param aOpenDownloadsListOnStart true (default) - Open downloads panel.
  69      *                                  false - Only show an icon indicator.
  70      *                                  This parameter is optional.
  71      */
  72     void init(in nsIURI aSource,
  73               in nsIURI aSourceOriginalURI,
  74               in nsIURI aTarget,
  75               in AString aDisplayName,
  76               in nsIMIMEInfo aMIMEInfo,
  77               in PRTime startTime,
  78               in nsIFile aTempFile,
  79               in nsICancelable aCancelable,
  80               in boolean aIsPrivate,
  81               in long aDownloadClassification,
  82               in nsIReferrerInfo aReferrerInfo,
  83               [optional] in boolean aOpenDownloadsListOnStart);
  84
  85     /**
  86      * Same as init, but allows for passing the browsingContext
  87      * which will allow for opening the download with the same
  88      * userContextId and auth header.
  89      *
  90      * @param aBrowsingContext BrowsingContext of the initiating document.
  91      *
  92      * @param aHandleInternally Set to true if the download should be opened within
  93      *                          the browser.
  94      * @param aHttpChannel Channel of the initiating document.
  95      */
  96     void initWithBrowsingContext(in nsIURI aSource,
  97                                   in nsIURI aTarget,
  98                                     in AString aDisplayName,
  99                                     in nsIMIMEInfo aMIMEInfo,
 100                                     in PRTime startTime,
 101                                     in nsIFile aTempFile,
 102                                     in nsICancelable aCancelable,
 103                                     in boolean aIsPrivate,
 104                                     in long aDownloadClassification,
 105                                     in nsIReferrerInfo aReferrerInfo,
 106                                     in boolean aOpenDownloadsListOnStart,
 107                                     in BrowsingContext aBrowsingContext,
 108                                     in boolean aHandleInternally,
 109                                     in nsIHttpChannel aHttpChannel);
 110
 111
 112     /*
 113      * Used to notify the transfer object of the hash of the downloaded file.
 114      * Must be called on the main thread, only after the download has finished
 115      * successfully.
 116      * @param aHash The SHA-256 hash in raw bytes of the downloaded file.
 117      */
 118     void setSha256Hash(in ACString aHash);
 119
 120     /*
 121      * Used to notify the transfer object of the signature of the downloaded
 122      * file.  Must be called on the main thread, only after the download has
 123      * finished successfully.
 124      * @param aSignatureInfo The Array of Array of Array of bytes
 125      *        certificates of the downloaded file.
 126      */
 127     void setSignatureInfo(in Array<Array<Array<uint8_t> > > aSignatureInfo);
 128
 129     /*
 130      * Used to notify the transfer object of the redirects associated with the
 131      * channel that terminated in the downloaded file.  Must be called on the
 132      * main thread, only after the download has finished successfully.
 133      * @param aRedirects The nsIArray of nsIPrincipal of redirected URIs
 134      *        associated with the downloaded file.
 135      */
 136     void setRedirects(in nsIArray aRedirects);
 137 };
 138
 139 %{C++
 140 /**
 141  * A component with this contract ID will be created each time a download is
 142  * started, and nsITransfer::Init will be called on it and an observer will be set.
 143  *
 144  * Notifications of the download progress will happen via
 145  * nsIWebProgressListener/nsIWebProgressListener2.
 146  *
 147  * INTERFACES THAT MUST BE IMPLEMENTED:
 148  *   nsITransfer
 149  *   nsIWebProgressListener
 150  *   nsIWebProgressListener2
 151  *
 152  * XXX move this to nsEmbedCID.h once the interfaces (and the contract ID) are
 153  * frozen.
 154  */
 155 #define NS_TRANSFER_CONTRACTID "@mozilla.org/transfer;1"
 156 %}