1QSocket(3qt)                                                      QSocket(3qt)
2
3
4

NAME

6       QSocket - Buffered TCP connection
7

SYNOPSIS

9       #include <qsocket.h>
10
11       Inherits QObject and QIODevice.
12
13   Public Members
14       enum Error { ErrConnectionRefused, ErrHostNotFound, ErrSocketRead }
15       QSocket ( QObject * parent = 0, const char * name = 0 )
16       virtual ~QSocket ()
17       enum State { Idle, HostLookup, Connecting, Connected, Closing,
18           Connection = Connected }
19       State state () const
20       int socket () const
21       virtual void setSocket ( int socket )
22       QSocketDevice * socketDevice ()
23       virtual void setSocketDevice ( QSocketDevice * device )
24       virtual void connectToHost ( const QString & host, Q_UINT16 port )
25       QString peerName () const
26       virtual bool open ( int m )
27       virtual void close ()
28       virtual void flush ()
29       virtual Offset size () const
30       virtual Offset at () const
31       virtual bool at ( Offset index )
32       virtual bool atEnd () const
33       Q_ULONG bytesAvailable () const
34       Q_ULONG waitForMore ( int msecs, bool * timeout ) const
35       Q_ULONG waitForMore ( int msecs ) const
36       Q_ULONG bytesToWrite () const
37       void clearPendingData ()
38       virtual Q_LONG readBlock ( char * data, Q_ULONG maxlen )
39       virtual Q_LONG writeBlock ( const char * data, Q_ULONG len )
40       virtual int getch ()
41       virtual int putch ( int ch )
42       virtual int ungetch ( int ch )
43       bool canReadLine () const
44       virtual QString readLine ()
45       Q_UINT16 port () const
46       Q_UINT16 peerPort () const
47       QHostAddress address () const
48       QHostAddress peerAddress () const
49       void setReadBufferSize ( Q_ULONG bufSize )
50       Q_ULONG readBufferSize () const
51
52   Signals
53       void hostFound ()
54       void connected ()
55       void connectionClosed ()
56       void delayedCloseFinished ()
57       void readyRead ()
58       void bytesWritten ( int nbytes )
59       void error ( int )
60

DESCRIPTION

62       The QSocket class provides a buffered TCP connection.
63
64       It provides a totally non-blocking QIODevice, and modifies and extends
65       the API of QIODevice with socket-specific code.
66
67       Note that a QApplication must have been constructed before this class
68       can be used.
69
70       The functions you're likely to call most are connectToHost(),
71       bytesAvailable(), canReadLine() and the ones it inherits from
72       QIODevice.
73
74       connectToHost() is the most-used function. As its name implies, it
75       opens a connection to a named host.
76
77       Most network protocols are either packet-oriented or line-oriented.
78       canReadLine() indicates whether a connection contains an entire unread
79       line or not, and bytesAvailable() returns the number of bytes available
80       for reading.
81
82       The signals error(), connected(), readyRead() and connectionClosed()
83       inform you of the progress of the connection. There are also some less
84       commonly used signals. hostFound() is emitted when connectToHost() has
85       finished its DNS lookup and is starting its TCP connection.
86       delayedCloseFinished() is emitted when close() succeeds. bytesWritten()
87       is emitted when QSocket moves data from its "to be written" queue into
88       the TCP implementation.
89
90       There are several access functions for the socket: state() returns
91       whether the object is idle, is doing a DNS lookup, is connecting, has
92       an operational connection, etc. address() and port() return the IP
93       address and port used for the connection. The peerAddress() and
94       peerPort() functions return the IP address and port used by the peer,
95       and peerName() returns the name of the peer (normally the name that was
96       passed to connectToHost()). socketDevice() returns a pointer to the
97       QSocketDevice used for this socket.
98
99       QSocket inherits QIODevice, and reimplements some functions. In
100       general, you can treat it as a QIODevice for writing, and mostly also
101       for reading. The match isn't perfect, since the QIODevice API is
102       designed for devices that are controlled by the same machine, and an
103       asynchronous peer-to-peer network connection isn't quite like that. For
104       example, there is nothing that matches QIODevice::size() exactly. The
105       documentation for open(), close(), flush(), size(), at(), atEnd(),
106       readBlock(), writeBlock(), getch(), putch(), ungetch() and readLine()
107       describes the differences in detail.
108
109       Warning: QSocket is not suitable for use in threads. If you need to
110       uses sockets in threads use the lower-level QSocketDevice class.
111
112       Warning: Because Qt doesn't use the native socketstream implementation
113       on Mac OS X, QSocket has an implicit transfer latency of 100ms. You can
114       achieve lower latency on Mac OS X by using QSocketDevice instead.
115
116       See also QSocketDevice, QHostAddress, QSocketNotifier, and Input/Output
117       and Networking.
118
119   Member Type Documentation

QSocket::Error

121       This enum specifies the possible errors:
122
123       QSocket::ErrConnectionRefused - if the connection was refused
124
125       QSocket::ErrHostNotFound - if the host was not found
126
127       QSocket::ErrSocketRead - if a read from the socket failed
128

QSocket::State

130       This enum defines the connection states:
131
132       QSocket::Idle - if there is no connection
133
134       QSocket::HostLookup - during a DNS lookup
135
136       QSocket::Connecting - during TCP connection establishment
137
138       QSocket::Connected - when there is an operational connection
139
140       QSocket::Closing - if the socket is closing down, but is not yet
141       closed.
142

MEMBER FUNCTION DOCUMENTATION

QSocket::QSocket ( QObject * parent = 0, const char * name = 0 )

145       Creates a QSocket object in QSocket::Idle state.
146
147       The parent and name arguments are passed on to the QObject constructor.
148
149       Note that a QApplication must have been constructed before sockets can
150       be used.
151

QSocket::~QSocket () [virtual]

153       Destroys the socket. Closes the connection if necessary.
154
155       See also close().
156

QHostAddress QSocket::address () const

158       Returns the host address of this socket. (This is normally the main IP
159       address of the host, but can be e.g. 127.0.0.1 for connections to
160       localhost.)
161

Offset QSocket::at () const [virtual]

163       Returns the current read index. Since QSocket is a sequential device,
164       the current read index is always zero.
165
166       Reimplemented from QIODevice.
167

bool QSocket::at ( Offset index ) [virtual]

169       This is an overloaded member function, provided for convenience. It
170       behaves essentially like the above function.
171
172       Moves the read index forward to index and returns TRUE if the operation
173       was successful; otherwise returns FALSE. Moving the index forward means
174       skipping incoming data.
175
176       Reimplemented from QIODevice.
177

bool QSocket::atEnd () const [virtual]

179       Returns TRUE if there is no more data to read; otherwise returns FALSE.
180
181       Reimplemented from QIODevice.
182

Q_ULONG QSocket::bytesAvailable () const

184       Returns the number of incoming bytes that can be read, i.e. the size of
185       the input buffer. Equivalent to size().
186
187       This function can trigger the readyRead() signal, if more data has
188       arrived on the socket.
189
190       See also bytesToWrite().
191
192       Example: network/networkprotocol/nntp.cpp.
193

Q_ULONG QSocket::bytesToWrite () const

195       Returns the number of bytes that are waiting to be written, i.e. the
196       size of the output buffer.
197
198       See also bytesAvailable() and clearPendingData().
199

void QSocket::bytesWritten ( int nbytes ) [signal]

201       This signal is emitted when data has been written to the network. The
202       nbytes parameter specifies how many bytes were written.
203
204       The bytesToWrite() function is often used in the same context; it
205       indicates how many buffered bytes there are left to write.
206
207       See also writeBlock() and bytesToWrite().
208

bool QSocket::canReadLine () const

210       Returns TRUE if it's possible to read an entire line of text from this
211       socket at this time; otherwise returns FALSE.
212
213       Note that if the peer closes the connection unexpectedly, this function
214       returns FALSE. This means that loops such as this won't work:
215
216               while( !socket->canReadLine() ) // WRONG
217                   ;
218
219       See also readLine().
220
221       Examples:
222

void QSocket::clearPendingData ()

224       Deletes the data that is waiting to be written. This is useful if you
225       want to close the socket without waiting for all the data to be
226       written.
227
228       See also bytesToWrite(), close(), and delayedCloseFinished().
229

void QSocket::close () [virtual]

231       Closes the socket.
232
233       The read buffer is cleared.
234
235       If the output buffer is empty, the state is set to QSocket::Idle and
236       the connection is terminated immediately. If the output buffer still
237       contains data to be written, QSocket goes into the QSocket::Closing
238       state and the rest of the data will be written. When all of the
239       outgoing data have been written, the state is set to QSocket::Idle and
240       the connection is terminated. At this point, the delayedCloseFinished()
241       signal is emitted.
242
243       If you don't want that the data of the output buffer is written, call
244       clearPendingData() before you call close().
245
246       See also state(), bytesToWrite(), and clearPendingData().
247
248       Examples:
249
250       Reimplemented from QIODevice.
251

void QSocket::connectToHost ( const QString & host, Q_UINT16 port ) [virtual]

253       Attempts to make a connection to host on the specified port and return
254       immediately.
255
256       Any connection or pending connection is closed immediately, and QSocket
257       goes into the HostLookup state. When the lookup succeeds, it emits
258       hostFound(), starts a TCP connection and goes into the Connecting
259       state. Finally, when the connection succeeds, it emits connected() and
260       goes into the Connected state. If there is an error at any point, it
261       emits error().
262
263       host may be an IP address in string form, or it may be a DNS name.
264       QSocket will do a normal DNS lookup if required. Note that port is in
265       native byte order, unlike some other libraries.
266
267       See also state().
268
269       Examples:
270

void QSocket::connected () [signal]

272       This signal is emitted after connectToHost() has been called and a
273       connection has been successfully established.
274
275       See also connectToHost() and connectionClosed().
276
277       Examples:
278

void QSocket::connectionClosed () [signal]

280       This signal is emitted when the other end has closed the connection.
281       The read buffers may contain buffered input data which you can read
282       after the connection was closed.
283
284       See also connectToHost() and close().
285
286       Examples:
287

void QSocket::delayedCloseFinished () [signal]

289       This signal is emitted when a delayed close is finished.
290
291       If you call close() and there is buffered output data to be written,
292       QSocket goes into the QSocket::Closing state and returns immediately.
293       It will then keep writing to the socket until all the data has been
294       written. Then, the delayedCloseFinished() signal is emitted.
295
296       See also close().
297
298       Examples:
299

void QSocket::error ( int ) [signal]

301       This signal is emitted after an error occurred. The parameter is the
302       Error value.
303
304       Examples:
305

void QSocket::flush () [virtual]

307       Implementation of the abstract virtual QIODevice::flush() function.
308
309       Reimplemented from QIODevice.
310

int QSocket::getch () [virtual]

312       Reads a single byte/character from the internal read buffer. Returns
313       the byte/character read, or -1 if there is nothing to be read.
314
315       See also bytesAvailable() and putch().
316
317       Reimplemented from QIODevice.
318

void QSocket::hostFound () [signal]

320       This signal is emitted after connectToHost() has been called and the
321       host lookup has succeeded.
322
323       See also connected().
324
325       Example: network/networkprotocol/nntp.cpp.
326

bool QSocket::open ( int m ) [virtual]

328       Opens the socket using the specified QIODevice file mode m. This
329       function is called automatically when needed and you should not call it
330       yourself.
331
332       See also close().
333
334       Reimplemented from QIODevice.
335

QHostAddress QSocket::peerAddress () const

337       Returns the address of the connected peer if the socket is in Connected
338       state; otherwise an empty QHostAddress is returned.
339

QString QSocket::peerName () const

341       Returns the host name as specified to the connectToHost() function. An
342       empty string is returned if none has been set.
343
344       Example: network/mail/smtp.cpp.
345

Q_UINT16 QSocket::peerPort () const

347       Returns the peer's host port number, normally as specified to the
348       connectToHost() function. If none has been set, this function returns
349       0.
350
351       Note that Qt always uses native byte order, i.e. 67 is 67 in Qt; there
352       is no need to call htons().
353

Q_UINT16 QSocket::port () const

355       Returns the host port number of this socket, in native byte order.
356

int QSocket::putch ( int ch ) [virtual]

358       Writes the character ch to the output buffer.
359
360       Returns ch, or -1 if an error occurred.
361
362       See also getch().
363
364       Reimplemented from QIODevice.
365

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

367       Reads maxlen bytes from the socket into data and returns the number of
368       bytes read. Returns -1 if an error occurred.
369
370       Example: network/networkprotocol/nntp.cpp.
371
372       Reimplemented from QIODevice.
373

Q_ULONG QSocket::readBufferSize () const

375       Returns the size of the read buffer.
376
377       See also setReadBufferSize().
378

QString QSocket::readLine () [virtual]

380       Returns a line of text including a terminating newline character (\n).
381       Returns "" if canReadLine() returns FALSE.
382
383       See also canReadLine().
384
385       Examples:
386

void QSocket::readyRead () [signal]

388       This signal is emitted every time there is new incoming data.
389
390       Bear in mind that new incoming data is only reported once; if you do
391       not read all the data, this class buffers the data and you can read it
392       later, but no signal is emitted unless new data arrives. A good
393       practice is to read all data in the slot connected to this signal
394       unless you are sure that you need to receive more data to be able to
395       process it.
396
397       See also readBlock(), readLine(), and bytesAvailable().
398
399       Examples:
400

void QSocket::setReadBufferSize ( Q_ULONG bufSize )

402       Sets the size of the QSocket's internal read buffer to bufSize.
403
404       Usually QSocket reads all data that is available from the operating
405       system's socket. If the buffer size is limited to a certain size, this
406       means that the QSocket class doesn't buffer more than this size of
407       data.
408
409       If the size of the read buffer is 0, the read buffer is unlimited and
410       all incoming data is buffered. This is the default.
411
412       If you read the data in the readyRead() signal, you shouldn't use this
413       option since it might slow down your program unnecessary. This option
414       is useful if you only need to read the data at certain points in time,
415       like in a realtime streaming application.
416
417       See also readBufferSize().
418

void QSocket::setSocket ( int socket ) [virtual]

420       Sets the socket to use socket and the state() to Connected. The socket
421       must already be connected.
422
423       This allows us to use the QSocket class as a wrapper for other socket
424       types (e.g. Unix Domain Sockets).
425
426       Example: network/httpd/httpd.cpp.
427

void QSocket::setSocketDevice ( QSocketDevice * device ) [virtual]

429       Sets the internal socket device to device. Passing a device of 0 will
430       cause the internal socket device to be used. Any existing connection
431       will be disconnected before using the new device.
432
433       The new device should not be connected before being associated with a
434       QSocket; after setting the socket call connectToHost() to make the
435       connection.
436
437       This function is useful if you need to subclass QSocketDevice and want
438       to use the QSocket API, for example, to implement Unix domain sockets.
439

Offset QSocket::size () const [virtual]

441       Returns the number of incoming bytes that can be read right now (like
442       bytesAvailable()).
443
444       Reimplemented from QIODevice.
445

int QSocket::socket () const

447       Returns the socket number, or -1 if there is no socket at the moment.
448

QSocketDevice * QSocket::socketDevice ()

450       Returns a pointer to the internal socket device.
451
452       There is normally no need to manipulate the socket device directly
453       since this class does the necessary setup for most applications.
454

State QSocket::state () const

456       Returns the current state of the socket connection.
457
458       See also QSocket::State.
459
460       Examples:
461

int QSocket::ungetch ( int ch ) [virtual]

463       This implementation of the virtual function QIODevice::ungetch()
464       prepends the character ch to the read buffer so that the next read
465       returns this character as the first character of the output.
466
467       Reimplemented from QIODevice.
468

Q_ULONG QSocket::waitForMore ( int msecs, bool * timeout ) const

470       Wait up to msecs milliseconds for more data to be available.
471
472       If msecs is -1 the call will block indefinitely.
473
474       Returns the number of bytes available.
475
476       If timeout is non-null and no error occurred (i.e. it does not return
477       -1): this function sets *timeout to TRUE, if the reason for returning
478       was that the timeout was reached; otherwise it sets *timeout to FALSE.
479       This is useful to find out if the peer closed the connection.
480
481       Warning: This is a blocking call and should be avoided in event driven
482       applications.
483
484       See also bytesAvailable().
485

Q_ULONG QSocket::waitForMore ( int msecs ) const

487       This is an overloaded member function, provided for convenience. It
488       behaves essentially like the above function.
489

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

491       Writes len bytes to the socket from data and returns the number of
492       bytes written. Returns -1 if an error occurred.
493
494       Example: network/networkprotocol/nntp.cpp.
495
496       Reimplemented from QIODevice.
497
498

SEE ALSO

500       http://doc.trolltech.com/qsocket.html
501       http://www.trolltech.com/faq/tech.html
502
504       Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
505       license file included in the distribution for a complete license
506       statement.
507

AUTHOR

509       Generated automatically from the source code.
510

BUGS

512       If you find a bug in Qt, please report it as described in
513       http://doc.trolltech.com/bughowto.html.  Good bug reports help us to
514       help you. Thank you.
515
516       The definitive Qt documentation is provided in HTML format; it is
517       located at $QTDIR/doc/html and can be read using Qt Assistant or with a
518       web browser. This man page is provided as a convenience for those users
519       who prefer man pages, although this format is not officially supported
520       by Trolltech.
521
522       If you find errors in this manual page, please report them to qt-
523       bugs@trolltech.com.  Please include the name of the manual page
524       (qsocket.3qt) and the Qt version (3.3.8).
525
526
527
528Trolltech AS                    2 February 2007                   QSocket(3qt)
Impressum