netwerk/base/nsIBackgroundFileSaver.idl

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #include "nsISupports.idl"
   8
   9 interface nsIArray;
  10 interface nsIBackgroundFileSaverObserver;
  11 interface nsIFile;
  12
  13 /**
  14  * Allows saving data to a file, while handling all the input/output on a
  15  * background thread, including the initial file name assignment and any
  16  * subsequent renaming of the target file.
  17  *
  18  * This interface is designed for file downloads.  Generally, they start in the
  19  * temporary directory, while the user is selecting the final name.  Then, they
  20  * are moved to the chosen target directory with a ".part" extension appended to
  21  * the file name.  Finally, they are renamed when the download is completed.
  22  *
  23  * Components implementing both nsIBackgroundFileSaver and nsIStreamListener
  24  * allow data to be fed using an implementation of OnDataAvailable that never
  25  * blocks the calling thread.  They suspend the request that drives the stream
  26  * listener in case too much data is being fed, and resume it when the data has
  27  * been written.  Calling OnStopRequest does not necessarily close the target
  28  * file, and the Finish method must be called to complete the operation.
  29  *
  30  * Components implementing both nsIBackgroundFileSaver and nsIAsyncOutputStream
  31  * allow data to be fed directly to the non-blocking output stream, that however
  32  * may return NS_BASE_STREAM_WOULD_BLOCK in case too much data is being fed.
  33  * Closing the output stream does not necessarily close the target file, and the
  34  * Finish method must be called to complete the operation.
  35  *
  36  * @remarks Implementations may require the consumer to always call Finish.  If
  37  *          the object reference is released without calling Finish, a memory
  38  *          leak may occur, and the target file might be kept locked. All
  39  *          public methods of the interface may only be called from the main
  40  *          thread.
  41  */
  42 [scriptable, uuid(c43544a4-682c-4262-b407-2453d26e660d)]
  43 interface nsIBackgroundFileSaver : nsISupports
  44 {
  45   /**
  46    * This observer receives notifications when the target file name changes and
  47    * when the operation completes, successfully or not.
  48    *
  49    * @remarks A strong reference to the observer is held.  Notification events
  50    *          are dispatched to the thread that created the object that
  51    *          implements nsIBackgroundFileSaver.
  52    */
  53   attribute nsIBackgroundFileSaverObserver observer;
  54
  55   /**
  56    * An Array of Array of Array of bytes, representing a chain of
  57    * X.509 certificates, the last of which signed the downloaded file.
  58    * Each list may belong to a different signer and contain certificates
  59    * all the way up to the root.
  60    *
  61    * @throws NS_ERROR_NOT_AVAILABLE
  62    *         In case this is called before the onSaveComplete method has been
  63    *         called to notify success, or enableSignatureInfo has not been
  64    *         called.
  65    */
  66   readonly attribute Array<Array<Array<uint8_t> > > signatureInfo;
  67
  68   /**
  69    * The SHA-256 hash, in raw bytes, associated with the data that was saved.
  70    *
  71    * In case the enableAppend method has been called, the hash computation
  72    * includes the contents of the existing file, if any.
  73    *
  74    * @throws NS_ERROR_NOT_AVAILABLE
  75    *         In case the enableSha256 method has not been called, or before the
  76    *         onSaveComplete method has been called to notify success.
  77    */
  78   readonly attribute ACString sha256Hash;
  79
  80   /**
  81    * Instructs the component to compute the signatureInfo of the target file,
  82    * and make it available in the signatureInfo property.
  83    *
  84    * @remarks This must be set on the main thread before the first call to
  85    *          setTarget.
  86    */
  87   void enableSignatureInfo();
  88
  89   /**
  90    * Instructs the component to compute the SHA-256 hash of the target file, and
  91    * make it available in the sha256Hash property.
  92    *
  93    * @remarks This must be set on the main thread before the first call to
  94    *          setTarget.
  95    */
  96   void enableSha256();
  97
  98   /**
  99    * Instructs the component to append data to the initial target file, that
 100    * will be specified by the first call to the setTarget method, instead of
 101    * overwriting the file.
 102    *
 103    * If the initial target file does not exist, this method has no effect.
 104    *
 105    * @remarks This must be set on the main thread before the first call to
 106    *          setTarget.
 107    */
 108   void enableAppend();
 109
 110   /**
 111    * Sets the name of the output file to be written.  The target can be changed
 112    * after data has already been fed, in which case the existing file will be
 113    * moved to the new destination.
 114    *
 115    * In case the specified file already exists, and this method is called for
 116    * the first time, the file may be either overwritten or appended to, based on
 117    * whether the enableAppend method was called.  Subsequent calls always
 118    * overwrite the specified target file with the previously saved data.
 119    *
 120    * No file will be written until this function is called at least once.  It's
 121    * recommended not to feed any data until the output file is set.
 122    *
 123    * If an input/output error occurs with the specified file, the save operation
 124    * fails.  Failure is notified asynchronously through the observer.
 125    *
 126    * @param aTarget
 127    *        New output file to be written.
 128    * @param aKeepPartial
 129    *        Indicates whether aFile should be kept as partially completed,
 130    *        rather than deleted, if the operation fails or is canceled.  This is
 131    *        generally set for downloads that use temporary ".part" files.
 132    */
 133   void setTarget(in nsIFile aTarget, in boolean aKeepPartial);
 134
 135   /**
 136    * Terminates access to the output file, then notifies the observer with the
 137    * specified status code.  A failure code will force the operation to be
 138    * canceled, in which case the output file will be deleted if requested.
 139    *
 140    * This forces the involved streams to be closed, thus no more data should be
 141    * fed to the component after this method has been called.
 142    *
 143    * This is the last method that should be called on this object, and the
 144    * target file name cannot be changed anymore after this method has been
 145    * called.  Conversely, before calling this method, the file can still be
 146    * renamed even if all the data has been fed.
 147    *
 148    * @param aStatus
 149    *        Result code that determines whether the operation should succeed or
 150    *        be canceled, and is notified to the observer.  If the operation
 151    *        fails meanwhile for other reasons, or the observer has been already
 152    *        notified of completion, this status code is ignored.
 153    */
 154   void finish(in nsresult aStatus);
 155 };
 156
 157 [scriptable, uuid(ee7058c3-6e54-4411-b76b-3ce87b76fcb6)]
 158 interface nsIBackgroundFileSaverObserver : nsISupports
 159 {
 160   /**
 161    * Called when the name of the output file has been determined.  This function
 162    * may be called more than once if the target file is renamed while saving.
 163    *
 164    * @param aSaver
 165    *        Reference to the object that raised the notification.
 166    * @param aTarget
 167    *        Name of the file that is being written.
 168    */
 169   void onTargetChange(in nsIBackgroundFileSaver aSaver, in nsIFile aTarget);
 170
 171   /**
 172    * Called when the operation completed, and the target file has been closed.
 173    * If the operation succeeded, the target file is ready to be used, otherwise
 174    * it might have been already deleted.
 175    *
 176    * @param aSaver
 177    *        Reference to the object that raised the notification.
 178    * @param aStatus
 179    *        Result code that determines whether the operation succeeded or
 180    *        failed, as well as the failure reason.
 181    */
 182   void onSaveComplete(in nsIBackgroundFileSaver aSaver, in nsresult aStatus);
 183 };