Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdelibs@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 428 insertions, 0 deletions

diff --git a/kdecore/network/ksocketdevice.h b/kdecore/network/ksocketdevice.h
new file mode 100644
index 000000000..301bc2b07
--- /dev/null
+++ b/kdecore/network/ksocketdevice.h
@@ -0,0 +1,428 @@
+/*  -*- C++ -*-
+ *  Copyright (C) 2003 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.
+ */
+
+#ifndef KSOCKETDEVICE_H
+#define KSOCKETDEVICE_H
+
+#include <qsocketnotifier.h>
+#include "ksocketbase.h"
+
+namespace KNetwork {
+
+class KSocketDevice;
+class KSocketDeviceFactoryBase;
+
+class KSocketDevicePrivate;
+/** @class KSocketDevice ksocketdevice.h ksocketdevice.h
+ *  @brief Low-level socket functionality.
+ *
+ * This class provides low-level socket functionality. 
+ *
+ * Most users will prefer "cooked" interfaces like those of @ref KStreamSocket or
+ * @ref KServerSocket.
+ *
+ * Descended classes from this one provide some other kinds of socket functionality,
+ * like proxying or specific socket types.
+ *
+ * @author Thiago Macieira <thiago.macieira@kdemail.net>
+ */
+class KDECORE_EXPORT KSocketDevice: public KActiveSocketBase, public KPassiveSocketBase
+{
+public:
+  /**
+   * Capabilities for the socket implementation.
+   *
+   * KSocketDevice-derived classes can implement certain capabilities that are not
+   * available in the default class. These capabilities are described by these flags.
+   * The default KSocketDevice class has none of these capabilities.
+   *
+   * For the negative capabilities (inabilities, the CanNot* forms), when a capability 
+   * is not present, the implementation will default to the original behaviour.
+   */
+  enum Capabilities
+    {
+      /** Can connect to hostnames.
+       *  If this flag is present, the string form of @ref connect can be used. */
+      CanConnectString = 0x01,
+
+      /** Can bind to hostnames.
+       *  If this flag is present, the string form of @ref bind can be used */
+      CanBindString = 0x02,
+
+      /** Can not bind.
+       *  If this flag is present, this implementation cannot bind */
+      CanNotBind = 0x04,
+
+      /** Can not listen.
+       *  If this flag is present, this implementation cannot listen */
+      CanNotListen = 0x08,
+
+      /**
+       * Can send multicast as well as join/leave multicast groups.
+       */
+      CanMulticast = 0x10,
+
+      /**
+       * Can not use datagrams.
+       * Note that this implies multicast capability not being available either.
+       */
+      CanNotUseDatagrams = 0x20
+    };
+protected:
+  /// The socket file descriptor. It is used throughout the implementation
+  /// and subclasses.
+  int m_sockfd;
+
+public:
+  /**
+   * Default constructor.
+   *
+   * The parameter is used to specify which socket this object is used as
+   * a device for.
+   */
+  explicit KSocketDevice(const KSocketBase* = 0L);
+
+  /**
+   * Constructs a new object around an already-open socket.
+   *
+   * Note: you should write programs that create sockets through
+   * the classes whenever possible.
+   */
+  explicit KSocketDevice(int fd);
+
+  /**
+   * Destructor. This closes the socket if it's open.
+   */
+  virtual ~KSocketDevice();
+
+  /**
+   * Returns the file descriptor for this socket.
+   */
+  inline int socket() const
+  { return m_sockfd; }
+
+  /**
+   * Returns the set of capabilities this socket class implements.
+   * The set of capabilities is defined as an OR-ed mask of 
+   * @ref Capabilities bits.
+   *
+   * The default implementation is guaranteed to always return 0. That
+   * is, derived implementations always return bits where they differ
+   * from the system standard sockets.
+   */
+  virtual int capabilities() const
+  { return 0; }
+
+  /**
+   * This implementation sets the options on the socket.
+   */
+  virtual bool setSocketOptions(int opts);
+
+  /**
+   * Reimplementation from QIODevice. You should not call this function in sockets.
+   */
+  virtual bool open(int mode);
+
+  /**
+   * Closes the socket. Reimplemented from QIODevice.
+   *
+   * Use this function to close the socket this object is holding open.
+   */
+  virtual void close();
+
+  /**
+   * This call is not supported on sockets. Reimplemented from QIODevice.
+   */
+  virtual void flush()
+  { }
+
+  /**
+   * Creates a socket but don't connect or bind anywhere.
+   * This function is the equivalent of the system call socket(2).
+   */
+  virtual bool create(int family, int type, int protocol);
+
+  /**
+   * @overload
+   * Creates a socket but don't connect or bind anywhere.
+   */
+  bool create(const KResolverEntry& address);
+
+  /**
+   * Binds this socket to the given address.
+   */
+  virtual bool bind(const KResolverEntry& address);
+
+  /**
+   * Puts this socket into listening mode.
+   */
+  virtual bool listen(int backlog = 5);	// 5 is arbitrary
+
+  /**
+   * Connect to a remote host.
+   */
+  virtual bool connect(const KResolverEntry& address);
+
+  /**
+   * Accepts a new incoming connection.
+   * Note: this function returns a socket of type KSocketDevice.
+   */
+  virtual KSocketDevice* accept();
+
+  /**
+   * Disconnects this socket.
+   */
+  virtual bool disconnect();
+
+  /**
+   * Returns the number of bytes available for reading without blocking.
+   */
+  virtual Q_LONG bytesAvailable() const;
+
+  /**
+   * Waits up to @p msecs for more data to be available on this socket.
+   *
+   * This function is a wrapper against @ref poll. This function will wait
+   * for any read events.
+   */
+  virtual Q_LONG waitForMore(int msecs, bool *timeout = 0L);
+
+  /**
+   * Reads data from this socket.
+   */
+  virtual Q_LONG readBlock(char *data, Q_ULONG maxlen);
+
+  /**
+   * Reads data and the source address from this socket.
+   */
+  virtual Q_LONG readBlock(char *data, Q_ULONG maxlen, KSocketAddress& from);
+
+  /**
+   * Peeks data in the socket.
+   */
+  virtual Q_LONG peekBlock(char *data, Q_ULONG maxlen);
+
+  /**
+   * Peeks the data in the socket and the source address.
+   */
+  virtual Q_LONG peekBlock(char *data, Q_ULONG maxlen, KSocketAddress& from);
+
+  /**
+   * Writes data to the socket.
+   */
+  virtual Q_LONG writeBlock(const char *data, Q_ULONG len);
+
+  /**
+   * Writes the given data to the given destination address.
+   */
+  virtual Q_LONG writeBlock(const char *data, Q_ULONG len, const KSocketAddress& to);
+
+  /**
+   * Returns this socket's local address.
+   */
+  virtual KSocketAddress localAddress() const;
+
+  /**
+   * Returns this socket's peer address. If this implementation does proxying
+   * of some sort, this is the real external address, not the proxy's address.
+   */
+  virtual KSocketAddress peerAddress() const;
+
+  /**
+   * Returns this socket's externally visible local address.
+   *
+   * If this socket has a local address visible externally different
+   * from the normal local address (as returned by @ref localAddress), then
+   * return it.
+   *
+   * Certain implementations will use proxies and thus have externally visible
+   * addresses different from the local socket values. The default implementation
+   * returns the same value as @ref localAddress.
+   *
+   * @note This function may return an empty KSocketAddress. In that case, the
+   *       externally visible address could/can not be determined.
+   */
+  virtual KSocketAddress externalAddress() const;
+
+  /**
+   * Returns a socket notifier for input on this socket.
+   * The notifier is created only when requested. Whether
+   * it is enabled or not depends on the implementation.
+   *
+   * This function might return NULL.
+   */
+  QSocketNotifier* readNotifier() const;
+
+  /**
+   * Returns a socket notifier for output on this socket.
+   * The is created only when requested.
+   *
+   * This function might return NULL.
+   */
+  QSocketNotifier* writeNotifier() const;
+
+  /**
+   * Returns a socket notifier for exceptional events on this socket.
+   * The is created only when requested.
+   *
+   * This function might return NULL.
+   */
+  QSocketNotifier* exceptionNotifier() const;
+
+  /**
+   * Executes a poll in the socket, via select(2) or poll(2).
+   * The events polled are returned in the parameters pointers.
+   * Set any of them to NULL to disable polling of that event.
+   *
+   * On exit, @p input, @p output and @p exception will contain
+   * true if an event of that kind is waiting on the socket or false
+   * if not. If a timeout occurred, set @p timedout to true (all other
+   * parameters are necessarily set to false).
+   *
+   * @param input	if set, turns on polling for input events
+   * @param output	if set, turns on polling for output events
+   * @param exception	if set, turns on polling for exceptional events
+   * @param timeout	the time in milliseconds to wait for an event;
+   *			0 for no wait and any negative value to wait forever
+   * @param timedout	on exit, will contain true if the polling timed out
+   * @return true if the poll call succeeded and false if an error occurred
+   */
+  virtual bool poll(bool* input, bool* output, bool* exception = 0L,
+		    int timeout = -1, bool* timedout = 0L);
+
+  /**
+   * Shorter version to poll for any events in a socket. This call
+   * polls for input, output and exceptional events in a socket but
+   * does not return their states. This is useful if you need to wait for
+   * any event, but don't need to know which; or for timeouts.
+   *
+   * @param timeout	the time in milliseconds to wait for an event;
+   *			0 for no wait and any negative value to wait forever
+   * @param timedout	on exit, will contain true if the polling timed out
+   * @return true if the poll call succeeded and false if an error occurred
+   */
+  bool poll(int timeout = -1, bool* timedout = 0L);
+
+protected:
+  /**
+   * Special constructor. This constructor will cause the internal
+   * socket device NOT to be set. Use this if your socket device class
+   * takes another underlying socket device.
+   *
+   * @param parent	the parent, if any
+   */
+  KSocketDevice(bool, const KSocketBase* parent = 0L);
+
+  /**
+   * Creates a socket notifier of the given type.
+   *
+   * This function is called by @ref readNotifier, @ref writeNotifier and
+   * @ref exceptionNotifier when they need to create a socket notifier
+   * (i.e., the first call to those functions after the socket is open).
+   * After that call, those functions cache the socket notifier and will
+   * not need to call this function again.
+   *
+   * Reimplement this function in your derived class if your socket type
+   * requires a different kind of QSocketNotifier. The return value should
+   * be deleteable with delete. (@ref close deletes them).
+   *
+   * @param type	the socket notifier type
+   */
+  virtual QSocketNotifier* createNotifier(QSocketNotifier::Type type) const;
+
+public:
+  /**
+   * Creates a new default KSocketDevice object given
+   * the parent object.
+   *
+   * The capabilities flag indicates the desired capabilities the object being
+   * created should possess. Those capabilities are not guaranteed: if no factory
+   * can provide such an object, a default object will be created.
+   *
+   * @param parent	the KSocketBase parent
+   */
+  static KSocketDevice* createDefault(KSocketBase* parent);
+
+  /**
+   * @overload
+   *
+   * This will create an object only if the requested capabilities match.
+   *
+   * @param parent		the parent
+   * @param capabilities	the requested capabilities
+   */
+  static KSocketDevice* createDefault(KSocketBase* parent, int capabilities);
+
+  /**
+   * Sets the default KSocketDevice implementation to use and
+   * return the old factory.
+   *
+   * @param factory	the factory object for the implementation
+   */
+  static KSocketDeviceFactoryBase* setDefaultImpl(KSocketDeviceFactoryBase* factory);
+
+  /**
+   * Adds a factory of KSocketDevice objects to the list, along with its
+   * capabilities flag.
+   */
+  static void addNewImpl(KSocketDeviceFactoryBase* factory, int capabilities);
+
+private:
+  KSocketDevice(const KSocketDevice&);
+  KSocketDevice& operator=(const KSocketDevice&);
+
+  KSocketDevicePrivate *d;
+};
+
+/** @internal
+ * This class provides functionality for creating and registering
+ *  socket implementations.
+ */
+class KSocketDeviceFactoryBase
+{
+public:
+  KSocketDeviceFactoryBase() {}
+  virtual ~KSocketDeviceFactoryBase() {}
+
+  virtual KSocketDevice* create(KSocketBase*) const = 0;
+};
+
+/**
+ * This class provides functionality for creating and registering 
+ * socket implementations.
+ */
+template<class Impl>
+class KSocketDeviceFactory: public KSocketDeviceFactoryBase
+{
+public:
+  KSocketDeviceFactory() {}
+  virtual ~KSocketDeviceFactory() {}
+
+  virtual KSocketDevice* create(KSocketBase* parent) const
+  { return new Impl(parent); }
+};
+
+}				// namespaces
+
+#endif