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++ 10struct PRFileDesc; 11%} 12 13[ptr] native PRFileDescStar(PRFileDesc); 14 15interface nsIUTF8StringEnumerator; 16interface nsIInputStream; 17interface nsIFile; 18 19[scriptable, uuid(fad6f72f-13d8-4e26-9173-53007a4afe71)] 20interface 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)] 66interface 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)] 199interface 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//////////////////////////////////////////////////////////////////////////////// 271