kextsock.h

来自「konqueror3 embedded版本, KDE环境下的当家浏览器的嵌入式版」· C头文件 代码 · 共 1,111 行 · 第 1/3 页

/*
 *  This file is part of the KDE libraries
 *  Copyright (C) 2000-2004 Thiago Macieira <[e-mail]>
 *
 *  This library is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Library General Public
 *  License as published by the Free Software Foundation; either
 *  version 2 of the License, or (at your option) any later version.
 *
 *  This library is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *  Library General Public License for more details.
 *
 *  You should have received a copy of the GNU Library General Public License
 *  along with this library; see the file COPYING.LIB.  If not, write to
 *  the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
 *  Boston, MA 02110-1301, USA.
 */
#ifndef KEXTSOCK_H
#define KEXTSOCK_H

#include "kdelibs_export.h"

#ifdef Q_OS_UNIX

#include <sys/time.h>

#include <qstring.h>
#include <qptrlist.h>
#include <qiodevice.h>

#include "kbufferedio.h"
#include "ksockaddr.h"

/* External reference to netdb.h */
struct addrinfo;
struct kde_addrinfo;
class KAddressInfo;		/* our abstraction of it */
class QSocketNotifier;

/*
 * This is extending QIODevice's error codes
 *
 * According to qiodevice.h, the last error is IO_UnspecifiedError
 * These errors will never occur in functions declared in QIODevice
 * (except open, but you shouldn't call open)
 */
#define IO_ListenError		(IO_UnspecifiedError+1)
#define IO_AcceptError		(IO_UnspecifiedError+2)
#define IO_LookupError		(IO_UnspecifiedError+3)

class KExtendedSocketPrivate;
/**
 * The extended socket class.
 *
 * This class should be used instead of KSocket whenever the user needs
 * fine-grained control over the socket being created. Unlike KSocket, which
 * does everything at once, without much intervention, KExtendedSocket allows
 * intervention at every step of the process and the setting of parameters.
 *
 * This class allows for the creation of both server and client sockets. The
 * only difference is that the passiveSocket flag must be passed either to
 * the constructor or to setSocketFlags(). If passiveSocket is used, the class will
 * enable functions listen() and accept() and related signals, and will
 * also disable readBlock() and writeBlock().
 *
 * To create a Unix socket, one would pass flag unixSocket to the constructor
 * or setSocketFlags(). The hostname and service/port can be set to whatever is
 * necessary. If no hostname is given, but a service/port is, the socket created
 * will be implementation dependant (usually in /tmp). In any other case, the
 * fields will be concatenated.
 *
 * To create an Internet socket, inetSocket flag can be used. If, on the other
 * hand a specific IP protocol is desired, ipv4Socket and/or ipv6Socket can be
 * used.
 *
 * Note that the socket type selection flags are cumulative. One could select
 * Unix and Internet sockets by using unixSocket | inetSocket. Or, for instance,
 * to make sure only IPv4 and IPv6 sockets are selected, even if future implementations
 * support newer IP protocols, ipv4Socket | ipv6Socket is your guy.
 *
 * @deprecated
 *	This class is now deprecated. Please use the classes in KNetwork for
 *	new programs. In particular, this class is replaced by KNetwork::KStreamSocket
 *	and @ref KNetwork::KServerSocket.
 *
 * @author Thiago Macieira <[e-mail]>
 * @short an extended socket
 */
class KDECORE_EXPORT KExtendedSocket: public KBufferedIO // public QObject, public QIODevice
{
  Q_OBJECT

public:
  /**
   * flags that can be passed down to the member functions
   */
  enum Flags
  {
    /* socket address families */
    /*
     * NOTE: if you change this, you have to change function valid_socket() as well
     * These values are hard coded!
     */
    anySocket = 0x00,
    knownSocket = 0x01,
    unixSocket = knownSocket | 0x02,
    inetSocket = knownSocket | 0x04,
    ipv4Socket = inetSocket | 0x100,
    ipv6Socket = inetSocket | 0x200,

    passiveSocket = 0x1000,	/* passive socket (i.e., one that accepts connections) */
    canonName = 0x2000,		/* request that the canon name be found */
    noResolve = 0x4000,		/* do not attempt to resolve, treat as numeric host */

    streamSocket = 0x8000,	/* request a streaming socket (e.g., TCP) */
    datagramSocket = 0x10000,	/* request a datagram socket (e.g., UDP) */
    rawSocket = 0x20000,	/* request a raw socket. This probably requires privileges */

    inputBufferedSocket = 0x200000, /* buffer input in this socket */
    outputBufferedSocket = 0x400000, /* buffer output in this socket */
    bufferedSocket = 0x600000	/* make this a fully buffered socket */
  };

  /**
   * status of the class
   * The status are sequential. If a change to one status is requested,
   * all the prior status will be passed and their actions, performed
   */
  enum SockStatus
  {
    // the numbers are scattered so that we leave room for future expansion
    error = -1,			// invalid status!

    nothing = 0,		// no status, the class has just been created

    lookupInProgress = 50,	// lookup is in progress. Signals will be sent
    lookupDone = 70,		// lookup has been done. Flags cannot be changed
				// from this point on

    created = 100,		// ::socket() has been called, a socket exists
    bound = 140,		// socket has been bound

    connecting = 200,		// socket is connecting (not passiveSocket)
    connected = 220,		// socket has connected (not passiveSocket)

    listening = 200,		// socket is listening (passiveSocket)
    accepting = 220,		// socket is accepting (passiveSocket)

    closing = 350,		// socket is closing (delayed close)

    done = 400			// socket has been closed
  };

public:
  /**
   * Creates an empty KExtendedSocket.
   */
  KExtendedSocket();

  /**
   * Creates a socket with the given hostname and port.
   *
   * If this is a connecting (active) socket, the hostname and port specify
   * the remote address to which we will connect.
   *
   * If this is a listening (passive) socket, the hostname and port specify
   * the address to listen on. In order to listen on every interface
   * available on this node, set @p host to QString::null. To let the operating
   * system select a port, set it to 0.
   *
   * @sa setAddress
   * @param host	the hostname
   * @param port	the port number
   * @param flags	flags
   */
  KExtendedSocket(const QString& host, int port, int flags = 0);

  /**
   * Creates a socket with the given hostname and service.
   *
   * If this is a connecting (active) socket, the hostname and service specify
   * the remote address to which we will connect.
   *
   * If this is a listening (passive) socket, the hostname and service specify
   * the address to listen on. In order to listen on every interface
   * available on this node, set @p host to QString::null. To let the operating
   * system select a port, set the service to "0".
   *
   * @sa setAddress
   * @param host	the hostname
   * @param service	the service
   * @param flags	flags
   */
  KExtendedSocket(const QString& host, const QString& service, int flags = 0);

  /**
   * Destroys the socket, disconnecting if still connected and
   * freeing any related resources still being kept.
   */
  virtual ~KExtendedSocket();

  /**
   * Resets the socket, disconnecting if still connected and
   * freeing any related resources still being kept.
   * @since 3.1
   */
  void reset();

  /*
   * --- status, flags and internal variables --- *
   */

  /**
   * Returns the class status.
   * @return the class status
   * @see ::SockStatus
   */
  int socketStatus() const;

  /**
   * Returns the related system error code
   * Except for IO_LookupError errors, these are codes found in
   * errno
   * @return the system error code
   */
  int systemError() const;

  /**
   * Sets the given flags.
   * @param flags	the flags to be set
   * @return the new flags status, or -1 if flags can no longer be set
   */
  int setSocketFlags(int flags);

  /**
   * Returns the current flags
   * @return the current flags
   * @see ::Flags
   */
  int socketFlags() const;

  /**
   * Sets the hostname to the given value. 
   *
   * If this is a listening (passive) socket, the hostname is the host to which the socket
   * will bind in order to listen. If you want to listen in every interface, set it
   * to "*" or QString::null.
   *
   * If this is a connecting (active) socket, the hostname is the host to which we will try
   * to connect.
   *
   * @param host	the hostname
   * @return true on success, false on error
   */
  bool setHost(const QString& host);

  /**
   * Returns the hostname.
   * @return the hostname or QString::null if no host has been set
   */
  QString host() const;

  /**
   * Sets the port/service.
   * @param port	the port
   */
  bool setPort(int port);

  /**
   * Sets the port/service.
   *
   * In the case of Unix-domain sockets, the port is the filename for the socket.
   * If the name is not an absolute path, "/tmp/" will be prepended.
   *
   * @param port	the port
   * @return true if successful, false on error (e.g. connection already established)
   */
  bool setPort(const QString& port);

  /**
   * Returns the port/service. If it is a port, the string contains a number.
   * @return the port or QString::null if it has not been set.
   */
  QString port() const;

  /**
   * Sets the address where we will connect to.
   *
   * See @ref setHost and @ref setPort for information on the parameters.
   *
   * @param host	the hostname
   * @param port	port number
   * @return true if successful, false on error (e.g. connection already established)
   */
  bool setAddress(const QString& host, int port);

  /**
   * Sets the address where we will connect to.
   *
   * See @ref setHost and @ref setPort for information on the parameters.
   *
   * @param host	the hostname
   * @param serv	the service
   * @return true if successful, false on error (e.g. connection already established)
   */
  bool setAddress(const QString& host, const QString& serv);

  /**
   * Sets the hostname to which we will bind locally before connecting.
   * @param host	the hostname
   * @return false if this is a passiveSocket, otherwise true.
   */
  bool setBindHost(const QString& host);

  /**
   * Unsets the bind hostname. That is, don't request a binding host.
   * @return true if successful, false on error (e.g. connection already established)
   */
  bool unsetBindHost();

  /**
   * Returns the hostname to which the socket will be/is bound.
   * @return the host or QString::null if it has not been set.
   */
  QString bindHost() const;

  /**
   * Sets the port/service to which we will bind before connecting
   * @param port	the port number
   * @return true if successful, false on error (e.g. connection already established)
   */
  bool setBindPort(int port);

  /**
   * Sets the port/service to which we will bind before connecting.
   * @param service	the port number or service name
   * @return true if successful, false on error (e.g. connection already established)
   */
  bool setBindPort(const QString& service);

  /**
   * Unsets the bind port/service.
   * @return true if successful, false on error (e.g. connection already established)
   */
  bool unsetBindPort();

  /**
   * Returns the service to which the socket will be/is bound.
   * @return the host or QString::null if it has not been set.
   */
  QString bindPort() const;

  /**
   * Sets both host and port to which we will bind the socket. Will return
   * false if this is a passiveSocket.
   * @param host	the hostname
   * @param port	the port number
   * @return true if successful, false on error (e.g. connection already established)
   */
  bool setBindAddress(const QString& host, int port);

  /**
   * Sets both host and service to which we will bind the socket. Will return
   * false if this is a passiveSocket.
   * @param host	the hostname
   * @param service	the service
   * @return true if successful, false on error (e.g. connection already established)
   */
  bool setBindAddress(const QString& host, const QString& service);