diff options
Diffstat (limited to 'modules/libjar/nsIZipReader.idl')
| -rw-r--r-- | modules/libjar/nsIZipReader.idl | 273 |
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 } \ +} + +%} + +//////////////////////////////////////////////////////////////////////////////// |