kio/kio/kzip.h

   1 /* This file is part of the KDE libraries
   2    Copyright (C) 2002 Holger Schroeder <holger-kde@holgis.net>
   3
   4    This library is free software; you can redistribute it and/or
   5    modify it under the terms of the GNU Library General Public
   6    License version 2 as published by the Free Software Foundation.
   7
   8    This library is distributed in the hope that it will be useful,
   9    but WITHOUT ANY WARRANTY; without even the implied warranty of
  10    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  11    Library General Public License for more details.
  12
  13    You should have received a copy of the GNU Library General Public License
  14    along with this library; see the file COPYING.LIB.  If not, write to
  15    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  16    Boston, MA 02110-1301, USA.
  17 */
  18 #ifndef KZIP_H
  19 #define KZIP_H
  20
  21 #include <karchive.h>
  22
  23 class KZipFileEntry;
  24 /**
  25  *   This class implements a kioslave to access zip files from KDE.
  26  *   You can use it in QIODevice::ReadOnly or in QIODevice::WriteOnly mode, and it
  27  *   behaves just as expected.
  28  *   It can also be used in QIODevice::ReadWrite mode, in this case one can
  29  *   append files to an existing zip archive. When you append new files, which
  30  *   are not yet in the zip, it works as expected, i.e. the files are appended at the end.
  31  *   When you append a file, which is already in the file, the reference to the
  32  *   old file is dropped and the new one is added to the zip - but the
  33  *   old data from the file itself is not deleted, it is still in the
  34  *   zipfile. so when you want to have a small and garbage-free zipfile,
  35  *   just read the contents of the appended zip file and write it to a new one
  36  *   in QIODevice::WriteOnly mode. This is especially important when you don't want
  37  *   to leak information of how intermediate versions of files in the zip
  38  *   were looking.
  39  *   For more information on the zip fileformat go to
  40  *   http://www.pkware.com/products/enterprise/white_papers/appnote.html
  41  * @short A class for reading/writing zip archives.
  42  * @author Holger Schroeder <holger-kde@holgis.net>
  43  */
  44 class KIO_EXPORT KZip : public KArchive
  45 {
  46 public:
  47     /**
  48      * Creates an instance that operates on the given filename.
  49      * using the compression filter associated to given mimetype.
  50      *
  51      * @param filename is a local path (e.g. "/home/holger/myfile.zip")
  52      */
  53     KZip( const QString& filename );
  54
  55     /**
  56      * Creates an instance that operates on the given device.
  57      * The device can be compressed (KFilterDev) or not (QFile, etc.).
  58      * @warning Do not assume that giving a QFile here will decompress the file,
  59      * in case it's compressed!
  60      * @param dev the device to access
  61      */
  62     KZip( QIODevice * dev );
  63
  64     /**
  65      * If the zip file is still opened, then it will be
  66      * closed automatically by the destructor.
  67      */
  68     virtual ~KZip();
  69
  70     /**
  71      * Describes the contents of the "extra field" for a given file in the Zip archive.
  72      */
  73     enum ExtraField { NoExtraField = 0,      ///< No extra field
  74                       ModificationTime = 1,  ///< Modification time ("extended timestamp" header)
  75                       DefaultExtraField = 1
  76     };
  77
  78     /**
  79      * Call this before writeFile or prepareWriting, to define what the next
  80      * file to be written should have in its extra field.
  81      * @param ef the type of "extra field"
  82      * @see extraField()
  83      */
  84     void setExtraField( ExtraField ef );
  85
  86     /**
  87      * The current type of "extra field" that will be used for new files.
  88      * @return the current type of "extra field"
  89      * @see setExtraField()
  90      */
  91     ExtraField extraField() const;
  92
  93     /**
  94      * Describes the compression type for a given file in the Zip archive.
  95      */
  96     enum Compression { NoCompression = 0,     ///< Uncompressed.
  97                        DeflateCompression = 1 ///< Deflate compression method.
  98     };
  99
 100
 101     /**
 102      * Call this before writeFile or prepareWriting, to define whether the next
 103      * files to be written should be compressed or not.
 104      * @param c the new compression mode
 105      * @see compression()
 106      */
 107     void setCompression( Compression c );
 108
 109     /**
 110      * The current compression mode that will be used for new files.
 111      * @return the current compression mode
 112      * @see setCompression()
 113      */
 114     Compression compression() const;
 115
 116     /**
 117      * Write data to a file that has been created using prepareWriting().
 118      * @param data a pointer to the data
 119      * @param size the size of the chunk
 120      * @return true if successful, false otherwise
 121      */
 122     virtual bool writeData( const char* data, qint64 size );
 123
 124 protected:
 125     /// Reimplemented from KArchive
 126     virtual bool doWriteSymLink(const QString &name, const QString &target,
 127                                 const QString &user, const QString &group,
 128                                 mode_t perm, time_t atime, time_t mtime, time_t ctime);
 129     /// Reimplemented from KArchive
 130     virtual bool doPrepareWriting( const QString& name, const QString& user,
 131                                  const QString& group, qint64 size, mode_t perm,
 132                                  time_t atime, time_t mtime, time_t ctime );
 133
 134     /**
 135      * Write data to a file that has been created using prepareWriting().
 136      * @param size the size of the file
 137      * @return true if successful, false otherwise
 138      */
 139     virtual bool doFinishWriting( qint64 size );
 140
 141     /**
 142      * Opens the archive for reading.
 143      * Parses the directory listing of the archive
 144      * and creates the KArchiveDirectory/KArchiveFile entries.
 145      * @param mode the mode of the file
 146      */
 147     virtual bool openArchive( QIODevice::OpenMode mode );
 148
 149     /// Closes the archive
 150     virtual bool closeArchive();
 151
 152     /**
 153      * @internal Not needed for zip
 154      */
 155     virtual bool doWriteDir( const QString& name, const QString& user,
 156                              const QString& group, mode_t perm, time_t atime,
 157                              time_t mtime, time_t ctime );
 158
 159 protected:
 160     virtual void virtual_hook( int id, void* data );
 161
 162 private:
 163     class KZipPrivate;
 164     KZipPrivate * const d;
 165 };
 166
 167
 168 /**
 169  * A KZipFileEntry represents an file in a zip archive.
 170  */
 171 class KIO_EXPORT KZipFileEntry : public KArchiveFile
 172 {
 173 public:
 174     /**
 175      * Creates a new zip file entry. Do not call this, KZip takes care of it.
 176      */
 177     KZipFileEntry( KZip* zip, const QString& name, int access, int date,
 178                    const QString& user, const QString& group, const QString& symlink,
 179                    const QString& path, qint64 start, qint64 uncompressedSize,
 180                    int encoding, qint64 compressedSize);
 181
 182     /**
 183      * Destructor. Do not call this.
 184      */
 185     ~KZipFileEntry();
 186
 187     int encoding() const;
 188     qint64 compressedSize() const;
 189
 190     /// Only used when writing
 191     void setCompressedSize(qint64 compressedSize);
 192
 193     /// Header start: only used when writing
 194     void setHeaderStart(qint64 headerstart);
 195     qint64 headerStart() const;
 196
 197     /// CRC: only used when writing
 198     unsigned long crc32() const;
 199     void setCRC32(unsigned long crc32);
 200
 201     /// Name with complete path - KArchiveFile::name() is the filename only (no path)
 202     const QString &path() const;
 203
 204     /**
 205      * @return the content of this file.
 206      * Call data() with care (only once per file), this data isn't cached.
 207      */
 208     virtual QByteArray data() const;
 209
 210     /**
 211      * This method returns a QIODevice to read the file contents.
 212      * This is obviously for reading only.
 213      * Note that the ownership of the device is being transferred to the caller,
 214      * who will have to delete it.
 215      * The returned device auto-opens (in readonly mode), no need to open it.
 216      */
 217     virtual QIODevice* createDevice() const;
 218
 219 private:
 220     class KZipFileEntryPrivate;
 221     KZipFileEntryPrivate * const d;
 222 };
 223
 224 #endif