diff options
Diffstat (limited to 'kdecore/network/ksocketbase.h')
| -rw-r--r-- | kdecore/network/ksocketbase.h | 771 |
1 files changed, 0 insertions, 771 deletions
diff --git a/kdecore/network/ksocketbase.h b/kdecore/network/ksocketbase.h deleted file mode 100644 index 8a94cbbcb..000000000 --- a/kdecore/network/ksocketbase.h +++ /dev/null @@ -1,771 +0,0 @@ -/* -*- 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 |