modules/libjar/nsIZipReader.idl

   1 /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
   2  *
   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 %{C++
  10 struct PRFileDesc;
  11 %}
  12
  13 [ptr] native PRFileDescStar(PRFileDesc);
  14
  15 interface nsIUTF8StringEnumerator;
  16 interface nsIInputStream;
  17 interface nsIFile;
  18
  19 [scriptable, uuid(fad6f72f-13d8-4e26-9173-53007a4afe71)]
  20 interface nsIZipEntry : nsISupports
  21 {
  22     /**
  23      * The type of compression used for the item.  The possible values and
  24      * their meanings are defined in the zip file specification at
  25      * http://www.pkware.com/business_and_developers/developer/appnote/
  26      */
  27     readonly attribute unsigned short   compression;
  28     /**
  29      * The compressed size of the data in the item.
  30      */
  31     readonly attribute unsigned long    size;
  32     /**
  33      * The uncompressed size of the data in the item.
  34      */
  35     readonly attribute unsigned long    realSize;
  36     /**
  37      * The CRC-32 hash of the file in the entry.
  38      */
  39     readonly attribute unsigned long    CRC32;
  40     /**
  41      * True if the name of the entry ends with '/' and false otherwise.
  42      */
  43     readonly attribute boolean          isDirectory;
  44     /**
  45      * The time at which this item was last modified.
  46      */
  47     readonly attribute PRTime           lastModifiedTime;
  48     /**
  49      * Use this attribute to determine whether this item is an actual zip entry
  50      * or is one synthesized for part of a real entry's path.  A synthesized
  51      * entry represents a directory within the zip file which has no
  52      * corresponding entry within the zip file.  For example, the entry for the
  53      * directory foo/ in a zip containing exactly one entry for foo/bar.txt
  54      * is synthetic.  If the zip file contains an actual entry for a directory,
  55      * this attribute will be false for the nsIZipEntry for that directory.
  56      * It is impossible for a file to be synthetic.
  57      */
  58     readonly attribute boolean          isSynthetic;
  59     /**
  60      * The UNIX style file permissions of this item.
  61      */
  62     readonly attribute unsigned long    permissions;
  63 };
  64
  65 [scriptable, uuid(9ba4ef54-e0a0-4f65-9d23-128482448885)]
  66 interface nsIZipReader : nsISupports
  67 {
  68     /**
  69      * Opens a zip file for reading.
  70      * It is allowed to open with another file,
  71      * but it needs to be closed first with close().
  72      */
  73     void open(in nsIFile zipFile);
  74
  75     /**
  76      * Opens a zip file inside a zip file for reading.
  77      */
  78     void openInner(in nsIZipReader zipReader, in AUTF8String zipEntry);
  79
  80     /**
  81      * Opens a zip file stored in memory; the file attribute will be null.
  82      *
  83      * The ZipReader does not copy or take ownership of this memory; the
  84      * caller must ensure that it is valid and unmodified until the
  85      * ZipReader is closed or destroyed, and must free the memory as
  86      * appropriate afterwards.
  87      */
  88     void openMemory(in voidPtr aData, in unsigned long aLength);
  89
  90     /**
  91      * The file that represents the zip with which this zip reader was
  92      * initialized.  This will be null if there is no underlying file.
  93      */
  94     readonly attribute nsIFile file;
  95
  96     /**
  97      * Closes a zip reader. Subsequent attempts to extract files or read from
  98      * its input stream will result in an error.
  99      *
 100      * Subsequent attempts to access a nsIZipEntry obtained from this zip
 101      * reader will cause unspecified behavior.
 102      */
 103     void close();
 104
 105     /**
 106      * Tests the integrity of the archive by performing a CRC check
 107      * on each item expanded into memory.  If an entry is specified
 108      * the integrity of only that item is tested.  If null (javascript)
 109      * or ""_ns (c++) is passed in the integrity of all items
 110      * in the archive are tested.
 111      */
 112     void test(in AUTF8String aEntryName);
 113
 114     /**
 115      * Extracts a zip entry into a local file specified by outFile.
 116      * The entry must be stored in the zip in either uncompressed or
 117      * DEFLATE-compressed format for the extraction to be successful.
 118      * If the entry is a directory, the directory will be extracted
 119      * non-recursively.
 120      */
 121     void extract(in AUTF8String zipEntry, in nsIFile outFile);
 122
 123     /**
 124      * Returns a nsIZipEntry describing a specified zip entry.
 125      */
 126     nsIZipEntry getEntry(in AUTF8String zipEntry);
 127
 128     /**
 129      * Checks whether the zipfile contains an entry specified by entryName.
 130      */
 131     boolean hasEntry(in AUTF8String zipEntry);
 132
 133     /**
 134      * Returns a string enumerator containing the matching entry names.
 135      *
 136      * @param aPattern
 137      *   A regular expression used to find matching entries in the zip file.
 138      *   Set this parameter to null (javascript) or ""_ns (c++) or "*"
 139      *   to get all entries; otherwise, use the
 140      *   following syntax:
 141      *
 142      *   o * matches anything
 143      *   o ? matches one character
 144      *   o $ matches the end of the string
 145      *   o [abc] matches one occurrence of a, b, or c. The only character that
 146      *           must be escaped inside the brackets is ].  ^ and - must never
 147      *           appear in the first and second positions within the brackets,
 148      *           respectively.  (In the former case, the behavior specified for
 149      *           '[^az]' will happen.)
 150      *   o [a-z] matches any character between a and z.  The characters a and z
 151      *           must either both be letters or both be numbers, with the
 152      *           character represented by 'a' having a lower ASCII value than
 153      *           the character represented by 'z'.
 154      *   o [^az] matches any character except a or z.  If ] is to appear inside
 155      *           the brackets as a character to not match, it must be escaped.
 156      *   o pat~pat2 returns matches to the pattern 'pat' which do not also match
 157      *              the pattern 'pat2'.  This may be used to perform filtering
 158      *              upon the results of one pattern to remove all matches which
 159      *              also match another pattern.  For example, because '*'
 160      *              matches any string and '*z*' matches any string containing a
 161      *              'z', '*~*z*' will match all strings except those containing
 162      *              a 'z'.  Note that a pattern may not use '~' multiple times,
 163      *              so a string such as '*~*z*~*y*' is not a valid pattern.
 164      *   o (foo|bar) will match either the pattern foo or the pattern bar.
 165      *               Neither of the patterns foo or bar may use the 'pat~pat2'
 166      *               syntax described immediately above.
 167      *   o \ will escape a special character.  Escaping is required for all
 168      *       special characters unless otherwise specified.
 169      *   o All other characters match case-sensitively.
 170      *
 171      *   An aPattern not conforming to this syntax has undefined behavior.
 172      *
 173      * @throws NS_ERROR_ILLEGAL_VALUE on many but not all invalid aPattern
 174      *                                values.
 175      */
 176     nsIUTF8StringEnumerator findEntries(in AUTF8String aPattern);
 177
 178     /**
 179      * Returns an input stream containing the contents of the specified zip
 180      * entry.
 181      * @param zipEntry the name of the entry to open the stream from
 182      */
 183     nsIInputStream getInputStream(in AUTF8String zipEntry);
 184
 185     /**
 186      * Returns an input stream containing the contents of the specified zip
 187      * entry. If the entry refers to a directory (ends with '/'), a directory stream
 188      * is opened, otherwise the contents of the file entry is returned.
 189      * @param aJarSpec the Spec of the URI for the JAR (only used for directory streams)
 190      * @param zipEntry the name of the entry to open the stream from
 191      */
 192     nsIInputStream getInputStreamWithSpec(in AUTF8String aJarSpec, in AUTF8String zipEntry);
 193 };
 194
 195 ////////////////////////////////////////////////////////////////////////////////
 196 // nsIZipReaderCache
 197
 198 [scriptable, uuid(31179807-9fcd-46c4-befa-2ade209a394b)]
 199 interface nsIZipReaderCache : nsISupports
 200 {
 201     /**
 202      * Initializes a new zip reader cache.
 203      * @param cacheSize - the number of released entries to maintain before
 204      *   beginning to throw some out (note that the number of outstanding
 205      *   entries can be much greater than this number -- this is the count
 206      *   for those otherwise unused entries)
 207      */
 208     void init(in unsigned long cacheSize);
 209
 210     /**
 211      * Returns a (possibly shared) nsIZipReader for an nsIFile.
 212      *
 213      * If the zip reader for given file is not in the cache, a new zip reader
 214      * is created, initialized, and opened (see nsIZipReader::init and
 215      * nsIZipReader::open). Otherwise the previously created zip reader is
 216      * returned.
 217      *
 218      * @note If someone called close() on the shared nsIZipReader, this method
 219      *       will return the closed zip reader.
 220      */
 221     nsIZipReader getZip(in nsIFile zipFile);
 222
 223     /**
 224      * Like getZip(), returns a (possibly shared) nsIZipReader for an nsIFile,
 225      * but if a zip reader for the given file is not in the cache, returns
 226      * error NS_ERROR_CACHE_KEY_NOT_FOUND rather than creating a new reader.
 227      *
 228      * @note If someone called close() on the shared nsIZipReader, this method
 229      *       will return the closed zip reader.
 230      */
 231     nsIZipReader getZipIfCached(in nsIFile zipFile);
 232
 233     /**
 234      * returns true if this zipreader already has this file cached
 235      */
 236     bool isCached(in nsIFile zipFile);
 237
 238     /**
 239      * Returns a (possibly shared) nsIZipReader for a zip inside another zip
 240      *
 241      * See getZip
 242      */
 243     nsIZipReader getInnerZip(in nsIFile zipFile, in AUTF8String zipEntry);
 244
 245     /**
 246      * Returns the cached NSPR file descriptor of the file.
 247      * Note: currently not supported on Windows platform.
 248      */
 249     PRFileDescStar getFd(in nsIFile zipFile);
 250 };
 251
 252 ////////////////////////////////////////////////////////////////////////////////
 253
 254 %{C++
 255
 256 #define NS_ZIPREADER_CID                             \
 257 { /* 88e2fd0b-f7f4-480c-9483-7846b00e8dad */         \
 258    0x88e2fd0b, 0xf7f4, 0x480c,                       \
 259   { 0x94, 0x83, 0x78, 0x46, 0xb0, 0x0e, 0x8d, 0xad } \
 260 }
 261
 262 #define NS_ZIPREADERCACHE_CID                        \
 263 { /* 608b7f6f-4b60-40d6-87ed-d933bf53d8c1 */         \
 264    0x608b7f6f, 0x4b60, 0x40d6,                       \
 265   { 0x87, 0xed, 0xd9, 0x33, 0xbf, 0x53, 0xd8, 0xc1 } \
 266 }
 267
 268 %}
 269
 270 ////////////////////////////////////////////////////////////////////////////////