1/* This file is part of the KDE libraries
2 Copyright (C) 2000 David Faure <faure@kde.org>
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 __kfilterdev_h
19#define __kfilterdev_h
20
21#include <karchive_export.h>
22#include <QtCore/QIODevice>
23#include <QtCore/QString>
24
25class QFile;
26class KFilterBase;
27
28/**
29 * A class for reading and writing compressed data onto a device
30 * (e.g. file, but other usages are possible, like a buffer or a socket).
31 *
32 * To simply read/write compressed files, see deviceForFile.
33 *
34 * @author David Faure <faure@kde.org>
35 */
36class KARCHIVE_EXPORT KFilterDev : public QIODevice
37{
38public:
39 /**
40 * Destructs the KFilterDev.
41 * Calls close() if the filter device is still open.
42 */
43 virtual ~KFilterDev();
44
45 /**
46 * Open for reading or writing.
47 * If the KFilterBase's device is not opened, it will be opened.
48 */
49 virtual bool open( QIODevice::OpenMode mode );
50 /**
51 * Close after reading or writing.
52 * If the KFilterBase's device was opened by open(), it will be closed.
53 */
54 virtual void close();
55
56 /**
57 * For writing gzip compressed files only:
58 * set the name of the original file, to be used in the gzip header.
59 * @param fileName the name of the original file
60 */
61 void setOrigFileName( const QByteArray & fileName );
62
63 /**
64 * Call this let this device skip the gzip headers when reading/writing.
65 * This way KFilterDev (with gzip filter) can be used as a direct wrapper
66 * around zlib - this is used by KZip.
67 */
68 void setSkipHeaders();
69
70 /**
71 * That one can be quite slow, when going back. Use with care.
72 */
73 virtual bool seek( qint64 );
74
75 virtual bool atEnd() const;
76
77 /// Reimplemented to return true. KFilterDev is a sequential QIODevice.
78 /// Well, not really, since it supports seeking and KZip uses that.
79 //virtual bool isSequential() const { return true; }
80
81public:
82
83
84 // KDE4 TODO: turn those static methods into constructors
85
86 /**
87 * Creates an i/o device that is able to read from @p fileName,
88 * whether it's compressed or not. Available compression filters
89 * (gzip/bzip2 etc.) will automatically be used.
90 *
91 * The compression filter to be used is determined from the @p fileName
92 * if @p mimetype is empty. Pass "application/x-gzip" or "application/x-bzip"
93 * to force the corresponding decompression filter, if available.
94 *
95 * Warning: application/x-bzip may not be available.
96 * In that case a QFile opened on the compressed data will be returned !
97 * Use KFilterBase::findFilterByMimeType and code similar to what
98 * deviceForFile is doing, to better control what's happening.
99 *
100 * The returned QIODevice has to be deleted after using.
101 *
102 * @param fileName the name of the file to filter
103 * @param mimetype the mime type of the file to filter, or QString() if unknown
104 * @param forceFilter if true, the function will either find a compression filter, or return 0.
105 * If false, it will always return a QIODevice. If no
106 * filter is available it will return a simple QFile.
107 * This can be useful if the file is usable without a filter.
108 * @return if a filter has been found, the QIODevice for the filter. If the
109 * filter does not exist, the return value depends on @p forceFilter.
110 * The returned QIODevice has to be deleted after using.
111 */
112 static QIODevice * deviceForFile( const QString & fileName, const QString & mimetype = QString(),
113 bool forceFilter = false );
114
115 /**
116 * Creates an i/o device that is able to read from the QIODevice @p inDevice,
117 * whether the data is compressed or not. Available compression filters
118 * (gzip/bzip2 etc.) will automatically be used.
119 *
120 * The compression filter to be used is determined @p mimetype .
121 * Pass "application/x-gzip" or "application/x-bzip"
122 * to use the corresponding decompression filter.
123 *
124 * Warning: application/x-bzip may not be available.
125 * In that case 0 will be returned !
126 *
127 * The returned QIODevice has to be deleted after using.
128 * @param inDevice input device. Won't be deleted if @p autoDeleteInDevice = false
129 * @param mimetype the mime type for the filter
130 * @param autoDeleteInDevice if true, @p inDevice will be deleted automatically
131 * @return a KFilterDev that filters the original stream. Must be deleted after using
132 */
133 static QIODevice * device( QIODevice* inDevice, const QString & mimetype, bool autoDeleteInDevice = true );
134
135protected:
136 virtual qint64 readData( char *data, qint64 maxlen );
137 virtual qint64 writeData( const char *data, qint64 len );
138
139private:
140 /**
141 * Constructs a KFilterDev for a given filter (e.g. gzip, bzip2 etc.).
142 * @param filter the KFilterBase to use
143 * @param autoDeleteFilterBase when true this object will become the
144 * owner of @p filter.
145 */
146 explicit KFilterDev( KFilterBase * filter, bool autoDeleteFilterBase = false );
147private:
148 class Private;
149 Private* const d;
150};
151
152
153#endif
154