tdelibs/kdecore/network/ksocketbase.h

/*  -*- C++ -*-
 *  Copyright (C) 2003,2005 Thiago Macieira <thiago.macieira@kdemail.net>
 *
 *
 *  Permission is hereby granted, free of charge, to any person obtaining
 *  a copy of this software and associated documentation files (the
 *  "Software"), to deal in the Software without restriction, including
 *  without limitation the rights to use, copy, modify, merge, publish,
 *  distribute, sublicense, and/or sell copies of the Software, and to
 *  permit persons to whom the Software is furnished to do so, subject to
 *  the following conditions:
 *
 *  The above copyright notice and this permission notice shall be included 
 *  in all copies or substantial portions of the Software.
 *
 *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 *  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 *  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 *  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
 *  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
 *  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 *  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */

/*
 * Even before our #ifdef, clean up the namespace
 */
#ifdef socket
#undef socket
#endif

#ifdef bind
#undef bind
#endif

#ifdef listen
#undef listen
#endif

#ifdef connect
#undef connect
#endif

#ifdef accept
#undef accept
#endif

#ifdef getpeername
#undef getpeername
#endif

#ifdef getsockname
#undef getsockname
#endif

#ifndef KSOCKETBASE_H
#define KSOCKETBASE_H

#include <tqiodevice.h>
#include <tqstring.h>

#include "ksocketaddress.h"
#include <kdelibs_export.h>

/*
 * This is extending QIODevice's error codes
 *
 * According to tqiodevice.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)
#define IO_SocketCreateError	(IO_UnspecifiedError+4)
#define IO_BindError		(IO_UnspecifiedError+5)

class TQMutex;

namespace KNetwork {

class KResolverEntry;
class KSocketDevice;

class KSocketBasePrivate;
/** @class KSocketBase ksocketbase.h ksocketbase.h
 *  @brief Basic socket functionality.
 *
 * This class provides the basic socket functionlity for descended classes.
 * Socket classes are thread-safe and provide a recursive mutex should it be 
 * needed.
 *
 * @note This class is abstract.
 *
 * @author Thiago Macieira <thiago.macieira@kdemail.net>
 */
class KDECORE_EXPORT KSocketBase
{
public:
  /**
   * Possible socket options.
   *
   * These are the options that may be set on a socket:
   *  - Blocking: whether the socket shall operate in blocking
   *    or non-blocking mode. This flag defaults to on.
   *    See @ref setBlocking.
   *  - AddressReusable: whether the address used by this socket will
   *    be available for reuse by other sockets. This flag defaults to off.
   *    See @ref setAddressReuseable.
   *  - IPv6Only: whether an IPv6 socket will accept IPv4 connections
   *    through a mapped address. This flag defaults to off.
   *    See @ref setIPv6Only.
   *  - KeepAlive: whether TCP should send keepalive probes when a connection
   *    has gone idle for far too long.
   *  - Broadcast: whether this socket is allowed to send broadcast packets
   *    and will receive packets sent to broadcast.
   */
  enum SocketOptions
    {
      Blocking = 0x01,
      AddressReuseable = 0x02,
      IPv6Only = 0x04,
      Keepalive = 0x08,
      Broadcast = 0x10
    };

  /**
   * Possible socket error codes.
   *
   * This is a list of possible error conditions that socket classes may
   * be expected to find.
   *
   * - NoError: no error has been detected
   * - LookupFailure: if a name lookup has failed
   * - AddressInUse: address is already in use
   * - AlreadyBound: cannot bind again
   * - AlreadyCreated: cannot recreate the socket
   * - NotBound: operation required socket to be bound and it isn't
   * - NotCreated: operation required socket to exist and it doesn't
   * - WouldBlock: requested I/O operation would block
   * - ConnectionRefused: connection actively refused
   * - ConnectionTimedOut: connection timed out
   * - InProgress: operation (connection) is already in progress
   * - NetFailure: a network failure occurred (no route, host down, host unreachable or similar)
   * - NotSupported: requested operation is not supported
   * - Timeout: a timed operation timed out
   * - UnknownError: an unknown/unexpected error has happened
   * - RemotelyDisconnected: when a connection is disconnected by the other end (since 3.4)
   *
   * @sa error, errorString
   */
  enum SocketError
    {
      NoError = 0,
      LookupFailure,
      AddressInUse,
      AlreadyCreated,
      AlreadyBound,
      AlreadyConnected,
      NotConnected,
      NotBound,
      NotCreated,
      WouldBlock,
      ConnectionRefused,
      ConnectionTimedOut,
      InProgress,
      NetFailure,
      NotSupported,
      Timeout,
      UnknownError,
      RemotelyDisconnected
    };

public:
  /**
   * Default constructor.
   */
  KSocketBase();

  /**
   * Destructor.
   */
  virtual ~KSocketBase();

  /*
   * The following functions are shared by all descended classes and will have
   * to be reimplemented.
   */

protected:
  /**
   * Set the given socket options.
   *
   * The default implementation does nothing but store the mask internally.
   * Descended classes must override this function to achieve functionality and
   * must also call this implementation.
   *
   * @param opts	a mask of @ref SocketOptions or-ed bits of options to set
   *			or unset
   * @returns true on success
   * @note this function sets the options corresponding to the bits enabled in @p opts
   *       but will also unset the optiosn corresponding to the bits not set.
   */
  virtual bool setSocketOptions(int opts);

  /**
   * Retrieves the socket options that have been set.
   *
   * The default implementation just retrieves the mask from an internal variable.
   * Descended classes may choose to override this function to read the values
   * from the operating system.
   *
   * @returns the mask of the options set
   */
  virtual int socketOptions() const;

public:
  /**
   * Sets this socket's blocking mode.
   *
   * In blocking operation, all I/O functions are susceptible to blocking --
   * i.e., will not return unless the I/O can be satisfied. In non-blocking
   * operation, if the I/O would block, the function will return an error
   * and set the corresponding error code.
   *
   * The default implementation toggles the Blocking flag with the current
   * socket options and calls @ref setSocketOptions.
   *
   * @param enable		whether to set this socket to blocking mode
   * @returns whether setting this value was successful; it is NOT the 
   *          final blocking mode.
   */
  virtual bool setBlocking(bool enable);

  /**
   * Retrieves this socket's blocking mode.
   *
   * @returns true if this socket is/will be operated in blocking mode,
   *          false if non-blocking.
   */
  bool blocking() const;

  /**
   * Sets this socket's address reuseable flag.
   *
   * When the address reuseable flag is active, the address used by
   * this socket is left reuseable for other sockets to bind. If
   * the flag is not active, no other sockets may reuse the same
   * address.
   *
   * The default implementation toggles the AddressReuseable flag with the current
   * socket options and calls @ref setSocketOptions.
   *
   * @param enable		whether to set the flag on or off
   * @returns true if setting this flag was successful
   */
  virtual bool setAddressReuseable(bool enable);

  /**
   * Retrieves this socket's address reuseability flag.
   *
   * @returns true if this socket's address can be reused,
   *          false if it can't.
   */
  bool addressReuseable() const;

  /**
   * Sets this socket's IPv6 Only flag.
   *
   * When this flag is on, an IPv6 socket will only accept, connect, send to or
   * receive from IPv6 addresses. When it is off, it will also talk to
   * IPv4 addresses through v4-mapped addresses.
   *
   * This option has no effect on non-IPv6 sockets.
   *
   * The default implementation toggles the IPv6Only flag with the current
   * socket options and calls @ref setSocketOptions.
   *
   * @param enable		whether to set the flag on or off
   * @returns true if setting this flag was successful
   */
  virtual bool setIPv6Only(bool enable);

  /**
   * Retrieves this socket's IPv6 Only flag.
   *
   * @returns true if this socket will ignore IPv4-compatible and IPv4-mapped
   *	      addresses, false if it will accept them.
   */
  bool isIPv6Only() const;

  /**
   * Sets this socket Broadcast flag.
   *
   * Datagram-oriented sockets cannot normally send packets to broadcast
   * addresses, nor will they receive packets that were sent to a broadcast
   * address. To do so, you need to enable the Broadcast flag.
   *
   * This option has no effect on stream-oriented sockets.
   *
   * @returns true if setting this flag was successful.
   */
  virtual bool setBroadcast(bool enable);

  /**
   * Retrieves this socket's Broadcast flag.
   *
   * @returns true if this socket can send and receive broadcast packets,
   *          false if it can't.
   */
  bool broadcast() const;

  /**
   * Retrieves the socket implementation used on this socket.
   *
   * This function creates the device if none has been set
   * using the default factory.
   */
  KSocketDevice* socketDevice() const;

  /**
   * Sets the socket implementation to be used on this socket.
   *
   * Note: it is an error to set this if the socket device has
   * already been set once.
   *
   * This function is provided virtual so that derived classes can catch
   * the setting of a device and properly set their own states and internal
   * variables. The parent class must be called.
   *
   * This function is called by @ref socketDevice above when the socket is
   * first created.
   */
  virtual void setSocketDevice(KSocketDevice* device);

  /**
   * Sets the internally requested capabilities for a socket device.
   *
   * Most socket classes can use any back-end implementation. However, a few
   * may require specific capabilities not provided in the default
   * implementation. By using this function, derived classes can request
   * that a backend with those capabilities be created when necessary.
   *
   * For the possible flags, see @ref KSocketDevice::Capabilities. However, note
   * that only the Can* flags make sense in this context.
   *
   * @note Since socketDevice must always return a valid backend object, it
   *       is is possible that the created device does not conform to all
   *       requirements requested. Implementations sensitive to this fact
   *       should test the object returned by @ref socketDevice (through
   *       @ref KSocketDevice::capabilities, for instance) the availability.
   *
   * @param add		mask of @ref KSocketDevice::Capabilities to add
   * @param remove	mask of bits to remove from the requirements
   * @return the current mask of requested capabilities
   */
  int setRequestedCapabilities(int add, int remove = 0);

protected:
  /**
   * Returns true if the socket device has been initialised in this
   * object, either by calling @ref socketDevice() or @ref setSocketDevice
   */
  bool hasDevice() const;

  /**
   * Sets the socket's error code.
   *
   * @param error		the error code
   */
  void setError(SocketError error);

public:
  /**
   * Retrieves the socket error code.
   * @sa errorString
   */
  SocketError error() const;

  /**
   * Returns the error string corresponding to this error condition.
   */
  inline TQString errorString() const
  { return errorString(error()); }

  /**
   * Returns the internal mutex for this class.
   *
   * Note on multithreaded use of sockets:
   * the socket classes are thread-safe by design, but you should be aware of
   * problems regarding socket creation, connection and destruction in
   * multi-threaded programs. The classes are guaranteed to work while
   * the socket exists, but it's not wise to call connect in multiple
   * threads. 
   *
   * Also, this mutex must be unlocked before the object is destroyed, which
   * means you cannot use it to guard against other threads accessing the object
   * while destroying it. You must ensure there are no further references to this
   * object when deleting it.
   */
  TQMutex* mutex() const;

public:
  /**
   * Returns the string describing the given error code, i18n'ed.
   *
   * @param code		the error code
   */
  static TQString errorString(SocketError code);

  /**
   * Returns true if the given error code is a fatal one, false
   * otherwise. The parameter here is of type int so that
   * casting isn't necessary when using the parameter to signal
   * QClientSocketBase::gotError.
   *
   * @param code		the code to test
   */
  static bool isFatalError(int code);

private:
  /// @internal
  /// called by KSocketDevice
  void unsetSocketDevice();

  KSocketBase(const KSocketBase&);
  KSocketBase& operator =(const KSocketBase&);

  KSocketBasePrivate *d;

  friend class KSocketDevice;
};

/**
 * @class KActiveSocketBase ksocketbase.h ksocketbase.h
 * @brief Abstract class for active sockets
 *
 * This class provides the standard interfaces for active sockets, i.e.,
 * sockets that are used to connect to external addresses.
 *
 * @author Thiago Macieira <thiago.macieira@kdemail.net>
 */
class KDECORE_EXPORT KActiveSocketBase: public TQIODevice, virtual public KSocketBase
{
public:
  /**
   * Constructor.
   */
  KActiveSocketBase();

  /**
   * Destructor.
   */
  virtual ~KActiveSocketBase();

  /**
   * Binds this socket to the given address.
   *
   * The socket will be constructed with the address family,
   * socket type and protocol as those given in the
   * @p address object.
   *
   * @param address		the address to bind to
   * @returns true if the binding was successful, false otherwise
   */
  virtual bool bind(const KResolverEntry& address) = 0;

  /**
   * Connect to a remote host.
   *
   * This will make this socket try to connect to the remote host.
   * If the socket is not yet created, it will be created using the
   * address family, socket type and protocol specified in the
   * @p address object.
   *
   * If this function returns with error InProgress, calling it
   * again with the same address after a time will cause it to test
   * if the connection has succeeded in the mean time.
   *
   * @param address		the address to connect to
   * @returns true if the connection was successful or has been successfully
   *          queued; false if an error occurred.
   */
  virtual bool connect(const KResolverEntry& address) = 0;

  /**
   * Disconnects this socket from a connection, if possible.
   *
   * If this socket was connected to an endpoint, the connection
   * is severed, but the socket is not closed. If the socket wasn't
   * connected, this function does nothing.
   *
   * If the socket hadn't yet been created, this function does nothing
   * either.
   *
   * Not all socket types can disconnect. Most notably, only
   * connectionless datagram protocols such as UDP support this operation.
   *
   * @return true if the socket is now disconnected or false on error.
   */
  virtual bool disconnect() = 0;

  /**
   * This call is not supported on sockets. Reimplemented from TQIODevice.
   * This will always return 0.
   */
#ifdef USE_QT4
  virtual qint64 size() const
#else // USE_QT4
  virtual Offset size() const
#endif // USE_QT4
  { return 0; }

  /**
   * This call is not supported on sockets. Reimplemented from TQIODevice.
   * This will always return 0.
   */
  virtual Offset at() const
  { return 0; }

  /**
   * This call is not supported on sockets. Reimplemented from TQIODevice.
   * This will always return false.
   */
  virtual bool at(Offset)
  { return false; }

  /**
   * This call is not supported on sockets. Reimplemented from TQIODevice.
   * This will always return true.
   */
  virtual bool atEnd() const
  { return true; }

  /**
   * Returns the number of bytes available for reading without
   * blocking.
   */
#ifdef USE_QT3
  virtual TQ_LONG bytesAvailable() const = 0;
#endif
#ifdef USE_QT4
  virtual qint64 bytesAvailable() const = 0;
#endif

  /**
   * Waits up to @p msecs for more data to be available on this socket.
   *
   * If msecs is -1, this call will block indefinetely until more data
   * is indeed available; if it's 0, this function returns immediately.
   *
   * If @p timeout is not NULL, this function will set it to indicate
   * if a timeout occurred.
   *
   * @returns the number of bytes available
   */
  virtual TQ_LONG waitForMore(int msecs, bool *timeout = 0L) = 0;

  /**
   * Reads data from the socket.
   *
   * Reimplemented from TQIODevice. See TQIODevice::readBlock for
   * more information.
   */
  virtual TQT_TQIO_LONG tqreadBlock(char *data, TQT_TQIO_ULONG len) = 0;

  /** @overload
   * Receives data and the source address.
   *
   * This call will read data in the socket and will also
   * place the sender's address in @p from object.
   *
   * @param data		where to write the read data to
   * @param maxlen		the maximum number of bytes to read
   * @param from		the address of the sender will be stored here
   * @returns the actual number of bytes read
   */
  virtual TQT_TQIO_LONG tqreadBlock(char *data, TQT_TQIO_ULONG maxlen, KSocketAddress& from) = 0;

  /**
   * Peeks the data in the socket.
   *
   * This call will allow you to peek the data to be received without actually
   * receiving it -- that is, it will be available for further peekings and
   * for the next read call.
   *
   * @param data		where to write the peeked data to
   * @param maxlen		the maximum number of bytes to peek
   * @returns the actual number of bytes copied into @p data
   */
  virtual TQ_LONG peekBlock(char *data, TQ_ULONG maxlen) = 0;

  /** @overload
   * Peeks the data in the socket and the source address.
   *
   * This call will allow you to peek the data to be received without actually
   * receiving it -- that is, it will be available for further peekings and
   * for the next read call.
   *
   * @param data		where to write the peeked data to
   * @param maxlen		the maximum number of bytes to peek
   * @param from		the address of the sender will be stored here
   * @returns the actual number of bytes copied into @p data
   */
  virtual TQ_LONG peekBlock(char *data, TQ_ULONG maxlen, KSocketAddress& from) = 0;

  /**
   * Writes the given data to the socket.
   *
   * Reimplemented from TQIODevice. See TQIODevice::writeBlock for
   * more information.
   */
  virtual TQT_TQIO_LONG tqwriteBlock(const char *data, TQT_TQIO_ULONG len) = 0;

  /** @overload
   * Writes the given data to the destination address.
   *
   * Note that not all socket connections allow sending data to different
   * addresses than the one the socket is connected to.
   *
   * @param data		the data to write
   * @param len			the length of the data
   * @param to			the address to send to
   * @returns the number of bytes actually sent
   */
  virtual TQT_TQIO_LONG tqwriteBlock(const char *data, TQT_TQIO_ULONG len, const KSocketAddress& to) = 0;

  /**
   * Reads one character from the socket.
   * Reimplementation from TQIODevice. See TQIODevice::getch for more information.
   */
  virtual int getch();

  /**
   * Writes one character to the socket.
   * Reimplementation from TQIODevice. See TQIODevice::putch for more information.
   */
  virtual int putch(int ch);

  /**
   * This call is not supported on sockets. Reimplemented from TQIODevice.
   * This will always return -1;
   */
  virtual int ungetch(int)
  { return -1; }

  /**
   * Returns this socket's local address.
   */
  virtual KSocketAddress localAddress() const = 0;

  /**
   * Return this socket's peer address, if we are connected.
   * If the address cannot be retrieved, the returned object will contain
   * an invalid address.
   */
  virtual KSocketAddress peerAddress() const = 0;

  // FIXME KDE 4.0:
  // enable this function
#if 0
  /**
   * Returns this socket's externally-visible address, if known.
   */
  virtual KSocketAddress externalAddress() const = 0;
#endif

protected:
  /**
   * Sets the socket's error code and the I/O Device's status.
   *
   * @param status		the I/O Device status
   * @param error		the error code
   */
  void setError(int status, SocketError error);

  /**
   * Resets the socket error code and the I/O Device's status.
   */
  void resetError();
};

/**
 * @class KPassiveSocketBase ksocketbase.h ksocketbase.h
 * @brief Abstract base class for passive sockets.
 *
 * This socket provides the initial functionality for passive sockets,
 * i.e., sockets that accept incoming connections.
 *
 * @author Thiago Macieira <thiago.macieira@kdemail.net>
 */
class KDECORE_EXPORT KPassiveSocketBase: virtual public KSocketBase
{
public:
  /**
   * Constructor
   */
  KPassiveSocketBase();

  /**
   * Destructor
   */
  virtual ~KPassiveSocketBase();

  /**
   * Binds this socket to the given address.
   *
   * The socket will be constructed with the address family,
   * socket type and protocol as those given in the
   * @p address object.
   *
   * @param address		the address to bind to
   * @returns true if the binding was successful, false otherwise
   */
  virtual bool bind(const KResolverEntry& address) = 0;

  /**
   * Puts this socket into listening mode.
   *
   * Placing a socket in listening mode means that it will
   * be allowed to receive incoming connections from
   * remote hosts.
   *
   * Note that some socket types or protocols cannot be
   * put in listening mode.
   *
   * @param backlog		the number of accepted connections to
   *				hold before starting to refuse
   * @returns true if the socket is now in listening mode
   */
  virtual bool listen(int backlog) = 0;

  /**
   * Closes this socket. All resources used are freed. Note that closing
   * a passive socket does not close the connections accepted with it.
   */
  virtual void close() = 0;

  /**
   * Accepts a new incoming connection.
   *
   * If this socket was in listening mode, you can call this
   * function to accept an incoming connection.
   *
   * If this function cannot accept a new connection (either
   * because it is not listening for one or because the operation
   * would block), it will return NULL.
   *
   * Also note that descended classes will override this function
   * to return specialised socket classes.
   */
  virtual KActiveSocketBase* accept() = 0;

  /**
   * Returns this socket's local address.
   */
  virtual KSocketAddress localAddress() const = 0;

  /**
   * Returns this socket's externally-visible address if known.
   */
  virtual KSocketAddress externalAddress() const = 0;

private:
  KPassiveSocketBase(const KPassiveSocketBase&);
  KPassiveSocketBase& operator = (const KPassiveSocketBase&);
};

}				// namespace KNetwork

#endif