kdecore/sycoca/kprotocolinfo.h

   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 <QtCore/QVariant>
  28 #include <QtCore/QStringList>
  29
  30 class QDataStream;
  31 class KProtocolInfoPrivate;
  32
  33 /**
  34  * \class KProtocolInfo kprotocolinfo.h <KProtocolInfo>
  35  *
  36  * Information about I/O (Internet, etc.) protocols supported by KDE.
  37
  38  * This class is useful if you want to know which protocols
  39  * KDE supports. In addition you can find out lots of information
  40  * about a certain protocol. A KProtocolInfo instance represents a
  41  * single protocol. Most of the functionality is provided by the static
  42  * methods that scan the *.protocol files of all installed kioslaves to get
  43  * this information.
  44  *
  45  * *.protocol files are installed in the "services" resource.
  46  *
  47  * @author Torben Weis <weis@kde.org>
  48  */
  49 class KDECORE_EXPORT KProtocolInfo : public KSycocaEntry
  50 {
  51   friend class KProtocolInfoFactory;
  52   friend class KBuildProtocolInfoFactory;
  53   friend class KProtocolManager;
  54 public:
  55   typedef KSharedPtr<KProtocolInfo> Ptr;
  56     typedef QList<Ptr> List;
  57
  58 public:
  59
  60   //
  61   // Static functions:
  62   //
  63
  64   /**
  65    * Returns list of all known protocols.
  66    * @return a list of all known protocols
  67    */
  68   static QStringList protocols();
  69
  70   /**
  71    * Returns whether a protocol is installed that is able to handle @p url.
  72    *
  73    * @param url the url to check
  74    * @return true if the protocol is known
  75    * @see name()
  76    */
  77   static bool isKnownProtocol( const KUrl &url );
  78
  79   /**
  80    * Same as above except you can supply just the protocol instead of
  81    * the whole URL.
  82    */
  83   static bool isKnownProtocol( const QString& protocol );
  84
  85   /**
  86    * Returns the library / executable to open for the protocol @p protocol
  87    * Example : "kio_ftp", meaning either the executable "kio_ftp" or
  88    * the library "kio_ftp.la" (recommended), whichever is available.
  89    *
  90    * This corresponds to the "exec=" field in the protocol description file.
  91    * @param protocol the protocol to check
  92    * @return the executable of library to open, or QString() for
  93    *         unsupported protocols
  94    * @see KUrl::protocol()
  95    */
  96   static QString exec( const QString& protocol );
  97
  98   /**
  99    * Describes the type of a protocol.
 100    * For instance ftp:// appears as a filesystem with folders and files,
 101    * while bzip2:// appears as a single file (a stream of data),
 102    * and telnet:// doesn't output anything.
 103    * @see outputType
 104    */
 105   enum Type { T_STREAM, ///< stream of data (e.g. single file)
 106               T_FILESYSTEM, ///< structured directory
 107               T_NONE,   ///< no information about the type available
 108               T_ERROR   ///< used to signal an error
 109   };
 110
 111   /**
 112    * Definition of an extra field in the UDS entries, returned by a listDir operation.
 113    *
 114    * The name is the name of the column, translated.
 115    *
 116    * The type name comes from QVariant::typeName()
 117    * Currently supported types: "QString", "QDateTime" (ISO-8601 format)
 118    */
 119   struct ExtraField {
 120
 121     enum Type { String = QVariant::String, DateTime = QVariant::DateTime, Invalid = QVariant::Invalid };
 122
 123     ExtraField() : type(Invalid) {}
 124     ExtraField(const QString& _name, Type _type )
 125       : name(_name), type(_type) {
 126     }
 127     QString name;
 128     Type type;
 129   };
 130   typedef QList<ExtraField> ExtraFieldList;
 131   /**
 132    * Definition of extra fields in the UDS entries, returned by a listDir operation.
 133    *
 134    * This corresponds to the "ExtraNames=" and "ExtraTypes=" fields in the protocol description file.
 135    * Those two lists should be separated with ',' in the protocol description file.
 136    * See ExtraField for details about names and types
 137    */
 138   static ExtraFieldList extraFields( const KUrl& url );
 139
 140   /**
 141    * Returns whether the protocol can act as a helper protocol.
 142    * A helper protocol invokes an external application and does not return
 143    * a file or stream.
 144    *
 145    * This corresponds to the "helper=" field in the protocol description file.
 146    * Valid values for this field are "true" or "false" (default).
 147    *
 148    * @param url the url to check
 149    * @return true if the protocol is a helper protocol (e.g. vnc), false
 150    *              if not (e.g. http)
 151    */
 152   static bool isHelperProtocol( const KUrl &url );
 153
 154   /**
 155    * Same as above except you can supply just the protocol instead of
 156    * the whole URL.
 157    */
 158   static bool isHelperProtocol( const QString& protocol );
 159
 160   /**
 161    * Returns whether the protocol can act as a filter protocol.
 162    *
 163    * A filter protocol can operate on data that is passed to it
 164    * but does not retrieve/store data itself, like gzip.
 165    * A filter protocol is the opposite of a source protocol.
 166    *
 167    * The "source=" field in the protocol description file determines
 168    * whether a protocol is a source protocol or a filter protocol.
 169    * Valid values for this field are "true" (default) for source protocol or
 170    * "false" for filter protocol.
 171    *
 172    * @param url the url to check
 173    * @return true if the protocol is a filter (e.g. gzip), false if the
 174    *         protocol is a helper or source
 175    */
 176   static bool isFilterProtocol( const KUrl &url );
 177
 178   /**
 179    * Same as above except you can supply just the protocol instead of
 180    * the whole URL.
 181    */
 182   static bool isFilterProtocol( const QString& protocol );
 183
 184   /**
 185    * Returns the name of the icon, associated with the specified protocol.
 186    *
 187    * This corresponds to the "Icon=" field in the protocol description file.
 188    *
 189    * @param protocol the protocol to check
 190    * @return the icon of the protocol, or null if unknown
 191    */
 192   static QString icon( const QString& protocol );
 193
 194   /**
 195    * Returns the name of the config file associated with the
 196    * specified protocol. This is useful if two similar protocols
 197    * need to share a single config file, e.g. http and https.
 198    *
 199    * This corresponds to the "config=" field in the protocol description file.
 200    * The default is the protocol name, see name()
 201    *
 202    * @param protocol the protocol to check
 203    * @return the config file, or null if unknown
 204    */
 205   static QString config( const QString& protocol );
 206
 207   /**
 208    * Returns the soft limit on the number of slaves for this protocol.
 209    * This limits the number of slaves used for a single operation, note
 210    * that multiple operations may result in a number of instances that
 211    * exceeds this soft limit.
 212    *
 213    * This corresponds to the "maxInstances=" field in the protocol description file.
 214    * The default is 1.
 215    *
 216    * @param protocol the protocol to check
 217    * @return the maximum number of slaves, or 1 if unknown
 218    */
 219   static int maxSlaves( const QString& protocol );
 220
 221   /**
 222    * Returns whether mimetypes can be determined based on extension for this
 223    * protocol. For some protocols, e.g. http, the filename extension in the URL
 224    * can not be trusted to truly reflect the file type.
 225    *
 226    * This corresponds to the "determineMimetypeFromExtension=" field in the protocol description file.
 227    * Valid values for this field are "true" (default) or "false".
 228    *
 229    * @param protocol the protocol to check
 230    * @return true if the mime types can be determined by extension
 231    */
 232   static bool determineMimetypeFromExtension( const QString &protocol );
 233
 234   /**
 235    * Returns the documentation path for the specified protocol.
 236    *
 237    * This corresponds to the "X-DocPath=" or "DocPath=" field in the protocol description file.
 238    *
 239    * @param protocol the protocol to check
 240    * @return the docpath of the protocol, or null if unknown
 241    */
 242   static QString docPath( const QString& protocol );
 243
 244   /**
 245    * Returns the protocol class for the specified protocol.
 246    *
 247    * This corresponds to the "Class=" field in the protocol description file.
 248    *
 249    * The following classes are defined:
 250    * @li ":internet" for common internet protocols
 251    * @li ":local" for protocols that access local resources
 252    *
 253    * Protocol classes always start with a ':' so that they can not be confused with
 254    * the protocols themselves.
 255    *
 256    * @param protocol the protocol to check
 257    * @return the class of the protocol, or null if unknown
 258    */
 259   static QString protocolClass( const QString& protocol );
 260
 261   /**
 262    * Returns whether file previews should be shown for the specified protocol.
 263    *
 264    * This corresponds to the "ShowPreviews=" field in the protocol description file.
 265    *
 266    * By default previews are shown if protocolClass is :local.
 267    *
 268    * @param protocol the protocol to check
 269    * @return true if previews should be shown by default, false otherwise
 270    */
 271   static bool showFilePreview( const QString& protocol );
 272
 273   /**
 274    * Returns the suggested URI parsing mode for the KUrl parser.
 275    *
 276    * This corresponds to the "URIMode=" field in the protocol description file.
 277    *
 278    * The following parsing modes are defined:
 279    * @li "url" for a standards compliant URL
 280    * @li "rawuri" for a non-conformant URI for which URL parsing would be meaningless
 281    * @li "mailto" for a mailto style URI (the path part contains only an email address)
 282    *
 283    * @param protocol the protocol to check
 284    * @return the suggested parsing mode, or KUrl::Auto if unspecified
 285    */
 286   //static KUrl::URIMode uriParseMode( const QString& protocol ); - gone in Qt-4.x
 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 } 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 };
 375
 376 KDECORE_EXPORT QDataStream& operator>>( QDataStream& s, KProtocolInfo::ExtraField& field );
 377 KDECORE_EXPORT QDataStream& operator<<( QDataStream& s, const KProtocolInfo::ExtraField& field );
 378
 379 #endif