Warning, file /frameworks/kdelibs4support/src/kdecore/k3socketdevice.h was not indexed or was modified since last indexation (in which case cross-reference links may be missing, inaccurate or erroneous).

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 #ifndef KSOCKETDEVICE_H
0026 #define KSOCKETDEVICE_H
0027 
0028 #include <QSocketNotifier>
0029 #include "k3socketbase.h"
0030 
0031 namespace KNetwork
0032 {
0033 
0034 class KSocketDevice;
0035 class KSocketDeviceFactoryBase;
0036 
0037 class KSocketDevicePrivate;
0038 /** @class KSocketDevice k3socketdevice.h k3socketdevice.h
0039  *  @brief Low-level socket functionality.
0040  *
0041  * This class provides low-level socket functionality.
0042  *
0043  * Most users will prefer "cooked" interfaces like those of KStreamSocket or
0044  * KServerSocket.
0045  *
0046  * Descended classes from this one provide some other kinds of socket functionality,
0047  * like proxying or specific socket types.
0048  *
0049  * @author Thiago Macieira <thiago@kde.org>
0050  * @deprecated Use KSocketFactory or KLocalSocket instead
0051  */
0052 class KDELIBS4SUPPORT_DEPRECATED_EXPORT KSocketDevice: public KActiveSocketBase, public KPassiveSocketBase
0053 {
0054 public:
0055     /**
0056      * Capabilities for the socket implementation.
0057      *
0058      * KSocketDevice-derived classes can implement certain capabilities that are not
0059      * available in the default class. These capabilities are described by these flags.
0060      * The default KSocketDevice class has none of these capabilities.
0061      *
0062      * For the negative capabilities (inabilities, the CanNot* forms), when a capability
0063      * is not present, the implementation will default to the original behaviour.
0064      */
0065     enum Capabilities {
0066         /** Can connect to hostnames.
0067          *  If this flag is present, the string form of connect() can be used. */
0068         CanConnectString = 0x01,
0069 
0070         /** Can bind to hostnames.
0071          *  If this flag is present, the string form of bind() can be used */
0072         CanBindString = 0x02,
0073 
0074         /** Can not bind.
0075          *  If this flag is present, this implementation cannot bind */
0076         CanNotBind = 0x04,
0077 
0078         /** Can not listen.
0079          *  If this flag is present, this implementation cannot listen */
0080         CanNotListen = 0x08,
0081 
0082         /**
0083          * Can send multicast as well as join/leave multicast groups.
0084          */
0085         CanMulticast = 0x10,
0086 
0087         /**
0088          * Can not use datagrams.
0089          * Note that this implies multicast capability not being available either.
0090          */
0091         CanNotUseDatagrams = 0x20
0092     };
0093 protected:
0094     /// The socket file descriptor. It is used throughout the implementation
0095     /// and subclasses.
0096     int m_sockfd;
0097 
0098 public:
0099     /**
0100      * Default constructor.
0101      *
0102      * The parameter is used to specify which socket this object is used as
0103      * a device for.
0104      */
0105     KDELIBS4SUPPORT_DEPRECATED explicit KSocketDevice(const KSocketBase * = nullptr, QObject *objparent = nullptr);
0106 
0107     /**
0108      * Constructs a new object around an already-open socket.
0109      *
0110      * Note: you should write programs that create sockets through
0111      * the classes whenever possible.
0112      */
0113     KDELIBS4SUPPORT_DEPRECATED explicit KSocketDevice(int fd, OpenMode mode = ReadWrite);
0114 
0115     /**
0116      * QObject constructor
0117      */
0118     KSocketDevice(QObject *parent);
0119 
0120     /**
0121      * Destructor. This closes the socket if it's open.
0122      */
0123     ~KSocketDevice() override;
0124 
0125     /**
0126      * Returns the file descriptor for this socket.
0127      */
0128     int socket() const;
0129 
0130     /**
0131      * Returns the set of capabilities this socket class implements.
0132      * The set of capabilities is defined as an OR-ed mask of
0133      * Capabilities bits.
0134      *
0135      * The default implementation is guaranteed to always return 0. That
0136      * is, derived implementations always return bits where they differ
0137      * from the system standard sockets.
0138      */
0139     virtual int capabilities() const;
0140 
0141     /**
0142      * This implementation sets the options on the socket.
0143      */
0144     bool setSocketOptions(int opts) override;
0145 
0146     /**
0147      * Closes the socket. Reimplemented from QIODevice.
0148      *
0149      * Use this function to close the socket this object is holding open.
0150      */
0151     void close() override;
0152 
0153     /**
0154      * This call is not supported on sockets. Reimplemented from QIODevice.
0155      */
0156     virtual bool flush();
0157 
0158     /**
0159      * Creates a socket but don't connect or bind anywhere.
0160      * This function is the equivalent of the system call socket(2).
0161      */
0162     virtual bool create(int family, int type, int protocol);
0163 
0164     /**
0165      * @overload
0166      * Creates a socket but don't connect or bind anywhere.
0167      */
0168     bool create(const KResolverEntry &address);
0169 
0170     /**
0171      * Binds this socket to the given address.
0172      */
0173     bool bind(const KResolverEntry &address) override;
0174 
0175     /**
0176      * Puts this socket into listening mode.
0177      */
0178     bool listen(int backlog = 5) override; // 5 is arbitrary
0179 
0180     /**
0181      * Connect to a remote host.
0182      */
0183     bool connect(const KResolverEntry &address,
0184                          OpenMode mode = ReadWrite) override;
0185 
0186     /**
0187      * Accepts a new incoming connection.
0188      * Note: this function returns a socket of type KSocketDevice.
0189      */
0190     KSocketDevice *accept() override;
0191 
0192     /**
0193      * Disconnects this socket.
0194      */
0195     bool disconnect() override;
0196 
0197     /**
0198      * Returns the number of bytes available for reading without blocking.
0199      */
0200     qint64 bytesAvailable() const override;
0201 
0202     /**
0203      * Waits up to @p msecs for more data to be available on this socket.
0204      *
0205      * This function is a wrapper against poll(). This function will wait
0206      * for any read events.
0207      */
0208     qint64 waitForMore(int msecs, bool *timeout = nullptr) override;
0209 
0210     /**
0211      * Returns this socket's local address.
0212      */
0213     KSocketAddress localAddress() const override;
0214 
0215     /**
0216      * Returns this socket's peer address. If this implementation does proxying
0217      * of some sort, this is the real external address, not the proxy's address.
0218      */
0219     KSocketAddress peerAddress() const override;
0220 
0221     /**
0222      * Returns this socket's externally visible local address.
0223      *
0224      * If this socket has a local address visible externally different
0225      * from the normal local address (as returned by localAddress()), then
0226      * return it.
0227      *
0228      * Certain implementations will use proxies and thus have externally visible
0229      * addresses different from the local socket values. The default implementation
0230      * returns the same value as localAddress().
0231      *
0232      * @note This function may return an empty KSocketAddress. In that case, the
0233      *       externally visible address could/can not be determined.
0234      */
0235     KSocketAddress externalAddress() const override;
0236 
0237     /**
0238      * Returns a socket notifier for input on this socket.
0239      * The notifier is created only when requested. Whether
0240      * it is enabled or not depends on the implementation.
0241      *
0242      * This function might return NULL.
0243      */
0244     QSocketNotifier *readNotifier() const;
0245 
0246     /**
0247      * Returns a socket notifier for output on this socket.
0248      * The is created only when requested.
0249      *
0250      * This function might return NULL.
0251      */
0252     QSocketNotifier *writeNotifier() const;
0253 
0254     /**
0255      * Returns a socket notifier for exceptional events on this socket.
0256      * The is created only when requested.
0257      *
0258      * This function might return NULL.
0259      */
0260     QSocketNotifier *exceptionNotifier() const;
0261 
0262     /**
0263      * Reads data and the source address from this socket.
0264      */
0265     qint64 readData(char *data, qint64 maxlen, KSocketAddress *from = nullptr) override;
0266 
0267     /**
0268      * Peeks the data in the socket and the source address.
0269      */
0270     qint64 peekData(char *data, qint64 maxlen, KSocketAddress *from = nullptr) override;
0271 
0272     /**
0273      * Writes the given data to the given destination address.
0274      */
0275     qint64 writeData(const char *data, qint64 len,
0276                              const KSocketAddress *to = nullptr) override;
0277 
0278     /**
0279      * Executes a poll in the socket, via select(2) or poll(2).
0280      * The events polled are returned in the parameters pointers.
0281      * Set any of them to NULL to disable polling of that event.
0282      *
0283      * On exit, @p input, @p output and @p exception will contain
0284      * true if an event of that kind is waiting on the socket or false
0285      * if not. If a timeout occurred, set @p timedout to true (all other
0286      * parameters are necessarily set to false).
0287      *
0288      * @param input   if set, turns on polling for input events
0289      * @param output  if set, turns on polling for output events
0290      * @param exception   if set, turns on polling for exceptional events
0291      * @param timeout the time in milliseconds to wait for an event;
0292      *            0 for no wait and any negative value to wait forever
0293      * @param timedout    on exit, will contain true if the polling timed out
0294      * @return true if the poll call succeeded and false if an error occurred
0295      */
0296     virtual bool poll(bool *input, bool *output, bool *exception = nullptr,
0297                       int timeout = -1, bool *timedout = nullptr);
0298 
0299     /**
0300      * Shorter version to poll for any events in a socket. This call
0301      * polls for input, output and exceptional events in a socket but
0302      * does not return their states. This is useful if you need to wait for
0303      * any event, but don't need to know which; or for timeouts.
0304      *
0305      * @param timeout the time in milliseconds to wait for an event;
0306      *            0 for no wait and any negative value to wait forever
0307      * @param timedout    on exit, will contain true if the polling timed out
0308      * @return true if the poll call succeeded and false if an error occurred
0309      */
0310     bool poll(int timeout = -1, bool *timedout = nullptr);
0311 
0312 protected:
0313     /**
0314      * Special constructor. This constructor will cause the internal
0315      * socket device NOT to be set. Use this if your socket device class
0316      * takes another underlying socket device.
0317      *
0318      * @param parent  the parent, if any
0319      */
0320     KDELIBS4SUPPORT_DEPRECATED explicit KSocketDevice(bool, const KSocketBase *parent = nullptr);
0321 
0322     /**
0323      * Creates a socket notifier of the given type.
0324      *
0325      * This function is called by readNotifier(), writeNotifier() and
0326      * exceptionNotifier() when they need to create a socket notifier
0327      * (i.e., the first call to those functions after the socket is open).
0328      * After that call, those functions cache the socket notifier and will
0329      * not need to call this function again.
0330      *
0331      * Reimplement this function in your derived class if your socket type
0332      * requires a different kind of QSocketNotifier. The return value should
0333      * be deleteable with delete. (close() deletes them).
0334      *
0335      * @param type    the socket notifier type
0336      */
0337     virtual QSocketNotifier *createNotifier(QSocketNotifier::Type type) const;
0338 
0339 public:
0340     /**
0341      * Creates a new default KSocketDevice object given
0342      * the parent object.
0343      *
0344      * The capabilities flag indicates the desired capabilities the object being
0345      * created should possess. Those capabilities are not guaranteed: if no factory
0346      * can provide such an object, a default object will be created.
0347      *
0348      * @param parent  the KSocketBase parent
0349      */
0350     static KSocketDevice *createDefault(KSocketBase *parent);
0351 
0352     /**
0353      * @overload
0354      *
0355      * This will create an object only if the requested capabilities match.
0356      *
0357      * @param parent      the parent
0358      * @param capabilities    the requested capabilities
0359      */
0360     static KSocketDevice *createDefault(KSocketBase *parent, int capabilities);
0361 
0362     /**
0363      * Sets the default KSocketDevice implementation to use and
0364      * return the old factory.
0365      *
0366      * @param factory the factory object for the implementation
0367      */
0368     static KSocketDeviceFactoryBase *setDefaultImpl(KSocketDeviceFactoryBase *factory);
0369 
0370     /**
0371      * Adds a factory of KSocketDevice objects to the list, along with its
0372      * capabilities flag.
0373      */
0374     static void addNewImpl(KSocketDeviceFactoryBase *factory, int capabilities);
0375 
0376 private:
0377     KSocketDevice(const KSocketDevice &);
0378     KSocketDevice &operator=(const KSocketDevice &);
0379 
0380     KSocketDevicePrivate *const d;
0381 };
0382 
0383 /** @internal
0384  * This class provides functionality for creating and registering
0385  *  socket implementations.
0386  */
0387 class KSocketDeviceFactoryBase
0388 {
0389 public:
0390     KSocketDeviceFactoryBase() {}
0391     virtual ~KSocketDeviceFactoryBase() {}
0392 
0393     virtual KSocketDevice *create(KSocketBase *) const = 0;
0394 };
0395 
0396 /**
0397  * This class provides functionality for creating and registering
0398  * socket implementations.
0399  */
0400 template<class Impl>
0401 class KSocketDeviceFactory: public KSocketDeviceFactoryBase
0402 {
0403 public:
0404     KSocketDeviceFactory() {}
0405     ~KSocketDeviceFactory() override {}
0406 
0407     /** Create the socket implementation.
0408         @param parent Parent socket for this implementation
0409         @todo Who owns the parent afterwards?
0410     */
0411     KSocketDevice *create(KSocketBase *parent) const override
0412     {
0413         return new Impl(parent);
0414     }
0415 };
0416 
0417 }               // namespaces
0418 
0419 #endif