korn/protocol.h

   1 /*
   2  * Copyright (C) 2005, Mart Kelder (mart.kde@hccnet.nl)
   3  *
   4  * This program is free software; you can redistribute it and/or modify
   5  * it under the terms of the GNU General Public License as published by
   6  * the Free Software Foundation; either version 2 of the License, or
   7  * (at your option) any later version.
   8  *
   9  * This program 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
  12  * GNU General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License
  15  * along with this program; if not, write to the Free Software
  16  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
  17  */
  18
  19
  20 #ifndef PROTOCOL_H
  21 #define PROTOCOL_H
  22
  23 /**
  24  * @file
  25  * This file has one class. That class is used to determine the properties
  26  * of a protocol. It gives back the way the configuration dialog should look
  27  * like, and the way the settings are merge together to be useful for the
  28  * maildrop.
  29  *
  30  * The function is to make it possible to use a small number of maildrop's for a
  31  * (relative) big amount of protocols.
  32  */
  33
  34 class AccountInput;
  35 class AccountSettings;
  36 class KIO_Protocol;
  37 class KMailDrop;
  38
  39 class QObject;
  40 class QString;
  41 class QStringList;
  42 class QWidget;
  43
  44 template< class T> class QList;
  45 template< class T> class QVector;
  46 template< class T, class S> class QMap;
  47
  48 /**
  49  * This is the base class for every protocol. This class manage the properties of a protocol.
  50  * For example, it defines the input boxes in the configuration dialog, but it determines also the way a configuration file is readed.
  51  *
  52  * @author Mart Kelder <mart.kde@hccnet.nl>
  53  */
  54 class Protocol
  55 {
  56 public:
  57         /**
  58          * Empty contructor
  59          */
  60         Protocol() {}
  61         /**
  62          * Empty destructor
  63          */
  64         virtual ~Protocol() {}
  65
  66         /**
  67          * This function return another protocol which has to be used given the configuration file.
  68          * This way, it is possible to specify the protocol based on the configuration.
  69          *
  70          * KMail_Proto makes use of this function. It reads the KMail configuration file, and gives the protocol of the
  71          * specified KMail account.
  72          *
  73          * The protocol is not created with new, and thus it is not neccesairy to delete the returned pointer.
  74          *
  75          * @param config the configuration group of an account with protocol 'implementation'.
  76          * @return a (new) protocol which states the protocol to use after this function call.
  77          */
  78         virtual const Protocol* getProtocol( AccountSettings *config ) const = 0;
  79         /**
  80          * This function returns the mail drop belonging to this protocol.
  81          * The return value of this function also depends on the configuration, just like getProtocol().
  82          *
  83          * @param config the configuration of the account
  84          * @return the KMailDrop which should be used for this protocol.
  85          */
  86         virtual KMailDrop* createMaildrop( AccountSettings *config ) const = 0;
  87         /**
  88          * This function makes a configuration mapping given a the contents of a configuration file.
  89          * The password is shipped apart, because it can be stored in a wallet.
  90          *
  91          * This function makes it possible to get the settings from another place then the KOrn configuration file.
  92          *
  93          * The returning type is a mapping from a config key to a value.
  94          * The caller is responsable for deleting this object.
  95          *
  96          * @param config the configuration file to determine the mapping
  97          * @param password the password which could be stored elsewhere
  98          * @return a mapping from a configuration key to a value
  99          */
 100         virtual QMap< QString, QString > * createConfig( AccountSettings* config ) const = 0;
 101
 102         /**
 103          * This function return the name of the protocol as it is specified in the configuration file.
 104          * In the configuration file, only a name of a protocol is given.
 105          * This function makes it possible to compare the protocol in a configuration file with the Protocol class.
 106          *
 107          * This function should be constant and only depend on the Protocol class.
 108          *
 109          * @return the type of the account and the name in the configuration file
 110          */
 111         virtual QString configName() const = 0;
 112
 113         /**
 114          * This function fills a string list with names of groupboxes.
 115          * If the configuration dialog is called, this account screen can
 116          * be split up in several group boxes. The number of them and the
 117          * names of the groupboxes are coming from this function.
 118          * The input field are specified in configFields().
 119          *
 120          * @param list a pointer to an empty list which must be filled with names of group boxes in this function.
 121          */
 122         virtual void configFillGroupBoxes( QStringList* list ) const = 0;
 123         /**
 124          * This function puts the input fields into the groupboxes.
 125          * The groupboxes are the widgets in the @p vector.
 126          * The input fields whould be append to the list @p list.
 127          * The QObject of the caller is specified in the parameter @p obj.
 128          *
 129          * @param vector a vector which pointers to groupboxes where the input fields must be placed in
 130          * @param obj the QObject of the configuration dialog to connect signals to
 131          * @param list A pointer to a list of AccountInput*. This list should be filled in this function.
 132          */
 133         virtual void configFields( QVector< QWidget* >* vector, const QObject* obj, QList< AccountInput* >* list ) const = 0;
 134         /**
 135          * This function called to change a configuration mapping right after reading it.
 136          * After the data is read in, the configuration mapping can be changed to
 137          * fits the needs of the configuration dialog.
 138          *
 139          * @param config the configuration mapping which could be changed
 140          */
 141         virtual void readEntries( QMap< QString, QString >* config ) const = 0;
 142         /**
 143          * This function is called to change a configuration mapping right before writing it.
 144          * It is a bit like the inverse function of readEntries().
 145          * It can be used to put things back in place before writing it to file.
 146          *
 147          * @param config a pointer to the configuration mapping which can be changed
 148          */
 149         virtual void writeEntries( QMap< QString, QString >* config ) const = 0;
 150
 151         /**
 152          * The function return the default port of a protocol.
 153          *
 154          * @param ssl true gives the default ssl-port back; false the default normal port
 155          * @return a port number depending on the protocol and the usage of ssl
 156          */
 157         virtual unsigned short defaultPort( bool ) const { return 0; }
 158
 159         /**
 160          * This is a function to prevent a cast. If gives a pointer to a KIO_Protocol
 161          * if the Protocol* is an KIO_Protocol, and 0 elsewise.
 162          *
 163          * @return a pointer to this as KIO_Protocol if this implementation is a KIO_Protocol; 0 elsewise
 164          */
 165         virtual const KIO_Protocol* getKIOProtocol() const { return 0; }
 166
 167         /**
 168          * This function returns if the protocol can be rechecked after a certain interval.
 169          *
 170          * @return true if it is possible to recheck after a certain interval; false otherwise
 171          */
 172         virtual bool isPollable() const { return true; }
 173 };
 174
 175 #endif //PROTOCOL_H
 176