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 | |
31 | class QDataStream; |
32 | class 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 | */ |
50 | class KDECORE_EXPORT KProtocolInfo : public KSycocaEntry |
51 | { |
52 | friend class KProtocolInfoFactory; |
53 | friend class KBuildProtocolInfoFactory; |
54 | friend class KProtocolManager; |
55 | public: |
56 | typedef KSharedPtr<KProtocolInfo> Ptr; |
57 | typedef QList<Ptr> List; |
58 | |
59 | public: |
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 { |
121 | |
122 | enum { = QVariant::String, = QVariant::DateTime, = QVariant::Invalid }; |
123 | |
124 | () : type(Invalid) {} |
125 | (const QString& _name, Type _type ) |
126 | : name(_name), type(_type) { |
127 | } |
128 | QString ; |
129 | Type ; |
130 | }; |
131 | typedef QList<ExtraField> ; |
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 ( 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 | |
317 | public: |
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 | |
335 | protected: |
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 | |
364 | private: |
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 | |
378 | KDECORE_EXPORT QDataStream& ( QDataStream& s, KProtocolInfo::ExtraField& field ); |
379 | KDECORE_EXPORT QDataStream& ( QDataStream& s, const KProtocolInfo::ExtraField& field ); |
380 | |
381 | #endif |
382 | |