nsIZipReader.idl (10296B)
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, builtinclass, 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 [infallible] readonly attribute unsigned short compression; 28 /** 29 * The compressed size of the data in the item. 30 */ 31 [infallible] readonly attribute unsigned long size; 32 /** 33 * The uncompressed size of the data in the item. 34 */ 35 [infallible] readonly attribute unsigned long realSize; 36 /** 37 * The CRC-32 hash of the file in the entry. 38 */ 39 [infallible] readonly attribute unsigned long CRC32; 40 /** 41 * True if the name of the entry ends with '/' and false otherwise. 42 */ 43 [infallible] 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 [infallible] readonly attribute boolean isSynthetic; 59 /** 60 * The UNIX style file permissions of this item. 61 */ 62 [infallible] 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 [noscript] 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. If the entry refers to a directory (ends with '/'), a directory stream 181 * is opened, otherwise the contents of the file entry is returned. 182 * @param zipEntry the name of the entry to open the stream from 183 */ 184 nsIInputStream getInputStream(in AUTF8String zipEntry); 185 }; 186 187 //////////////////////////////////////////////////////////////////////////////// 188 // nsIZipReaderCache 189 190 [scriptable, uuid(31179807-9fcd-46c4-befa-2ade209a394b)] 191 interface nsIZipReaderCache : nsISupports 192 { 193 /** 194 * Initializes a new zip reader cache. 195 * @param cacheSize - the number of released entries to maintain before 196 * beginning to throw some out (note that the number of outstanding 197 * entries can be much greater than this number -- this is the count 198 * for those otherwise unused entries) 199 */ 200 void init(in unsigned long cacheSize); 201 202 /** 203 * Returns a (possibly shared) nsIZipReader for an nsIFile. 204 * 205 * If the zip reader for given file is not in the cache, a new zip reader 206 * is created, initialized, and opened (see nsIZipReader::init and 207 * nsIZipReader::open). Otherwise the previously created zip reader is 208 * returned. 209 * 210 * @note If someone called close() on the shared nsIZipReader, this method 211 * will return the closed zip reader. 212 */ 213 nsIZipReader getZip(in nsIFile zipFile); 214 215 /** 216 * Like getZip(), returns a (possibly shared) nsIZipReader for an nsIFile, 217 * but if a zip reader for the given file is not in the cache, returns 218 * error NS_ERROR_CACHE_KEY_NOT_FOUND rather than creating a new reader. 219 * 220 * @note If someone called close() on the shared nsIZipReader, this method 221 * will return the closed zip reader. 222 */ 223 nsIZipReader getZipIfCached(in nsIFile zipFile); 224 225 /** 226 * returns true if this zipreader already has this file cached 227 */ 228 boolean isCached(in nsIFile zipFile); 229 230 /** 231 * Returns a (possibly shared) nsIZipReader for a zip inside another zip 232 * 233 * See getZip 234 */ 235 nsIZipReader getInnerZip(in nsIFile zipFile, in AUTF8String zipEntry); 236 237 /** 238 * Returns the cached NSPR file descriptor of the file. 239 * Note: currently not supported on Windows platform. 240 */ 241 [noscript] PRFileDescStar getFd(in nsIFile zipFile); 242 }; 243 244 //////////////////////////////////////////////////////////////////////////////// 245 246 %{C++ 247 248 #define NS_ZIPREADER_CID \ 249 { /* 88e2fd0b-f7f4-480c-9483-7846b00e8dad */ \ 250 0x88e2fd0b, 0xf7f4, 0x480c, \ 251 { 0x94, 0x83, 0x78, 0x46, 0xb0, 0x0e, 0x8d, 0xad } \ 252 } 253 254 #define NS_ZIPREADERCACHE_CID \ 255 { /* 608b7f6f-4b60-40d6-87ed-d933bf53d8c1 */ \ 256 0x608b7f6f, 0x4b60, 0x40d6, \ 257 { 0x87, 0xed, 0xd9, 0x33, 0xbf, 0x53, 0xd8, 0xc1 } \ 258 } 259 260 %} 261 262 ////////////////////////////////////////////////////////////////////////////////