/* -*- 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(94ecd586-d405-4801-93d3-8ac7bef81bde)] 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); /** * Whether to keep NSPR file descriptor for newly opened files in the cache. * When aMustCacheFd is enabled and a file is given, the file will be flushed * from the cache if its file descriptor was not cached. * Note: currently not supported on Windows platform. */ void setMustCacheFd(in nsIFile zipFile, in bool aMustCacheFd); /** * 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 } \ } %} ////////////////////////////////////////////////////////////////////////////////