summaryrefslogtreecommitdiffstats
path: root/modules/libjar/nsIZipReader.idl
diff options
context:
space:
mode:
Diffstat (limited to 'modules/libjar/nsIZipReader.idl')
-rw-r--r--modules/libjar/nsIZipReader.idl273
1 files changed, 273 insertions, 0 deletions
diff --git a/modules/libjar/nsIZipReader.idl b/modules/libjar/nsIZipReader.idl
new file mode 100644
index 000000000..9ca111a3a
--- /dev/null
+++ b/modules/libjar/nsIZipReader.idl
@@ -0,0 +1,273 @@
+/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+#include "nsISupports.idl"
+
+%{C++
+struct PRFileDesc;
+%}
+
+[ptr] native PRFileDescStar(PRFileDesc);
+
+interface nsIUTF8StringEnumerator;
+interface nsIInputStream;
+interface nsIFile;
+interface nsIX509Cert;
+
+[scriptable, uuid(fad6f72f-13d8-4e26-9173-53007a4afe71)]
+interface nsIZipEntry : nsISupports
+{
+ /**
+ * The type of compression used for the item. The possible values and
+ * their meanings are defined in the zip file specification at
+ * http://www.pkware.com/business_and_developers/developer/appnote/
+ */
+ readonly attribute unsigned short compression;
+ /**
+ * The compressed size of the data in the item.
+ */
+ readonly attribute unsigned long size;
+ /**
+ * The uncompressed size of the data in the item.
+ */
+ readonly attribute unsigned long realSize;
+ /**
+ * The CRC-32 hash of the file in the entry.
+ */
+ readonly attribute unsigned long CRC32;
+ /**
+ * True if the name of the entry ends with '/' and false otherwise.
+ */
+ readonly attribute boolean isDirectory;
+ /**
+ * The time at which this item was last modified.
+ */
+ readonly attribute PRTime lastModifiedTime;
+ /**
+ * Use this attribute to determine whether this item is an actual zip entry
+ * or is one synthesized for part of a real entry's path. A synthesized
+ * entry represents a directory within the zip file which has no
+ * corresponding entry within the zip file. For example, the entry for the
+ * directory foo/ in a zip containing exactly one entry for foo/bar.txt
+ * is synthetic. If the zip file contains an actual entry for a directory,
+ * this attribute will be false for the nsIZipEntry for that directory.
+ * It is impossible for a file to be synthetic.
+ */
+ readonly attribute boolean isSynthetic;
+ /**
+ * The UNIX style file permissions of this item.
+ */
+ readonly attribute unsigned long permissions;
+};
+
+[scriptable, uuid(9ba4ef54-e0a0-4f65-9d23-128482448885)]
+interface nsIZipReader : nsISupports
+{
+ /**
+ * Opens a zip file for reading.
+ * It is allowed to open with another file,
+ * but it needs to be closed first with close().
+ */
+ void open(in nsIFile zipFile);
+
+ /**
+ * Opens a zip file inside a zip file for reading.
+ */
+ void openInner(in nsIZipReader zipReader, in AUTF8String zipEntry);
+
+ /**
+ * Opens a zip file stored in memory; the file attribute will be null.
+ *
+ * The ZipReader does not copy or take ownership of this memory; the
+ * caller must ensure that it is valid and unmodified until the
+ * ZipReader is closed or destroyed, and must free the memory as
+ * appropriate afterwards.
+ */
+ void openMemory(in voidPtr aData, in unsigned long aLength);
+
+ /**
+ * The file that represents the zip with which this zip reader was
+ * initialized. This will be null if there is no underlying file.
+ */
+ readonly attribute nsIFile file;
+
+ /**
+ * Closes a zip reader. Subsequent attempts to extract files or read from
+ * its input stream will result in an error.
+ *
+ * Subsequent attempts to access a nsIZipEntry obtained from this zip
+ * reader will cause unspecified behavior.
+ */
+ void close();
+
+ /**
+ * Tests the integrity of the archive by performing a CRC check
+ * on each item expanded into memory. If an entry is specified
+ * the integrity of only that item is tested. If null (javascript)
+ * or EmptyCString() (c++) is passed in the integrity of all items
+ * in the archive are tested.
+ */
+ void test(in AUTF8String aEntryName);
+
+ /**
+ * Extracts a zip entry into a local file specified by outFile.
+ * The entry must be stored in the zip in either uncompressed or
+ * DEFLATE-compressed format for the extraction to be successful.
+ * If the entry is a directory, the directory will be extracted
+ * non-recursively.
+ */
+ void extract(in AUTF8String zipEntry, in nsIFile outFile);
+
+ /**
+ * Returns a nsIZipEntry describing a specified zip entry.
+ */
+ nsIZipEntry getEntry(in AUTF8String zipEntry);
+
+ /**
+ * Checks whether the zipfile contains an entry specified by entryName.
+ */
+ boolean hasEntry(in AUTF8String zipEntry);
+
+ /**
+ * Returns a string enumerator containing the matching entry names.
+ *
+ * @param aPattern
+ * A regular expression used to find matching entries in the zip file.
+ * Set this parameter to null (javascript) or EmptyCString() (c++) or "*"
+ * to get all entries; otherwise, use the
+ * following syntax:
+ *
+ * o * matches anything
+ * o ? matches one character
+ * o $ matches the end of the string
+ * o [abc] matches one occurrence of a, b, or c. The only character that
+ * must be escaped inside the brackets is ]. ^ and - must never
+ * appear in the first and second positions within the brackets,
+ * respectively. (In the former case, the behavior specified for
+ * '[^az]' will happen.)
+ * o [a-z] matches any character between a and z. The characters a and z
+ * must either both be letters or both be numbers, with the
+ * character represented by 'a' having a lower ASCII value than
+ * the character represented by 'z'.
+ * o [^az] matches any character except a or z. If ] is to appear inside
+ * the brackets as a character to not match, it must be escaped.
+ * o pat~pat2 returns matches to the pattern 'pat' which do not also match
+ * the pattern 'pat2'. This may be used to perform filtering
+ * upon the results of one pattern to remove all matches which
+ * also match another pattern. For example, because '*'
+ * matches any string and '*z*' matches any string containing a
+ * 'z', '*~*z*' will match all strings except those containing
+ * a 'z'. Note that a pattern may not use '~' multiple times,
+ * so a string such as '*~*z*~*y*' is not a valid pattern.
+ * o (foo|bar) will match either the pattern foo or the pattern bar.
+ * Neither of the patterns foo or bar may use the 'pat~pat2'
+ * syntax described immediately above.
+ * o \ will escape a special character. Escaping is required for all
+ * special characters unless otherwise specified.
+ * o All other characters match case-sensitively.
+ *
+ * An aPattern not conforming to this syntax has undefined behavior.
+ *
+ * @throws NS_ERROR_ILLEGAL_VALUE on many but not all invalid aPattern
+ * values.
+ */
+ nsIUTF8StringEnumerator findEntries(in AUTF8String aPattern);
+
+ /**
+ * Returns an input stream containing the contents of the specified zip
+ * entry.
+ * @param zipEntry the name of the entry to open the stream from
+ */
+ nsIInputStream getInputStream(in AUTF8String zipEntry);
+
+ /**
+ * Returns an input stream containing the contents of the specified zip
+ * entry. If the entry refers to a directory (ends with '/'), a directory stream
+ * is opened, otherwise the contents of the file entry is returned.
+ * @param aJarSpec the Spec of the URI for the JAR (only used for directory streams)
+ * @param zipEntry the name of the entry to open the stream from
+ */
+ nsIInputStream getInputStreamWithSpec(in AUTF8String aJarSpec, in AUTF8String zipEntry);
+
+ /**
+ * Returns an object describing the entity which signed
+ * an entry. parseManifest must be called first. If aEntryName is an
+ * entry in the jar, getInputStream must be called after parseManifest.
+ * If aEntryName is an external file which has meta-information
+ * stored in the jar, verifyExternalFile (not yet implemented) must
+ * be called before getPrincipal.
+ */
+ nsIX509Cert getSigningCert(in AUTF8String aEntryName);
+
+ readonly attribute uint32_t manifestEntriesCount;
+};
+
+////////////////////////////////////////////////////////////////////////////////
+// nsIZipReaderCache
+
+[scriptable, uuid(31179807-9fcd-46c4-befa-2ade209a394b)]
+interface nsIZipReaderCache : nsISupports
+{
+ /**
+ * Initializes a new zip reader cache.
+ * @param cacheSize - the number of released entries to maintain before
+ * beginning to throw some out (note that the number of outstanding
+ * entries can be much greater than this number -- this is the count
+ * for those otherwise unused entries)
+ */
+ void init(in unsigned long cacheSize);
+
+ /**
+ * Returns a (possibly shared) nsIZipReader for an nsIFile.
+ *
+ * If the zip reader for given file is not in the cache, a new zip reader
+ * is created, initialized, and opened (see nsIZipReader::init and
+ * nsIZipReader::open). Otherwise the previously created zip reader is
+ * returned.
+ *
+ * @note If someone called close() on the shared nsIZipReader, this method
+ * will return the closed zip reader.
+ */
+ nsIZipReader getZip(in nsIFile zipFile);
+
+ /**
+ * returns true if this zipreader already has this file cached
+ */
+ bool isCached(in nsIFile zipFile);
+
+ /**
+ * Returns a (possibly shared) nsIZipReader for a zip inside another zip
+ *
+ * See getZip
+ */
+ nsIZipReader getInnerZip(in nsIFile zipFile, in AUTF8String zipEntry);
+
+ /**
+ * Returns the cached NSPR file descriptor of the file.
+ * Note: currently not supported on Windows platform.
+ */
+ PRFileDescStar getFd(in nsIFile zipFile);
+};
+
+////////////////////////////////////////////////////////////////////////////////
+
+%{C++
+
+#define NS_ZIPREADER_CID \
+{ /* 88e2fd0b-f7f4-480c-9483-7846b00e8dad */ \
+ 0x88e2fd0b, 0xf7f4, 0x480c, \
+ { 0x94, 0x83, 0x78, 0x46, 0xb0, 0x0e, 0x8d, 0xad } \
+}
+
+#define NS_ZIPREADERCACHE_CID \
+{ /* 608b7f6f-4b60-40d6-87ed-d933bf53d8c1 */ \
+ 0x608b7f6f, 0x4b60, 0x40d6, \
+ { 0x87, 0xed, 0xd9, 0x33, 0xbf, 0x53, 0xd8, 0xc1 } \
+}
+
+%}
+
+////////////////////////////////////////////////////////////////////////////////