File indexing completed on 2024-03-03 15:03:11

0001 /*  -*- C++ -*-
0002  *  Copyright (C) 2003,2005 Thiago Macieira <thiago@kde.org>
0003  *
0004  *
0005  *  Permission is hereby granted, free of charge, to any person obtaining
0006  *  a copy of this software and associated documentation files (the
0007  *  "Software"), to deal in the Software without restriction, including
0008  *  without limitation the rights to use, copy, modify, merge, publish,
0009  *  distribute, sublicense, and/or sell copies of the Software, and to
0010  *  permit persons to whom the Software is furnished to do so, subject to
0011  *  the following conditions:
0012  *
0013  *  The above copyright notice and this permission notice shall be included
0014  *  in all copies or substantial portions of the Software.
0015  *
0016  *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
0017  *  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
0018  *  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
0019  *  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
0020  *  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
0021  *  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
0022  *  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
0023  */
0024 
0025 /*
0026  * Even before our #ifdef, clean up the namespace
0027  */
0028 #ifdef socket
0029 #undef socket
0030 #endif
0031 
0032 #ifdef bind
0033 #undef bind
0034 #endif
0035 
0036 #ifdef listen
0037 #undef listen
0038 #endif
0039 
0040 #ifdef connect
0041 #undef connect
0042 #endif
0043 
0044 #ifdef accept
0045 #undef accept
0046 #endif
0047 
0048 #ifdef getpeername
0049 #undef getpeername
0050 #endif
0051 
0052 #ifdef getsockname
0053 #undef getsockname
0054 #endif
0055 
0056 #ifndef KSOCKETBASE_H
0057 #define KSOCKETBASE_H
0058 
0059 #include <QIODevice>
0060 #include <QString>
0061 
0062 #include <kdelibs4support_export.h>
0063 #include "k3socketaddress.h"
0064 
0065 class QMutex;
0066 
0067 namespace KNetwork
0068 {
0069 
0070 class KResolverEntry;
0071 class KSocketDevice;
0072 
0073 class KSocketBasePrivate;
0074 /** @class KSocketBase k3socketbase.h k3socketbase.h
0075  *  @brief Basic socket functionality.
0076  *
0077  * This class provides the basic socket functionlity for descended classes.
0078  * Socket classes are thread-safe and provide a recursive mutex should it be
0079  * needed.
0080  *
0081  * @note This class is abstract.
0082  *
0083  * @author Thiago Macieira <thiago@kde.org>
0084  * @deprecated Use KSocketFactory or KLocalSocket instead
0085  */
0086 class KDELIBS4SUPPORT_DEPRECATED_EXPORT KSocketBase
0087 {
0088 public:
0089     /**
0090      * Possible socket options.
0091      *
0092      * These are the options that may be set on a socket:
0093      *  - Blocking: whether the socket shall operate in blocking
0094      *    or non-blocking mode. This flag defaults to on.
0095      *    See setBlocking().
0096      *  - AddressReusable: whether the address used by this socket will
0097      *    be available for reuse by other sockets. This flag defaults to off.
0098      *    See setAddressReuseable().
0099      *  - IPv6Only: whether an IPv6 socket will accept IPv4 connections
0100      *    through a mapped address. This flag defaults to off.
0101      *    See setIPv6Only().
0102      *  - KeepAlive: whether TCP should send keepalive probes when a connection
0103      *    has gone idle for far too long.
0104      *  - Broadcast: whether this socket is allowed to send broadcast packets
0105      *    and will receive packets sent to broadcast.
0106      *  - NoDelay: disable the Nagle algorithm for socket types that support
0107      *    it.
0108      */
0109     enum SocketOptions {
0110         Blocking = 0x01,
0111         AddressReuseable = 0x02,
0112         IPv6Only = 0x04,
0113         Keepalive = 0x08,
0114         Broadcast = 0x10,
0115         NoDelay = 0x20
0116     };
0117 
0118     /**
0119      * Possible socket error codes.
0120      *
0121      * This is a list of possible error conditions that socket classes may
0122      * be expected to find.
0123      *
0124      * - NoError: no error has been detected
0125      * - LookupFailure: if a name lookup has failed
0126      * - AddressInUse: address is already in use
0127      * - AlreadyBound: cannot bind again
0128      * - AlreadyCreated: cannot recreate the socket
0129      * - NotBound: operation required socket to be bound and it isn't
0130      * - NotCreated: operation required socket to exist and it doesn't
0131      * - WouldBlock: requested I/O operation would block
0132      * - ConnectionRefused: connection actively refused
0133      * - ConnectionTimedOut: connection timed out
0134      * - InProgress: operation (connection) is already in progress
0135      * - NetFailure: a network failure occurred (no route, host down, host unreachable or similar)
0136      * - NotSupported: requested operation is not supported
0137      * - Timeout: a timed operation timed out
0138      * - UnknownError: an unknown/unexpected error has happened
0139      * - RemotelyDisconnected: when a connection is disconnected by the other end (since 3.4)
0140      *
0141      * @sa error, errorString
0142      */
0143     enum SocketError {
0144         NoError = 0,
0145         LookupFailure,
0146         AddressInUse,
0147         AlreadyCreated,
0148         AlreadyBound,
0149         AlreadyConnected,
0150         NotConnected,
0151         NotBound,
0152         NotCreated,
0153         WouldBlock,
0154         ConnectionRefused,
0155         ConnectionTimedOut,
0156         InProgress,
0157         NetFailure,
0158         NotSupported,
0159         Timeout,
0160         UnknownError,
0161         RemotelyDisconnected
0162     };
0163 
0164 public:
0165     /**
0166      * Default constructor.
0167      */
0168     KSocketBase();
0169 
0170     /**
0171      * Destructor.
0172      */
0173     virtual ~KSocketBase();
0174 
0175     /*
0176      * The following functions are shared by all descended classes and will have
0177      * to be reimplemented.
0178      */
0179 
0180 protected:
0181     /**
0182      * Set the given socket options.
0183      *
0184      * The default implementation does nothing but store the mask internally.
0185      * Descended classes must override this function to achieve functionality and
0186      * must also call this implementation.
0187      *
0188      * @param opts    a mask of SocketOptions or-ed bits of options to set
0189      *            or unset
0190      * @returns true on success
0191      * @note this function sets the options corresponding to the bits enabled in @p opts
0192      *       but will also unset the optiosn corresponding to the bits not set.
0193      */
0194     virtual bool setSocketOptions(int opts);
0195 
0196     /**
0197      * Retrieves the socket options that have been set.
0198      *
0199      * The default implementation just retrieves the mask from an internal variable.
0200      * Descended classes may choose to override this function to read the values
0201      * from the operating system.
0202      *
0203      * @returns the mask of the options set
0204      */
0205     virtual int socketOptions() const;
0206 
0207 public:
0208     /**
0209      * Sets this socket's blocking mode.
0210      *
0211      * In blocking operation, all I/O functions are susceptible to blocking --
0212      * i.e., will not return unless the I/O can be satisfied. In non-blocking
0213      * operation, if the I/O would block, the function will return an error
0214      * and set the corresponding error code.
0215      *
0216      * The default implementation toggles the Blocking flag with the current
0217      * socket options and calls setSocketOptions().
0218      *
0219      * @param enable      whether to set this socket to blocking mode
0220      * @returns whether setting this value was successful; it is NOT the
0221      *          final blocking mode.
0222      */
0223     virtual bool setBlocking(bool enable);
0224 
0225     /**
0226      * Retrieves this socket's blocking mode.
0227      *
0228      * @returns true if this socket is/will be operated in blocking mode,
0229      *          false if non-blocking.
0230      */
0231     bool blocking() const;
0232 
0233     /**
0234      * Sets this socket's address reuseable flag.
0235      *
0236      * When the address reuseable flag is active, the address used by
0237      * this socket is left reuseable for other sockets to bind. If
0238      * the flag is not active, no other sockets may reuse the same
0239      * address.
0240      *
0241      * The default implementation toggles the AddressReuseable flag with the current
0242      * socket options and calls setSocketOptions().
0243      *
0244      * @param enable      whether to set the flag on or off
0245      * @returns true if setting this flag was successful
0246      */
0247     virtual bool setAddressReuseable(bool enable);
0248 
0249     /**
0250      * Retrieves this socket's address reuseability flag.
0251      *
0252      * @returns true if this socket's address can be reused,
0253      *          false if it can't.
0254      */
0255     bool addressReuseable() const;
0256 
0257     /**
0258      * Sets this socket's IPv6 Only flag.
0259      *
0260      * When this flag is on, an IPv6 socket will only accept, connect, send to or
0261      * receive from IPv6 addresses. When it is off, it will also talk to
0262      * IPv4 addresses through v4-mapped addresses.
0263      *
0264      * This option has no effect on non-IPv6 sockets.
0265      *
0266      * The default implementation toggles the IPv6Only flag with the current
0267      * socket options and calls setSocketOptions().
0268      *
0269      * @param enable      whether to set the flag on or off
0270      * @returns true if setting this flag was successful
0271      */
0272     virtual bool setIPv6Only(bool enable);
0273 
0274     /**
0275      * Retrieves this socket's IPv6 Only flag.
0276      *
0277      * @returns true if this socket will ignore IPv4-compatible and IPv4-mapped
0278      *          addresses, false if it will accept them.
0279      */
0280     bool isIPv6Only() const;
0281 
0282     /**
0283      * Sets this socket Broadcast flag.
0284      *
0285      * Datagram-oriented sockets cannot normally send packets to broadcast
0286      * addresses, nor will they receive packets that were sent to a broadcast
0287      * address. To do so, you need to enable the Broadcast flag.
0288      *
0289      * This option has no effect on stream-oriented sockets.
0290      *
0291      * @returns true if setting this flag was successful.
0292      */
0293     virtual bool setBroadcast(bool enable);
0294 
0295     /**
0296      * Retrieves this socket's Broadcast flag.
0297      *
0298      * @returns true if this socket can send and receive broadcast packets,
0299      *          false if it can't.
0300      */
0301     bool broadcast() const;
0302 
0303     /**
0304      * Sets this socket's NoDelay flag.
0305      *
0306      * Stream-oriented protocols, like TCP, have an internal algorithm
0307      * (called Nagle's algorithm) that collects data in a buffer so that
0308      * the transmission doesn't occur after every single write operation.
0309      * The side-effect is that the transmission of short messages is
0310      * delayed.
0311      *
0312      * Setting NoDelay to 'true' will disable this algorithm.
0313      *
0314      * @returns true if setting this flag was successful.
0315      */
0316     virtual bool setNoDelay(bool enable);
0317 
0318     /**
0319      * Retrieves this socket's NoDelay flag.
0320      *
0321      * @returns true if this socket's Nagle algorithm is disabled.
0322      */
0323     bool noDelay() const;
0324 
0325     /**
0326      * Retrieves the socket implementation used on this socket.
0327      *
0328      * This function creates the device if none has been set
0329      * using the default factory.
0330      */
0331     KSocketDevice *socketDevice() const;
0332 
0333     /**
0334      * Sets the socket implementation to be used on this socket.
0335      *
0336      * Note: it is an error to set this if the socket device has
0337      * already been set once.
0338      *
0339      * This function is provided virtual so that derived classes can catch
0340      * the setting of a device and properly set their own states and internal
0341      * variables. The parent class must be called.
0342      *
0343      * This function is called by socketDevice() above when the socket is
0344      * first created.
0345      */
0346     virtual void setSocketDevice(KSocketDevice *device);
0347 
0348     /**
0349      * Sets the internally requested capabilities for a socket device.
0350      *
0351      * Most socket classes can use any back-end implementation. However, a few
0352      * may require specific capabilities not provided in the default
0353      * implementation. By using this function, derived classes can request
0354      * that a backend with those capabilities be created when necessary.
0355      *
0356      * For the possible flags, see KSocketDevice::Capabilities. However, note
0357      * that only the Can* flags make sense in this context.
0358      *
0359      * @note Since socketDevice must always return a valid backend object, it
0360      *       is is possible that the created device does not conform to all
0361      *       requirements requested. Implementations sensitive to this fact
0362      *       should test the object returned by socketDevice() (through
0363      *       KSocketDevice::capabilities(), for instance) the availability.
0364      *
0365      * @param add     mask of KSocketDevice::Capabilities to add
0366      * @param remove  mask of bits to remove from the requirements
0367      * @return the current mask of requested capabilities
0368      */
0369     int setRequestedCapabilities(int add, int remove = 0);
0370 
0371 protected:
0372     /**
0373      * Returns true if the socket device has been initialised in this
0374      * object, either by calling socketDevice() or setSocketDevice()
0375      */
0376     bool hasDevice() const;
0377 
0378     /**
0379      * Sets the socket's error code.
0380      *
0381      * @param error       the error code
0382      */
0383     void setError(SocketError error);
0384 
0385     /**
0386      * Resets the socket error code and the I/O Device's status.
0387      */
0388     void resetError();
0389 
0390 public:
0391     /**
0392      * Retrieves the socket error code.
0393      * @sa errorString
0394      */
0395     SocketError error() const;
0396 
0397     /**
0398      * Returns the error string corresponding to this error condition.
0399      */
0400     QString errorString() const;
0401 
0402     /**
0403      * Returns the internal mutex for this class.
0404      *
0405      * Note on multithreaded use of sockets:
0406      * the socket classes are thread-safe by design, but you should be aware of
0407      * problems regarding socket creation, connection and destruction in
0408      * multi-threaded programs. The classes are guaranteed to work while
0409      * the socket exists, but it's not wise to call connect in multiple
0410      * threads.
0411      *
0412      * Also, this mutex must be unlocked before the object is destroyed, which
0413      * means you cannot use it to guard against other threads accessing the object
0414      * while destroying it. You must ensure there are no further references to this
0415      * object when deleting it.
0416      */
0417     QMutex *mutex() const;
0418 
0419 public:
0420     /**
0421      * Returns the string describing the given error code, i18n'ed.
0422      *
0423      * @param code        the error code
0424      */
0425     static QString errorString(SocketError code);
0426 
0427     /**
0428      * Returns true if the given error code is a fatal one, false
0429      * otherwise. The parameter here is of type int so that
0430      * casting isn't necessary when using the parameter to signal
0431      * QClientSocketBase::gotError.
0432      *
0433      * @param code        the code to test
0434      */
0435     static bool isFatalError(int code);
0436 
0437 private:
0438     /// @internal
0439     /// called by KSocketDevice
0440     void unsetSocketDevice();
0441 
0442     KSocketBase(const KSocketBase &);
0443     KSocketBase &operator =(const KSocketBase &);
0444 
0445     KSocketBasePrivate *const d;
0446 
0447     friend class KSocketDevice;
0448 };
0449 
0450 /**
0451  * @class KActiveSocketBase k3socketbase.h k3socketbase.h
0452  * @brief Abstract class for active sockets
0453  *
0454  * This class provides the standard interfaces for active sockets, i.e.,
0455  * sockets that are used to connect to external addresses.
0456  *
0457  * @author Thiago Macieira <thiago@kde.org>
0458  * @deprecated Use KSocketFactory or KLocalSocket instead
0459  */
0460 class KDELIBS4SUPPORT_DEPRECATED_EXPORT KActiveSocketBase: public QIODevice, virtual public KSocketBase
0461 {
0462     Q_OBJECT
0463 public:
0464     /**
0465      * Constructor.
0466      */
0467     KActiveSocketBase(QObject *parent);
0468 
0469     /**
0470      * Destructor.
0471      */
0472     ~KActiveSocketBase() override;
0473 
0474     /**
0475      * Unshadow errorString from QIODevice
0476      */
0477     QString errorString() const;
0478 
0479     /**
0480      * @reimp
0481      */
0482     void setSocketDevice(KSocketDevice *device) override;
0483 
0484     /**
0485      * Reimplemented from QIODevice.
0486      */
0487     bool open(OpenMode mode) override;
0488 
0489     /**
0490      * Binds this socket to the given address.
0491      *
0492      * The socket will be constructed with the address family,
0493      * socket type and protocol as those given in the
0494      * @p address object.
0495      *
0496      * @param address     the address to bind to
0497      * @returns true if the binding was successful, false otherwise
0498      */
0499     virtual bool bind(const KResolverEntry &address) = 0;
0500 
0501     /**
0502      * Connect to a remote host.
0503      *
0504      * This will make this socket try to connect to the remote host.
0505      * If the socket is not yet created, it will be created using the
0506      * address family, socket type and protocol specified in the
0507      * @p address object.
0508      *
0509      * If this function returns with error InProgress, calling it
0510      * again with the same address after a time will cause it to test
0511      * if the connection has succeeded in the mean time.
0512      *
0513      * @param address     the address to connect to
0514      * @param mode                mode for connection, from QIODevice
0515      *
0516      * @returns true if the connection was successful or has been successfully
0517      *          queued; false if an error occurred.
0518      */
0519     virtual bool connect(const KResolverEntry &address,
0520                          OpenMode mode = ReadWrite) = 0;
0521 
0522     /**
0523      * Disconnects this socket from a connection, if possible.
0524      *
0525      * If this socket was connected to an endpoint, the connection
0526      * is severed, but the socket is not closed. If the socket wasn't
0527      * connected, this function does nothing.
0528      *
0529      * If the socket hadn't yet been created, this function does nothing
0530      * either.
0531      *
0532      * Not all socket types can disconnect. Most notably, only
0533      * connectionless datagram protocols such as UDP support this operation.
0534      *
0535      * @return true if the socket is now disconnected or false on error.
0536      */
0537     virtual bool disconnect() = 0;
0538 
0539     /**
0540      * Sockets are sequential
0541      */
0542     bool isSequential() const override;
0543 
0544     /**
0545      * This call is not supported on sockets. Reimplemented from QIODevice.
0546      * This will always return 0.
0547      */
0548     qint64 size() const override;
0549 
0550     /**
0551      * This call is not supported on sockets. Reimplemented from QIODevice.
0552      * This will always return 0.
0553      */
0554     qint64 pos() const override;
0555 
0556     /**
0557      * This call is not supported on sockets. Reimplemented from QIODevice.
0558      * This will always return false.
0559      */
0560     bool seek(qint64) override;
0561 
0562     /**
0563      * This call is not supported on sockets. Reimplemented from QIODevice.
0564      * This will always return true.
0565      */
0566     bool atEnd() const override;
0567 
0568     /**
0569      * Reads data from the socket.
0570      *
0571      * Reimplemented from QIODevice. See QIODevice::read for
0572      * more information.
0573      */
0574     qint64 read(char *data, qint64 maxlen);
0575 
0576     /**
0577      * Reads data from the socket.
0578      *
0579      * Reimplemented from QIODevice. See QIODevice::read for
0580      * more information.
0581      */
0582     QByteArray read(qint64 len);
0583 
0584     /** @overload
0585      * Receives data and the source address.
0586      *
0587      * This call will read data in the socket and will also
0588      * place the sender's address in @p from object.
0589      *
0590      * @param data        where to write the read data to
0591      * @param maxlen      the maximum number of bytes to read
0592      * @param from        the address of the sender will be stored here
0593      * @returns the actual number of bytes read
0594      */
0595     qint64 read(char *data, qint64 maxlen, KSocketAddress &from);
0596 
0597     /**
0598      * Peeks the data in the socket and the source address.
0599      *
0600      * This call will allow you to peek the data to be received without actually
0601      * receiving it -- that is, it will be available for further peekings and
0602      * for the next read call.
0603      *
0604      * @param data        where to write the peeked data to
0605      * @param maxlen      the maximum number of bytes to peek
0606      * @returns the actual number of bytes copied into @p data
0607      */
0608     qint64 peek(char *data, qint64 maxlen);
0609 
0610     /**
0611      * @overload
0612      * Peeks the data in the socket and the source address.
0613      *
0614      * This call will allow you to peek the data to be received without actually
0615      * receiving it -- that is, it will be available for further peekings and
0616      * for the next read call.
0617      *
0618      * @param data        where to write the peeked data to
0619      * @param maxlen      the maximum number of bytes to peek
0620      * @param from        the address of the sender will be stored here
0621      * @returns the actual number of bytes copied into @p data
0622      */
0623     qint64 peek(char *data, qint64 maxlen, KSocketAddress &from);
0624 
0625     /**
0626      * Writes the given data to the socket.
0627      *
0628      * Reimplemented from QIODevice. See QIODevice::write for
0629      * more information.
0630      */
0631     qint64 write(const char *data, qint64 len);
0632 
0633     /**
0634      * Writes the given data to the socket.
0635      *
0636      * Reimplemented from QIODevice. See QIODevice::write for
0637      * more information.
0638      */
0639     qint64 write(const QByteArray &data);
0640 
0641     /** @overload
0642      * Writes the given data to the destination address.
0643      *
0644      * Note that not all socket connections allow sending data to different
0645      * addresses than the one the socket is connected to.
0646      *
0647      * @param data        the data to write
0648      * @param len         the length of the data
0649      * @param to          the address to send to
0650      * @returns the number of bytes actually sent
0651      */
0652     qint64 write(const char *data, qint64 len, const KSocketAddress &to);
0653 
0654     /**
0655      * Waits up to @p msecs for more data to be available on this socket.
0656      *
0657      * If msecs is -1, this call will block indefinetely until more data
0658      * is indeed available; if it's 0, this function returns immediately.
0659      *
0660      * If @p timeout is not NULL, this function will set it to indicate
0661      * if a timeout occurred.
0662      *
0663      * @returns the number of bytes available
0664      */
0665     virtual qint64 waitForMore(int msecs, bool *timeout = nullptr) = 0;
0666 
0667     /**
0668      * This call is not supported on sockets. Reimplemented from QIODevice.
0669      */
0670     void ungetChar(char);
0671 
0672     /**
0673      * Returns this socket's local address.
0674      */
0675     virtual KSocketAddress localAddress() const = 0;
0676 
0677     /**
0678      * Return this socket's peer address, if we are connected.
0679      * If the address cannot be retrieved, the returned object will contain
0680      * an invalid address.
0681      */
0682     virtual KSocketAddress peerAddress() const = 0;
0683 
0684     // FIXME KDE 4.0:
0685     // enable this function
0686 #if 0
0687     /**
0688      * Returns this socket's externally-visible address, if known.
0689      */
0690     virtual KSocketAddress externalAddress() const = 0;
0691 #endif
0692 
0693 protected:
0694     /**
0695      * Reads data from the socket.
0696      *
0697      * Reimplemented from QIODevice. See QIODevice::readData for
0698      * more information.
0699      */
0700     qint64 readData(char *data, qint64 len) override;
0701 
0702     /** @overload
0703      * Receives data and the source address.
0704      *
0705      * This call will read data in the socket and will also
0706      * place the sender's address in @p from object.
0707      *
0708      * @param data        where to write the read data to
0709      * @param maxlen      the maximum number of bytes to read
0710      * @param from        the address of the sender will be stored here
0711      * @returns the actual number of bytes read
0712      */
0713     virtual qint64 readData(char *data, qint64 maxlen, KSocketAddress *from) = 0;
0714 
0715     /**
0716      * Peeks the data in the socket and the source address.
0717      *
0718      * This call will allow you to peek the data to be received without actually
0719      * receiving it -- that is, it will be available for further peekings and
0720      * for the next read call.
0721      *
0722      * @param data        where to write the peeked data to
0723      * @param maxlen      the maximum number of bytes to peek
0724      * @param from        the address of the sender will be stored here
0725      * @returns the actual number of bytes copied into @p data
0726      */
0727     virtual qint64 peekData(char *data, qint64 maxlen, KSocketAddress *from) = 0;
0728 
0729     /**
0730      * Writes the given data to the socket.
0731      *
0732      * Reimplemented from QIODevice. See QIODevice::writeData for
0733      * more information.
0734      */
0735     qint64 writeData(const char *data, qint64 len) override;
0736 
0737     /** @overload
0738      * Writes the given data to the destination address.
0739      *
0740      * Note that not all socket connections allow sending data to different
0741      * addresses than the one the socket is connected to.
0742      *
0743      * @param data        the data to write
0744      * @param len         the length of the data
0745      * @param to          the address to send to
0746      * @returns the number of bytes actually sent
0747      */
0748     virtual qint64 writeData(const char *data, qint64 len, const KSocketAddress *to) = 0;
0749 
0750     /**
0751      * Sets the socket's error code.
0752      *
0753      * @param error       the error code
0754      */
0755     void setError(SocketError error);
0756 
0757     /**
0758      * Resets the socket error code and the I/O Device's status.
0759      */
0760     void resetError();
0761 };
0762 
0763 /**
0764  * @class KPassiveSocketBase k3socketbase.h k3socketbase.h
0765  * @brief Abstract base class for passive sockets.
0766  *
0767  * This socket provides the initial functionality for passive sockets,
0768  * i.e., sockets that accept incoming connections.
0769  *
0770  * @author Thiago Macieira <thiago@kde.org>
0771  * @deprecated Use KSocketFactory or KLocalSocket instead
0772  */
0773 class KDELIBS4SUPPORT_DEPRECATED_EXPORT KPassiveSocketBase: virtual public KSocketBase
0774 {
0775 public:
0776     /**
0777      * Constructor
0778      */
0779     KPassiveSocketBase();
0780 
0781     /**
0782      * Destructor
0783      */
0784     ~KPassiveSocketBase() override;
0785 
0786     /**
0787      * Binds this socket to the given address.
0788      *
0789      * The socket will be constructed with the address family,
0790      * socket type and protocol as those given in the
0791      * @p address object.
0792      *
0793      * @param address     the address to bind to
0794      * @returns true if the binding was successful, false otherwise
0795      */
0796     virtual bool bind(const KResolverEntry &address) = 0;
0797 
0798     /**
0799      * Puts this socket into listening mode.
0800      *
0801      * Placing a socket in listening mode means that it will
0802      * be allowed to receive incoming connections from
0803      * remote hosts.
0804      *
0805      * Note that some socket types or protocols cannot be
0806      * put in listening mode.
0807      *
0808      * @param backlog     the number of accepted connections to
0809      *                hold before starting to refuse
0810      * @returns true if the socket is now in listening mode
0811      */
0812     virtual bool listen(int backlog) = 0;
0813 
0814     /**
0815      * Closes this socket. All resources used are freed. Note that closing
0816      * a passive socket does not close the connections accepted with it.
0817      */
0818     virtual void close() = 0;
0819 
0820     /**
0821      * Accepts a new incoming connection.
0822      *
0823      * If this socket was in listening mode, you can call this
0824      * function to accept an incoming connection.
0825      *
0826      * If this function cannot accept a new connection (either
0827      * because it is not listening for one or because the operation
0828      * would block), it will return NULL.
0829      *
0830      * Also note that descended classes will override this function
0831      * to return specialized socket classes.
0832      */
0833     virtual KActiveSocketBase *accept() = 0;
0834 
0835     /**
0836      * Returns this socket's local address.
0837      */
0838     virtual KSocketAddress localAddress() const = 0;
0839 
0840     /**
0841      * Returns this socket's externally-visible address if known.
0842      */
0843     virtual KSocketAddress externalAddress() const = 0;
0844 
0845 private:
0846     KPassiveSocketBase(const KPassiveSocketBase &);
0847     KPassiveSocketBase &operator = (const KPassiveSocketBase &);
0848 };
0849 
0850 }               // namespace KNetwork
0851 
0852 #endif