modules/libjar/nsIZipReader.idl

   1 /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
   2  *
   3  * ***** BEGIN LICENSE BLOCK *****
   4  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   5  *
   6  * The contents of this file are subject to the Mozilla Public License Version
   7  * 1.1 (the "License"); you may not use this file except in compliance with
   8  * the License. You may obtain a copy of the License at
   9  * http://www.mozilla.org/MPL/
  10  *
  11  * Software distributed under the License is distributed on an "AS IS" basis,
  12  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  13  * for the specific language governing rights and limitations under the
  14  * License.
  15  *
  16  * The Original Code is Mozilla Communicator client code, released
  17  * March 31, 1998.
  18  *
  19  * The Initial Developer of the Original Code is
  20  * Netscape Communications Corporation.
  21  * Portions created by the Initial Developer are Copyright (C) 1998
  22  * the Initial Developer. All Rights Reserved.
  23  *
  24  * Contributor(s):
  25  *   Daniel Veditz <dveditz@netscape.com>
  26  *   Don Bragg <dbragg@netscape.com>
  27  *   Samir Gehani <sgehani@netscape.com>
  28  *   Mitch Stoltz <mstoltz@netscape.com>
  29  *   Jeff Walden <jwalden+code@mit.edu>
  30  *
  31  * Alternatively, the contents of this file may be used under the terms of
  32  * either the GNU General Public License Version 2 or later (the "GPL"), or
  33  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  34  * in which case the provisions of the GPL or the LGPL are applicable instead
  35  * of those above. If you wish to allow use of your version of this file only
  36  * under the terms of either the GPL or the LGPL, and not to allow others to
  37  * use your version of this file under the terms of the MPL, indicate your
  38  * decision by deleting the provisions above and replace them with the notice
  39  * and other provisions required by the GPL or the LGPL. If you do not delete
  40  * the provisions above, a recipient may use your version of this file under
  41  * the terms of any one of the MPL, the GPL or the LGPL.
  42  *
  43  * ***** END LICENSE BLOCK ***** */
  44
  45 #include "nsISupports.idl"
  46
  47 interface nsIUTF8StringEnumerator;
  48 interface nsIInputStream;
  49 interface nsIFile;
  50
  51 [scriptable, uuid(e1c028bc-c478-11da-95a8-00e08161165f)]
  52 interface nsIZipEntry : nsISupports
  53 {
  54     /**
  55      * The type of compression used for the item.  The possible values and
  56      * their meanings are defined in the zip file specification at
  57      * http://www.pkware.com/business_and_developers/developer/appnote/
  58      */
  59     readonly attribute unsigned short   compression;
  60     /**
  61      * The compressed size of the data in the item.
  62      */
  63     readonly attribute unsigned long    size;
  64     /**
  65      * The uncompressed size of the data in the item.
  66      */
  67     readonly attribute unsigned long    realSize;
  68     /**
  69      * The CRC-32 hash of the file in the entry.
  70      */
  71     readonly attribute unsigned long    CRC32;
  72     /**
  73      * True if the name of the entry ends with '/' and false otherwise.
  74      */
  75     readonly attribute boolean          isDirectory;
  76     /**
  77      * The time at which this item was last modified.
  78      */
  79     readonly attribute PRTime           lastModifiedTime;
  80     /**
  81      * Use this attribute to determine whether this item is an actual zip entry
  82      * or is one synthesized for part of a real entry's path.  A synthesized
  83      * entry represents a directory within the zip file which has no
  84      * corresponding entry within the zip file.  For example, the entry for the
  85      * directory foo/ in a zip containing exactly one entry for foo/bar.txt
  86      * is synthetic.  If the zip file contains an actual entry for a directory,
  87      * this attribute will be false for the nsIZipEntry for that directory.
  88      * It is impossible for a file to be synthetic.
  89      */
  90     readonly attribute boolean          isSynthetic;
  91 };
  92
  93 [scriptable, uuid(5cce7f53-23b3-47f8-be05-122c0ba703fd)]
  94 interface nsIZipReader : nsISupports
  95 {
  96     /**
  97      * Opens a zip file for reading.
  98      * It is allowed to open with another file,
  99      * but it needs to be closed first with close().
 100      */
 101     void open(in nsIFile zipFile);
 102
 103     /**
 104      * The file that represents the zip with which this zip reader was
 105      * initialized.
 106      */
 107     readonly attribute nsIFile file;
 108
 109     /**
 110      * Closes a zip reader. Subsequent attempts to extract files or read from
 111      * its input stream will result in an error.
 112      */
 113     void close();
 114
 115     /**
 116      * Tests the integrity of the archive by performing a CRC check
 117      * on each item expanded into memory.  If an entry is specified
 118      * the integrity of only that item is tested.  If NULL is passed
 119      * in the integrity of all items in the archive are tested.
 120      */
 121     void test(in string aEntryName);
 122
 123     /**
 124      * Extracts a zip entry into a local file specified by outFile.
 125      * The entry must be stored in the zip in either uncompressed or
 126      * DEFLATE-compressed format for the extraction to be successful.
 127      * If the entry is a directory, the directory will be extracted
 128      * non-recursively.
 129      */
 130     void extract(in string zipEntry, in nsIFile outFile);
 131
 132     /**
 133      * Returns a nsIZipEntry describing a specified zip entry.
 134      */
 135     nsIZipEntry getEntry(in string zipEntry);
 136
 137     /**
 138      * Checks whether the zipfile contains an entry specified by entryName.
 139      */
 140     boolean hasEntry(in AUTF8String zipEntry);
 141
 142     /**
 143      * Returns a string enumerator containing the matching entry names.
 144      *
 145      * @param aPattern
 146      *   A regular expression used to find matching entries in the zip file.
 147      *   Set this parameter to null to get all entries; otherwise, use the
 148      *   following syntax:
 149      *
 150      *   o * matches anything
 151      *   o ? matches one character
 152      *   o $ matches the end of the string
 153      *   o [abc] matches one occurrence of a, b, or c. The only character that
 154      *           must be escaped inside the brackets is ].  ^ and - must never
 155      *           appear in the first and second positions within the brackets,
 156      *           respectively.  (In the former case, the behavior specified for
 157      *           '[^az]' will happen.)
 158      *   o [a-z] matches any character between a and z.  The characters a and z
 159      *           must either both be letters or both be numbers, with the
 160      *           character represented by 'a' having a lower ASCII value than
 161      *           the character represented by 'z'.
 162      *   o [^az] matches any character except a or z.  If ] is to appear inside
 163      *           the brackets as a character to not match, it must be escaped.
 164      *   o pat~pat2 returns matches to the pattern 'pat' which do not also match
 165      *              the pattern 'pat2'.  This may be used to perform filtering
 166      *              upon the results of one pattern to remove all matches which
 167      *              also match another pattern.  For example, because '*'
 168      *              matches any string and '*z*' matches any string containing a
 169      *              'z', '*~*z*' will match all strings except those containing
 170      *              a 'z'.  Note that a pattern may not use '~' multiple times,
 171      *              so a string such as '*~*z*~*y*' is not a valid pattern.
 172      *   o (foo|bar) will match either the pattern foo or the pattern bar.
 173      *               Neither of the patterns foo or bar may use the 'pat~pat2'
 174      *               syntax described immediately above.
 175      *   o \ will escape a special character.  Escaping is required for all
 176      *       special characters unless otherwise specified.
 177      *   o All other characters match case-sensitively.
 178      *
 179      *   An aPattern not conforming to this syntax has undefined behavior.
 180      *
 181      * @throws NS_ERROR_ILLEGAL_VALUE on many but not all invalid aPattern
 182      *                                values.
 183      */
 184     nsIUTF8StringEnumerator findEntries(in string aPattern);
 185
 186     /**
 187      * Returns an input stream containing the contents of the specified zip
 188      * entry.
 189      * @param zipEntry the name of the entry to open the stream from
 190      */
 191     nsIInputStream getInputStream(in string zipEntry);
 192
 193     /**
 194      * Returns an input stream containing the contents of the specified zip
 195      * entry. If the entry refers to a directory (ends with '/'), a directory stream
 196      * is opened, otherwise the contents of the file entry is returned.
 197      * @param aJarSpec the Spec of the URI for the JAR (only used for directory streams)
 198      * @param zipEntry the name of the entry to open the stream from
 199      */
 200     nsIInputStream getInputStreamWithSpec(in AUTF8String aJarSpec, in string zipEntry);
 201 };
 202
 203 ////////////////////////////////////////////////////////////////////////////////
 204 // nsIZipReaderCache
 205
 206 [scriptable, uuid(52c45d86-0cc3-11d4-986e-00c04fa0cf4a)]
 207 interface nsIZipReaderCache : nsISupports
 208 {
 209     /**
 210      * Initializes a new zip reader cache.
 211      * @param cacheSize - the number of released entries to maintain before
 212      *   beginning to throw some out (note that the number of outstanding
 213      *   entries can be much greater than this number -- this is the count
 214      *   for those otherwise unused entries)
 215      */
 216     void init(in unsigned long cacheSize);
 217
 218     /**
 219      * Returns a (possibly shared) nsIZipReader for an nsIFile.
 220      *
 221      * If the zip reader for given file is not in the cache, a new zip reader
 222      * is created, initialized, and opened (see nsIZipReader::init and
 223      * nsIZipReader::open). Otherwise the previously created zip reader is
 224      * returned.
 225      *
 226      * @note If someone called close() on the shared nsIZipReader, this method
 227      *       will return the closed zip reader.
 228      */
 229     nsIZipReader getZip(in nsIFile zipFile);
 230 };
 231
 232 ////////////////////////////////////////////////////////////////////////////////
 233
 234 %{C++
 235
 236 #define NS_ZIPREADER_CID                             \
 237 { /* 7526a738-9632-11d3-8cd9-0060b0fc14a3 */         \
 238     0x7526a738,                                      \
 239     0x9632,                                          \
 240     0x11d3,                                          \
 241     {0x8c, 0xd9, 0x00, 0x60, 0xb0, 0xfc, 0x14, 0xa3} \
 242 }
 243
 244 #define NS_ZIPREADERCACHE_CID                        \
 245 { /* 1b117e16-0cad-11d4-986e-00c04fa0cf4a */         \
 246     0x1b117e16,                                      \
 247     0x0cad,                                          \
 248     0x11d4,                                          \
 249     {0x98, 0x6e, 0x00, 0xc0, 0x4f, 0xa0, 0xcf, 0x4a} \
 250 }
 251
 252 %}
 253
 254 ////////////////////////////////////////////////////////////////////////////////