summaryrefslogtreecommitdiffstats
path: root/tdecore/network/kclientsocketbase.h
diff options
context:
space:
mode:
Diffstat (limited to 'tdecore/network/kclientsocketbase.h')
-rw-r--r--tdecore/network/kclientsocketbase.h532
1 files changed, 532 insertions, 0 deletions
diff --git a/tdecore/network/kclientsocketbase.h b/tdecore/network/kclientsocketbase.h
new file mode 100644
index 000000000..75e796ffc
--- /dev/null
+++ b/tdecore/network/kclientsocketbase.h
@@ -0,0 +1,532 @@
+/* -*- 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 KCLIENTSOCKETBASE_H
+#define KCLIENTSOCKETBASE_H
+
+#include <tqobject.h>
+#include <tqstring.h>
+
+#include "ksocketbase.h"
+#include "kresolver.h"
+#include <kdelibs_export.h>
+
+#ifdef Q_MOC_RUN
+#define USE_QT4
+#endif // Q_MOC_RUN
+
+namespace KNetwork {
+
+class KClientSocketBasePrivate;
+/** @class KClientSocketBase kclientsocketbase.h kclientsocketbase.h
+ * @brief Abstract client socket class.
+ *
+ * This class provides the base functionality for client sockets,
+ * such as, and especially, name resolution and signals.
+ *
+ * @note This class is abstract. If you're looking for a normal,
+ * client socket class, see @ref KStreamSocket and KBufferedSocket
+ *
+ * @author Thiago Macieira <thiago.macieira@kdemail.net>
+ */
+class KDECORE_EXPORT KClientSocketBase :
+#ifdef USE_QT4
+#else // USE_QT4
+public TQObject,
+#endif // USE_QT4
+public KActiveSocketBase
+{
+ Q_OBJECT
+ TQ_OBJECT
+
+public:
+ /**
+ * Socket states.
+ *
+ * These are the possible states for a KClientSocketBase:
+ * - Idle: socket is not connected
+ * - HostLookup: socket is doing host lookup prior to connecting
+ * - HostFound: name lookup is complete
+ * - Bound: the socket is locally bound
+ * - Connecting: socket is attempting connection
+ * - Open: socket is open
+ * - Connected (=Open): socket is connected
+ * - Connection (=Open): yet another name for a connected socket
+ * - Closing: socket is shutting down
+ *
+ * Whenever the socket state changes, the @ref stateChanged(int) signal
+ * will be emitted.
+ */
+ enum SocketState
+ {
+ Idle,
+ HostLookup,
+ HostFound,
+ Bound,
+ Connecting,
+ Open,
+ Closing,
+
+ Unconnected = Bound,
+ Connected = Open,
+ Connection = Open
+ };
+
+public:
+ /**
+ * Default constructor.
+ *
+ * @param parent the parent TQObject object
+ * @param name the name of this object
+ */
+ KClientSocketBase(TQObject* parent, const char *name);
+
+ /**
+ * Destructor.
+ */
+ virtual ~KClientSocketBase();
+
+ /**
+ * Returns the current state for this socket.
+ * @see SocketState
+ */
+ SocketState state() const;
+
+protected:
+ /**
+ * Sets the socket options. Reimplemented from KSocketBase.
+ */
+ virtual bool setSocketOptions(int opts);
+
+public:
+ /**
+ * Returns the internal KResolver object used for
+ * looking up the peer host name and service.
+ *
+ * This can be used to set extra options to the
+ * lookup process other than the default values, as well
+ * as obtaining the error codes in case of lookup failure.
+ */
+ KResolver& peerResolver() const;
+
+ /**
+ * Returns the internal list of resolved results for the peer address.
+ */
+ const KResolverResults& peerResults() const;
+
+ /**
+ * Returns the internal KResolver object used for
+ * looking up the local host name and service.
+ *
+ * This can be used to set extra options to the
+ * lookup process other than the default values, as well
+ * as obtaining the error codes in case of lookup failure.
+ */
+ KResolver& localResolver() const;
+
+ /**
+ * Returns the internal list of resolved results for the local address.
+ */
+ const KResolverResults& localResults() const;
+
+ /**
+ * Enables or disables name resolution. If this flag is set to true,
+ * @ref bind and @ref connect operations will trigger name lookup
+ * operations (i.e., converting a hostname into its binary form).
+ * If the flag is set to false, those operations will instead
+ * try to convert a string representation of an address without
+ * attempting name resolution.
+ *
+ * This is useful, for instance, when IP addresses are in
+ * their string representation (such as "1.2.3.4") or come
+ * from other sources like @ref KSocketAddress.
+ *
+ * @param enable whether to enable
+ */
+ void setResolutionEnabled(bool enable);
+
+ /**
+ * Sets the allowed families for the resolutions.
+ *
+ * @param families the families that we want/accept
+ * @see KResolver::SocketFamilies for possible values
+ */
+ void setFamily(int families);
+
+ /**
+ * Starts the lookup for peer and local hostnames as
+ * well as their services.
+ *
+ * If the blocking mode for this object is on, this function will
+ * wait for the lookup results to be available (by calling the
+ * @ref KResolver::wait method on the resolver objects).
+ *
+ * When the lookup is done, the signal @ref hostFound will be
+ * emitted (only once, even if we're doing a double lookup).
+ * If the lookup failed (for any of the two lookups) the
+ * @ref gotError signal will be emitted with the appropriate
+ * error condition (see @ref KSocketBase::SocketError).
+ *
+ * This function returns true on success and false on error. Note that
+ * this is not the lookup result!
+ */
+ virtual bool lookup();
+
+ /**
+ * Binds this socket to the given nodename and service,
+ * or use the default ones if none are given.
+ *
+ * Upon successful binding, the @ref bound signal will be
+ * emitted. If an error is found, the @ref gotError
+ * signal will be emitted.
+ *
+ * @note Due to the internals of the name lookup and binding
+ * mechanism, some (if not most) implementations of this function
+ * do not actually bind the socket until the connection
+ * is requested (see @ref connect). They only set the values
+ * for future reference.
+ *
+ * This function returns true on success.
+ *
+ * @param node the nodename
+ * @param service the service
+ */
+ virtual bool bind(const TQString& node = TQString::null,
+ const TQString& service = TQString::null) = 0;
+
+ /**
+ * Reimplemented from KSocketBase. Connect this socket to this
+ * specific address.
+ *
+ * Unlike @ref bind(const TQString&, const TQString&) above, this function
+ * really does bind the socket. No lookup is performed. The @ref bound
+ * signal will be emitted.
+ */
+ virtual bool bind(const KResolverEntry& address);
+
+ /**
+ * Attempts to connect to the these hostname and service,
+ * or use the default ones if none are given. If a connection attempt
+ * is already in progress, check on its state and set the error status
+ * (NoError or InProgress).
+ *
+ * If the blocking mode for this object is on, this function will only
+ * return when all the resolved peer addresses have been tried or when
+ * a connection is established.
+ *
+ * Upon successfully connecting, the @ref connected signal
+ * will be emitted. If an error is found, the @ref gotError
+ * signal will be emitted.
+ *
+ * @par Note for derived classes:
+ * Derived classes must implement this function. The implementation
+ * will set the parameters for the lookup (using the peer KResolver
+ * object) and call @ref lookup to start it.
+ *
+ * @par
+ * The implementation should use the @ref hostFound
+ * signal to be notified of the completion of the lookup process and
+ * then proceed to start the connection itself. Care should be taken
+ * regarding the value of @ref blocking flag.
+ *
+ * @param node the nodename
+ * @param service the service
+ */
+ virtual bool connect(const TQString& node = TQString::null,
+ const TQString& service = TQString::null) = 0;
+
+ /**
+ * @overload
+ * Reimplemented from KSocketBase.
+ */
+ virtual bool connect(const KResolverEntry& address);
+
+ /**
+ * @deprecated
+ * This is a convenience function provided to ease migrating from
+ * Qt 3.x's TQSocket class.
+ */
+ inline void connectToHost(const TQString& host, TQ_UINT16 port)
+ { connect(host, TQString::number(port)); }
+
+ /**
+ * Disconnects the socket.
+ * Note that not all socket types can disconnect.
+ */
+ virtual bool disconnect();
+
+ /**
+ * Opens the socket. Reimplemented from TQIODevice.
+ *
+ * You should not call this function; instead, use @ref connect
+ */
+ virtual inline bool open(TQ_OpenMode)
+ { return connect(); }
+
+ /**
+ * Closes the socket. Reimplemented from TQIODevice.
+ *
+ * The closing of the socket causes the emission of the
+ * signal @ref closed.
+ */
+ virtual void close();
+
+ /**
+ * This call is not supported on sockets. Reimplemented from TQIODevice.
+ */
+ virtual void flush()
+ { }
+
+ /**
+ * Returns the number of bytes available on this socket.
+ * Reimplemented from KSocketBase.
+ */
+#ifdef USE_QT3
+ virtual TQ_LONG bytesAvailable() const;
+#endif
+#ifdef USE_QT4
+ virtual qint64 bytesAvailable() const;
+#endif
+
+ /**
+ * Waits for more data. Reimplemented from KSocketBase.
+ */
+ virtual TQ_LONG waitForMore(int msecs, bool *timeout = 0L);
+
+ /**
+ * Reads data from a socket. Reimplemented from KSocketBase.
+ */
+ virtual TQT_TQIO_LONG tqreadBlock(char *data, TQT_TQIO_ULONG maxlen);
+
+ /**
+ * @overload
+ * Reads data from a socket. Reimplemented from KSocketBase.
+ */
+ virtual TQT_TQIO_LONG tqreadBlock(char *data, TQT_TQIO_ULONG maxlen, KSocketAddress& from);
+
+ /**
+ * Peeks data from the socket. Reimplemented from KSocketBase.
+ */
+ virtual TQ_LONG peekBlock(char *data, TQ_ULONG maxlen);
+
+ /**
+ * @overload
+ * Peeks data from the socket. Reimplemented from KSocketBase.
+ */
+ virtual TQ_LONG peekBlock(char *data, TQ_ULONG maxlen, KSocketAddress &from);
+
+ /**
+ * Writes data to the socket. Reimplemented from KSocketBase.
+ */
+ virtual TQT_TQIO_LONG tqwriteBlock(const char *data, TQT_TQIO_ULONG len);
+
+ /**
+ * @overload
+ * Writes data to the socket. Reimplemented from KSocketBase.
+ */
+ virtual TQT_TQIO_LONG tqwriteBlock(const char *data, TQT_TQIO_ULONG len, const KSocketAddress& to);
+
+ /**
+ * Returns the local socket address. Reimplemented from KSocketBase.
+ */
+ virtual KSocketAddress localAddress() const;
+
+ /**
+ * Returns the peer socket address. Reimplemented from KSocketBase.
+ */
+ virtual KSocketAddress peerAddress() const;
+
+ /**
+ * Returns true if the readyRead signal is set to be emitted.
+ */
+ bool emitsReadyRead() const;
+
+ /**
+ * Enables the emission of the readyRead signal.
+ * By default, this signal is enabled.
+ *
+ * @param enable whether to enable the signal
+ */
+ virtual void enableRead(bool enable);
+
+ /**
+ * Returns true if the readyWrite signal is set to be emitted.
+ */
+ bool emitsReadyWrite() const;
+
+ /**
+ * Enables the emission of the readyWrite signal.
+ * By default, this signal is disabled.
+ *
+ * @param enable whether to enable the signal
+ */
+ virtual void enableWrite(bool enable);
+
+protected slots:
+ // protected slots
+
+ /**
+ * This slot is connected to the read notifier's signal meaning
+ * the socket can read more data.
+ *
+ * The default implementation only emits the readyRead signal.
+ *
+ * Override if your class requires processing of incoming
+ * data.
+ */
+ virtual void slotReadActivity();
+
+ /**
+ * This slot is connected to the write notifier's signal
+ * meaning the socket can write more data.
+ *
+ * The default implementation only emits the readyWrite signal.
+ *
+ * Override if your class writes data from another source
+ * (like a buffer).
+ */
+ virtual void slotWriteActivity();
+
+private slots:
+ void lookupFinishedSlot();
+
+signals:
+ /**
+ * This signal is emitted whenever the socket state changes.
+ *
+ * Note: do not delete this object inside the slot called by this
+ * signal.
+ *
+ * @param newstate the new state of the socket object
+ */
+ void stateChanged(int newstate);
+
+ /**
+ * This signal is emitted when this object finds an error.
+ * The @p code parameter contains the error code that can
+ * also be found by calling @ref error.
+ */
+ void gotError(int code);
+
+ /**
+ * This signal is emitted when the lookup is successfully completed.
+ */
+ void hostFound();
+
+ /**
+ * This signal is emitted when the socket successfully binds
+ * to an address.
+ *
+ * @param local the local address we bound to
+ */
+ void bound(const KResolverEntry& local);
+
+ /**
+ * This signal is emitted when the socket is about to connect
+ * to an address (but before doing so).
+ *
+ * The @p skip parameter can be used to make the loop skip this address.
+ * Its value is initially false: change it to true if you want to
+ * skip the current address (as given by @p remote).
+ *
+ * This function is also useful if one wants to reset the timeout.
+ *
+ * @param remote the address we're about to connect to
+ * @param skip set to true if you want to skip this address
+ * @note if the connection is successful, the @ref connected signal will be
+ * emitted.
+ */
+ void aboutToConnect(const KResolverEntry& remote, bool& skip);
+
+ /**
+ * This socket is emitted when the socket successfully connects
+ * to a remote address.
+ *
+ * @param remote the remote address we did connect to
+ */
+ void connected(const KResolverEntry& remote);
+
+ /**
+ * This signal is emitted when the socket completes the
+ * closing/shut down process.
+ */
+ void closed();
+
+ /**
+ * This signal is emitted whenever the socket is ready for
+ * reading -- i.e., there is data to be read in the buffers.
+ * The subsequent read operation is guaranteed to be non-blocking.
+ *
+ * You can toggle the emission of this signal with the @ref enableRead
+ * function. This signal is by default enabled.
+ */
+ void readyRead();
+
+ /**
+ * This signal is emitted whenever the socket is ready for
+ * writing -- i.e., whenever there's space available in the buffers
+ * to receive more data. The subsequent write operation is
+ * guaranteed to be non-blocking.
+ *
+ * You can toggle the emission of this signal with the @ref enableWrite
+ * function. This signal is by default disabled. You will
+ * want to disable this signal after the first reception, since
+ * it'll probably fire at every event loop.
+ */
+ void readyWrite();
+
+protected:
+ /**
+ * Sets the socket state to @p state. This function does not
+ * emit the @ref stateChanged signal.
+ */
+ void setState(SocketState state);
+
+ /**
+ * This function is called by @ref setState whenever the state
+ * changes. You should override it if you need to specify any
+ * actions to be done when the state changes.
+ *
+ * The default implementation acts for these states only:
+ * - Connected: it sets up the socket notifiers to fire readyRead and
+ * readyWrite signals.
+ */
+ virtual void stateChanging(SocketState newState);
+
+ /**
+ * Convenience function to set this object's error code to match
+ * that of the socket device.
+ */
+ void copyError();
+
+private:
+ KClientSocketBase(const KClientSocketBase&);
+ KClientSocketBase& operator=(const KClientSocketBase&);
+
+ KClientSocketBasePrivate *d;
+};
+
+} // namespace KNetwork
+
+#endif