File indexing completed on 2025-02-02 14:10:45
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