1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
|
/* -*- 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 QMutex;
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.
*/
virtual Offset size() const
{ 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.
*/
virtual Q_LONG bytesAvailable() const = 0;
/**
* 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 Q_LONG waitForMore(int msecs, bool *timeout = 0L) = 0;
/**
* Reads data from the socket.
*
* Reimplemented from TQIODevice. See TQIODevice::readBlock for
* more information.
*/
virtual Q_LONG readBlock(char *data, Q_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 Q_LONG readBlock(char *data, Q_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 Q_LONG peekBlock(char *data, Q_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 Q_LONG peekBlock(char *data, Q_ULONG maxlen, KSocketAddress& from) = 0;
/**
* Writes the given data to the socket.
*
* Reimplemented from TQIODevice. See TQIODevice::writeBlock for
* more information.
*/
virtual Q_LONG writeBlock(const char *data, Q_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 Q_LONG writeBlock(const char *data, Q_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
|