1QSocketDevice(3qt) QSocketDevice(3qt)
2
6 QSocketDevice - Platform-independent low-level socket API
7
9 #include <qsocketdevice.h>
10 Inherits QIODevice.
12 Public Members
14 enum Type { Stream, Datagram }
15 enum Protocol { IPv4, IPv6, Unknown }
16 QSocketDevice ( Type type = Stream )
17 QSocketDevice ( Type type, Protocol protocol, int dummy )
18 QSocketDevice ( int socket, Type type )
19 virtual ~QSocketDevice ()
20 bool isValid () const
21 Type type () const
22 Protocol protocol () const
23 int socket () const
24 virtual void setSocket ( int socket, Type type )
25 bool blocking () const
26 virtual void setBlocking ( bool enable )
27 bool addressReusable () const
28 virtual void setAddressReusable ( bool enable )
29 int receiveBufferSize () const
30 virtual void setReceiveBufferSize ( uint size )
31 int sendBufferSize () const
32 virtual void setSendBufferSize ( uint size )
33 virtual bool connect ( const QHostAddress & addr, Q_UINT16 port )
34 virtual bool bind ( const QHostAddress & address, Q_UINT16 port )
35 virtual bool listen ( int backlog )
36 virtual int accept ()
37 Q_LONG bytesAvailable () const
38 Q_LONG waitForMore ( int msecs, bool * timeout = 0 ) const
39 virtual Q_LONG readBlock ( char * data, Q_ULONG maxlen )
40 virtual Q_LONG writeBlock ( const char * data, Q_ULONG len )
41 virtual Q_LONG writeBlock ( const char * data, Q_ULONG len, const
42 QHostAddress & host, Q_UINT16 port )
43 Q_UINT16 port () const
44 Q_UINT16 peerPort () const
45 QHostAddress address () const
46 QHostAddress peerAddress () const
47 enum Error { NoError, AlreadyBound, Inaccessible, NoResources,
48 InternalError, Bug = InternalError, Impossible, NoFiles,
49 ConnectionRefused, NetworkFailure, UnknownError }
50 Error error () const
51 Protected Members
53 void setError ( Error err )
54
56 The QSocketDevice class provides a platform-independent low-level
57 socket API.
58 This class provides a low level API for working with sockets. Users of
60 this class are assumed to have networking experience. For most users
61 the QSocket class provides a much easier and high level alternative,
62 but certain things (like UDP) can't be done with QSocket and if you
63 need a platform-independent API for those, QSocketDevice is the right
64 choice.
65 The essential purpose of the class is to provide a QIODevice that works
67 on sockets, wrapped in a platform-independent API.
68 When calling connect() or bind(), QSocketDevice detects the protocol
70 family (IPv4, IPv6) automatically. Passing the protocol family to
71 QSocketDevice's constructor or to setSocket() forces creation of a
72 socket device of a specific protocol. If not set, the protocol will be
73 detected at the first call to connect() or bind().
74 See also QSocket, QSocketNotifier, QHostAddress, and Input/Output and
76 Networking.
77 Member Type Documentation
80 This enum type describes the error states of QSocketDevice.
81 QSocketDevice::NoError - No error has occurred.
83 QSocketDevice::AlreadyBound - The device is already bound, according to
85 bind().
86 QSocketDevice::Inaccessible - The operating system or firewall
88 prohibited the action.
89 QSocketDevice::NoResources - The operating system ran out of a
91 resource.
92 QSocketDevice::InternalError - An internal error occurred in
94 QSocketDevice.
95 QSocketDevice::Impossible - An attempt was made to do something which
97 makes no sense. For example:
98 ::close( sd->socket() );
100 sd->writeBlock( someData, 42 );
101 The libc ::close() closes the socket, but QSocketDevice is not
102 aware of this. So when you call writeBlock(), the impossible
103 happens.
104 QSocketDevice::NoFiles - The operating system will not let
106 QSocketDevice open another file.
107 QSocketDevice::ConnectionRefused - A connection attempt was rejected by
109 the peer.
110 QSocketDevice::NetworkFailure - There is a network failure.
112 QSocketDevice::UnknownError - The operating system did something
114 unexpected.
115
117 This enum type describes the protocol family of the socket. Possible
118 values are:
119 QSocketDevice::IPv4 - The socket is an IPv4 socket.
121 QSocketDevice::IPv6 - The socket is an IPv6 socket.
123 QSocketDevice::Unknown - The protocol family of the socket is not
125 known. This can happen if you use QSocketDevice with an already
126 existing socket; it tries to determine the protocol family, but this
127 can fail if the protocol family is not known to QSocketDevice.
128 See also protocol() and setSocket().
130
132 This enum type describes the type of the socket:
133 QSocketDevice::Stream - a stream socket (TCP, usually)
135 QSocketDevice::Datagram - a datagram socket (UDP, usually)
137
140 Creates a QSocketDevice object for a stream or datagram socket.
141 The type argument must be either QSocketDevice::Stream for a reliable,
143 connection-oriented TCP socket, or QSocketDevice::Datagram for an
144 unreliable UDP socket.
145 The socket is created as an IPv4 socket.
147 See also blocking() and protocol().
149
151 Creates a QSocketDevice object for a stream or datagram socket.
152 The type argument must be either QSocketDevice::Stream for a reliable,
154 connection-oriented TCP socket, or QSocketDevice::Datagram for an
155 unreliable UDP socket.
156 The protocol indicates whether the socket should be of type IPv4 or
158 IPv6. Passing Unknown is not meaningful in this context and you should
159 avoid using (it creates an IPv4 socket, but your code is not easily
160 readable).
161 The argument dummy is necessary for compatibility with some compilers.
163 See also blocking() and protocol().
165
167 Creates a QSocketDevice object for the existing socket socket.
168 The type argument must match the actual socket type; use
170 QSocketDevice::Stream for a reliable, connection-oriented TCP socket,
171 or QSocketDevice::Datagram for an unreliable, connectionless UDP
172 socket.
173
175 Destroys the socket device and closes the socket if it is open.
176
178 Extracts the first connection from the queue of pending connections for
179 this socket and returns a new socket identifier. Returns -1 if the
180 operation failed.
181 See also bind() and listen().
183
185 Returns the address of this socket device. This may be 0.0.0.0 for a
186 while, but is set to something sensible as soon as a sensible value is
187 available.
188
190 Returns TRUE if the address of this socket can be used by other sockets
191 at the same time, and FALSE if this socket claims exclusive ownership.
192 See also setAddressReusable().
194
196 [virtual]
197 Assigns a name to an unnamed socket. The name is the host address
198 address and the port number port. If the operation succeeds, bind()
199 returns TRUE; otherwise it returns FALSE without changing what port()
200 and address() return.
201 bind() is used by servers for setting up incoming connections. Call
203 bind() before listen().
204
206 Returns TRUE if the socket is valid and in blocking mode; otherwise
207 returns FALSE.
208 Note that this function does not set error().
210 Warning: On Windows, this function always returns TRUE since the
212 ioctlsocket() function is broken.
213 See also setBlocking() and isValid().
215
217 Returns the number of bytes available for reading, or -1 if an error
218 occurred.
219 Warning: On Microsoft Windows, we use the ioctlsocket() function to
221 determine the number of bytes queued on the socket. According to
222 Microsoft (KB Q125486), ioctlsocket() sometimes returns an incorrect
223 number. The only safe way to determine the amount of data on the socket
224 is to read it using readBlock(). QSocket has workarounds to deal with
225 this problem.
226
228 [virtual]
229 Connects to the IP address and port specified by addr and port. Returns
230 TRUE if it establishes a connection; otherwise returns FALSE. If it
231 returns FALSE, error() explains why.
232 Note that error() commonly returns NoError for non-blocking sockets;
234 this just means that you can call connect() again in a little while and
235 it'll probably succeed.
236
238 Returns the first error seen.
239
241 Returns TRUE if this is a valid socket; otherwise returns FALSE.
242 See also socket().
244
246 Specifies how many pending connections a server socket can have.
247 Returns TRUE if the operation was successful; otherwise returns FALSE.
248 A backlog value of 50 is quite common.
249 The listen() call only applies to sockets where type() is Stream, i.e.
251 not to Datagram sockets. listen() must not be called before bind() or
252 after accept().
253 See also bind() and accept().
255
257 Returns the address of the port this socket device is connected to.
258 This may be 0.0.0.0 for a while, but is set to something sensible as
259 soon as a sensible value is available.
260 Note that for Datagram sockets, this is the source port of the last
262 packet received.
263
265 Returns the port number of the port this socket device is connected to.
266 This may be 0 for a while, but is set to something sensible as soon as
267 a sensible value is available.
268 Note that for Datagram sockets, this is the source port of the last
270 packet received, and that it is in native byte order.
271
273 Returns the port number of this socket device. This may be 0 for a
274 while, but is set to something sensible as soon as a sensible value is
275 available.
276 Note that Qt always uses native byte order, i.e. 67 is 67 in Qt; there
278 is no need to call htons().
279
281 Returns the socket's protocol family, which is one of Unknown, IPv4, or
282 IPv6.
283 QSocketDevice either creates a socket with a well known protocol family
285 or it uses an already existing socket. In the first case, this function
286 returns the protocol family it was constructed with. In the second
287 case, it tries to determine the protocol family of the socket; if this
288 fails, it returns Unknown.
289 See also Protocol and setSocket().
291
293 Reads maxlen bytes from the socket into data and returns the number of
294 bytes read. Returns -1 if an error occurred. Returning 0 is not an
295 error. For Stream sockets, 0 is returned when the remote host closes
296 the connection. For Datagram sockets, 0 is a valid datagram size.
297 Reimplemented from QIODevice.
299
301 Returns the size of the operating system receive buffer.
302 See also setReceiveBufferSize().
304
306 Returns the size of the operating system send buffer.
307 See also setSendBufferSize().
309
311 Sets the address of this socket to be usable by other sockets too if
312 enable is TRUE, and to be used exclusively by this socket if enable is
313 FALSE.
314 When a socket is reusable, other sockets can use the same port number
316 (and IP address), which is generally useful. Of course other sockets
317 cannot use the same (address,port,peer-address,peer-port) 4-tuple as
318 this socket, so there is no risk of confusing the two TCP connections.
319 See also addressReusable().
321
323 Makes the socket blocking if enable is TRUE or nonblocking if enable is
324 FALSE.
325 Sockets are blocking by default, but we recommend using nonblocking
327 socket operations, especially for GUI programs that need to be
328 responsive.
329 Warning: On Windows, this function should be used with care since
331 whenever you use a QSocketNotifier on Windows, the socket is
332 immediately made nonblocking.
333 See also blocking() and isValid().
335
337 Allows subclasses to set the error state to err.
338
340 Sets the size of the operating system receive buffer to size.
341 The operating system receive buffer size effectively limits two things:
343 how much data can be in transit at any one moment, and how much data
344 can be received in one iteration of the main event loop.
345 The default is operating system-dependent. A socket that receives large
347 amounts of data is probably best with a buffer size of 49152.
348
350 Sets the size of the operating system send buffer to size.
351 The operating system send buffer size effectively limits how much data
353 can be in transit at any one moment.
354 The default is operating system-dependent. A socket that sends large
356 amounts of data is probably best with a buffer size of 49152.
357
359 Sets the socket device to operate on the existing socket socket.
360 The type argument must match the actual socket type; use
362 QSocketDevice::Stream for a reliable, connection-oriented TCP socket,
363 or QSocketDevice::Datagram for an unreliable, connectionless UDP
364 socket.
365 Any existing socket is closed.
367 See also isValid() and close().
369
371 Returns the socket number, or -1 if it is an invalid socket.
372 See also isValid() and type().
374
376 Returns the socket type which is either QSocketDevice::Stream or
377 QSocketDevice::Datagram.
378 See also socket().
380
382 Wait up to msecs milliseconds for more data to be available. If msecs
383 is -1 the call will block indefinitely.
384 Returns the number of bytes available for reading, or -1 if an error
386 occurred.
387 If timeout is non-null and no error occurred (i.e. it does not return
389 -1): this function sets *timeout to TRUE, if the reason for returning
390 was that the timeout was reached; otherwise it sets *timeout to FALSE.
391 This is useful to find out if the peer closed the connection.
392 Warning: This is a blocking call and should be avoided in event driven
394 applications.
395 See also bytesAvailable().
397
399 Writes len bytes to the socket from data and returns the number of
400 bytes written. Returns -1 if an error occurred.
401 This is used for QSocketDevice::Stream sockets.
403 Reimplemented from QIODevice.
405
407 QHostAddress & host, Q_UINT16 port ) [virtual]
408 This is an overloaded member function, provided for convenience. It
409 behaves essentially like the above function.
410 Writes len bytes to the socket from data and returns the number of
412 bytes written. Returns -1 if an error occurred.
413 This is used for QSocketDevice::Datagram sockets. You must specify the
415 host and port of the destination of the data.
416
419 http://doc.trolltech.com/qsocketdevice.html
420 http://www.trolltech.com/faq/tech.html
421
423 Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com. See the
424 license file included in the distribution for a complete license
425 statement.
426
428 Generated automatically from the source code.
429
431 If you find a bug in Qt, please report it as described in
432 http://doc.trolltech.com/bughowto.html. Good bug reports help us to
433 help you. Thank you.
434 The definitive Qt documentation is provided in HTML format; it is
436 located at $QTDIR/doc/html and can be read using Qt Assistant or with a
437 web browser. This man page is provided as a convenience for those users
438 who prefer man pages, although this format is not officially supported
439 by Trolltech.
440 If you find errors in this manual page, please report them to qt-
442 bugs@trolltech.com. Please include the name of the manual page
443 (qsocketdevice.3qt) and the Qt version (3.3.8).
444Trolltech AS 2 February 2007 QSocketDevice(3qt)