KDELibs4Support

k3socketdevice.h
1 /* -*- C++ -*-
2  * Copyright (C) 2003,2005 Thiago Macieira <[email protected]>
3  *
4  *
5  * Permission is hereby granted, free of charge, to any person obtaining
6  * a copy of this software and associated documentation files (the
7  * "Software"), to deal in the Software without restriction, including
8  * without limitation the rights to use, copy, modify, merge, publish,
9  * distribute, sublicense, and/or sell copies of the Software, and to
10  * permit persons to whom the Software is furnished to do so, subject to
11  * the following conditions:
12  *
13  * The above copyright notice and this permission notice shall be included
14  * in all copies or substantial portions of the Software.
15  *
16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
17  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
18  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
19  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
20  * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
21  * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
22  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
23  */
24 
25 #ifndef KSOCKETDEVICE_H
26 #define KSOCKETDEVICE_H
27 
28 #include <QSocketNotifier>
29 #include "k3socketbase.h"
30 
31 namespace KNetwork
32 {
33 
34 class KSocketDevice;
35 class KSocketDeviceFactoryBase;
36 
37 class KSocketDevicePrivate;
38 /** @class KSocketDevice k3socketdevice.h k3socketdevice.h
39  * @brief Low-level socket functionality.
40  *
41  * This class provides low-level socket functionality.
42  *
43  * Most users will prefer "cooked" interfaces like those of KStreamSocket or
44  * KServerSocket.
45  *
46  * Descended classes from this one provide some other kinds of socket functionality,
47  * like proxying or specific socket types.
48  *
49  * @author Thiago Macieira <[email protected]>
50  * @deprecated Use KSocketFactory or KLocalSocket instead
51  */
52 class KDELIBS4SUPPORT_DEPRECATED_EXPORT KSocketDevice: public KActiveSocketBase, public KPassiveSocketBase
53 {
54 public:
55  /**
56  * Capabilities for the socket implementation.
57  *
58  * KSocketDevice-derived classes can implement certain capabilities that are not
59  * available in the default class. These capabilities are described by these flags.
60  * The default KSocketDevice class has none of these capabilities.
61  *
62  * For the negative capabilities (inabilities, the CanNot* forms), when a capability
63  * is not present, the implementation will default to the original behaviour.
64  */
65  enum Capabilities {
66  /** Can connect to hostnames.
67  * If this flag is present, the string form of connect() can be used. */
68  CanConnectString = 0x01,
69 
70  /** Can bind to hostnames.
71  * If this flag is present, the string form of bind() can be used */
72  CanBindString = 0x02,
73 
74  /** Can not bind.
75  * If this flag is present, this implementation cannot bind */
76  CanNotBind = 0x04,
77 
78  /** Can not listen.
79  * If this flag is present, this implementation cannot listen */
80  CanNotListen = 0x08,
81 
82  /**
83  * Can send multicast as well as join/leave multicast groups.
84  */
85  CanMulticast = 0x10,
86 
87  /**
88  * Can not use datagrams.
89  * Note that this implies multicast capability not being available either.
90  */
91  CanNotUseDatagrams = 0x20
92  };
93 protected:
94  /// The socket file descriptor. It is used throughout the implementation
95  /// and subclasses.
96  int m_sockfd;
97 
98 public:
99  /**
100  * Default constructor.
101  *
102  * The parameter is used to specify which socket this object is used as
103  * a device for.
104  */
105  KDELIBS4SUPPORT_DEPRECATED explicit KSocketDevice(const KSocketBase * = nullptr, QObject *objparent = nullptr);
106 
107  /**
108  * Constructs a new object around an already-open socket.
109  *
110  * Note: you should write programs that create sockets through
111  * the classes whenever possible.
112  */
113  KDELIBS4SUPPORT_DEPRECATED explicit KSocketDevice(int fd, OpenMode mode = ReadWrite);
114 
115  /**
116  * QObject constructor
117  */
118  KSocketDevice(QObject *parent);
119 
120  /**
121  * Destructor. This closes the socket if it's open.
122  */
123  ~KSocketDevice() override;
124 
125  /**
126  * Returns the file descriptor for this socket.
127  */
128  int socket() const;
129 
130  /**
131  * Returns the set of capabilities this socket class implements.
132  * The set of capabilities is defined as an OR-ed mask of
133  * Capabilities bits.
134  *
135  * The default implementation is guaranteed to always return 0. That
136  * is, derived implementations always return bits where they differ
137  * from the system standard sockets.
138  */
139  virtual int capabilities() const;
140 
141  /**
142  * This implementation sets the options on the socket.
143  */
144  bool setSocketOptions(int opts) override;
145 
146  /**
147  * Closes the socket. Reimplemented from QIODevice.
148  *
149  * Use this function to close the socket this object is holding open.
150  */
151  void close() override;
152 
153  /**
154  * This call is not supported on sockets. Reimplemented from QIODevice.
155  */
156  virtual bool flush();
157 
158  /**
159  * Creates a socket but don't connect or bind anywhere.
160  * This function is the equivalent of the system call socket(2).
161  */
162  virtual bool create(int family, int type, int protocol);
163 
164  /**
165  * @overload
166  * Creates a socket but don't connect or bind anywhere.
167  */
168  bool create(const KResolverEntry &address);
169 
170  /**
171  * Binds this socket to the given address.
172  */
173  bool bind(const KResolverEntry &address) override;
174 
175  /**
176  * Puts this socket into listening mode.
177  */
178  bool listen(int backlog = 5) override; // 5 is arbitrary
179 
180  /**
181  * Connect to a remote host.
182  */
183  bool connect(const KResolverEntry &address,
184  OpenMode mode = ReadWrite) override;
185 
186  /**
187  * Accepts a new incoming connection.
188  * Note: this function returns a socket of type KSocketDevice.
189  */
190  KSocketDevice *accept() override;
191 
192  /**
193  * Disconnects this socket.
194  */
195  bool disconnect() override;
196 
197  /**
198  * Returns the number of bytes available for reading without blocking.
199  */
200  qint64 bytesAvailable() const override;
201 
202  /**
203  * Waits up to @p msecs for more data to be available on this socket.
204  *
205  * This function is a wrapper against poll(). This function will wait
206  * for any read events.
207  */
208  qint64 waitForMore(int msecs, bool *timeout = nullptr) override;
209 
210  /**
211  * Returns this socket's local address.
212  */
213  KSocketAddress localAddress() const override;
214 
215  /**
216  * Returns this socket's peer address. If this implementation does proxying
217  * of some sort, this is the real external address, not the proxy's address.
218  */
219  KSocketAddress peerAddress() const override;
220 
221  /**
222  * Returns this socket's externally visible local address.
223  *
224  * If this socket has a local address visible externally different
225  * from the normal local address (as returned by localAddress()), then
226  * return it.
227  *
228  * Certain implementations will use proxies and thus have externally visible
229  * addresses different from the local socket values. The default implementation
230  * returns the same value as localAddress().
231  *
232  * @note This function may return an empty KSocketAddress. In that case, the
233  * externally visible address could/can not be determined.
234  */
235  KSocketAddress externalAddress() const override;
236 
237  /**
238  * Returns a socket notifier for input on this socket.
239  * The notifier is created only when requested. Whether
240  * it is enabled or not depends on the implementation.
241  *
242  * This function might return NULL.
243  */
244  QSocketNotifier *readNotifier() const;
245 
246  /**
247  * Returns a socket notifier for output on this socket.
248  * The is created only when requested.
249  *
250  * This function might return NULL.
251  */
252  QSocketNotifier *writeNotifier() const;
253 
254  /**
255  * Returns a socket notifier for exceptional events on this socket.
256  * The is created only when requested.
257  *
258  * This function might return NULL.
259  */
260  QSocketNotifier *exceptionNotifier() const;
261 
262  /**
263  * Reads data and the source address from this socket.
264  */
265  qint64 readData(char *data, qint64 maxlen, KSocketAddress *from = nullptr) override;
266 
267  /**
268  * Peeks the data in the socket and the source address.
269  */
270  qint64 peekData(char *data, qint64 maxlen, KSocketAddress *from = nullptr) override;
271 
272  /**
273  * Writes the given data to the given destination address.
274  */
275  qint64 writeData(const char *data, qint64 len,
276  const KSocketAddress *to = nullptr) override;
277 
278  /**
279  * Executes a poll in the socket, via select(2) or poll(2).
280  * The events polled are returned in the parameters pointers.
281  * Set any of them to NULL to disable polling of that event.
282  *
283  * On exit, @p input, @p output and @p exception will contain
284  * true if an event of that kind is waiting on the socket or false
285  * if not. If a timeout occurred, set @p timedout to true (all other
286  * parameters are necessarily set to false).
287  *
288  * @param input if set, turns on polling for input events
289  * @param output if set, turns on polling for output events
290  * @param exception if set, turns on polling for exceptional events
291  * @param timeout the time in milliseconds to wait for an event;
292  * 0 for no wait and any negative value to wait forever
293  * @param timedout on exit, will contain true if the polling timed out
294  * @return true if the poll call succeeded and false if an error occurred
295  */
296  virtual bool poll(bool *input, bool *output, bool *exception = nullptr,
297  int timeout = -1, bool *timedout = nullptr);
298 
299  /**
300  * Shorter version to poll for any events in a socket. This call
301  * polls for input, output and exceptional events in a socket but
302  * does not return their states. This is useful if you need to wait for
303  * any event, but don't need to know which; or for timeouts.
304  *
305  * @param timeout the time in milliseconds to wait for an event;
306  * 0 for no wait and any negative value to wait forever
307  * @param timedout on exit, will contain true if the polling timed out
308  * @return true if the poll call succeeded and false if an error occurred
309  */
310  bool poll(int timeout = -1, bool *timedout = nullptr);
311 
312 protected:
313  /**
314  * Special constructor. This constructor will cause the internal
315  * socket device NOT to be set. Use this if your socket device class
316  * takes another underlying socket device.
317  *
318  * @param parent the parent, if any
319  */
320  KDELIBS4SUPPORT_DEPRECATED explicit KSocketDevice(bool, const KSocketBase *parent = nullptr);
321 
322  /**
323  * Creates a socket notifier of the given type.
324  *
325  * This function is called by readNotifier(), writeNotifier() and
326  * exceptionNotifier() when they need to create a socket notifier
327  * (i.e., the first call to those functions after the socket is open).
328  * After that call, those functions cache the socket notifier and will
329  * not need to call this function again.
330  *
331  * Reimplement this function in your derived class if your socket type
332  * requires a different kind of QSocketNotifier. The return value should
333  * be deleteable with delete. (close() deletes them).
334  *
335  * @param type the socket notifier type
336  */
337  virtual QSocketNotifier *createNotifier(QSocketNotifier::Type type) const;
338 
339 public:
340  /**
341  * Creates a new default KSocketDevice object given
342  * the parent object.
343  *
344  * The capabilities flag indicates the desired capabilities the object being
345  * created should possess. Those capabilities are not guaranteed: if no factory
346  * can provide such an object, a default object will be created.
347  *
348  * @param parent the KSocketBase parent
349  */
350  static KSocketDevice *createDefault(KSocketBase *parent);
351 
352  /**
353  * @overload
354  *
355  * This will create an object only if the requested capabilities match.
356  *
357  * @param parent the parent
358  * @param capabilities the requested capabilities
359  */
360  static KSocketDevice *createDefault(KSocketBase *parent, int capabilities);
361 
362  /**
363  * Sets the default KSocketDevice implementation to use and
364  * return the old factory.
365  *
366  * @param factory the factory object for the implementation
367  */
368  static KSocketDeviceFactoryBase *setDefaultImpl(KSocketDeviceFactoryBase *factory);
369 
370  /**
371  * Adds a factory of KSocketDevice objects to the list, along with its
372  * capabilities flag.
373  */
374  static void addNewImpl(KSocketDeviceFactoryBase *factory, int capabilities);
375 
376 private:
377  KSocketDevice(const KSocketDevice &);
378  KSocketDevice &operator=(const KSocketDevice &);
379 
380  KSocketDevicePrivate *const d;
381 };
382 
383 /** @internal
384  * This class provides functionality for creating and registering
385  * socket implementations.
386  */
388 {
389 public:
391  virtual ~KSocketDeviceFactoryBase() {}
392 
393  virtual KSocketDevice *create(KSocketBase *) const = 0;
394 };
395 
396 /**
397  * This class provides functionality for creating and registering
398  * socket implementations.
399  */
400 template<class Impl>
402 {
403 public:
405  ~KSocketDeviceFactory() override {}
406 
407  /** Create the socket implementation.
408  @param parent Parent socket for this implementation
409  @todo Who owns the parent afterwards?
410  */
411  KSocketDevice *create(KSocketBase *parent) const override
412  {
413  return new Impl(parent);
414  }
415 };
416 
417 } // namespaces
418 
419 #endif
Abstract class for active sockets.
Definition: k3socketbase.h:460
One resolution entry.
Definition: k3resolver.h:72
KSocketDevice * create(KSocketBase *parent) const override
Create the socket implementation.
A generic socket address.
A namespace to store all networking-related (socket) classes.
This class provides functionality for creating and registering socket implementations.
int m_sockfd
The socket file descriptor.
Capabilities
Capabilities for the socket implementation.
Low-level socket functionality.
Abstract base class for passive sockets.
Definition: k3socketbase.h:773
Basic socket functionality.
Definition: k3socketbase.h:86
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Mon Mar 8 2021 22:58:07 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.