modules/libjar/nsIZipReader.idl@b8a032363ba2
modules/libjar/nsIZipReader.idl
Thu, 22 Jan 2015 13:21:57 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Thu, 22 Jan 2015 13:21:57 +0100
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
- permissions
- -rw-r--r--
Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6
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/. */
7 #include "nsISupports.idl"
9 interface nsIUTF8StringEnumerator;
10 interface nsIInputStream;
11 interface nsIFile;
12 interface nsICertificatePrincipal;
14 [scriptable, uuid(fad6f72f-13d8-4e26-9173-53007a4afe71)]
15 interface nsIZipEntry : nsISupports
16 {
17 /**
18 * The type of compression used for the item. The possible values and
19 * their meanings are defined in the zip file specification at
20 * http://www.pkware.com/business_and_developers/developer/appnote/
21 */
22 readonly attribute unsigned short compression;
23 /**
24 * The compressed size of the data in the item.
25 */
26 readonly attribute unsigned long size;
27 /**
28 * The uncompressed size of the data in the item.
29 */
30 readonly attribute unsigned long realSize;
31 /**
32 * The CRC-32 hash of the file in the entry.
33 */
34 readonly attribute unsigned long CRC32;
35 /**
36 * True if the name of the entry ends with '/' and false otherwise.
37 */
38 readonly attribute boolean isDirectory;
39 /**
40 * The time at which this item was last modified.
41 */
42 readonly attribute PRTime lastModifiedTime;
43 /**
44 * Use this attribute to determine whether this item is an actual zip entry
45 * or is one synthesized for part of a real entry's path. A synthesized
46 * entry represents a directory within the zip file which has no
47 * corresponding entry within the zip file. For example, the entry for the
48 * directory foo/ in a zip containing exactly one entry for foo/bar.txt
49 * is synthetic. If the zip file contains an actual entry for a directory,
50 * this attribute will be false for the nsIZipEntry for that directory.
51 * It is impossible for a file to be synthetic.
52 */
53 readonly attribute boolean isSynthetic;
54 /**
55 * The UNIX style file permissions of this item.
56 */
57 readonly attribute unsigned long permissions;
58 };
60 [scriptable, uuid(38d6d07a-8a58-4fe7-be8b-ef6472fa83ff)]
61 interface nsIZipReader : nsISupports
62 {
63 /**
64 * Opens a zip file for reading.
65 * It is allowed to open with another file,
66 * but it needs to be closed first with close().
67 */
68 void open(in nsIFile zipFile);
70 /**
71 * Opens a zip file inside a zip file for reading.
72 */
73 void openInner(in nsIZipReader zipReader, in AUTF8String zipEntry);
75 /**
76 * The file that represents the zip with which this zip reader was
77 * initialized.
78 */
79 readonly attribute nsIFile file;
81 /**
82 * Closes a zip reader. Subsequent attempts to extract files or read from
83 * its input stream will result in an error.
84 *
85 * Subsequent attempts to access a nsIZipEntry obtained from this zip
86 * reader will cause unspecified behavior.
87 */
88 void close();
90 /**
91 * Tests the integrity of the archive by performing a CRC check
92 * on each item expanded into memory. If an entry is specified
93 * the integrity of only that item is tested. If null (javascript)
94 * or EmptyCString() (c++) is passed in the integrity of all items
95 * in the archive are tested.
96 */
97 void test(in AUTF8String aEntryName);
99 /**
100 * Extracts a zip entry into a local file specified by outFile.
101 * The entry must be stored in the zip in either uncompressed or
102 * DEFLATE-compressed format for the extraction to be successful.
103 * If the entry is a directory, the directory will be extracted
104 * non-recursively.
105 */
106 void extract(in AUTF8String zipEntry, in nsIFile outFile);
108 /**
109 * Returns a nsIZipEntry describing a specified zip entry.
110 */
111 nsIZipEntry getEntry(in AUTF8String zipEntry);
113 /**
114 * Checks whether the zipfile contains an entry specified by entryName.
115 */
116 boolean hasEntry(in AUTF8String zipEntry);
118 /**
119 * Returns a string enumerator containing the matching entry names.
120 *
121 * @param aPattern
122 * A regular expression used to find matching entries in the zip file.
123 * Set this parameter to null (javascript) or EmptyCString() (c++) or "*"
124 * to get all entries; otherwise, use the
125 * following syntax:
126 *
127 * o * matches anything
128 * o ? matches one character
129 * o $ matches the end of the string
130 * o [abc] matches one occurrence of a, b, or c. The only character that
131 * must be escaped inside the brackets is ]. ^ and - must never
132 * appear in the first and second positions within the brackets,
133 * respectively. (In the former case, the behavior specified for
134 * '[^az]' will happen.)
135 * o [a-z] matches any character between a and z. The characters a and z
136 * must either both be letters or both be numbers, with the
137 * character represented by 'a' having a lower ASCII value than
138 * the character represented by 'z'.
139 * o [^az] matches any character except a or z. If ] is to appear inside
140 * the brackets as a character to not match, it must be escaped.
141 * o pat~pat2 returns matches to the pattern 'pat' which do not also match
142 * the pattern 'pat2'. This may be used to perform filtering
143 * upon the results of one pattern to remove all matches which
144 * also match another pattern. For example, because '*'
145 * matches any string and '*z*' matches any string containing a
146 * 'z', '*~*z*' will match all strings except those containing
147 * a 'z'. Note that a pattern may not use '~' multiple times,
148 * so a string such as '*~*z*~*y*' is not a valid pattern.
149 * o (foo|bar) will match either the pattern foo or the pattern bar.
150 * Neither of the patterns foo or bar may use the 'pat~pat2'
151 * syntax described immediately above.
152 * o \ will escape a special character. Escaping is required for all
153 * special characters unless otherwise specified.
154 * o All other characters match case-sensitively.
155 *
156 * An aPattern not conforming to this syntax has undefined behavior.
157 *
158 * @throws NS_ERROR_ILLEGAL_VALUE on many but not all invalid aPattern
159 * values.
160 */
161 nsIUTF8StringEnumerator findEntries(in AUTF8String aPattern);
163 /**
164 * Returns an input stream containing the contents of the specified zip
165 * entry.
166 * @param zipEntry the name of the entry to open the stream from
167 */
168 nsIInputStream getInputStream(in AUTF8String zipEntry);
170 /**
171 * Returns an input stream containing the contents of the specified zip
172 * entry. If the entry refers to a directory (ends with '/'), a directory stream
173 * is opened, otherwise the contents of the file entry is returned.
174 * @param aJarSpec the Spec of the URI for the JAR (only used for directory streams)
175 * @param zipEntry the name of the entry to open the stream from
176 */
177 nsIInputStream getInputStreamWithSpec(in AUTF8String aJarSpec, in AUTF8String zipEntry);
179 /**
180 * Returns an object describing the entity which signed
181 * an entry. parseManifest must be called first. If aEntryName is an
182 * entry in the jar, getInputStream must be called after parseManifest.
183 * If aEntryName is an external file which has meta-information
184 * stored in the jar, verifyExternalFile (not yet implemented) must
185 * be called before getPrincipal.
186 */
187 nsICertificatePrincipal getCertificatePrincipal(in AUTF8String aEntryName);
189 readonly attribute uint32_t manifestEntriesCount;
190 };
192 ////////////////////////////////////////////////////////////////////////////////
193 // nsIZipReaderCache
195 [scriptable, uuid(748050ac-3ab6-4472-bc2a-cb1564ac6a81)]
196 interface nsIZipReaderCache : nsISupports
197 {
198 /**
199 * Initializes a new zip reader cache.
200 * @param cacheSize - the number of released entries to maintain before
201 * beginning to throw some out (note that the number of outstanding
202 * entries can be much greater than this number -- this is the count
203 * for those otherwise unused entries)
204 */
205 void init(in unsigned long cacheSize);
207 /**
208 * Returns a (possibly shared) nsIZipReader for an nsIFile.
209 *
210 * If the zip reader for given file is not in the cache, a new zip reader
211 * is created, initialized, and opened (see nsIZipReader::init and
212 * nsIZipReader::open). Otherwise the previously created zip reader is
213 * returned.
214 *
215 * @note If someone called close() on the shared nsIZipReader, this method
216 * will return the closed zip reader.
217 */
218 nsIZipReader getZip(in nsIFile zipFile);
220 /**
221 * returns true if this zipreader already has this file cached
222 */
223 bool isCached(in nsIFile zipFile);
225 /**
226 * Returns a (possibly shared) nsIZipReader for a zip inside another zip
227 *
228 * See getZip
229 */
230 nsIZipReader getInnerZip(in nsIFile zipFile, in AUTF8String zipEntry);
231 };
233 ////////////////////////////////////////////////////////////////////////////////
235 %{C++
237 #define NS_ZIPREADER_CID \
238 { /* 88e2fd0b-f7f4-480c-9483-7846b00e8dad */ \
239 0x88e2fd0b, 0xf7f4, 0x480c, \
240 { 0x94, 0x83, 0x78, 0x46, 0xb0, 0x0e, 0x8d, 0xad } \
241 }
243 #define NS_ZIPREADERCACHE_CID \
244 { /* 608b7f6f-4b60-40d6-87ed-d933bf53d8c1 */ \
245 0x608b7f6f, 0x4b60, 0x40d6, \
246 { 0x87, 0xed, 0xd9, 0x33, 0xbf, 0x53, 0xd8, 0xc1 } \
247 }
249 %}
251 ////////////////////////////////////////////////////////////////////////////////
