kdecore/network/k3resolverworkerbase.h

   1 /*  -*- C++ -*-
   2  *  Copyright (C) 2003-2005 Thiago Macieira <thiago@kde.org>
   3  *
   4  *
   5  *  Permission is hereby granted, free of charge, to any person obtaining
   6  *  a copy of this software and associated documentation files (the
   7  *  "Software"), to deal in the Software without restriction, including
   8  *  without limitation the rights to use, copy, modify, merge, publish,
   9  *  distribute, sublicense, and/or sell copies of the Software, and to
  10  *  permit persons to whom the Software is furnished to do so, subject to
  11  *  the following conditions:
  12  *
  13  *  The above copyright notice and this permission notice shall be included
  14  *  in all copies or substantial portions of the Software.
  15  *
  16  *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  17  *  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  18  *  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  19  *  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
  20  *  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
  21  *  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  22  *  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  23  */
  24
  25 #ifndef KRESOLVERWORKERBASE_H
  26 #define KRESOLVERWORKERBASE_H
  27
  28 #include "k3resolver.h"
  29
  30 // forward declarations
  31 class QString;
  32 template <class T> class QValueList;
  33
  34 namespace KNetwork {
  35
  36   namespace Internal
  37   {
  38     class KResolverThread;
  39     struct InputData;
  40   }
  41
  42 /**
  43  * @class KResolverWorkerBase k3resolverworkerbase.h k3resolverworkerbase.h
  44  *
  45  * @internal
  46  *
  47  * This class is the base functionality for a resolver worker. That is,
  48  * the class that does the actual work.
  49  *
  50  * In the future, this class might be exposed to allow plug-ins. So, try and
  51  * make it binary compatible.
  52  *
  53  * Note that hostnames are still encoded in Unicode at this point. It's up to
  54  * the worker class to decide which encoding to use. In the case of DNS,
  55  * an ASCII Compatible Encoding (ACE) must be used.
  56  * See KResolver::domainToAscii().
  57  *
  58  * Also specially note that the run method in this class is called in a
  59  * thread that is not the program's main thread. So do not do anything there
  60  * that you shouldn't!
  61  *
  62  * @deprecated Use KSocketFactory or KLocalSocket instead
  63  */
  64 class KResolverWorkerBase
  65 {
  66 public:
  67
  68   /**
  69    * Helper class for locking the resolver subsystem.
  70    * Similar to QMutexLocker.
  71    *
  72    * @author Luís Pedro Coelho
  73    */
  74   class ResolverLocker
  75   {
  76   public:
  77     /**
  78      * Constructor. Acquires a lock.
  79      */
  80     ResolverLocker(KResolverWorkerBase* parent)
  81       : parent( parent )
  82     {
  83       parent->acquireResolver();
  84     }
  85
  86     /**
  87      * Destructor. Releases the lock.
  88      */
  89     ~ResolverLocker()
  90     {
  91       parent->releaseResolver();
  92     }
  93
  94     /**
  95      * Releases the lock and then reacquires it.
  96      * It may be necessary to call this if the resolving function
  97      * decides to retry.
  98      */
  99     void openClose()
 100     {
 101       parent->releaseResolver();
 102       parent->acquireResolver();
 103     }
 104
 105   private:
 106     /// @internal
 107     KResolverWorkerBase* parent;
 108   };
 109 private:
 110   // this will be like our d pointer
 111   KNetwork::Internal::KResolverThread *th;
 112   const KNetwork::Internal::InputData *input;
 113   friend class KNetwork::Internal::KResolverThread;
 114   friend class KNetwork::Internal::KResolverManager;
 115   friend class KResolverWorkerBase::ResolverLocker;
 116
 117   int m_finished : 1;
 118   int m_reserved : 31;          // reserved
 119
 120 public:
 121   /**
 122    * Derived classes will put their resolved data in this list, or will
 123    * leave it empty in case of error.
 124    *
 125    * Status and error codes should also be stored in this object (the
 126    * setError() function does that).
 127    */
 128   KResolverResults results;
 129
 130 public:
 131   // default constructor
 132   KResolverWorkerBase();
 133
 134   // virtual destructor
 135   virtual ~KResolverWorkerBase();
 136
 137   /**
 138    * This is the hostname to be looked for
 139    */
 140   QString nodeName() const;
 141
 142   /**
 143    * And this is the service name
 144    */
 145   QString serviceName() const;
 146
 147   /**
 148    * gets the flags
 149    */
 150   int flags() const;
 151
 152   /**
 153    * gets the family mask
 154    */
 155   int familyMask() const;
 156
 157   /**
 158    * gets the socket type
 159    */
 160   int socketType() const;
 161
 162   /**
 163    * gets the protocol number
 164    */
 165   int protocol() const;
 166
 167   /**
 168    * gets the protocol name, if applicable
 169    */
 170   QByteArray protocolName() const;
 171
 172   /**
 173    * Call this function to indicate that processing
 174    * has finished. This is useful in the preprocessing
 175    * stage, to indicate that run() doesn't have to be
 176    * called.
 177    */
 178   void finished();
 179
 180 protected:
 181   // like a QThread
 182   /**
 183    * This is the function that should be overridden in derived classes.
 184    *
 185    * Derived classes will do their blocking job in this function and return
 186    * either success or failure to work (not the lookup). That is, whether the
 187    * lookup result was a domain found or not, if we got our answer, we should
 188    * indicate success. The error itself must be set with setError().
 189    *
 190    * \b Important: this function gets called in a separate thread!
 191    *
 192    * @return true on success
 193    */
 194   virtual bool run() = 0;
 195
 196   /**
 197    * This function gets called during pre processing for this class and you must
 198    * override it.
 199    *
 200    * \b Important: this function gets called in the main event thread. And it MUST
 201    * NOT block.
 202    *
 203    * This function can be used for an object to determine if it will be able
 204    * to resolve the given data or not even before launching into a blocking
 205    * operation. This function should return true if the object is capable of
 206    * handling this kind of data; false otherwise. Note that the return value
 207    * of 'true' means that the object's blocking answer will be considered authoritative.
 208    *
 209    * This function MUST NOT queue further requests. Leave that to run().
 210    *
 211    * This function is pure virtual; you must override it.
 212    *
 213    * @return true on success
 214    */
 215   virtual bool preprocess() = 0;
 216
 217   /**
 218    * This function gets called during post processing for this class.
 219    *
 220    * \b Important: this function gets called in the main event thread. And it MUST
 221    * NOT block.
 222    *
 223    * @returns true on success
 224    */
 225   virtual bool postprocess();
 226
 227   /**
 228    * Sets the error
 229    */
 230   inline void setError(int errorcode, int syserror = 0)
 231   { results.setError(errorcode, syserror); }
 232
 233   /**
 234    * Enqueue the given resolver for post-processing.
 235    *
 236    * Use this function to make the manager call for another resolution.
 237    * This is suitable for workers that do post-processing.
 238    *
 239    * The manager will make sure that any requests enqueued by this function
 240    * are done before calling the postprocessing function, which you should
 241    * override.
 242    *
 243    * \b Important: do use KResolver's own enqueueing functions (i.e., KResolver::start()).
 244    * Instead, use this function.
 245    *
 246    * @returns true on successful queuing or false if a problem ocurred
 247    */
 248   bool enqueue(KResolver* other);
 249
 250   /**
 251    * @overload
 252    */
 253   bool enqueue(KResolverWorkerBase* worker);
 254
 255   /**
 256    * Checks the resolver subsystem status.
 257    * @returns true if the resolver subsystem changed, false otherwise.
 258    *          If this function returns true, it might be necessary to
 259    *          restart the resolution altogether.
 260    */
 261   bool checkResolver();
 262
 263   /**
 264    * This function has to be called from the resolver workers that require
 265    * use of the DNS resolver code (i.e., res_* functions, generally in
 266    * libresolv). It indicates that the function is starting a resolution
 267    * and that the resolver backend shouldn't change asynchronously.
 268    *
 269    * If any pending res_init's are required, they will be performed before
 270    * this function returns.
 271    */
 272   void acquireResolver();
 273
 274   /**
 275    * This function is the counterpart for acquireResolver() - the worker
 276    * thread indicates that it's done with the resolver.
 277    */
 278   void releaseResolver();
 279
 280 };
 281
 282 /**
 283  * @class KResolverWorkerFactoryBase k3resolverworkerbase.h k3resolverworkerbase.h
 284  *
 285  * @internal
 286  *
 287  * This class provides functionality for creating and registering worker classes.
 288  *
 289  * @deprecated Use KSocketFactory or KLocalSocket instead
 290  */
 291 class KResolverWorkerFactoryBase
 292 {
 293 public:
 294   virtual ~KResolverWorkerFactoryBase() {}
 295   virtual KResolverWorkerBase* create() const = 0;
 296   /**
 297    * Wrapper call to register workers
 298    *
 299    * It is NOT thread-safe!
 300    */
 301   static void registerNewWorker(KResolverWorkerFactoryBase* factory);
 302 };
 303
 304 /**
 305  * @class KResolverWorkerFactory k3resolverworkerbase.h k3resolverworkerbase.h
 306  *
 307  * @internal
 308  *
 309  * This class provides functionality for creating and registering worker classes.
 310  *
 311  * @deprecated Use KSocketFactory or KLocalSocket instead
 312  */
 313 template<class Worker>
 314 class KResolverWorkerFactory: public KResolverWorkerFactoryBase
 315 {
 316 public:
 317   virtual KResolverWorkerBase* create() const
 318   { return new Worker; }
 319 };
 320
 321 }                               // namespace KNetwork
 322
 323 #endif