The Tor Browser: modules/libjar/nsIZipReader.idl@b8a032363ba2 (annotated)

modules/libjar/nsIZipReader.idl@b8a032363ba2 (annotated)

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

 /* -*- 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"
 interface nsIUTF8StringEnumerator;
 interface nsIInputStream;
 interface nsIFile;
 interface nsICertificatePrincipal;
 [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(38d6d07a-8a58-4fe7-be8b-ef6472fa83ff)]
 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);
     /**
      * The file that represents the zip with which this zip reader was
      * initialized.
      */
     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.
      */
     nsICertificatePrincipal getCertificatePrincipal(in AUTF8String aEntryName);
     readonly attribute uint32_t manifestEntriesCount;
 };
 ////////////////////////////////////////////////////////////////////////////////
 // nsIZipReaderCache
 [scriptable, uuid(748050ac-3ab6-4472-bc2a-cb1564ac6a81)]
 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);
 };
 ////////////////////////////////////////////////////////////////////////////////
 %{C++
 #define NS_ZIPREADER_CID                             \
 { /* 88e2fd0b-f7f4-480c-9483-7846b00e8dad */         \
 x88e2fd0b, 0xf7f4, 0x480c,                       \
   { 0x94, 0x83, 0x78, 0x46, 0xb0, 0x0e, 0x8d, 0xad } \
 }
 #define NS_ZIPREADERCACHE_CID                        \
 { /* 608b7f6f-4b60-40d6-87ed-d933bf53d8c1 */         \
 x608b7f6f, 0x4b60, 0x40d6,                       \
   { 0x87, 0xed, 0xd9, 0x33, 0xbf, 0x53, 0xd8, 0xc1 } \
 }
 %}
 ////////////////////////////////////////////////////////////////////////////////

The Tor Browser / annotate

modules/libjar/nsIZipReader.idl@b8a032363ba2 (annotated)

modules/libjar/nsIZipReader.idl