<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!-- /tmp/qt-3.0-reggie-28534/qt-x11-free-3.0.2/src/network/qsocketdevice.cpp:55 -->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>QSocketDevice Class</title>
<style type="text/css"><!--
h3.fn,span.fn { margin-left: 1cm; text-indent: -1cm; }
a:link { color: #004faf; text-decoration: none }
a:visited { color: #672967; text-decoration: none }
body { background: #ffffff; color: black; }
--></style>
</head>
<body>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr bgcolor="#E5E5E5">
<td valign=center>
<a href="index.html">
<font color="#004faf">Home</font></a>
| <a href="classes.html">
<font color="#004faf">All Classes</font></a>
| <a href="mainclasses.html">
<font color="#004faf">Main Classes</font></a>
| <a href="annotated.html">
<font color="#004faf">Annotated</font></a>
| <a href="groups.html">
<font color="#004faf">Grouped Classes</font></a>
| <a href="functions.html">
<font color="#004faf">Functions</font></a>
</td>
<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>QSocketDevice Class Reference<br><small>[<a href="network.html">network module</a>]</small></h1>
<p>The QSocketDevice class provides a platform-independent low-level socket API.
<a href="#details">More...</a>
<p><tt>#include <<a href="qsocketdevice-h.html">qsocketdevice.h</a>></tt>
<p>Inherits <a href="qiodevice.html">QIODevice</a>.
<p><a href="qsocketdevice-members.html">List of all member functions.</a>
<h2>Public Members</h2>
<ul>
<li><div class=fn>enum <a href="#Type-enum"><b>Type</b></a> { Stream, Datagram }</div></li>
<li><div class=fn><a href="#QSocketDevice"><b>QSocketDevice</b></a> ( Type type = Stream )</div></li>
<li><div class=fn><a href="#QSocketDevice-2"><b>QSocketDevice</b></a> ( int socket, Type type )</div></li>
<li><div class=fn>virtual <a href="#~QSocketDevice"><b>~QSocketDevice</b></a> ()</div></li>
<li><div class=fn>bool <a href="#isValid"><b>isValid</b></a> () const</div></li>
<li><div class=fn>Type <a href="#type"><b>type</b></a> () const</div></li>
<li><div class=fn>int <a href="#socket"><b>socket</b></a> () const</div></li>
<li><div class=fn>virtual void <a href="#setSocket"><b>setSocket</b></a> ( int socket, Type type )</div></li>
<li><div class=fn>bool <a href="#blocking"><b>blocking</b></a> () const</div></li>
<li><div class=fn>virtual void <a href="#setBlocking"><b>setBlocking</b></a> ( bool enable )</div></li>
<li><div class=fn>bool <a href="#addressReusable"><b>addressReusable</b></a> () const</div></li>
<li><div class=fn>virtual void <a href="#setAddressReusable"><b>setAddressReusable</b></a> ( bool enable )</div></li>
<li><div class=fn>int <a href="#receiveBufferSize"><b>receiveBufferSize</b></a> () const</div></li>
<li><div class=fn>virtual void <a href="#setReceiveBufferSize"><b>setReceiveBufferSize</b></a> ( uint size )</div></li>
<li><div class=fn>int <a href="#sendBufferSize"><b>sendBufferSize</b></a> () const</div></li>
<li><div class=fn>virtual void <a href="#setSendBufferSize"><b>setSendBufferSize</b></a> ( uint size )</div></li>
<li><div class=fn>virtual bool <a href="#connect"><b>connect</b></a> ( const QHostAddress & addr, Q_UINT16 port )</div></li>
<li><div class=fn>virtual bool <a href="#bind"><b>bind</b></a> ( const QHostAddress & address, Q_UINT16 port )</div></li>
<li><div class=fn>virtual bool <a href="#listen"><b>listen</b></a> ( int backlog )</div></li>
<li><div class=fn>virtual int <a href="#accept"><b>accept</b></a> ()</div></li>
<li><div class=fn>Q_LONG <a href="#bytesAvailable"><b>bytesAvailable</b></a> () const</div></li>
<li><div class=fn>Q_LONG <a href="#waitForMore"><b>waitForMore</b></a> ( int msecs, bool * timeout = 0 ) const</div></li>
<li><div class=fn>virtual Q_LONG <a href="#readBlock"><b>readBlock</b></a> ( char * data, Q_ULONG maxlen )</div></li>
<li><div class=fn>virtual Q_LONG <a href="#writeBlock"><b>writeBlock</b></a> ( const char * data, Q_ULONG len )</div></li>
<li><div class=fn>virtual Q_LONG <a href="#writeBlock-2"><b>writeBlock</b></a> ( const char * data, Q_ULONG len, const QHostAddress & host, Q_UINT16 port )</div></li>
<li><div class=fn>Q_UINT16 <a href="#port"><b>port</b></a> () const</div></li>
<li><div class=fn>Q_UINT16 <a href="#peerPort"><b>peerPort</b></a> () const</div></li>
<li><div class=fn>QHostAddress <a href="#address"><b>address</b></a> () const</div></li>
<li><div class=fn>QHostAddress <a href="#peerAddress"><b>peerAddress</b></a> () const</div></li>
<li><div class=fn>enum <a href="#Error-enum"><b>Error</b></a> { NoError, AlreadyBound, Inaccessible, NoResources, Bug, Impossible, NoFiles, ConnectionRefused, NetworkFailure, UnknownError }</div></li>
<li><div class=fn>Error <a href="#error"><b>error</b></a> () const</div></li>
</ul>
<h2>Protected Members</h2>
<ul>
<li><div class=fn>void <a href="#setError"><b>setError</b></a> ( Error err )</div></li>
</ul>
<hr><a name="details"></a><h2>Detailed Description</h2>
The QSocketDevice class provides a platform-independent low-level socket API.
<p>
<p> This class is not really intended for use outside Qt. It can be used
to achieve some things that <a href="qsocket.html">QSocket</a> does not provide, but it's
not particularly easy to understand or use.
<p> The essential purpose of the class is to provide a <a href="qiodevice.html">QIODevice</a> that works
on sockets, wrapped in a platform-independent API.
<p> <p>See also <a href="qsocket.html">QSocket</a>, <a href="qsocketnotifier.html">QSocketNotifier</a>, <a href="qhostaddress.html">QHostAddress</a> and <a href="io.html">Input/Output and Networking</a>.
<hr><h2>Member Type Documentation</h2>
<h3 class=fn><a name="Error-enum"></a>QSocketDevice::Error</h3>
<p> This enum type describes the error states of QSocketDevice. At present these
errors are defined:
<ul>
<li><tt>QSocketDevice::NoError</tt> - all is fine.
<li><tt>QSocketDevice::AlreadyBound</tt> - <a href="#bind">bind</a>() said so.
<li><tt>QSocketDevice::Inaccessible</tt> - the operating system or firewall prohibits something.
<li><tt>QSocketDevice::NoResources</tt> - the operating system ran out of something.
<li><tt>QSocketDevice::Bug</tt> - there seems to be a bug in QSocketDevice.
<li><tt>QSocketDevice::Impossible</tt> - the impossible happened, usually because you confused
QSocketDevice horribly. Simple example:
<pre>
::close( sd->socket() );
sd->writeBlock( someData, 42 );
</pre>
The libc ::close() closes the socket, but QSocketDevice is not aware
of this. So when you call <a href="#writeBlock">writeBlock</a>(), the impossible happens.
<li><tt>QSocketDevice::NoFiles</tt> - the operating system will not let QSocketDevice open
another file.
<li><tt>QSocketDevice::ConnectionRefused</tt> - a connection attempt was rejected by the
peer.
<li><tt>QSocketDevice::NetworkFailure</tt> - there is a network failure between this host
and... and whatever.
<li><tt>QSocketDevice::UnknownError</tt> - the operating system reacted in a way that the
Qt developers did not foresee.
</ul>
<h3 class=fn><a name="Type-enum"></a>QSocketDevice::Type</h3>
<p> This enum type describes the type of the socket:
<ul>
<li><tt>QSocketDevice::Stream</tt> - a stream socket (TCP, usually)
<li><tt>QSocketDevice::Datagram</tt> - a datagram socket (UDP, usually)
</ul>
<hr><h2>Member Function Documentation</h2>
<h3 class=fn><a name="QSocketDevice"></a>QSocketDevice::QSocketDevice ( <a href="qsocketdevice.html#Type-enum">Type</a> type = Stream )
</h3>
Creates a QSocketDevice object for a stream or datagram socket.
<p> The <em>type</em> argument must be either <a href="#Type-enum">QSocketDevice::Stream</a> for a
reliable, connection-oriented TCP socket, or <a href="#Type-enum">QSocketDevice::Datagram</a> for an unreliable UDP socket.
<p> <p>See also <a href="#blocking">blocking</a>().
<h3 class=fn><a name="QSocketDevice-2"></a>QSocketDevice::QSocketDevice ( int socket, <a href="qsocketdevice.html#Type-enum">Type</a> type )
</h3>
Creates a QSocketDevice object for the existing socket <em>socket</em>.
<p> The <em>type</em> argument must match the actual socket type; use <a href="#Type-enum">QSocketDevice::Stream</a> for a reliable, connection-oriented TCP
socket, or <a href="#Type-enum">QSocketDevice::Datagram</a> for an unreliable,
connectionless UDP socket.
<h3 class=fn><a name="~QSocketDevice"></a>QSocketDevice::~QSocketDevice ()<tt> [virtual]</tt>
</h3>
Destroys the socket device and closes the socket if it is open.
<h3 class=fn>int <a name="accept"></a>QSocketDevice::accept ()<tt> [virtual]</tt>
</h3>
Extracts the first connection from the queue of pending connections
for this socket and returns a new socket identifier. Returns -1
if the operation failed.
<p> <p>See also <a href="#bind">bind</a>() and <a href="#listen">listen</a>().
<h3 class=fn><a href="qhostaddress.html">QHostAddress</a> <a name="address"></a>QSocketDevice::address () const
</h3>
Returns the address of this socket device. This may be 0.0.0.0 for a while,
but is set to something sensible when there is a sensible value it can have.
<h3 class=fn>bool <a name="addressReusable"></a>QSocketDevice::addressReusable () const
</h3>
Returns TRUE if the address of this socket can be used by other
sockets at the same time, and FALSE if this socket claims exclusive
ownership.
<p> <p>See also <a href="#setAddressReusable">setAddressReusable</a>().
<h3 class=fn>bool <a name="bind"></a>QSocketDevice::bind ( const <a href="qhostaddress.html">QHostAddress</a> & address, Q_UINT16 port )<tt> [virtual]</tt>
</h3>
Assigns a name to an unnamed socket. The name is the host address <em>address</em>
and the port number <em>port</em>. If the operation succeeds, <a href="#bind">bind</a>() returns TRUE.
Otherwise, it returns FALSE without changing what <a href="#port">port</a>() and <a href="#address">address</a>()
return.
<p> bind() is used by servers for setting up incoming connections.
Call bind() before <a href="#listen">listen</a>().
<h3 class=fn>bool <a name="blocking"></a>QSocketDevice::blocking () const
</h3>
Returns TRUE if the socket is in blocking mode, or FALSE if it
is in nonblocking mode or if the socket is invalid.
<p> Note that this function does not set <a href="#error">error</a>().
<p> <b>Warning:</b> On Windows, this function always returns TRUE since the
ioctlsocket() function is broken.
<p> <p>See also <a href="#setBlocking">setBlocking</a>() and <a href="#isValid">isValid</a>().
<h3 class=fn>Q_LONG <a name="bytesAvailable"></a>QSocketDevice::bytesAvailable () const
</h3>
Returns the number of bytes available for reading, or -1 if an
error occurred.
<p> <b>Warning:</b> On Microsoft Windows, we use the ioctlsocket() function
to determine the number of bytes queued on the socket.
According to Microsoft (KB Q125486), ioctlsocket() sometimes
return an incorrect number. The only safe way to determine the
amount of data on the socket is to read it using <a href="#readBlock">readBlock</a>().
<a href="qsocket.html">QSocket</a> has workarounds to deal with this problem.
<h3 class=fn>bool <a name="connect"></a>QSocketDevice::connect ( const <a href="qhostaddress.html">QHostAddress</a> & addr, Q_UINT16 port )<tt> [virtual]</tt>
</h3>
Connects to the IP address and port specified by <em>addr</em> and <em>port</em>.
Returns TRUE if it establishes a connection, and FALSE if not. <a href="#error">error</a>()
explains why.
<p> Note that error() commonly returns NoError for non-blocking sockets;
this just means that you can call <a href="#connect">connect</a>() again in a little while
and it'll probably succeed.
<h3 class=fn><a href="qsocketdevice.html#Error-enum">Error</a> <a name="error"></a>QSocketDevice::error () const
</h3>
Returns the first error seen.
<h3 class=fn>bool <a name="isValid"></a>QSocketDevice::isValid () const
</h3>
Returns TRUE if this is a valid socket; otherwise returns FALSE.
<p> <p>See also <a href="#socket">socket</a>().
<h3 class=fn>bool <a name="listen"></a>QSocketDevice::listen ( int backlog )<tt> [virtual]</tt>
</h3>
Specifies how many pending connections a server socket can have.
Returns TRUE if the operation was successful, otherwise FALSE.
<p> The <a href="#listen">listen</a>() call only applies to sockets where <a href="#type">type</a>() is <a href="#Type-enum">Stream</a>,
not <a href="#Type-enum">Datagram</a> sockets. listen() must not be called before <a href="#bind">bind</a>()
or after <a href="#accept">accept</a>(). It is common to use a <em>backlog</em> value of 50 on
most Unix systems.
<p> <p>See also <a href="#bind">bind</a>() and <a href="#accept">accept</a>().
<h3 class=fn><a href="qhostaddress.html">QHostAddress</a> <a name="peerAddress"></a>QSocketDevice::peerAddress () const
</h3>
Returns the address of the port this socket device is connected to. This may
be 0.0.0.0 for a while, but is set to something sensible when there is a
sensible value it can have.
<p> Note that for Datagram sockets, this is the source port of the last
packet received, and that it is in native byte order.
<h3 class=fn>Q_UINT16 <a name="peerPort"></a>QSocketDevice::peerPort () const
</h3>
Returns the port number of the port this socket device is connected to. This
may be 0 for a while, but is set to something sensible when there is a
sensible value it can have.
<p> Note that for Datagram sockets, this is the source port of the last packet
received.
<h3 class=fn>Q_UINT16 <a name="port"></a>QSocketDevice::port () const
</h3>
Returns the port number of this socket device. This may be 0 for a while,
but is set to something sensible when there is a sensible value it can have.
<p> Note that Qt always uses native byte order, i.e. 67 is 67 in Qt, there
is no need to call htons().
<h3 class=fn>Q_LONG <a name="readBlock"></a>QSocketDevice::readBlock ( char * data, Q_ULONG maxlen )<tt> [virtual]</tt>
</h3>
Reads max <em>maxlen</em> bytes from the socket into <em>data</em> and returns
the number of bytes read. Returns -1 if an error occurred.
<p>Reimplemented from <a href="qiodevice.html#readBlock">QIODevice</a>.
<h3 class=fn>int <a name="receiveBufferSize"></a>QSocketDevice::receiveBufferSize () const
</h3>
Returns the size of the OS receive buffer.
<p> <p>See also <a href="#setReceiveBufferSize">setReceiveBufferSize</a>().
<h3 class=fn>int <a name="sendBufferSize"></a>QSocketDevice::sendBufferSize () const
</h3>
Returns the size of the OS send buffer.
<p> <p>See also <a href="#setSendBufferSize">setSendBufferSize</a>().
<h3 class=fn>void <a name="setAddressReusable"></a>QSocketDevice::setAddressReusable ( bool enable )<tt> [virtual]</tt>
</h3>
Sets the address of this socket to be usable by other sockets too
if <em>enable</em> is TRUE, and to be used exclusively by this socket if
<em>enable</em> is FALSE.
<p> When a socket is reusable, other sockets can use the same port
number (and IP address), which is, in general, good. Of course other
sockets cannot use the same (address,port,peer-address,peer-port)
4-tuple as this socket, so there is no risk of confusing the two TCP
connections.
<p> <p>See also <a href="#addressReusable">addressReusable</a>().
<h3 class=fn>void <a name="setBlocking"></a>QSocketDevice::setBlocking ( bool enable )<tt> [virtual]</tt>
</h3>
Makes the socket blocking if <em>enable</em> is TRUE or nonblocking if
<em>enable</em> is FALSE.
<p> Sockets are blocking by default, but we recommend using
nonblocking socket operations, especially for GUI programs that need
to be responsive.
<p> <b>Warning:</b> On Windows, this function does nothing since the
ioctlsocket() function is broken.
<p> Whenever you use a <a href="qsocketnotifier.html">QSocketNotifier</a> on Windows, the socket is immediately
made nonblocking.
<p> <p>See also <a href="#blocking">blocking</a>() and <a href="#isValid">isValid</a>().
<h3 class=fn>void <a name="setError"></a>QSocketDevice::setError ( <a href="qsocketdevice.html#Error-enum">Error</a> err )<tt> [protected]</tt>
</h3>
Allows subclasses to set the error state to <em>err</em>.
<h3 class=fn>void <a name="setReceiveBufferSize"></a>QSocketDevice::setReceiveBufferSize ( uint size )<tt> [virtual]</tt>
</h3>
Sets the size of the OS receive buffer to <em>size</em>.
<p> The OS receive buffer size effectively limits two things: how much
data can be in transit at any one moment, and how much data can be
received in one iteration of the main event loop.
<p> The default is OS-dependent. A socket that receives large amounts
of data is probably best off with a buffer size of 49152.
<h3 class=fn>void <a name="setSendBufferSize"></a>QSocketDevice::setSendBufferSize ( uint size )<tt> [virtual]</tt>
</h3>
Sets the size of the OS send buffer to <em>size</em>.
<p> The OS send buffer size effectively limits how much data can be in
transit at any one moment.
<p> The default is OS-dependent. A socket that sends large amounts of
data is probably best off with a buffer size of 49152.
<h3 class=fn>void <a name="setSocket"></a>QSocketDevice::setSocket ( int socket, <a href="qsocketdevice.html#Type-enum">Type</a> type )<tt> [virtual]</tt>
</h3>
Sets the socket device to operate on the existing socket <em>socket</em>.
<p> The <em>type</em> argument must match the actual socket type;
use <a href="#Type-enum">QSocketDevice::Stream</a> for a reliable, connection-oriented TCP
socket, or <a href="#Type-enum">QSocketDevice::Datagram</a> for an unreliable,
connectionless UDP socket.
<p> Any existing socket is closed.
<p> <p>See also <a href="#isValid">isValid</a>() and <a href="qiodevice.html#close">close</a>().
<h3 class=fn>int <a name="socket"></a>QSocketDevice::socket () const
</h3>
Returns the socket number, or -1 if it is an invalid socket.
<p> <p>See also <a href="#isValid">isValid</a>() and <a href="#type">type</a>().
<h3 class=fn><a href="qsocketdevice.html#Type-enum">Type</a> <a name="type"></a>QSocketDevice::type () const
</h3>
<p> Returns the socket type which is either <a href="#Type-enum">QSocketDevice::Stream</a> or
<a href="#Type-enum">QSocketDevice::Datagram</a>.
<p> <p>See also <a href="#socket">socket</a>().
<h3 class=fn>Q_LONG <a name="waitForMore"></a>QSocketDevice::waitForMore ( int msecs, bool * timeout = 0 ) const
</h3>
Wait up to <em>msecs</em> milliseconds for more data to be available.
If <em>msecs</em> is -1 the call will block indefinitely.
<p> This is a blocking call and should be avoided in event driven
applications.
<p> Returns the number of bytes available for reading, or -1 if an
error occurred.
<p> If <em>timeout</em> is non-null and no error occurred (i.e. it does not return -1),
then this function sets <em>timeout</em> out to TRUE, if the reason for returning
was that the timeout was reached, otherwise it sets <em>timeout</em> to FALSE. This
is useful to find out if the peer closed the connection.
<p> <p>See also <a href="#bytesAvailable">bytesAvailable</a>().
<h3 class=fn>Q_LONG <a name="writeBlock"></a>QSocketDevice::writeBlock ( const char * data, Q_ULONG len )<tt> [virtual]</tt>
</h3>
Writes <em>len</em> bytes to the socket from <em>data</em> and returns
the number of bytes written. Returns -1 if an error occurred.
<p> This is used for <a href="#Type-enum">QSocketDevice::Stream</a> sockets.
<p>Reimplemented from <a href="qiodevice.html#writeBlock">QIODevice</a>.
<h3 class=fn>Q_LONG <a name="writeBlock-2"></a>QSocketDevice::writeBlock ( const char * data, Q_ULONG len, const <a href="qhostaddress.html">QHostAddress</a> & host, Q_UINT16 port )<tt> [virtual]</tt>
</h3> This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
<p> Writes <em>len</em> bytes to the socket from <em>data</em> and returns
the number of bytes written. Returns -1 if an error occurred.
<p> This is used for <a href="#Type-enum">QSocketDevice::Datagram</a> sockets. You have to specify the
<em>host</em> and <em>port</em> of the destination of the data.
<!-- eof -->
<hr><p>
This file is part of the <a href="index.html">Qt toolkit</a>.
Copyright © 1995-2001
<a href="http://www.trolltech.com/">Trolltech</a>. All Rights Reserved.<p><address><hr><div align=center>
<table width=100% cellspacing=0 border=0><tr>
<td>Copyright © 2001
<a href="http://www.trolltech.com">Trolltech</a><td><a href="http://www.trolltech.com/trademarks.html">Trademarks</a>
<td align=right><div align=right>Qt version 3.0.2</div>
</table></div></address></body>
</html>
distrib
>
Mandriva
>
8.2
>
i586
>
media
>
contrib
>
by-pkgid
>
112b0974ad288f6cd55bf971ee6026a9
>
files
>
1777
