kdecore/network/k3serversocket.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 KSERVERSOCKET_H
  26 #define KSERVERSOCKET_H
  27
  28 #include <QtCore/QObject>
  29 #include "k3socketbase.h"
  30 #include "k3streamsocket.h"
  31
  32 namespace KNetwork {
  33
  34 class KStreamSocket;
  35 class KResolver;
  36 class KResolverResults;
  37
  38 class KServerSocketPrivate;
  39 /**
  40  * @class KServerSocket k3serversocket.h k3serversocket.h
  41  * @brief A server socket for accepting connections.
  42  *
  43  * This class provides functionality for creating a socket to
  44  * listen for incoming connections and subsequently accept them.
  45  *
  46  * To use this class, you must first set the parameters for the listening
  47  * socket's address, then place it in listening mode.
  48  *
  49  * A typical example would look like:
  50  * \code
  51  *   QString service = "http";
  52  *   KServerSocket *ss = new KServerSocket(service);
  53  *   connect(ss, SIGNAL(readyAccept()), this, SLOT(slotReadyAccept()));
  54  *   connect(ss, SIGNAL(gotError(int)), this, SLOT(slotSocketError(int)));
  55  *   ss->listen();
  56  * \endcode
  57  *
  58  * In this case, this class will place the socket into listening mode on the
  59  * service pointed to by @p service and will emit the readyAccept() signal
  60  * when a connection is ready for accepting. The called slot is responsible for
  61  * calling accept().
  62  *
  63  * The location of the services file (where @p service is looked up)
  64  * is defined by _PATH_SERVICES in /usr/include/netdb.h.  This is
  65  * usually set to /etc/services.
  66  * See RFC 1700 for more information on services.
  67  * You can specify @p service as a port number directly, rather than as a service
  68  * name.  This is discouraged as it prevents the end user from easily modifying
  69  * the port number.
  70  *
  71  * For another example of usage, this below code attempts to make a connection on any port within a range:
  72  * \code
  73  *   KServerSocket *ss = new KServerSocket();
  74  *   ss->setFamily(KResolver::InetFamily);
  75  *   bool found = false;
  76  *   for( unsigned int port = firstport; port <= lastport; ++port) {
  77  *     ss->setAddress( QString::number( port ) );
  78  *     bool success = ss->listen();
  79  *     if( found = ( success && ss->error() ==
  80  *                              KSocketBase::NoError ) )
  81  *       break;
  82  *     ss->close();
  83  *   }
  84  *   if( !found ) {
  85  *     // Couldn't connect to any port.
  86  *   } else {
  87  *     connect(ss, SIGNAL(readyAccept()), this, SLOT(slotReadyAccept()));
  88  *     connect(ss, SIGNAL(gotError(int)), this, SLOT(slotSocketError(int)));
  89  *     ss->listen();
  90  *   }
  91  * \endcode
  92  *
  93  * The called slot slotReadyAccept() is responsible for calling
  94  * accept().
  95  *
  96  * It is important to note that accept() can return either an
  97  * object of type KNetwork::KStreamSocket or
  98  * KNetwork::KBufferedSocket (default). If you want to accept a
  99  * non-buffered socket, you must first call setAcceptBuffered.
 100  *
 101  * @warning If you use KServerSocket in an auxiliary (non-GUI) thread,
 102  *          you need to accept only KNetwork::KStreamSocket objects.
 103  *
 104  * @see KNetwork::KStreamSocket, KNetwork::KBufferedSocket
 105  * @author Thiago Macieira <thiago@kde.org>
 106  * @deprecated Use KSocketFactory or KLocalSocket instead
 107  */
 108 class KDECORE_EXPORT KServerSocket: public QObject, public KPassiveSocketBase
 109 {
 110   Q_OBJECT
 111 public:
 112   /**
 113    * Default constructor.
 114    *
 115    * If the binding address isn't changed by setAddress, this socket will
 116    * bind to all interfaces on this node and the port will be selected by the
 117    * operating system.
 118    *
 119    * @param parent              the parent QObject object
 120    */
 121   KServerSocket(QObject* parent = 0L);
 122
 123   /**
 124    * Construct this object specifying the service to listen on.
 125    *
 126    * If the binding address isn't changed by setAddress, this socket will
 127    * bind to all interfaces and will listen on the port specified by
 128    * @p service.  This is either a service name (e.g. 'www') or a port
 129    * number (e.g. '80').
 130    *
 131    * The location of the services file (where @p service is looked up)
 132    * is defined by _PATH_SERVICES in /usr/include/netdb.h.  This is
 133    * usually set to /etc/services.
 134    * See RFC 1700 for more information on services.
 135    *
 136    * @param service             the service name to listen on
 137    * @param parent              the parent QObject object
 138    */
 139   explicit KServerSocket(const QString& service, QObject* parent = 0L);
 140
 141   /**
 142    * Construct this object specifying the node and service names to listen on.
 143    *
 144    * If the binding address isn't changed by setAddress, this socket will
 145    * bind to the interface specified by @p node and the port specified by
 146    * @p service.  This is either a service name (e.g. 'www') or a port
 147    * number (e.g. '80').
 148    *
 149    * The location of the services file (where @p service is looked up)
 150    * is defined by _PATH_SERVICES in /usr/include/netdb.h.  This is
 151    * usually set to /etc/services.
 152    * See RFC 1700 for more information on services.
 153    *
 154    * @param node                the node to bind to
 155    * @param service             the service port to listen on
 156    * @param parent              the parent QObject object
 157    */
 158   KServerSocket(const QString& node, const QString& service,
 159                 QObject* parent = 0L);
 160
 161   /**
 162    * Destructor. This will close the socket, if open.
 163    *
 164    * Note, however, that accepted sockets do not get closed when this
 165    * object closes.
 166    */
 167   ~KServerSocket();
 168
 169 protected:
 170   /**
 171    * Sets the socket options. Reimplemented from KSocketBase.
 172    */
 173   virtual bool setSocketOptions(int opts);
 174
 175 public:
 176   /**
 177    * Returns the internal KResolver object used for
 178    * looking up the host name and service.
 179    *
 180    * This can be used to set extra options to the
 181    * lookup process other than the default values, as well
 182    * as obtaining the error codes in case of lookup failure.
 183    */
 184   KResolver& resolver() const;
 185
 186   /**
 187    * Returns the internal list of resolved results for the binding address.
 188    */
 189   const KResolverResults& resolverResults() const;
 190
 191   /**
 192    * Enables or disables name resolution. If this flag is set to true,
 193    * the bind() operation will trigger name lookup
 194    * operations (i.e., converting a hostname into its binary form).
 195    * If the flag is set to false, those operations will instead
 196    * try to convert a string representation of an address without
 197    * attempting name resolution.
 198    *
 199    * This is useful, for instance, when IP addresses are in
 200    * their string representation (such as "1.2.3.4") or come
 201    * from other sources like KSocketAddress.
 202    *
 203    * @param enable      whether to enable
 204    */
 205   void setResolutionEnabled(bool enable);
 206
 207   /**
 208    * Sets the allowed families for the resolutions.
 209    *
 210    * @param families            the families that we want/accept
 211    * @see KResolver::SocketFamilies for possible values
 212    */
 213   void setFamily(int families);
 214
 215   /**
 216    * Sets the address on which we will listen. The port to listen on is given by
 217    * @p service, and we will bind to all interfaces. To let the operating system choose a
 218    * port, set the service to "0".  @p service can either be a service name
 219    * (e.g. 'www') or a port number (e.g. '80').
 220    *
 221    * The location of the services file (where @p service is looked up)
 222    * is defined by _PATH_SERVICES in /usr/include/netdb.h.  This is
 223    * usually set to /etc/services.
 224    * See RFC 1700 for more information on services.
 225    *
 226    * @param service             the service name to listen on
 227    */
 228   void setAddress(const QString& service);
 229
 230   /**
 231    * @overload
 232    * Sets the address on which we will listen. This will cause the socket to listen
 233    * only on the interface given by @p node and on the port given by @p service.
 234    * @p service can either be a service name (e.g. 'www') or a port number
 235    * (e.g. '80').
 236    *
 237    * The location of the services file (where @p service is looked up)
 238    * is defined by _PATH_SERVICES in /usr/include/netdb.h.  This is
 239    * usually set to /etc/services.
 240    * See RFC 1700 for more information on services.
 241    *
 242    * @param node                the node to bind to
 243    * @param service             the service port to listen on
 244    */
 245   void setAddress(const QString& node, const QString& service);
 246
 247   /**
 248    * Sets the timeout for accepting. When you call accept(),
 249    * it will wait at most @p msecs milliseconds or return with an error
 250    * (returning a NULL object).
 251    *
 252    * @param msecs               the time in milliseconds to wait, 0 to wait forever
 253    */
 254   void setTimeout(int msecs);
 255
 256   /**
 257    * Starts the lookup for peer and local hostnames as
 258    * well as their services.
 259    *
 260    * If the blocking mode for this object is on, this function will
 261    * wait for the lookup results to be available (by calling the
 262    * KResolver::wait() method on the resolver objects).
 263    *
 264    * When the lookup is done, the signal hostFound() will be
 265    * emitted (only once, even if we're doing a double lookup).
 266    * If the lookup failed (for any of the two lookups) the
 267    * gotError() signal will be emitted with the appropriate
 268    * error condition (see KSocketBase::SocketError).
 269    *
 270    * This function returns true on success and false on error. Note that
 271    * this is not the lookup result!
 272    */
 273   virtual bool lookup();
 274
 275   /**
 276    * Binds this socket to the given nodename and service,
 277    * or use the default ones if none are given.
 278    *
 279    * Upon successful binding, the bound() signal will be
 280    * emitted. If an error is found, the gotError()
 281    * signal will be emitted.
 282    *
 283    * This function returns true on success.
 284    *
 285    * @param node        the nodename
 286    * @param service     the service
 287    */
 288   virtual bool bind(const QString& node, const QString& service);
 289
 290   /**
 291    * Binds the socket to the given service name.
 292    * @overload
 293    *
 294    * @param service     the service
 295    */
 296   virtual bool bind(const QString& service);
 297
 298   /**
 299    * Binds the socket to the addresses previously set with setAddress().
 300    * @overload
 301    *
 302    */
 303   virtual bool bind();
 304
 305   /**
 306    * Connect this socket to this specific address. Reimplemented from KSocketBase.
 307    *
 308    * Unlike bind(const QString&, const QString&) above, this function
 309    * really does bind the socket. No lookup is performed. The bound() signal
 310    * will be emitted.
 311    */
 312   virtual bool bind(const KResolverEntry& address);
 313
 314   /**
 315    * Puts this socket into listening mode. Reimplemented from KPassiveSocketBase.
 316    *
 317    * Placing a socket into listening mode means it will be able to receive incoming
 318    * connections through the accept() method.
 319    *
 320    * If you do not call this method but call accept() directly, the socket will
 321    * be placed into listening mode automatically.
 322    *
 323    * @param backlog             the number of connection the system is to
 324    *                            queue without accept() being called
 325    * @returns true if the socket is now in listening mode.
 326    */
 327   virtual bool listen(int backlog = 5); // 5 is arbitrary
 328
 329   /**
 330    * Closes this socket.
 331    */
 332   virtual void close();
 333
 334   /**
 335    * Toggles whether the accepted socket will be buffered or not.
 336    * That is, the accept() function will always return a KStreamSocket
 337    * object or descended from it. If buffering is enabled, the class
 338    * to be returned will be KBufferedSocket.
 339    *
 340    * By default, this flag is set to true.
 341    *
 342    * @param enable              whether to set the accepted socket to
 343    *                            buffered mode
 344    */
 345   void setAcceptBuffered(bool enable);
 346
 347   /**
 348    * Accepts one incoming connection and return the associated, open
 349    * socket.
 350    *
 351    * If this function cannot accept a new connection, it will return NULL.
 352    * The specific object class returned by this function may vary according
 353    * to the implementation: derived classes may return specialized objects
 354    * descended from KStreamSocket.
 355    *
 356    * @sa KBufferedSocket
 357    * @sa setAcceptBuffered
 358    */
 359   virtual KStreamSocket* accept();
 360
 361   /**
 362    * Returns this socket's local address.
 363    */
 364   virtual KSocketAddress localAddress() const;
 365
 366   /**
 367    * Returns this socket's externally-visible address if know.
 368    */
 369   virtual KSocketAddress externalAddress() const;
 370
 371 private Q_SLOTS:
 372   void lookupFinishedSlot();
 373
 374 Q_SIGNALS:
 375   /**
 376    * This signal is emitted when this object finds an error.
 377    * The @p code parameter contains the error code that can
 378    * also be found by calling error().
 379    */
 380   void gotError(int code);
 381
 382   /**
 383    * This signal is emitted when the lookup is successfully completed.
 384    */
 385   void hostFound();
 386
 387   /**
 388    * This signal is emitted when the socket successfully binds
 389    * to an address.
 390    *
 391    * @param local       the local address we bound to
 392    */
 393   void bound(const KNetwork::KResolverEntry& local);
 394
 395   /**
 396    * This signal is emitted when the socket completes the
 397    * closing/shut down process.
 398    */
 399   void closed();
 400
 401   /**
 402    * This signal is emitted whenever the socket is ready for
 403    * accepting -- i.e., there is at least one connection waiting to
 404    * be accepted.
 405    */
 406   void readyAccept();
 407
 408 protected:
 409   /**
 410    * Convenience function to set this object's error code to match
 411    * that of the socket device.
 412    */
 413   void copyError();
 414
 415 private:
 416   bool doBind();
 417   bool doListen();
 418
 419 private:
 420   KServerSocket(const KServerSocket&);
 421   KServerSocket& operator=(const KServerSocket&);
 422
 423   KServerSocketPrivate* const d;
 424 };
 425
 426 }                               // namespace KNetwork
 427
 428 #endif