1/* This file is part of the KDE libraries
2 Copyright (C) 1999 Torben Weis <weis@kde.org>
3 Copyright (C) 2000-2001 Waldo Bastian <bastian@kde.org>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Library General Public
7 License version 2 as published by the Free Software Foundation.
8
9 This library is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 Library General Public License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this library; see the file COPYING.LIB. If not, write to
16 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17 Boston, MA 02110-1301, USA.
18*/
19#ifndef KPROTOCOLINFO_H
20#define KPROTOCOLINFO_H
21
22#include <kglobal.h>
23
24#include <kurl.h>
25#include <ksycocaentry.h>
26#include <ksycocatype.h>
27#include <kservice.h>
28#include <QtCore/QVariant>
29#include <QtCore/QStringList>
30
31class QDataStream;
32class KProtocolInfoPrivate;
33
34/**
35 * \class KProtocolInfo kprotocolinfo.h <KProtocolInfo>
36 *
37 * Information about I/O (Internet, etc.) protocols supported by KDE.
38
39 * This class is useful if you want to know which protocols
40 * KDE supports. In addition you can find out lots of information
41 * about a certain protocol. A KProtocolInfo instance represents a
42 * single protocol. Most of the functionality is provided by the static
43 * methods that scan the *.protocol files of all installed kioslaves to get
44 * this information.
45 *
46 * *.protocol files are installed in the "services" resource.
47 *
48 * @author Torben Weis <weis@kde.org>
49 */
50class KDECORE_EXPORT KProtocolInfo : public KSycocaEntry
51{
52 friend class KProtocolInfoFactory;
53 friend class KBuildProtocolInfoFactory;
54 friend class KProtocolManager;
55public:
56 typedef KSharedPtr<KProtocolInfo> Ptr;
57 typedef QList<Ptr> List;
58
59public:
60
61 //
62 // Static functions:
63 //
64
65 /**
66 * Returns list of all known protocols.
67 * @return a list of all known protocols
68 */
69 static QStringList protocols();
70
71 /**
72 * Returns whether a protocol is installed that is able to handle @p url.
73 *
74 * @param url the url to check
75 * @return true if the protocol is known
76 * @see name()
77 */
78 static bool isKnownProtocol( const KUrl &url );
79
80 /**
81 * Same as above except you can supply just the protocol instead of
82 * the whole URL.
83 */
84 static bool isKnownProtocol( const QString& protocol );
85
86 /**
87 * Returns the library / executable to open for the protocol @p protocol
88 * Example : "kio_ftp", meaning either the executable "kio_ftp" or
89 * the library "kio_ftp.la" (recommended), whichever is available.
90 *
91 * This corresponds to the "exec=" field in the protocol description file.
92 * @param protocol the protocol to check
93 * @return the executable of library to open, or QString() for
94 * unsupported protocols
95 * @see KUrl::protocol()
96 */
97 static QString exec( const QString& protocol );
98
99 /**
100 * Describes the type of a protocol.
101 * For instance ftp:// appears as a filesystem with folders and files,
102 * while bzip2:// appears as a single file (a stream of data),
103 * and telnet:// doesn't output anything.
104 * @see outputType
105 */
106 enum Type { T_STREAM, ///< stream of data (e.g. single file)
107 T_FILESYSTEM, ///< structured directory
108 T_NONE, ///< no information about the type available
109 T_ERROR ///< used to signal an error
110 };
111
112 /**
113 * Definition of an extra field in the UDS entries, returned by a listDir operation.
114 *
115 * The name is the name of the column, translated.
116 *
117 * The type name comes from QVariant::typeName()
118 * Currently supported types: "QString", "QDateTime" (ISO-8601 format)
119 */
120 struct ExtraField {
121
122 enum Type { String = QVariant::String, DateTime = QVariant::DateTime, Invalid = QVariant::Invalid };
123
124 ExtraField() : type(Invalid) {}
125 ExtraField(const QString& _name, Type _type )
126 : name(_name), type(_type) {
127 }
128 QString name;
129 Type type;
130 };
131 typedef QList<ExtraField> ExtraFieldList;
132 /**
133 * Definition of extra fields in the UDS entries, returned by a listDir operation.
134 *
135 * This corresponds to the "ExtraNames=" and "ExtraTypes=" fields in the protocol description file.
136 * Those two lists should be separated with ',' in the protocol description file.
137 * See ExtraField for details about names and types
138 */
139 static ExtraFieldList extraFields( const KUrl& url );
140
141 /**
142 * Returns whether the protocol can act as a helper protocol.
143 * A helper protocol invokes an external application and does not return
144 * a file or stream.
145 *
146 * This corresponds to the "helper=" field in the protocol description file.
147 * Valid values for this field are "true" or "false" (default).
148 *
149 * @param url the url to check
150 * @return true if the protocol is a helper protocol (e.g. vnc), false
151 * if not (e.g. http)
152 */
153 static bool isHelperProtocol( const KUrl &url );
154
155 /**
156 * Same as above except you can supply just the protocol instead of
157 * the whole URL.
158 */
159 static bool isHelperProtocol( const QString& protocol );
160
161 /**
162 * Returns whether the protocol can act as a filter protocol.
163 *
164 * A filter protocol can operate on data that is passed to it
165 * but does not retrieve/store data itself, like gzip.
166 * A filter protocol is the opposite of a source protocol.
167 *
168 * The "source=" field in the protocol description file determines
169 * whether a protocol is a source protocol or a filter protocol.
170 * Valid values for this field are "true" (default) for source protocol or
171 * "false" for filter protocol.
172 *
173 * @param url the url to check
174 * @return true if the protocol is a filter (e.g. gzip), false if the
175 * protocol is a helper or source
176 */
177 static bool isFilterProtocol( const KUrl &url );
178
179 /**
180 * Same as above except you can supply just the protocol instead of
181 * the whole URL.
182 */
183 static bool isFilterProtocol( const QString& protocol );
184
185 /**
186 * Returns the name of the icon, associated with the specified protocol.
187 *
188 * This corresponds to the "Icon=" field in the protocol description file.
189 *
190 * @param protocol the protocol to check
191 * @return the icon of the protocol, or an empty string if unknown
192 */
193 static QString icon( const QString& protocol );
194
195 /**
196 * Returns the name of the config file associated with the
197 * specified protocol. This is useful if two similar protocols
198 * need to share a single config file, e.g. http and https.
199 *
200 * This corresponds to the "config=" field in the protocol description file.
201 * The default is the protocol name, see name()
202 *
203 * @param protocol the protocol to check
204 * @return the config file, or an empty string if unknown
205 */
206 static QString config( const QString& protocol );
207
208 /**
209 * Returns the soft limit on the number of slaves for this protocol.
210 * This limits the number of slaves used for a single operation, note
211 * that multiple operations may result in a number of instances that
212 * exceeds this soft limit.
213 *
214 * This corresponds to the "maxInstances=" field in the protocol description file.
215 * The default is 1.
216 *
217 * @param protocol the protocol to check
218 * @return the maximum number of slaves, or 1 if unknown
219 */
220 static int maxSlaves( const QString& protocol );
221
222
223 /**
224 * Returns the limit on the number of slaves for this protocol per host.
225 *
226 * This corresponds to the "maxInstancesPerHost=" field in the protocol description file.
227 * The default is 0 which means there is no per host limit.
228 *
229 * @param protocol the protocol to check
230 * @return the maximum number of slaves, or 1 if unknown
231 *
232 * @since 4.4
233 */
234 static int maxSlavesPerHost( const QString& protocol );
235
236 /**
237 * Returns whether mimetypes can be determined based on extension for this
238 * protocol. For some protocols, e.g. http, the filename extension in the URL
239 * can not be trusted to truly reflect the file type.
240 *
241 * This corresponds to the "determineMimetypeFromExtension=" field in the protocol description file.
242 * Valid values for this field are "true" (default) or "false".
243 *
244 * @param protocol the protocol to check
245 * @return true if the mime types can be determined by extension
246 */
247 static bool determineMimetypeFromExtension( const QString &protocol );
248
249 /**
250 * Returns the documentation path for the specified protocol.
251 *
252 * This corresponds to the "X-DocPath=" or "DocPath=" field in the protocol description file.
253 *
254 * @param protocol the protocol to check
255 * @return the docpath of the protocol, or an empty string if unknown
256 */
257 static QString docPath( const QString& protocol );
258
259 /**
260 * Returns the protocol class for the specified protocol.
261 *
262 * This corresponds to the "Class=" field in the protocol description file.
263 *
264 * The following classes are defined:
265 * @li ":internet" for common internet protocols
266 * @li ":local" for protocols that access local resources
267 *
268 * Protocol classes always start with a ':' so that they can not be confused with
269 * the protocols themselves.
270 *
271 * @param protocol the protocol to check
272 * @return the class of the protocol, or an empty string if unknown
273 */
274 static QString protocolClass( const QString& protocol );
275
276 /**
277 * Returns whether file previews should be shown for the specified protocol.
278 *
279 * This corresponds to the "ShowPreviews=" field in the protocol description file.
280 *
281 * By default previews are shown if protocolClass is :local.
282 *
283 * @param protocol the protocol to check
284 * @return true if previews should be shown by default, false otherwise
285 */
286 static bool showFilePreview( const QString& protocol );
287
288 /**
289 * Returns the list of capabilities provided by the kioslave implementing
290 * this protocol.
291 *
292 * This corresponds to the "Capabilities=" field in the protocol description file.
293 *
294 * The capability names are not defined globally, they are up to each
295 * slave implementation. For example when adding support for a new
296 * special command for mounting, one would add the string "Mount" to the
297 * capabilities list, and applications could check for that string
298 * before sending a special() command that would otherwise do nothing
299 * on older kioslave implementations.
300 *
301 * @param protocol the protocol to check
302 * @return the list of capabilities.
303 */
304 static QStringList capabilities( const QString& protocol );
305
306 /**
307 * Returns the name of the protocol through which the request
308 * will be routed if proxy support is enabled.
309 *
310 * A good example of this is the ftp protocol for which proxy
311 * support is commonly handled by the http protocol.
312 *
313 * This corresponds to the "ProxiedBy=" in the protocol description file.
314 */
315 static QString proxiedBy( const QString& protocol );
316
317public:
318 // Internal functions:
319 /**
320 * @internal construct a KProtocolInfo from a stream
321 */
322 KProtocolInfo( QDataStream& _str, int offset);
323
324 virtual ~KProtocolInfo();
325
326 typedef enum { Name, FromUrl, DisplayName } FileNameUsedForCopying;
327
328 /// @internal. Use KProtocolManager instead.
329 bool supportsListing() const;
330 /// @internal. Use KProtocolManager instead.
331 QString defaultMimeType() const;
332 /// @internal. Use KProtocolManager instead.
333 QStringList archiveMimeTypes() const;
334
335protected:
336 QString m_name;
337 QString m_exec;
338 Type m_inputType;
339 Type m_outputType;
340 QStringList m_listing;
341 bool m_isSourceProtocol;
342 bool m_isHelperProtocol;
343 bool m_supportsListing;
344 bool m_supportsReading;
345 bool m_supportsWriting;
346 bool m_supportsMakeDir;
347 bool m_supportsDeleting;
348 bool m_supportsLinking;
349 bool m_supportsMoving;
350 bool m_supportsOpening;
351 QString m_defaultMimetype;
352 bool m_determineMimetypeFromExtension;
353 QString m_icon;
354 bool m_canCopyFromFile;
355 bool m_canCopyToFile;
356 QString m_config;
357 int m_maxSlaves;
358
359 bool canRenameFromFile() const;
360 bool canRenameToFile() const;
361 bool canDeleteRecursive() const;
362 FileNameUsedForCopying fileNameUsedForCopying() const;
363
364private:
365 /**
366 * Read a protocol description file
367 * @param path the path of the description file
368 */
369 KProtocolInfo( const QString & path);
370
371 Q_DECLARE_PRIVATE(KProtocolInfo)
372
373 void load(QDataStream &s);
374 static void selectServiceOrHelper(const QString& protocol, KProtocolInfo::Ptr& returnProtocol, KService::Ptr& returnService);
375
376};
377
378KDECORE_EXPORT QDataStream& operator>>( QDataStream& s, KProtocolInfo::ExtraField& field );
379KDECORE_EXPORT QDataStream& operator<<( QDataStream& s, const KProtocolInfo::ExtraField& field );
380
381#endif
382