| 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
|---|
| 2 | <!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/src/network/qsocket.cpp:223 -->
|
|---|
| 3 | <html>
|
|---|
| 4 | <head>
|
|---|
| 5 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
|---|
| 6 | <title>QSocket Class</title>
|
|---|
| 7 | <style type="text/css"><!--
|
|---|
| 8 | fn { margin-left: 1cm; text-indent: -1cm; }
|
|---|
| 9 | a:link { color: #004faf; text-decoration: none }
|
|---|
| 10 | a:visited { color: #672967; text-decoration: none }
|
|---|
| 11 | body { background: #ffffff; color: black; }
|
|---|
| 12 | --></style>
|
|---|
| 13 | </head>
|
|---|
| 14 | <body>
|
|---|
| 15 |
|
|---|
| 16 | <table border="0" cellpadding="0" cellspacing="0" width="100%">
|
|---|
| 17 | <tr bgcolor="#E5E5E5">
|
|---|
| 18 | <td valign=center>
|
|---|
| 19 | <a href="index.html">
|
|---|
| 20 | <font color="#004faf">Home</font></a>
|
|---|
| 21 | | <a href="classes.html">
|
|---|
| 22 | <font color="#004faf">All Classes</font></a>
|
|---|
| 23 | | <a href="mainclasses.html">
|
|---|
| 24 | <font color="#004faf">Main Classes</font></a>
|
|---|
| 25 | | <a href="annotated.html">
|
|---|
| 26 | <font color="#004faf">Annotated</font></a>
|
|---|
| 27 | | <a href="groups.html">
|
|---|
| 28 | <font color="#004faf">Grouped Classes</font></a>
|
|---|
| 29 | | <a href="functions.html">
|
|---|
| 30 | <font color="#004faf">Functions</font></a>
|
|---|
| 31 | </td>
|
|---|
| 32 | <td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>QSocket Class Reference<br><small>[<a href="network.html">network module</a>]</small></h1>
|
|---|
| 33 |
|
|---|
| 34 | <p>The QSocket class provides a buffered TCP connection.
|
|---|
| 35 | <a href="#details">More...</a>
|
|---|
| 36 | <p><tt>#include <<a href="qsocket-h.html">qsocket.h</a>></tt>
|
|---|
| 37 | <p>Inherits <a href="qobject.html">QObject</a> and <a href="qiodevice.html">QIODevice</a>.
|
|---|
| 38 | <p><a href="qsocket-members.html">List of all member functions.</a>
|
|---|
| 39 | <h2>Public Members</h2>
|
|---|
| 40 | <ul>
|
|---|
| 41 | <li class=fn>enum <a href="#Error-enum"><b>Error</b></a> { ErrConnectionRefused, ErrHostNotFound, ErrSocketRead }</li>
|
|---|
| 42 | <li class=fn><a href="#QSocket"><b>QSocket</b></a> ( QObject * parent = 0, const char * name = 0 )</li>
|
|---|
| 43 | <li class=fn>virtual <a href="#~QSocket"><b>~QSocket</b></a> ()</li>
|
|---|
| 44 | <li class=fn>enum <a href="#State-enum"><b>State</b></a> { Idle, HostLookup, Connecting, Connected, Closing, Connection = Connected }</li>
|
|---|
| 45 | <li class=fn>State <a href="#state"><b>state</b></a> () const</li>
|
|---|
| 46 | <li class=fn>int <a href="#socket"><b>socket</b></a> () const</li>
|
|---|
| 47 | <li class=fn>virtual void <a href="#setSocket"><b>setSocket</b></a> ( int socket )</li>
|
|---|
| 48 | <li class=fn>QSocketDevice * <a href="#socketDevice"><b>socketDevice</b></a> ()</li>
|
|---|
| 49 | <li class=fn>virtual void <a href="#setSocketDevice"><b>setSocketDevice</b></a> ( QSocketDevice * device )</li>
|
|---|
| 50 | <li class=fn>virtual void <a href="#connectToHost"><b>connectToHost</b></a> ( const QString & host, Q_UINT16 port )</li>
|
|---|
| 51 | <li class=fn>QString <a href="#peerName"><b>peerName</b></a> () const</li>
|
|---|
| 52 | <li class=fn>virtual bool <a href="#open"><b>open</b></a> ( int m )</li>
|
|---|
| 53 | <li class=fn>virtual void <a href="#close"><b>close</b></a> ()</li>
|
|---|
| 54 | <li class=fn>virtual void <a href="#flush"><b>flush</b></a> ()</li>
|
|---|
| 55 | <li class=fn>virtual Offset <a href="#size"><b>size</b></a> () const</li>
|
|---|
| 56 | <li class=fn>virtual Offset <a href="#at"><b>at</b></a> () const</li>
|
|---|
| 57 | <li class=fn>virtual bool <a href="#at-2"><b>at</b></a> ( Offset index )</li>
|
|---|
| 58 | <li class=fn>virtual bool <a href="#atEnd"><b>atEnd</b></a> () const</li>
|
|---|
| 59 | <li class=fn>Q_ULONG <a href="#bytesAvailable"><b>bytesAvailable</b></a> () const</li>
|
|---|
| 60 | <li class=fn>Q_ULONG <a href="#waitForMore"><b>waitForMore</b></a> ( int msecs, bool * timeout ) const</li>
|
|---|
| 61 | <li class=fn>Q_ULONG <a href="#waitForMore-2"><b>waitForMore</b></a> ( int msecs ) const</li>
|
|---|
| 62 | <li class=fn>Q_ULONG <a href="#bytesToWrite"><b>bytesToWrite</b></a> () const</li>
|
|---|
| 63 | <li class=fn>void <a href="#clearPendingData"><b>clearPendingData</b></a> ()</li>
|
|---|
| 64 | <li class=fn>virtual Q_LONG <a href="#readBlock"><b>readBlock</b></a> ( char * data, Q_ULONG maxlen )</li>
|
|---|
| 65 | <li class=fn>virtual Q_LONG <a href="#writeBlock"><b>writeBlock</b></a> ( const char * data, Q_ULONG len )</li>
|
|---|
| 66 | <li class=fn>virtual int <a href="#getch"><b>getch</b></a> ()</li>
|
|---|
| 67 | <li class=fn>virtual int <a href="#putch"><b>putch</b></a> ( int ch )</li>
|
|---|
| 68 | <li class=fn>virtual int <a href="#ungetch"><b>ungetch</b></a> ( int ch )</li>
|
|---|
| 69 | <li class=fn>bool <a href="#canReadLine"><b>canReadLine</b></a> () const</li>
|
|---|
| 70 | <li class=fn>virtual QString <a href="#readLine"><b>readLine</b></a> ()</li>
|
|---|
| 71 | <li class=fn>Q_UINT16 <a href="#port"><b>port</b></a> () const</li>
|
|---|
| 72 | <li class=fn>Q_UINT16 <a href="#peerPort"><b>peerPort</b></a> () const</li>
|
|---|
| 73 | <li class=fn>QHostAddress <a href="#address"><b>address</b></a> () const</li>
|
|---|
| 74 | <li class=fn>QHostAddress <a href="#peerAddress"><b>peerAddress</b></a> () const</li>
|
|---|
| 75 | <li class=fn>void <a href="#setReadBufferSize"><b>setReadBufferSize</b></a> ( Q_ULONG bufSize )</li>
|
|---|
| 76 | <li class=fn>Q_ULONG <a href="#readBufferSize"><b>readBufferSize</b></a> () const</li>
|
|---|
| 77 | </ul>
|
|---|
| 78 | <h2>Signals</h2>
|
|---|
| 79 | <ul>
|
|---|
| 80 | <li class=fn>void <a href="#hostFound"><b>hostFound</b></a> ()</li>
|
|---|
| 81 | <li class=fn>void <a href="#connected"><b>connected</b></a> ()</li>
|
|---|
| 82 | <li class=fn>void <a href="#connectionClosed"><b>connectionClosed</b></a> ()</li>
|
|---|
| 83 | <li class=fn>void <a href="#delayedCloseFinished"><b>delayedCloseFinished</b></a> ()</li>
|
|---|
| 84 | <li class=fn>void <a href="#readyRead"><b>readyRead</b></a> ()</li>
|
|---|
| 85 | <li class=fn>void <a href="#bytesWritten"><b>bytesWritten</b></a> ( int nbytes )</li>
|
|---|
| 86 | <li class=fn>void <a href="#error"><b>error</b></a> ( int )</li>
|
|---|
| 87 | </ul>
|
|---|
| 88 | <hr><a name="details"></a><h2>Detailed Description</h2>
|
|---|
| 89 |
|
|---|
| 90 |
|
|---|
| 91 | The QSocket class provides a buffered TCP connection.
|
|---|
| 92 |
|
|---|
| 93 | <p>
|
|---|
| 94 |
|
|---|
| 95 | <p> It provides a totally non-blocking <a href="qiodevice.html">QIODevice</a>, and modifies and
|
|---|
| 96 | extends the API of QIODevice with socket-specific code.
|
|---|
| 97 | <p> Note that a <a href="qapplication.html">QApplication</a> must have been constructed before this
|
|---|
| 98 | class can be used.
|
|---|
| 99 | <p> The functions you're likely to call most are <a href="#connectToHost">connectToHost</a>(),
|
|---|
| 100 | <a href="#bytesAvailable">bytesAvailable</a>(), <a href="#canReadLine">canReadLine</a>() and the ones it inherits from
|
|---|
| 101 | QIODevice.
|
|---|
| 102 | <p> connectToHost() is the most-used function. As its name implies,
|
|---|
| 103 | it opens a connection to a named host.
|
|---|
| 104 | <p> Most network protocols are either packet-oriented or
|
|---|
| 105 | line-oriented. canReadLine() indicates whether a connection
|
|---|
| 106 | contains an entire unread line or not, and bytesAvailable()
|
|---|
| 107 | returns the number of bytes available for reading.
|
|---|
| 108 | <p> The signals <a href="#error">error</a>(), <a href="#connected">connected</a>(), <a href="#readyRead">readyRead</a>() and
|
|---|
| 109 | <a href="#connectionClosed">connectionClosed</a>() inform you of the progress of the connection.
|
|---|
| 110 | There are also some less commonly used signals. <a href="#hostFound">hostFound</a>() is
|
|---|
| 111 | emitted when connectToHost() has finished its DNS lookup and is
|
|---|
| 112 | starting its TCP connection. <a href="#delayedCloseFinished">delayedCloseFinished</a>() is emitted
|
|---|
| 113 | when <a href="#close">close</a>() succeeds. <a href="#bytesWritten">bytesWritten</a>() is emitted when QSocket
|
|---|
| 114 | moves data from its "to be written" queue into the TCP
|
|---|
| 115 | implementation.
|
|---|
| 116 | <p> There are several access functions for the socket: <a href="#state">state</a>() returns
|
|---|
| 117 | whether the object is idle, is doing a DNS lookup, is connecting,
|
|---|
| 118 | has an operational connection, etc. <a href="#address">address</a>() and <a href="#port">port</a>() return
|
|---|
| 119 | the IP address and port used for the connection. The <a href="#peerAddress">peerAddress</a>()
|
|---|
| 120 | and <a href="#peerPort">peerPort</a>() functions return the IP address and port used by
|
|---|
| 121 | the peer, and <a href="#peerName">peerName</a>() returns the name of the peer (normally
|
|---|
| 122 | the name that was passed to <a href="#connectToHost">connectToHost</a>()). <a href="#socketDevice">socketDevice</a>()
|
|---|
| 123 | returns a pointer to the <a href="qsocketdevice.html">QSocketDevice</a> used for this socket.
|
|---|
| 124 | <p> QSocket inherits <a href="qiodevice.html">QIODevice</a>, and reimplements some functions. In
|
|---|
| 125 | general, you can treat it as a QIODevice for writing, and mostly
|
|---|
| 126 | also for reading. The match isn't perfect, since the QIODevice
|
|---|
| 127 | API is designed for devices that are controlled by the same
|
|---|
| 128 | machine, and an asynchronous peer-to-peer network connection isn't
|
|---|
| 129 | quite like that. For example, there is nothing that matches
|
|---|
| 130 | <a href="qiodevice.html#size">QIODevice::size</a>() exactly. The documentation for <a href="#open">open</a>(), <a href="#close">close</a>(),
|
|---|
| 131 | <a href="#flush">flush</a>(), <a href="#size">size</a>(), <a href="#at">at</a>(), <a href="#atEnd">atEnd</a>(), <a href="#readBlock">readBlock</a>(), <a href="#writeBlock">writeBlock</a>(),
|
|---|
| 132 | <a href="#getch">getch</a>(), <a href="#putch">putch</a>(), <a href="#ungetch">ungetch</a>() and <a href="#readLine">readLine</a>() describes the
|
|---|
| 133 | differences in detail.
|
|---|
| 134 | <p> <b>Warning:</b> QSocket is not suitable for use in threads. If you need
|
|---|
| 135 | to uses sockets in threads use the lower-level <a href="qsocketdevice.html">QSocketDevice</a> class.
|
|---|
| 136 | <p> <b>Warning:</b> Because Qt doesn't use the native socketstream
|
|---|
| 137 | implementation on Mac OS X, QSocket has an implicit transfer
|
|---|
| 138 | latency of 100ms. You can achieve lower latency on Mac OS X by
|
|---|
| 139 | using QSocketDevice instead.
|
|---|
| 140 | <p> <p>See also <a href="qsocketdevice.html">QSocketDevice</a>, <a href="qhostaddress.html">QHostAddress</a>, <a href="qsocketnotifier.html">QSocketNotifier</a>, and <a href="io.html">Input/Output and Networking</a>.
|
|---|
| 141 |
|
|---|
| 142 | <hr><h2>Member Type Documentation</h2>
|
|---|
| 143 | <h3 class=fn><a name="Error-enum"></a>QSocket::Error</h3>
|
|---|
| 144 |
|
|---|
| 145 | <p> This enum specifies the possible errors:
|
|---|
| 146 | <ul>
|
|---|
| 147 | <li><tt>QSocket::ErrConnectionRefused</tt> - if the connection was refused
|
|---|
| 148 | <li><tt>QSocket::ErrHostNotFound</tt> - if the host was not found
|
|---|
| 149 | <li><tt>QSocket::ErrSocketRead</tt> - if a read from the socket failed
|
|---|
| 150 | </ul>
|
|---|
| 151 | <h3 class=fn><a name="State-enum"></a>QSocket::State</h3>
|
|---|
| 152 |
|
|---|
| 153 | <p> This enum defines the connection states:
|
|---|
| 154 | <ul>
|
|---|
| 155 | <li><tt>QSocket::Idle</tt> - if there is no connection
|
|---|
| 156 | <li><tt>QSocket::HostLookup</tt> - during a DNS lookup
|
|---|
| 157 | <li><tt>QSocket::Connecting</tt> - during TCP connection establishment
|
|---|
| 158 | <li><tt>QSocket::Connected</tt> - when there is an operational connection
|
|---|
| 159 | <li><tt>QSocket::Closing</tt> - if the socket is closing down, but is not yet closed.
|
|---|
| 160 | </ul>
|
|---|
| 161 | <hr><h2>Member Function Documentation</h2>
|
|---|
| 162 | <h3 class=fn><a name="QSocket"></a>QSocket::QSocket ( <a href="qobject.html">QObject</a> * parent = 0, const char * name = 0 )
|
|---|
| 163 | </h3>
|
|---|
| 164 | Creates a QSocket object in <a href="#State-enum">QSocket::Idle</a> state.
|
|---|
| 165 | <p> The <em>parent</em> and <em>name</em> arguments are passed on to the <a href="qobject.html">QObject</a>
|
|---|
| 166 | constructor.
|
|---|
| 167 | <p> Note that a <a href="qapplication.html">QApplication</a> must have been constructed before sockets
|
|---|
| 168 | can be used.
|
|---|
| 169 |
|
|---|
| 170 | <h3 class=fn><a name="~QSocket"></a>QSocket::~QSocket ()<tt> [virtual]</tt>
|
|---|
| 171 | </h3>
|
|---|
| 172 | Destroys the socket. Closes the connection if necessary.
|
|---|
| 173 | <p> <p>See also <a href="#close">close</a>().
|
|---|
| 174 |
|
|---|
| 175 | <h3 class=fn><a href="qhostaddress.html">QHostAddress</a> <a name="address"></a>QSocket::address () const
|
|---|
| 176 | </h3>
|
|---|
| 177 | Returns the host address of this socket. (This is normally the
|
|---|
| 178 | main IP address of the host, but can be e.g. 127.0.0.1 for
|
|---|
| 179 | connections to localhost.)
|
|---|
| 180 |
|
|---|
| 181 | <h3 class=fn><a href="qiodevice.html#Offset">Offset</a> <a name="at"></a>QSocket::at () const<tt> [virtual]</tt>
|
|---|
| 182 | </h3>
|
|---|
| 183 | Returns the current read index. Since QSocket is a sequential
|
|---|
| 184 | device, the current read index is always zero.
|
|---|
| 185 |
|
|---|
| 186 | <p>Reimplemented from <a href="qiodevice.html#at">QIODevice</a>.
|
|---|
| 187 | <h3 class=fn>bool <a name="at-2"></a>QSocket::at ( <a href="qiodevice.html#Offset">Offset</a> index )<tt> [virtual]</tt>
|
|---|
| 188 | </h3>
|
|---|
| 189 | This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
|
|---|
| 190 | <p> Moves the read index forward to <em>index</em> and returns TRUE if the
|
|---|
| 191 | operation was successful; otherwise returns FALSE. Moving the
|
|---|
| 192 | index forward means skipping incoming data.
|
|---|
| 193 |
|
|---|
| 194 | <p>Reimplemented from <a href="qiodevice.html#at-2">QIODevice</a>.
|
|---|
| 195 | <h3 class=fn>bool <a name="atEnd"></a>QSocket::atEnd () const<tt> [virtual]</tt>
|
|---|
| 196 | </h3>
|
|---|
| 197 | Returns TRUE if there is no more data to read; otherwise returns FALSE.
|
|---|
| 198 |
|
|---|
| 199 | <p>Reimplemented from <a href="qiodevice.html#atEnd">QIODevice</a>.
|
|---|
| 200 | <h3 class=fn>Q_ULONG <a name="bytesAvailable"></a>QSocket::bytesAvailable () const
|
|---|
| 201 | </h3>
|
|---|
| 202 | Returns the number of incoming bytes that can be read, i.e. the
|
|---|
| 203 | size of the input buffer. Equivalent to <a href="#size">size</a>().
|
|---|
| 204 | <p> This function can trigger the <a href="#readyRead">readyRead</a>() signal, if more data has
|
|---|
| 205 | arrived on the socket.
|
|---|
| 206 | <p> <p>See also <a href="#bytesToWrite">bytesToWrite</a>().
|
|---|
| 207 |
|
|---|
| 208 | <p>Example: <a href="networkprotocol-example.html#x677">network/networkprotocol/nntp.cpp</a>.
|
|---|
| 209 | <h3 class=fn>Q_ULONG <a name="bytesToWrite"></a>QSocket::bytesToWrite () const
|
|---|
| 210 | </h3>
|
|---|
| 211 | Returns the number of bytes that are waiting to be written, i.e.
|
|---|
| 212 | the size of the output buffer.
|
|---|
| 213 | <p> <p>See also <a href="#bytesAvailable">bytesAvailable</a>() and <a href="#clearPendingData">clearPendingData</a>().
|
|---|
| 214 |
|
|---|
| 215 | <h3 class=fn>void <a name="bytesWritten"></a>QSocket::bytesWritten ( int nbytes )<tt> [signal]</tt>
|
|---|
| 216 | </h3>
|
|---|
| 217 |
|
|---|
| 218 | <p> This signal is emitted when data has been written to the network.
|
|---|
| 219 | The <em>nbytes</em> parameter specifies how many bytes were written.
|
|---|
| 220 | <p> The <a href="#bytesToWrite">bytesToWrite</a>() function is often used in the same context; it
|
|---|
| 221 | indicates how many buffered bytes there are left to write.
|
|---|
| 222 | <p> <p>See also <a href="#writeBlock">writeBlock</a>() and <a href="#bytesToWrite">bytesToWrite</a>().
|
|---|
| 223 |
|
|---|
| 224 | <h3 class=fn>bool <a name="canReadLine"></a>QSocket::canReadLine () const
|
|---|
| 225 | </h3>
|
|---|
| 226 | Returns TRUE if it's possible to read an entire line of text from
|
|---|
| 227 | this socket at this time; otherwise returns FALSE.
|
|---|
| 228 | <p> Note that if the peer closes the connection unexpectedly, this
|
|---|
| 229 | function returns FALSE. This means that loops such as this won't
|
|---|
| 230 | work:
|
|---|
| 231 | <p> <pre>
|
|---|
| 232 | while( !socket->canReadLine() ) // WRONG
|
|---|
| 233 | ;
|
|---|
| 234 | </pre>
|
|---|
| 235 |
|
|---|
| 236 | <p> <p>See also <a href="#readLine">readLine</a>().
|
|---|
| 237 |
|
|---|
| 238 | <p>Examples: <a href="clientserver-example.html#x795">network/clientserver/client/client.cpp</a>, <a href="httpd-example.html#x727">network/httpd/httpd.cpp</a>, <a href="mail-example.html#x709">network/mail/smtp.cpp</a>, and <a href="networkprotocol-example.html#x678">network/networkprotocol/nntp.cpp</a>.
|
|---|
| 239 | <h3 class=fn>void <a name="clearPendingData"></a>QSocket::clearPendingData ()
|
|---|
| 240 | </h3>
|
|---|
| 241 | Deletes the data that is waiting to be written. This is useful if you want
|
|---|
| 242 | to close the socket without waiting for all the data to be written.
|
|---|
| 243 | <p> <p>See also <a href="#bytesToWrite">bytesToWrite</a>(), <a href="#close">close</a>(), and <a href="#delayedCloseFinished">delayedCloseFinished</a>().
|
|---|
| 244 |
|
|---|
| 245 | <h3 class=fn>void <a name="close"></a>QSocket::close ()<tt> [virtual]</tt>
|
|---|
| 246 | </h3>
|
|---|
| 247 | Closes the socket.
|
|---|
| 248 | <p> The read buffer is cleared.
|
|---|
| 249 | <p> If the output buffer is empty, the state is set to <a href="#State-enum">QSocket::Idle</a> and the connection is terminated immediately. If the
|
|---|
| 250 | output buffer still contains data to be written, QSocket goes into
|
|---|
| 251 | the <a href="#State-enum">QSocket::Closing</a> state and the rest of the data will be
|
|---|
| 252 | written. When all of the outgoing data have been written, the
|
|---|
| 253 | state is set to <a href="#State-enum">QSocket::Idle</a> and the connection is terminated.
|
|---|
| 254 | At this point, the <a href="#delayedCloseFinished">delayedCloseFinished</a>() signal is emitted.
|
|---|
| 255 | <p> If you don't want that the data of the output buffer is written, call
|
|---|
| 256 | <a href="#clearPendingData">clearPendingData</a>() before you call <a href="#close">close</a>().
|
|---|
| 257 | <p> <p>See also <a href="#state">state</a>(), <a href="#bytesToWrite">bytesToWrite</a>(), and <a href="#clearPendingData">clearPendingData</a>().
|
|---|
| 258 |
|
|---|
| 259 | <p>Examples: <a href="clientserver-example.html#x796">network/clientserver/client/client.cpp</a>, <a href="httpd-example.html#x728">network/httpd/httpd.cpp</a>, and <a href="networkprotocol-example.html#x679">network/networkprotocol/nntp.cpp</a>.
|
|---|
| 260 | <p>Reimplemented from <a href="qiodevice.html#close">QIODevice</a>.
|
|---|
| 261 | <h3 class=fn>void <a name="connectToHost"></a>QSocket::connectToHost ( const <a href="qstring.html">QString</a> & host, Q_UINT16 port )<tt> [virtual]</tt>
|
|---|
| 262 | </h3>
|
|---|
| 263 | Attempts to make a connection to <em>host</em> on the specified <em>port</em>
|
|---|
| 264 | and return immediately.
|
|---|
| 265 | <p> Any connection or pending connection is closed immediately, and
|
|---|
| 266 | QSocket goes into the <a href="#State-enum">HostLookup</a> state. When the lookup
|
|---|
| 267 | succeeds, it emits <a href="#hostFound">hostFound</a>(), starts a TCP connection and goes
|
|---|
| 268 | into the <a href="#State-enum">Connecting</a> state. Finally, when the connection
|
|---|
| 269 | succeeds, it emits <a href="#connected">connected</a>() and goes into the <a href="#State-enum">Connected</a>
|
|---|
| 270 | state. If there is an error at any point, it emits <a href="#error">error</a>().
|
|---|
| 271 | <p> <em>host</em> may be an IP address in string form, or it may be a DNS
|
|---|
| 272 | name. QSocket will do a normal DNS lookup if required. Note that
|
|---|
| 273 | <em>port</em> is in native byte order, unlike some other libraries.
|
|---|
| 274 | <p> <p>See also <a href="#state">state</a>().
|
|---|
| 275 |
|
|---|
| 276 | <p>Examples: <a href="clientserver-example.html#x797">network/clientserver/client/client.cpp</a>, <a href="mail-example.html#x710">network/mail/smtp.cpp</a>, and <a href="networkprotocol-example.html#x680">network/networkprotocol/nntp.cpp</a>.
|
|---|
| 277 | <h3 class=fn>void <a name="connected"></a>QSocket::connected ()<tt> [signal]</tt>
|
|---|
| 278 | </h3>
|
|---|
| 279 |
|
|---|
| 280 | <p> This signal is emitted after <a href="#connectToHost">connectToHost</a>() has been called and a
|
|---|
| 281 | connection has been successfully established.
|
|---|
| 282 | <p> <p>See also <a href="#connectToHost">connectToHost</a>() and <a href="#connectionClosed">connectionClosed</a>().
|
|---|
| 283 |
|
|---|
| 284 | <p>Examples: <a href="clientserver-example.html#x798">network/clientserver/client/client.cpp</a>, <a href="mail-example.html#x711">network/mail/smtp.cpp</a>, and <a href="networkprotocol-example.html#x681">network/networkprotocol/nntp.cpp</a>.
|
|---|
| 285 | <h3 class=fn>void <a name="connectionClosed"></a>QSocket::connectionClosed ()<tt> [signal]</tt>
|
|---|
| 286 | </h3>
|
|---|
| 287 |
|
|---|
| 288 | <p> This signal is emitted when the other end has closed the
|
|---|
| 289 | connection. The read buffers may contain buffered input data which
|
|---|
| 290 | you can read after the connection was closed.
|
|---|
| 291 | <p> <p>See also <a href="#connectToHost">connectToHost</a>() and <a href="#close">close</a>().
|
|---|
| 292 |
|
|---|
| 293 | <p>Examples: <a href="clientserver-example.html#x799">network/clientserver/client/client.cpp</a>, <a href="clientserver-example.html#x785">network/clientserver/server/server.cpp</a>, and <a href="networkprotocol-example.html#x682">network/networkprotocol/nntp.cpp</a>.
|
|---|
| 294 | <h3 class=fn>void <a name="delayedCloseFinished"></a>QSocket::delayedCloseFinished ()<tt> [signal]</tt>
|
|---|
| 295 | </h3>
|
|---|
| 296 |
|
|---|
| 297 | <p> This signal is emitted when a delayed close is finished.
|
|---|
| 298 | <p> If you call <a href="#close">close</a>() and there is buffered output data to be
|
|---|
| 299 | written, QSocket goes into the <a href="#State-enum">QSocket::Closing</a> state and
|
|---|
| 300 | returns immediately. It will then keep writing to the socket until
|
|---|
| 301 | all the data has been written. Then, the <a href="#delayedCloseFinished">delayedCloseFinished</a>()
|
|---|
| 302 | signal is emitted.
|
|---|
| 303 | <p> <p>See also <a href="#close">close</a>().
|
|---|
| 304 |
|
|---|
| 305 | <p>Examples: <a href="clientserver-example.html#x800">network/clientserver/client/client.cpp</a> and <a href="httpd-example.html#x729">network/httpd/httpd.cpp</a>.
|
|---|
| 306 | <h3 class=fn>void <a name="error"></a>QSocket::error ( int )<tt> [signal]</tt>
|
|---|
| 307 | </h3>
|
|---|
| 308 |
|
|---|
| 309 | <p> This signal is emitted after an error occurred. The parameter is
|
|---|
| 310 | the <a href="#Error-enum">Error</a> value.
|
|---|
| 311 |
|
|---|
| 312 | <p>Examples: <a href="clientserver-example.html#x801">network/clientserver/client/client.cpp</a> and <a href="networkprotocol-example.html#x683">network/networkprotocol/nntp.cpp</a>.
|
|---|
| 313 | <h3 class=fn>void <a name="flush"></a>QSocket::flush ()<tt> [virtual]</tt>
|
|---|
| 314 | </h3>
|
|---|
| 315 | Implementation of the abstract virtual <a href="qiodevice.html#flush">QIODevice::flush</a>() function.
|
|---|
| 316 |
|
|---|
| 317 | <p>Reimplemented from <a href="qiodevice.html#flush">QIODevice</a>.
|
|---|
| 318 | <h3 class=fn>int <a name="getch"></a>QSocket::getch ()<tt> [virtual]</tt>
|
|---|
| 319 | </h3>
|
|---|
| 320 | Reads a single byte/character from the internal read buffer.
|
|---|
| 321 | Returns the byte/character read, or -1 if there is nothing to be
|
|---|
| 322 | read.
|
|---|
| 323 | <p> <p>See also <a href="#bytesAvailable">bytesAvailable</a>() and <a href="#putch">putch</a>().
|
|---|
| 324 |
|
|---|
| 325 | <p>Reimplemented from <a href="qiodevice.html#getch">QIODevice</a>.
|
|---|
| 326 | <h3 class=fn>void <a name="hostFound"></a>QSocket::hostFound ()<tt> [signal]</tt>
|
|---|
| 327 | </h3>
|
|---|
| 328 |
|
|---|
| 329 | <p> This signal is emitted after <a href="#connectToHost">connectToHost</a>() has been called and
|
|---|
| 330 | the host lookup has succeeded.
|
|---|
| 331 | <p> <p>See also <a href="#connected">connected</a>().
|
|---|
| 332 |
|
|---|
| 333 | <p>Example: <a href="networkprotocol-example.html#x684">network/networkprotocol/nntp.cpp</a>.
|
|---|
| 334 | <h3 class=fn>bool <a name="open"></a>QSocket::open ( int m )<tt> [virtual]</tt>
|
|---|
| 335 | </h3>
|
|---|
| 336 | Opens the socket using the specified <a href="qiodevice.html">QIODevice</a> file mode <em>m</em>.
|
|---|
| 337 | This function is called automatically when needed and you should
|
|---|
| 338 | not call it yourself.
|
|---|
| 339 | <p> <p>See also <a href="#close">close</a>().
|
|---|
| 340 |
|
|---|
| 341 | <p>Reimplemented from <a href="qiodevice.html#open">QIODevice</a>.
|
|---|
| 342 | <h3 class=fn><a href="qhostaddress.html">QHostAddress</a> <a name="peerAddress"></a>QSocket::peerAddress () const
|
|---|
| 343 | </h3>
|
|---|
| 344 | Returns the address of the connected peer if the socket is in
|
|---|
| 345 | Connected state; otherwise an empty <a href="qhostaddress.html">QHostAddress</a> is returned.
|
|---|
| 346 |
|
|---|
| 347 | <h3 class=fn><a href="qstring.html">QString</a> <a name="peerName"></a>QSocket::peerName () const
|
|---|
| 348 | </h3>
|
|---|
| 349 | Returns the host name as specified to the <a href="#connectToHost">connectToHost</a>()
|
|---|
| 350 | function. An empty string is returned if none has been set.
|
|---|
| 351 |
|
|---|
| 352 | <p>Example: <a href="mail-example.html#x712">network/mail/smtp.cpp</a>.
|
|---|
| 353 | <h3 class=fn>Q_UINT16 <a name="peerPort"></a>QSocket::peerPort () const
|
|---|
| 354 | </h3>
|
|---|
| 355 | Returns the peer's host port number, normally as specified to the
|
|---|
| 356 | <a href="#connectToHost">connectToHost</a>() function. If none has been set, this function
|
|---|
| 357 | returns 0.
|
|---|
| 358 | <p> Note that Qt always uses native byte order, i.e. 67 is 67 in Qt;
|
|---|
| 359 | there is no need to call htons().
|
|---|
| 360 |
|
|---|
| 361 | <h3 class=fn>Q_UINT16 <a name="port"></a>QSocket::port () const
|
|---|
| 362 | </h3>
|
|---|
| 363 | Returns the host port number of this socket, in native byte order.
|
|---|
| 364 |
|
|---|
| 365 | <h3 class=fn>int <a name="putch"></a>QSocket::putch ( int ch )<tt> [virtual]</tt>
|
|---|
| 366 | </h3>
|
|---|
| 367 | Writes the character <em>ch</em> to the output buffer.
|
|---|
| 368 | <p> Returns <em>ch</em>, or -1 if an error occurred.
|
|---|
| 369 | <p> <p>See also <a href="#getch">getch</a>().
|
|---|
| 370 |
|
|---|
| 371 | <p>Reimplemented from <a href="qiodevice.html#putch">QIODevice</a>.
|
|---|
| 372 | <h3 class=fn>Q_LONG <a name="readBlock"></a>QSocket::readBlock ( char * data, Q_ULONG maxlen )<tt> [virtual]</tt>
|
|---|
| 373 | </h3>
|
|---|
| 374 | Reads <em>maxlen</em> bytes from the socket into <em>data</em> and returns the
|
|---|
| 375 | number of bytes read. Returns -1 if an error occurred.
|
|---|
| 376 |
|
|---|
| 377 | <p>Example: <a href="networkprotocol-example.html#x685">network/networkprotocol/nntp.cpp</a>.
|
|---|
| 378 | <p>Reimplemented from <a href="qiodevice.html#readBlock">QIODevice</a>.
|
|---|
| 379 | <h3 class=fn>Q_ULONG <a name="readBufferSize"></a>QSocket::readBufferSize () const
|
|---|
| 380 | </h3>
|
|---|
| 381 | Returns the size of the read buffer.
|
|---|
| 382 | <p> <p>See also <a href="#setReadBufferSize">setReadBufferSize</a>().
|
|---|
| 383 |
|
|---|
| 384 | <h3 class=fn><a href="qstring.html">QString</a> <a name="readLine"></a>QSocket::readLine ()<tt> [virtual]</tt>
|
|---|
| 385 | </h3>
|
|---|
| 386 | Returns a line of text including a terminating newline character
|
|---|
| 387 | (\n). Returns "" if <a href="#canReadLine">canReadLine</a>() returns FALSE.
|
|---|
| 388 | <p> <p>See also <a href="#canReadLine">canReadLine</a>().
|
|---|
| 389 |
|
|---|
| 390 | <p>Examples: <a href="clientserver-example.html#x802">network/clientserver/client/client.cpp</a>, <a href="httpd-example.html#x730">network/httpd/httpd.cpp</a>, <a href="mail-example.html#x713">network/mail/smtp.cpp</a>, and <a href="networkprotocol-example.html#x686">network/networkprotocol/nntp.cpp</a>.
|
|---|
| 391 | <h3 class=fn>void <a name="readyRead"></a>QSocket::readyRead ()<tt> [signal]</tt>
|
|---|
| 392 | </h3>
|
|---|
| 393 |
|
|---|
| 394 | <p> This signal is emitted every time there is new incoming data.
|
|---|
| 395 | <p> Bear in mind that new incoming data is only reported once; if you do not
|
|---|
| 396 | read all the data, this class buffers the data and you can read it later,
|
|---|
| 397 | but no signal is emitted unless new data arrives. A good practice is to
|
|---|
| 398 | read all data in the slot connected to this signal unless you are sure that
|
|---|
| 399 | you need to receive more data to be able to process it.
|
|---|
| 400 | <p> <p>See also <a href="#readBlock">readBlock</a>(), <a href="#readLine">readLine</a>(), and <a href="#bytesAvailable">bytesAvailable</a>().
|
|---|
| 401 |
|
|---|
| 402 | <p>Examples: <a href="clientserver-example.html#x803">network/clientserver/client/client.cpp</a>, <a href="httpd-example.html#x731">network/httpd/httpd.cpp</a>, <a href="mail-example.html#x714">network/mail/smtp.cpp</a>, and <a href="networkprotocol-example.html#x687">network/networkprotocol/nntp.cpp</a>.
|
|---|
| 403 | <h3 class=fn>void <a name="setReadBufferSize"></a>QSocket::setReadBufferSize ( Q_ULONG bufSize )
|
|---|
| 404 | </h3>
|
|---|
| 405 | Sets the size of the QSocket's internal read buffer to <em>bufSize</em>.
|
|---|
| 406 | <p> Usually QSocket reads all data that is available from the operating
|
|---|
| 407 | system's socket. If the buffer size is limited to a certain size, this
|
|---|
| 408 | means that the QSocket class doesn't buffer more than this size of data.
|
|---|
| 409 | <p> If the size of the read buffer is 0, the read buffer is unlimited and all
|
|---|
| 410 | incoming data is buffered. This is the default.
|
|---|
| 411 | <p> If you read the data in the <a href="#readyRead">readyRead</a>() signal, you shouldn't use this
|
|---|
| 412 | option since it might slow down your program unnecessary. This option is
|
|---|
| 413 | useful if you only need to read the data at certain points in time, like in
|
|---|
| 414 | a realtime streaming application.
|
|---|
| 415 | <p> <p>See also <a href="#readBufferSize">readBufferSize</a>().
|
|---|
| 416 |
|
|---|
| 417 | <h3 class=fn>void <a name="setSocket"></a>QSocket::setSocket ( int socket )<tt> [virtual]</tt>
|
|---|
| 418 | </h3>
|
|---|
| 419 | Sets the socket to use <em>socket</em> and the <a href="#state">state</a>() to <a href="#State-enum">Connected</a>.
|
|---|
| 420 | The socket must already be connected.
|
|---|
| 421 | <p> This allows us to use the QSocket class as a wrapper for other
|
|---|
| 422 | socket types (e.g. Unix Domain Sockets).
|
|---|
| 423 |
|
|---|
| 424 | <p>Example: <a href="httpd-example.html#x732">network/httpd/httpd.cpp</a>.
|
|---|
| 425 | <h3 class=fn>void <a name="setSocketDevice"></a>QSocket::setSocketDevice ( <a href="qsocketdevice.html">QSocketDevice</a> * device )<tt> [virtual]</tt>
|
|---|
| 426 | </h3>
|
|---|
| 427 | Sets the internal socket device to <em>device</em>. Passing a <em>device</em>
|
|---|
| 428 | of 0 will cause the internal socket device to be used. Any
|
|---|
| 429 | existing connection will be disconnected before using the new <em>device</em>.
|
|---|
| 430 | <p> The new device should not be connected before being associated
|
|---|
| 431 | with a QSocket; after setting the socket call <a href="#connectToHost">connectToHost</a>() to
|
|---|
| 432 | make the connection.
|
|---|
| 433 | <p> This function is useful if you need to subclass <a href="qsocketdevice.html">QSocketDevice</a> and
|
|---|
| 434 | want to use the QSocket API, for example, to implement Unix domain
|
|---|
| 435 | sockets.
|
|---|
| 436 |
|
|---|
| 437 | <h3 class=fn><a href="qiodevice.html#Offset">Offset</a> <a name="size"></a>QSocket::size () const<tt> [virtual]</tt>
|
|---|
| 438 | </h3>
|
|---|
| 439 | Returns the number of incoming bytes that can be read right now
|
|---|
| 440 | (like <a href="#bytesAvailable">bytesAvailable</a>()).
|
|---|
| 441 |
|
|---|
| 442 | <p>Reimplemented from <a href="qiodevice.html#size">QIODevice</a>.
|
|---|
| 443 | <h3 class=fn>int <a name="socket"></a>QSocket::socket () const
|
|---|
| 444 | </h3>
|
|---|
| 445 | Returns the socket number, or -1 if there is no socket at the moment.
|
|---|
| 446 |
|
|---|
| 447 | <h3 class=fn><a href="qsocketdevice.html">QSocketDevice</a> * <a name="socketDevice"></a>QSocket::socketDevice ()
|
|---|
| 448 | </h3>
|
|---|
| 449 | Returns a pointer to the internal socket device.
|
|---|
| 450 | <p> There is normally no need to manipulate the socket device directly
|
|---|
| 451 | since this class does the necessary setup for most applications.
|
|---|
| 452 |
|
|---|
| 453 | <h3 class=fn><a href="qsocket.html#State-enum">State</a> <a name="state"></a>QSocket::state () const
|
|---|
| 454 | </h3>
|
|---|
| 455 | Returns the current state of the socket connection.
|
|---|
| 456 | <p> <p>See also <a href="#State-enum">QSocket::State</a>.
|
|---|
| 457 |
|
|---|
| 458 | <p>Examples: <a href="clientserver-example.html#x804">network/clientserver/client/client.cpp</a> and <a href="networkprotocol-example.html#x688">network/networkprotocol/nntp.cpp</a>.
|
|---|
| 459 | <h3 class=fn>int <a name="ungetch"></a>QSocket::ungetch ( int ch )<tt> [virtual]</tt>
|
|---|
| 460 | </h3>
|
|---|
| 461 | This implementation of the virtual function <a href="qiodevice.html#ungetch">QIODevice::ungetch</a>()
|
|---|
| 462 | prepends the character <em>ch</em> to the read buffer so that the next
|
|---|
| 463 | read returns this character as the first character of the output.
|
|---|
| 464 |
|
|---|
| 465 | <p>Reimplemented from <a href="qiodevice.html#ungetch">QIODevice</a>.
|
|---|
| 466 | <h3 class=fn>Q_ULONG <a name="waitForMore"></a>QSocket::waitForMore ( int msecs, bool * timeout ) const
|
|---|
| 467 | </h3>
|
|---|
| 468 | Wait up to <em>msecs</em> milliseconds for more data to be available.
|
|---|
| 469 | <p> If <em>msecs</em> is -1 the call will block indefinitely.
|
|---|
| 470 | <p> Returns the number of bytes available.
|
|---|
| 471 | <p> If <em>timeout</em> is non-null and no error occurred (i.e. it does not
|
|---|
| 472 | return -1): this function sets <em>*timeout</em> to TRUE, if the reason
|
|---|
| 473 | for returning was that the timeout was reached; otherwise it sets
|
|---|
| 474 | <em>*timeout</em> to FALSE. This is useful to find out if the peer
|
|---|
| 475 | closed the connection.
|
|---|
| 476 | <p> <b>Warning:</b> This is a blocking call and should be avoided in event
|
|---|
| 477 | driven applications.
|
|---|
| 478 | <p> <p>See also <a href="#bytesAvailable">bytesAvailable</a>().
|
|---|
| 479 |
|
|---|
| 480 | <h3 class=fn>Q_ULONG <a name="waitForMore-2"></a>QSocket::waitForMore ( int msecs ) const
|
|---|
| 481 | </h3> This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
|
|---|
| 482 | <p>
|
|---|
| 483 | <h3 class=fn>Q_LONG <a name="writeBlock"></a>QSocket::writeBlock ( const char * data, Q_ULONG len )<tt> [virtual]</tt>
|
|---|
| 484 | </h3>
|
|---|
| 485 | Writes <em>len</em> bytes to the socket from <em>data</em> and returns the
|
|---|
| 486 | number of bytes written. Returns -1 if an error occurred.
|
|---|
| 487 |
|
|---|
| 488 | <p>Example: <a href="networkprotocol-example.html#x689">network/networkprotocol/nntp.cpp</a>.
|
|---|
| 489 | <p>Reimplemented from <a href="qiodevice.html#writeBlock">QIODevice</a>.
|
|---|
| 490 | <!-- eof -->
|
|---|
| 491 | <hr><p>
|
|---|
| 492 | This file is part of the <a href="index.html">Qt toolkit</a>.
|
|---|
| 493 | Copyright © 1995-2007
|
|---|
| 494 | <a href="http://www.trolltech.com/">Trolltech</a>. All Rights Reserved.<p><address><hr><div align=center>
|
|---|
| 495 | <table width=100% cellspacing=0 border=0><tr>
|
|---|
| 496 | <td>Copyright © 2007
|
|---|
| 497 | <a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
|
|---|
| 498 | <td align=right><div align=right>Qt 3.3.8</div>
|
|---|
| 499 | </table></div></address></body>
|
|---|
| 500 | </html>
|
|---|
