1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/modules/libjar/nsIZipReader.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,251 @@
1.4 +/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
1.5 + *
1.6 + * This Source Code Form is subject to the terms of the Mozilla Public
1.7 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.8 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.9 +
1.10 +#include "nsISupports.idl"
1.11 +
1.12 +interface nsIUTF8StringEnumerator;
1.13 +interface nsIInputStream;
1.14 +interface nsIFile;
1.15 +interface nsICertificatePrincipal;
1.16 +
1.17 +[scriptable, uuid(fad6f72f-13d8-4e26-9173-53007a4afe71)]
1.18 +interface nsIZipEntry : nsISupports
1.19 +{
1.20 + /**
1.21 + * The type of compression used for the item. The possible values and
1.22 + * their meanings are defined in the zip file specification at
1.23 + * http://www.pkware.com/business_and_developers/developer/appnote/
1.24 + */
1.25 + readonly attribute unsigned short compression;
1.26 + /**
1.27 + * The compressed size of the data in the item.
1.28 + */
1.29 + readonly attribute unsigned long size;
1.30 + /**
1.31 + * The uncompressed size of the data in the item.
1.32 + */
1.33 + readonly attribute unsigned long realSize;
1.34 + /**
1.35 + * The CRC-32 hash of the file in the entry.
1.36 + */
1.37 + readonly attribute unsigned long CRC32;
1.38 + /**
1.39 + * True if the name of the entry ends with '/' and false otherwise.
1.40 + */
1.41 + readonly attribute boolean isDirectory;
1.42 + /**
1.43 + * The time at which this item was last modified.
1.44 + */
1.45 + readonly attribute PRTime lastModifiedTime;
1.46 + /**
1.47 + * Use this attribute to determine whether this item is an actual zip entry
1.48 + * or is one synthesized for part of a real entry's path. A synthesized
1.49 + * entry represents a directory within the zip file which has no
1.50 + * corresponding entry within the zip file. For example, the entry for the
1.51 + * directory foo/ in a zip containing exactly one entry for foo/bar.txt
1.52 + * is synthetic. If the zip file contains an actual entry for a directory,
1.53 + * this attribute will be false for the nsIZipEntry for that directory.
1.54 + * It is impossible for a file to be synthetic.
1.55 + */
1.56 + readonly attribute boolean isSynthetic;
1.57 + /**
1.58 + * The UNIX style file permissions of this item.
1.59 + */
1.60 + readonly attribute unsigned long permissions;
1.61 +};
1.62 +
1.63 +[scriptable, uuid(38d6d07a-8a58-4fe7-be8b-ef6472fa83ff)]
1.64 +interface nsIZipReader : nsISupports
1.65 +{
1.66 + /**
1.67 + * Opens a zip file for reading.
1.68 + * It is allowed to open with another file,
1.69 + * but it needs to be closed first with close().
1.70 + */
1.71 + void open(in nsIFile zipFile);
1.72 +
1.73 + /**
1.74 + * Opens a zip file inside a zip file for reading.
1.75 + */
1.76 + void openInner(in nsIZipReader zipReader, in AUTF8String zipEntry);
1.77 +
1.78 + /**
1.79 + * The file that represents the zip with which this zip reader was
1.80 + * initialized.
1.81 + */
1.82 + readonly attribute nsIFile file;
1.83 +
1.84 + /**
1.85 + * Closes a zip reader. Subsequent attempts to extract files or read from
1.86 + * its input stream will result in an error.
1.87 + *
1.88 + * Subsequent attempts to access a nsIZipEntry obtained from this zip
1.89 + * reader will cause unspecified behavior.
1.90 + */
1.91 + void close();
1.92 +
1.93 + /**
1.94 + * Tests the integrity of the archive by performing a CRC check
1.95 + * on each item expanded into memory. If an entry is specified
1.96 + * the integrity of only that item is tested. If null (javascript)
1.97 + * or EmptyCString() (c++) is passed in the integrity of all items
1.98 + * in the archive are tested.
1.99 + */
1.100 + void test(in AUTF8String aEntryName);
1.101 +
1.102 + /**
1.103 + * Extracts a zip entry into a local file specified by outFile.
1.104 + * The entry must be stored in the zip in either uncompressed or
1.105 + * DEFLATE-compressed format for the extraction to be successful.
1.106 + * If the entry is a directory, the directory will be extracted
1.107 + * non-recursively.
1.108 + */
1.109 + void extract(in AUTF8String zipEntry, in nsIFile outFile);
1.110 +
1.111 + /**
1.112 + * Returns a nsIZipEntry describing a specified zip entry.
1.113 + */
1.114 + nsIZipEntry getEntry(in AUTF8String zipEntry);
1.115 +
1.116 + /**
1.117 + * Checks whether the zipfile contains an entry specified by entryName.
1.118 + */
1.119 + boolean hasEntry(in AUTF8String zipEntry);
1.120 +
1.121 + /**
1.122 + * Returns a string enumerator containing the matching entry names.
1.123 + *
1.124 + * @param aPattern
1.125 + * A regular expression used to find matching entries in the zip file.
1.126 + * Set this parameter to null (javascript) or EmptyCString() (c++) or "*"
1.127 + * to get all entries; otherwise, use the
1.128 + * following syntax:
1.129 + *
1.130 + * o * matches anything
1.131 + * o ? matches one character
1.132 + * o $ matches the end of the string
1.133 + * o [abc] matches one occurrence of a, b, or c. The only character that
1.134 + * must be escaped inside the brackets is ]. ^ and - must never
1.135 + * appear in the first and second positions within the brackets,
1.136 + * respectively. (In the former case, the behavior specified for
1.137 + * '[^az]' will happen.)
1.138 + * o [a-z] matches any character between a and z. The characters a and z
1.139 + * must either both be letters or both be numbers, with the
1.140 + * character represented by 'a' having a lower ASCII value than
1.141 + * the character represented by 'z'.
1.142 + * o [^az] matches any character except a or z. If ] is to appear inside
1.143 + * the brackets as a character to not match, it must be escaped.
1.144 + * o pat~pat2 returns matches to the pattern 'pat' which do not also match
1.145 + * the pattern 'pat2'. This may be used to perform filtering
1.146 + * upon the results of one pattern to remove all matches which
1.147 + * also match another pattern. For example, because '*'
1.148 + * matches any string and '*z*' matches any string containing a
1.149 + * 'z', '*~*z*' will match all strings except those containing
1.150 + * a 'z'. Note that a pattern may not use '~' multiple times,
1.151 + * so a string such as '*~*z*~*y*' is not a valid pattern.
1.152 + * o (foo|bar) will match either the pattern foo or the pattern bar.
1.153 + * Neither of the patterns foo or bar may use the 'pat~pat2'
1.154 + * syntax described immediately above.
1.155 + * o \ will escape a special character. Escaping is required for all
1.156 + * special characters unless otherwise specified.
1.157 + * o All other characters match case-sensitively.
1.158 + *
1.159 + * An aPattern not conforming to this syntax has undefined behavior.
1.160 + *
1.161 + * @throws NS_ERROR_ILLEGAL_VALUE on many but not all invalid aPattern
1.162 + * values.
1.163 + */
1.164 + nsIUTF8StringEnumerator findEntries(in AUTF8String aPattern);
1.165 +
1.166 + /**
1.167 + * Returns an input stream containing the contents of the specified zip
1.168 + * entry.
1.169 + * @param zipEntry the name of the entry to open the stream from
1.170 + */
1.171 + nsIInputStream getInputStream(in AUTF8String zipEntry);
1.172 +
1.173 + /**
1.174 + * Returns an input stream containing the contents of the specified zip
1.175 + * entry. If the entry refers to a directory (ends with '/'), a directory stream
1.176 + * is opened, otherwise the contents of the file entry is returned.
1.177 + * @param aJarSpec the Spec of the URI for the JAR (only used for directory streams)
1.178 + * @param zipEntry the name of the entry to open the stream from
1.179 + */
1.180 + nsIInputStream getInputStreamWithSpec(in AUTF8String aJarSpec, in AUTF8String zipEntry);
1.181 +
1.182 + /**
1.183 + * Returns an object describing the entity which signed
1.184 + * an entry. parseManifest must be called first. If aEntryName is an
1.185 + * entry in the jar, getInputStream must be called after parseManifest.
1.186 + * If aEntryName is an external file which has meta-information
1.187 + * stored in the jar, verifyExternalFile (not yet implemented) must
1.188 + * be called before getPrincipal.
1.189 + */
1.190 + nsICertificatePrincipal getCertificatePrincipal(in AUTF8String aEntryName);
1.191 +
1.192 + readonly attribute uint32_t manifestEntriesCount;
1.193 +};
1.194 +
1.195 +////////////////////////////////////////////////////////////////////////////////
1.196 +// nsIZipReaderCache
1.197 +
1.198 +[scriptable, uuid(748050ac-3ab6-4472-bc2a-cb1564ac6a81)]
1.199 +interface nsIZipReaderCache : nsISupports
1.200 +{
1.201 + /**
1.202 + * Initializes a new zip reader cache.
1.203 + * @param cacheSize - the number of released entries to maintain before
1.204 + * beginning to throw some out (note that the number of outstanding
1.205 + * entries can be much greater than this number -- this is the count
1.206 + * for those otherwise unused entries)
1.207 + */
1.208 + void init(in unsigned long cacheSize);
1.209 +
1.210 + /**
1.211 + * Returns a (possibly shared) nsIZipReader for an nsIFile.
1.212 + *
1.213 + * If the zip reader for given file is not in the cache, a new zip reader
1.214 + * is created, initialized, and opened (see nsIZipReader::init and
1.215 + * nsIZipReader::open). Otherwise the previously created zip reader is
1.216 + * returned.
1.217 + *
1.218 + * @note If someone called close() on the shared nsIZipReader, this method
1.219 + * will return the closed zip reader.
1.220 + */
1.221 + nsIZipReader getZip(in nsIFile zipFile);
1.222 +
1.223 + /**
1.224 + * returns true if this zipreader already has this file cached
1.225 + */
1.226 + bool isCached(in nsIFile zipFile);
1.227 +
1.228 + /**
1.229 + * Returns a (possibly shared) nsIZipReader for a zip inside another zip
1.230 + *
1.231 + * See getZip
1.232 + */
1.233 + nsIZipReader getInnerZip(in nsIFile zipFile, in AUTF8String zipEntry);
1.234 +};
1.235 +
1.236 +////////////////////////////////////////////////////////////////////////////////
1.237 +
1.238 +%{C++
1.239 +
1.240 +#define NS_ZIPREADER_CID \
1.241 +{ /* 88e2fd0b-f7f4-480c-9483-7846b00e8dad */ \
1.242 + 0x88e2fd0b, 0xf7f4, 0x480c, \
1.243 + { 0x94, 0x83, 0x78, 0x46, 0xb0, 0x0e, 0x8d, 0xad } \
1.244 +}
1.245 +
1.246 +#define NS_ZIPREADERCACHE_CID \
1.247 +{ /* 608b7f6f-4b60-40d6-87ed-d933bf53d8c1 */ \
1.248 + 0x608b7f6f, 0x4b60, 0x40d6, \
1.249 + { 0x87, 0xed, 0xd9, 0x33, 0xbf, 0x53, 0xd8, 0xc1 } \
1.250 +}
1.251 +
1.252 +%}
1.253 +
1.254 +////////////////////////////////////////////////////////////////////////////////
