1QSocketDevice(3qt)                                          QSocketDevice(3qt)
2
3
4

NAME

6       QSocketDevice - Platform-independent low-level socket API
7

SYNOPSIS

9       #include <qsocketdevice.h>
10
11       Inherits QIODevice.
12
13   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
52   Protected Members
53       void setError ( Error err )
54

DESCRIPTION

56       The QSocketDevice class provides a platform-independent low-level
57       socket API.
58
59       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
66       The essential purpose of the class is to provide a QIODevice that works
67       on sockets, wrapped in a platform-independent API.
68
69       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
75       See also QSocket, QSocketNotifier, QHostAddress, and Input/Output and
76       Networking.
77
78   Member Type Documentation

QSocketDevice::Error

80       This enum type describes the error states of QSocketDevice.
81
82       QSocketDevice::NoError - No error has occurred.
83
84       QSocketDevice::AlreadyBound - The device is already bound, according to
85       bind().
86
87       QSocketDevice::Inaccessible - The operating system or firewall
88       prohibited the action.
89
90       QSocketDevice::NoResources - The operating system ran out of a
91       resource.
92
93       QSocketDevice::InternalError - An internal error occurred in
94       QSocketDevice.
95
96       QSocketDevice::Impossible - An attempt was made to do something which
97       makes no sense. For example:
98
99                  ::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
105       QSocketDevice::NoFiles - The operating system will not let
106       QSocketDevice open another file.
107
108       QSocketDevice::ConnectionRefused - A connection attempt was rejected by
109       the peer.
110
111       QSocketDevice::NetworkFailure - There is a network failure.
112
113       QSocketDevice::UnknownError - The operating system did something
114       unexpected.
115

QSocketDevice::Protocol

117       This enum type describes the protocol family of the socket. Possible
118       values are:
119
120       QSocketDevice::IPv4 - The socket is an IPv4 socket.
121
122       QSocketDevice::IPv6 - The socket is an IPv6 socket.
123
124       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
129       See also protocol() and setSocket().
130

QSocketDevice::Type

132       This enum type describes the type of the socket:
133
134       QSocketDevice::Stream - a stream socket (TCP, usually)
135
136       QSocketDevice::Datagram - a datagram socket (UDP, usually)
137

MEMBER FUNCTION DOCUMENTATION

QSocketDevice::QSocketDevice ( Type type = Stream )

140       Creates a QSocketDevice object for a stream or datagram socket.
141
142       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
146       The socket is created as an IPv4 socket.
147
148       See also blocking() and protocol().
149

QSocketDevice::QSocketDevice ( Type type, Protocol protocol, int dummy )

151       Creates a QSocketDevice object for a stream or datagram socket.
152
153       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
157       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
162       The argument dummy is necessary for compatibility with some compilers.
163
164       See also blocking() and protocol().
165

QSocketDevice::QSocketDevice ( int socket, Type type )

167       Creates a QSocketDevice object for the existing socket socket.
168
169       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

QSocketDevice::~QSocketDevice () [virtual]

175       Destroys the socket device and closes the socket if it is open.
176

int QSocketDevice::accept () [virtual]

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
182       See also bind() and listen().
183

QHostAddress QSocketDevice::address () const

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

bool QSocketDevice::addressReusable () const

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
193       See also setAddressReusable().
194

bool QSocketDevice::bind ( const QHostAddress & address, Q_UINT16 port )

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
202       bind() is used by servers for setting up incoming connections. Call
203       bind() before listen().
204

bool QSocketDevice::blocking () const

206       Returns TRUE if the socket is valid and in blocking mode; otherwise
207       returns FALSE.
208
209       Note that this function does not set error().
210
211       Warning: On Windows, this function always returns TRUE since the
212       ioctlsocket() function is broken.
213
214       See also setBlocking() and isValid().
215

Q_LONG QSocketDevice::bytesAvailable () const

217       Returns the number of bytes available for reading, or -1 if an error
218       occurred.
219
220       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

bool QSocketDevice::connect ( const QHostAddress & addr, Q_UINT16 port )

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
233       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

Error QSocketDevice::error () const

238       Returns the first error seen.
239

bool QSocketDevice::isValid () const

241       Returns TRUE if this is a valid socket; otherwise returns FALSE.
242
243       See also socket().
244

bool QSocketDevice::listen ( int backlog ) [virtual]

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
250       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
254       See also bind() and accept().
255

QHostAddress QSocketDevice::peerAddress () const

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
261       Note that for Datagram sockets, this is the source port of the last
262       packet received.
263

Q_UINT16 QSocketDevice::peerPort () const

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
269       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

Q_UINT16 QSocketDevice::port () const

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
277       Note that Qt always uses native byte order, i.e. 67 is 67 in Qt; there
278       is no need to call htons().
279

Protocol QSocketDevice::protocol () const

281       Returns the socket's protocol family, which is one of Unknown, IPv4, or
282       IPv6.
283
284       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
290       See also Protocol and setSocket().
291

Q_LONG QSocketDevice::readBlock ( char * data, Q_ULONG maxlen ) [virtual]

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
298       Reimplemented from QIODevice.
299

int QSocketDevice::receiveBufferSize () const

301       Returns the size of the operating system receive buffer.
302
303       See also setReceiveBufferSize().
304

int QSocketDevice::sendBufferSize () const

306       Returns the size of the operating system send buffer.
307
308       See also setSendBufferSize().
309

void QSocketDevice::setAddressReusable ( bool enable ) [virtual]

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
315       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
320       See also addressReusable().
321

void QSocketDevice::setBlocking ( bool enable ) [virtual]

323       Makes the socket blocking if enable is TRUE or nonblocking if enable is
324       FALSE.
325
326       Sockets are blocking by default, but we recommend using nonblocking
327       socket operations, especially for GUI programs that need to be
328       responsive.
329
330       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
334       See also blocking() and isValid().
335

void QSocketDevice::setError ( Error err ) [protected]

337       Allows subclasses to set the error state to err.
338

void QSocketDevice::setReceiveBufferSize ( uint size ) [virtual]

340       Sets the size of the operating system receive buffer to size.
341
342       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
346       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

void QSocketDevice::setSendBufferSize ( uint size ) [virtual]

350       Sets the size of the operating system send buffer to size.
351
352       The operating system send buffer size effectively limits how much data
353       can be in transit at any one moment.
354
355       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

void QSocketDevice::setSocket ( int socket, Type type ) [virtual]

359       Sets the socket device to operate on the existing socket socket.
360
361       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
366       Any existing socket is closed.
367
368       See also isValid() and close().
369

int QSocketDevice::socket () const

371       Returns the socket number, or -1 if it is an invalid socket.
372
373       See also isValid() and type().
374

Type QSocketDevice::type () const

376       Returns the socket type which is either QSocketDevice::Stream or
377       QSocketDevice::Datagram.
378
379       See also socket().
380

Q_LONG QSocketDevice::waitForMore ( int msecs, bool * timeout = 0 ) const

382       Wait up to msecs milliseconds for more data to be available. If msecs
383       is -1 the call will block indefinitely.
384
385       Returns the number of bytes available for reading, or -1 if an error
386       occurred.
387
388       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
393       Warning: This is a blocking call and should be avoided in event driven
394       applications.
395
396       See also bytesAvailable().
397

Q_LONG QSocketDevice::writeBlock ( const char * data, Q_ULONG len ) [virtual]

399       Writes len bytes to the socket from data and returns the number of
400       bytes written. Returns -1 if an error occurred.
401
402       This is used for QSocketDevice::Stream sockets.
403
404       Reimplemented from QIODevice.
405

Q_LONG QSocketDevice::writeBlock ( const char * data, Q_ULONG len, const

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
411       Writes len bytes to the socket from data and returns the number of
412       bytes written. Returns -1 if an error occurred.
413
414       This is used for QSocketDevice::Datagram sockets. You must specify the
415       host and port of the destination of the data.
416
417

SEE ALSO

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

AUTHOR

428       Generated automatically from the source code.
429

BUGS

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
435       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
441       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).
444
445
446
447Trolltech AS                    2 February 2007             QSocketDevice(3qt)
Impressum