modules/libjar/zipwriter/public/nsIZipWriter.idl

   1 /* ***** BEGIN LICENSE BLOCK *****
   2  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   3  *
   4  * The contents of this file are subject to the Mozilla Public License Version
   5  * 1.1 (the "License"); you may not use this file except in compliance with
   6  * the License. You may obtain a copy of the License at
   7  * http://www.mozilla.org/MPL/
   8  *
   9  * Software distributed under the License is distributed on an "AS IS" basis,
  10  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  11  * for the specific language governing rights and limitations under the
  12  * License.
  13  *
  14  * The Original Code is Zip Writer Component.
  15  *
  16  * The Initial Developer of the Original Code is
  17  * Dave Townsend <dtownsend@oxymoronical.com>.
  18  *
  19  * Portions created by the Initial Developer are Copyright (C) 2007
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK *****
  37  */
  38
  39 #include "nsISupports.idl"
  40 interface nsIChannel;
  41 interface nsIInputStream;
  42 interface nsIRequestObserver;
  43 interface nsIFile;
  44 interface nsIZipEntry;
  45
  46 /**
  47  * nsIZipWriter
  48  *
  49  * An interface for a zip archiver that can be used from script.
  50  *
  51  * The interface supports both a synchronous method of archiving data and a
  52  * queueing system to allow operations to be prepared then run in sequence
  53  * with notification after completion.
  54  *
  55  * Operations added to the queue do not get performed until performQueue is
  56  * called at which point they will be performed in the order that they were
  57  * added to the queue.
  58  *
  59  * Operations performed on the queue will throw any errors out to the
  60  * observer.
  61  *
  62  * An attempt to perform a synchronous operation while the background queue
  63  * is in progress will throw NS_ERROR_IN_PROGRESS.
  64  *
  65  * Entry names should use /'s as path separators and should not start with
  66  * a /.
  67  *
  68  * It is not generally necessary to add directory entries in order to add file
  69  * entries within them, however it is possible that some zip programs may
  70  * experience problems what that.
  71  */
  72 [scriptable, uuid(6d4ef074-206c-4649-9884-57bc355864d6)]
  73 interface nsIZipWriter : nsISupports
  74 {
  75   /**
  76    * Some predefined compression levels
  77    */
  78   const PRUint32 COMPRESSION_NONE    = 0;
  79   const PRUint32 COMPRESSION_FASTEST = 1;
  80   const PRUint32 COMPRESSION_DEFAULT = 6;
  81   const PRUint32 COMPRESSION_BEST    = 9;
  82
  83   /**
  84    * Gets or sets the comment associated with the open zip file.
  85    *
  86    * @throws NS_ERROR_NOT_INITIALIZED if no zip file has been opened
  87    */
  88   attribute ACString comment;
  89
  90   /**
  91    * Indicates that operations on the background queue are being performed.
  92    */
  93   readonly attribute boolean inQueue;
  94
  95   /**
  96    * The file that the zipwriter is writing to.
  97    */
  98   readonly attribute nsIFile file;
  99
 100   /**
 101    * Opens a zip file.
 102    *
 103    * @param aFile the zip file to open
 104    * @param aIoFlags the open flags for the zip file from prio.h
 105    *
 106    * @throws NS_ERROR_ALREADY_INITIALIZED if a zip file is already open
 107    * @throws NS_ERROR_INVALID_ARG if aFile is null
 108    * @throws NS_ERROR_FILE_NOT_FOUND if aFile does not exist and flags did
 109    *  not allow for creation
 110    * @throws NS_ERROR_FILE_CORRUPTED if the file does not contain zip markers
 111    * @throws <other-error> on failure to open zip file (most likely corrupt
 112    *  or unsupported form)
 113    */
 114   void open(in nsIFile aFile, in PRInt32 aIoFlags);
 115
 116   /**
 117    * Returns a nsIZipEntry describing a specified zip entry or null if there
 118    * is no such entry in the zip file
 119    *
 120    * @param aZipEntry the path of the entry
 121    */
 122   nsIZipEntry getEntry(in AUTF8String aZipEntry);
 123
 124   /**
 125    * Checks whether the zipfile contains an entry specified by zipEntry.
 126    *
 127    * @param aZipEntry the path of the entry
 128    */
 129   boolean hasEntry(in AUTF8String aZipEntry);
 130
 131   /**
 132    * Adds a new directory entry to the zip file. If aZipEntry does not end with
 133    * "/" then it will be added.
 134    *
 135    * @param aZipEntry the path of the directory entry
 136    * @param aModTime the modification time of the entry in microseconds
 137    * @param aQueue adds the operation to the background queue. Will be
 138    *        performed when processQueue is called.
 139    *
 140    * @throws NS_ERROR_NOT_INITIALIZED if no zip file has been opened
 141    * @throws NS_ERROR_FILE_ALREADY_EXISTS if the path already exists in the
 142    *  file
 143    * @throws NS_ERROR_IN_PROGRESS if another operation is currently in progress
 144    */
 145   void addEntryDirectory(in AUTF8String aZipEntry, in PRTime aModTime,
 146                          in boolean aQueue);
 147
 148   /**
 149    * Adds a new file or directory to the zip file. If the specified file is
 150    * a directory then this will be equivalent to a call to
 151    * addEntryDirectory(aZipEntry, aFile.lastModifiedTime, aQueue)
 152    *
 153    * @param aZipEntry the path of the file entry
 154    * @param aCompression the compression level, 0 is no compression, 9 is best
 155    * @param aFile the file to get the data and modification time from
 156    * @param aQueue adds the operation to the background queue. Will be
 157    *        performed when processQueue is called.
 158    *
 159    * @throws NS_ERROR_NOT_INITIALIZED if no zip file has been opened
 160    * @throws NS_ERROR_FILE_ALREADY_EXISTS if the path already exists in the zip
 161    * @throws NS_ERROR_IN_PROGRESS if another operation is currently in progress
 162    * @throws NS_ERROR_FILE_NOT_FOUND if file does not exist
 163    */
 164   void addEntryFile(in AUTF8String aZipEntry,
 165                     in PRInt32 aCompression, in nsIFile aFile,
 166                     in boolean aQueue);
 167
 168   /**
 169    * Adds data from a channel to the zip file. If the operation is performed
 170    * on the queue then the channel will be opened asynchronously, otherwise
 171    * the channel must support being opened synchronously.
 172    *
 173    * @param aZipEntry the path of the file entry
 174    * @param aModTime the modification time of the entry in microseconds
 175    * @param aCompression the compression level, 0 is no compression, 9 is best
 176    * @param aChannel the channel to get the data from
 177    * @param aQueue adds the operation to the background queue. Will be
 178    *        performed when processQueue is called.
 179    *
 180    * @throws NS_ERROR_NOT_INITIALIZED if no zip file has been opened
 181    * @throws NS_ERROR_FILE_ALREADY_EXISTS if the path already exists in the zip
 182    * @throws NS_ERROR_IN_PROGRESS if another operation is currently in progress
 183    */
 184   void addEntryChannel(in AUTF8String aZipEntry, in PRTime aModTime,
 185                        in PRInt32 aCompression, in nsIChannel aChannel,
 186                        in boolean aQueue);
 187
 188   /**
 189    * Adds data from an input stream to the zip file.
 190    *
 191    * @param aZipEntry the path of the file entry
 192    * @param aModTime the modification time of the entry in microseconds
 193    * @param aCompression the compression level, 0 is no compression, 9 is best
 194    * @param aStream the input stream to get the data from
 195    * @param aQueue adds the operation to the background queue. Will be
 196    *        performed when processQueue is called.
 197    *
 198    * @throws NS_ERROR_NOT_INITIALIZED if no zip file has been opened
 199    * @throws NS_ERROR_FILE_ALREADY_EXISTS if the path already exists in the zip
 200    * @throws NS_ERROR_IN_PROGRESS if another operation is currently in progress
 201    */
 202   void addEntryStream(in AUTF8String aZipEntry, in PRTime aModTime,
 203                       in PRInt32 aCompression, in nsIInputStream aStream,
 204                       in boolean aQueue);
 205
 206   /**
 207    * Removes an existing entry from the zip file.
 208    *
 209    * @param aZipEntry the path of the entry to be removed
 210    * @param aQueue adds the operation to the background queue. Will be
 211    *        performed when processQueue is called.
 212    *
 213    * @throws NS_ERROR_NOT_INITIALIZED if no zip file has been opened
 214    * @throws NS_ERROR_IN_PROGRESS if another operation is currently in progress
 215    * @throws NS_ERROR_FILE_NOT_FOUND if no entry with the given path exists
 216    * @throws <other-error> on failure to update the zip file
 217    */
 218   void removeEntry(in AUTF8String aZipEntry, in boolean aQueue);
 219
 220   /**
 221    * Processes all queued items until complete or some error occurs. The
 222    * observer will be notified when the first operation starts and when the
 223    * last operation completes. Any failures will be passed to the observer.
 224    * The zip writer will be busy until the queue is complete or some error
 225    * halted processing of the queue early. In the event of an early failure,
 226    * remaining items will stay in the queue and calling processQueue will
 227    * continue.
 228    *
 229    * @throws NS_ERROR_NOT_INITIALIZED if no zip file has been opened
 230    * @throws NS_ERROR_IN_PROGRESS if the queue is already in progress
 231    */
 232   void processQueue(in nsIRequestObserver aObserver, in nsISupports aContext);
 233
 234   /**
 235    * Closes the zip file.
 236    *
 237    * @throws NS_ERROR_NOT_INITIALIZED if no zip file has been opened
 238    * @throws NS_ERROR_IN_PROGRESS if another operation is currently in progress
 239    * @throws <other-error> on failure to complete the zip file
 240    */
 241   void close();
 242 };