kextsock.h

来自「将konqueror浏览器移植到ARM9 2410中」· C头文件 代码 · 共 820 行 · 第 1/2 页

/*
 *  This file is part of the KDE libraries
 *  Copyright (C) 2000,2001 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., 59 Temple Place - Suite 330,
 *  Boston, MA 02111-1307, USA.
 */
#ifndef KEXTSOCK_H
#define KEXTSOCK_H

#include <sys/time.h>

#include <qobject.h>
#include <qstring.h>
#include <qlist.h>
#include <qiodevice.h>
#include <qsocketnotifier.h>

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

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

/*
 * 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)

/**
 * The extended socket class.
 *
 * This class should be used instead of @ref 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 @ref setSocketFlags(). If passiveSocket is used, the class will
 * enable functions @ref listen() and @ref accept() and related signals, and will
 * also disable @ref readBlock() and @ref writeBlock().
 *
 * To create a Unix socket, one would pass flag unixSocket to the constructor
 * or @ref 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.
 *
 * @author Thiago Macieira <[e-mail]>
 * @version $Id: kextsock.h,v 1.6.2.1 2001/10/24 19:43:45 waba Exp $
 * @short an extended socket
 */
class 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 = 4,	// lookup is in progress. Signals will be sent
    lookupDone = 5,		// lookup has been done. Flags cannot be changed
				// from this point on

    created = 10,		// ::socket() has been called, a socket exists
    bound = 11,			// socket has been bound

    connecting = 20,		// socket is connecting (not passiveSocket)
    connected = 21,		// socket has connected (not passiveSocket)

    listening = 20,		// socket is listening (passiveSocket)
    accepting = 21,		// socket is accepting (passiveSocket)

    closing = 35,		// socket is closing (delayed close)
    
    done = 40			// socket has been closed
  };

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

  /**
   * Creates a socket with the given hostname and port
   * @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
   * @param host	the hostname
   * @param serv	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();

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

  /**
   * Returns the class status
   */
  inline int socketStatus() const
  { return m_status; }

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

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

  /**
   * Returns the current flags
   */
  inline int socketFlags() const
  { return m_flags; }

  /**
   * Sets the hostname to the given value
   * Returns true on success, false on error
   * @param host	the hostname
   */
  bool setHost(const QString& host);

  /**
   * Returns the hostname
   */
  QString host() const;

  /**
   * Sets the port/service
   * @param port	the port
   */
  bool setPort(int port);
  bool setPort(const QString& service);

  /**
   * Returns the port/service
   */
  QString port() const;

  /**
   * Sets the address where we will connect to
   * @param host	the hostname
   * @param port	port number
   */
  bool setAddress(const QString& host, int port);

  /**
   * Sets the address where we will connect to
   * @param host	the hostname
   * @param serv	the service
   */
  bool setAddress(const QString& host, const QString& serv);

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

  /**
   * Unsets the bind hostname. That is, don't request a binding host.
   */
  bool unsetBindHost();

  /**
   * Returns the hostname to which the socket will be/is bound
   */
  inline QString bindHost() const;

  /**
   * Sets the port/service to which we will bind before connecting
   * @param port	the port number
   */
  bool setBindPort(int port);
  bool setBindPort(const QString& service);

  /**
   * Unsets the bind port/service.
   */
  bool unsetBindPort();

  /**
   * Returns the service to which the socket will be/is bound.
   */
  QString bindPort() const;

  /**
   * Sets both host and port to which we will bind the socket. Will return
   * -1 if this is a passiveSocket
   * @param host	the hostname
   * @param port	the port number
   */
  bool setBindAddress(const QString& host, int port);

  /**
   * Sets both host and service to which we will bind the socket. Will return
   * -1 if this is a passiveSocket
   * @param host	the hostname
   * @param serv	the service
   */
  bool setBindAddress(const QString& host, const QString& service);

  /**
   * Unsets the bind address for the socket. That means that we won't
   * attempt to bind to an address before connecting
   */
  bool unsetBindAddress();

  /**
   * Sets the timeout value for the connection, if this is not passiveSocket, or
   * acception, if this is a passiveSocket. In the event the given function
   * (connect or accept) returns due to time out, it's possible to call it again.
   * Setting the timeout to 0 disables the timeout feature.
   * Returns false if setting timeout makes no sense in the context.
   * @param secs	the timeout length, in seconds
   * @param usecs	the timeout complement, in microseconds
   */
  bool setTimeout(int secs, int usecs = 0);

  /**
   * Returns the timeout value for the connection
   */
  timeval timeout() const;

  /**
   * Sets/unsets blocking mode for the socket. When non-blocking mode is enabled,
   * I/O operations might return error and set errno to EWOULDBLOCK. Also,
   * it's not recommended to use this when using signals. Returns false on
   * error.
   * @param enable	if true, set blocking mode. False, non-blocking mode.
   */
  bool setBlockingMode(bool enable);

  /**
   * Returns the current blocking mode for this socket
   */
  bool blockingMode();

  /**
   * Sets/unsets address reusing flag for this socket.
   * This function returns true if the value was set correctly. That is NOT
   * the result of the set.
   * @param enable	if true, set address reusable
   */
  bool setAddressReusable(bool enable);

  /**
   * Returns whether this socket can be reused
   */
  bool addressReusable();

  /**
   * Sets the buffer sizes for this socket.
   *
   * This implementation allows any size for both parameters. The value given
   * will be interpreted as the maximum size allowed for the buffers, after
   * which the functions will stop buffering. The value of -1 will be
   * interpreted as "unlimited" size.
   *
   * Note: changing the buffer size to 0 for any buffer will cause the given
   * buffer's to be discarded. Likewise, setting the size to a value less than
   * the current size will cause the buffer to be shrunk to the wanted value,
   * as if the data had been read.
   *
   * Note 2: if we are not doing input buffering, the #ref closed signal will
   * not be emitted for remote connection closing. That happens because we aren't
   * reading from the connection, so we don't know when it closed.
   * @param rsize	read buffer size
   * @param wsize	write buffer size
   */
  virtual bool setBufferSize(int rsize, int wsize = -2);

  /**
   * Returns the local socket address
   */
  const KSocketAddress *localAddress();

  /**
   * Returns the peer socket address. Use KExtendedSocket::resolve() to
   * resolve this to a human-readable hostname/service or port.
   */
  const KSocketAddress *peerAddress();

  /**
   * Returns the file descriptor
   */
  inline int fd() const
  { return sockfd; }

  /*
   * -- socket creation -- *
   */

  /**
   * Performs lookup on the addresses we were given before
   * Returns 0 or an error. Codes are the same as for <em>getaddrinfo</em>
   * This will perform lookups on the bind addresses if they were given
   */
  virtual int lookup();

  /**
   * Starts an asynchronous lookup for the addresses given
   * This function returns 0 on success or -1 on error. Note that
   * returning 0 means that either we are in the process of doing
   * lookup or that it has finished already.
   * When the lookup is done, the lookupReady signal will be emitted.
   * Note that, depending on the parameters for the lookup, this function might
   * know the results without the need for blocking or queueing an
   * asynchronous lookup. That means that the lookupReady signal might be
   * emitted by this function, so your code should be prepared for that.
   * One such case is when noResolve flag is set.
   * If this function were able to determine the results without queueing
   * and we found an error during lookup, this function will return -1.
   */
  virtual int startAsyncLookup();

  /**
   * Cancels any on-going asynchronous lookups