<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
<html><head><title>QSocketNotifier Class Reference</title><style>h3.fn,span.fn { margin-left: 1cm; text-indent: -1cm }
a:link { color: #004faf; text-decoration: none }
a:visited { color: #672967; text-decoration: none }
td.postheader { font-family: sans-serif }
tr.address { font-family: sans-serif }
body { background: #ffffff; color: black; }
</style></head><body><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr /><td align="left" valign="top" width="32"><img align="left" border="0" height="32" src="images/rb-logo.png" width="32" /></td><td width="1">  </td><td class="postheader" 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="modules.html"><font color="#004faf">Modules</font></a></td></table><h1 align="center">QSocketNotifier Class Reference<br /><sup><sup>[<a href="qtcore.html">QtCore</a> module]</sup></sup></h1><p>The QSocketNotifier class provides support for monitoring
activity on a file descriptor. <a href="#details">More...</a></p>
<p>Inherits <a href="qobject.html">QObject</a>.</p><h3>Types</h3><ul><li><div class="fn" />enum <b><a href="qsocketnotifier.html#Type-enum">Type</a></b> { Read, Write, Exception }</li></ul><h3>Methods</h3><ul><li><div class="fn" /><b><a href="qsocketnotifier.html#QSocketNotifier">__init__</a></b> (<i>self</i>, int <i>socket</i>, Type <i>type</i>, QObject <i>parent</i> = None)</li><li><div class="fn" />bool <b><a href="qsocketnotifier.html#event">event</a></b> (<i>self</i>, QEvent)</li><li><div class="fn" />bool <b><a href="qsocketnotifier.html#isEnabled">isEnabled</a></b> (<i>self</i>)</li><li><div class="fn" /><b><a href="qsocketnotifier.html#setEnabled">setEnabled</a></b> (<i>self</i>, bool)</li><li><div class="fn" />int <b><a href="qsocketnotifier.html#socket">socket</a></b> (<i>self</i>)</li><li><div class="fn" />Type <b><a href="qsocketnotifier.html#type">type</a></b> (<i>self</i>)</li></ul><h3>Qt Signals</h3><ul><li><div class="fn" />void <b><a href="qsocketnotifier.html#activated">activated</a></b> (int)</li></ul><a name="details" /><hr /><h2>Detailed Description</h2><p>The QSocketNotifier class provides support for monitoring
activity on a file descriptor.</p>
<p>The QSocketNotifier makes it possible to integrate Qt's event
loop with other event loops based on file descriptors. For example,
the <a href="http://qt.digia.com/products/add-on-products/catalog/4/Utilities/qtcorba/">
CORBA Framework</a> uses it to process CORBA events. File
descriptor action is detected in Qt's main event loop (<a href="qcoreapplication.html#exec">QCoreApplication.exec</a>()).</p>
<a id="write-notifiers" name="write-notifiers" />
<p>Once you have opened a device using a low-level (usually
platform-specific) API, you can create a socket notifier to monitor
the file descriptor. The socket notifier is enabled by default,
i.e. it emits the <a href="qsocketnotifier.html#activated">activated</a>() signal whenever a
socket event corresponding to its type occurs. Connect the <a href="qsocketnotifier.html#activated">activated</a>() signal to the slot
you want to be called when an event corresponding to your socket
notifier's type occurs.</p>
<p>There are three types of socket notifiers: read, write, and
exception. The type is described by the <a href="qsocketnotifier.html#Type-enum">Type</a> enum, and must be
specified when constructing the socket notifier. After construction
it can be determined using the <a href="qsocketnotifier.html#type">type</a>() function. Note that if you
need to monitor both reads and writes for the same file descriptor,
you must create two socket notifiers. Note also that it is not
possible to install two socket notifiers of the same type (<a href="qsocketnotifier.html#Type-enum">Read</a>, <a href="qsocketnotifier.html#Type-enum">Write</a>, <a href="qsocketnotifier.html#Type-enum">Exception</a>) on the same
socket.</p>
<p>The <a href="qsocketnotifier.html#setEnabled">setEnabled</a>()
function allows you to disable as well as enable the socket
notifier. It is generally advisable to explicitly enable or disable
the socket notifier, especially for write notifiers. A disabled
notifier ignores socket events (the same effect as not creating the
socket notifier). Use the <a href="qsocketnotifier.html#isEnabled">isEnabled</a>() function to
determine the notifier's current status.</p>
<p>Finally, you can use the <a href="qsocketnotifier.html#socket">socket</a>() function to retrieve the
socket identifier. Although the class is called QSocketNotifier, it
is normally used for other types of devices than sockets. <a href="qtcpsocket.html">QTcpSocket</a> and <a href="qudpsocket.html">QUdpSocket</a> provide notification through
signals, so there is normally no need to use a QSocketNotifier on
them.</p>
<a id="notes-for-windows-users" name="notes-for-windows-users" />
<h3>Notes for Windows Users</h3>
<p>The socket passed to QSocketNotifier will become non-blocking,
even if it was created as a blocking socket. The <a href="qsocketnotifier.html#activated">activated</a>() signal is
sometimes triggered by high general activity on the host, even if
there is nothing to read. A subsequent read from the socket can
then fail, the error indicating that there is no data available
(e.g., <tt>WSAEWOULDBLOCK</tt>). This is an operating system
limitation, and not a bug in QSocketNotifier.</p>
<p>To ensure that the socket notifier handles read notifications
correctly, follow these steps when you receive a notification:</p>
<ol class="1">
<li>Disable the notifier.</li>
<li>Read data from the socket.</li>
<li>Re-enable the notifier if you are interested in more data (such
as after having written a new command to a remote server).</li>
</ol>
<p>To ensure that the socket notifier handles write notifications
correctly, follow these steps when you receive a notification:</p>
<ol class="1">
<li>Disable the notifier.</li>
<li>Write as much data as you can (before <tt>EWOULDBLOCK</tt> is
returned).</li>
<li>Re-enable notifier if you have more data to write.</li>
</ol>
<p><b>Further information:</b> On Windows, Qt always disables the
notifier after getting a notification, and only re-enables it if
more data is expected. For example, if data is read from the socket
and it can be used to read more, or if reading or writing is not
possible because the socket would block, in which case it is
necessary to wait before attempting to read or write again.</p>
<hr /><h2>Type Documentation</h2><h3 class="fn"><a name="Type-enum" />QSocketNotifier.Type</h3><p>This enum describes the various types of events that a socket
notifier can recognize. The type must be specified when
constructing the socket notifier.</p>
<p>Note that if you need to monitor both reads and writes for the
same file descriptor, you must create two socket notifiers. Note
also that it is not possible to install two socket notifiers of the
same type (Read, Write, Exception) on the same socket.</p>
<table class="valuelist">
<tr class="odd" valign="top">
<th class="tblConst">Constant</th>
<th class="tblval">Value</th>
<th class="tbldscr">Description</th>
</tr>
<tr>
<td class="topAlign"><tt>QSocketNotifier.Read</tt></td>
<td class="topAlign"><tt>0</tt></td>
<td class="topAlign">There is data to be read.</td>
</tr>
<tr>
<td class="topAlign"><tt>QSocketNotifier.Write</tt></td>
<td class="topAlign"><tt>1</tt></td>
<td class="topAlign">Data can be written.</td>
</tr>
<tr>
<td class="topAlign"><tt>QSocketNotifier.Exception</tt></td>
<td class="topAlign"><tt>2</tt></td>
<td class="topAlign">An exception has occurred. We recommend
against using this.</td>
</tr>
</table>
<p><b>See also</b> <a href="qsocketnotifier.html#QSocketNotifier">QSocketNotifier</a>() and
<a href="qsocketnotifier.html#type">type</a>().</p>
<hr /><h2>Method Documentation</h2><h3 class="fn"><a name="QSocketNotifier" />QSocketNotifier.__init__ (<i>self</i>, int <i>socket</i>, <a href="qsocketnotifier.html#Type-enum">Type</a> <i>type</i>, <a href="qobject.html">QObject</a> <i>parent</i> = None)</h3><p>The <i>parent</i> argument, if not None, causes <i>self</i> to be owned by Qt instead of PyQt.</p><p>Constructs a socket notifier with the given <i>parent</i>. It
enables the <i>socket</i>, and watches for events of the given
<i>type</i>.</p>
<p>It is generally advisable to explicitly enable or disable the
socket notifier, especially for write notifiers.</p>
<p><b>Note for Windows users:</b> The socket passed to <a href="qsocketnotifier.html">QSocketNotifier</a> will become
non-blocking, even if it was created as a blocking socket.</p>
<p><b>See also</b> <a href="qsocketnotifier.html#setEnabled">setEnabled</a>() and <a href="qsocketnotifier.html#isEnabled">isEnabled</a>().</p>
<h3 class="fn"><a name="event" />bool QSocketNotifier.event (<i>self</i>, <a href="qevent.html">QEvent</a>)</h3><p>Reimplemented from <a href="qobject.html#event">QObject.event</a>().</p>
<h3 class="fn"><a name="isEnabled" />bool QSocketNotifier.isEnabled (<i>self</i>)</h3><p>Returns true if the notifier is enabled; otherwise returns
false.</p>
<p><b>See also</b> <a href="qsocketnotifier.html#setEnabled">setEnabled</a>().</p>
<h3 class="fn"><a name="setEnabled" />QSocketNotifier.setEnabled (<i>self</i>, bool)</h3><p>This method is also a Qt slot with the C++ signature <tt>void setEnabled(bool)</tt>.</p><p>If <i>enable</i> is true, the notifier is enabled; otherwise the
notifier is disabled.</p>
<p>The notifier is enabled by default, i.e. it emits the <a href="qsocketnotifier.html#activated">activated</a>() signal whenever a
socket event corresponding to its <a href="qsocketnotifier.html#type">type</a> occurs. If it is disabled, it
ignores socket events (the same effect as not creating the socket
notifier).</p>
<p>Write notifiers should normally be disabled immediately after
the <a href="qsocketnotifier.html#activated">activated</a>() signal
has been emitted</p>
<p><b>See also</b> <a href="qsocketnotifier.html#isEnabled">isEnabled</a>() and <a href="qsocketnotifier.html#activated">activated</a>().</p>
<h3 class="fn"><a name="socket" />int QSocketNotifier.socket (<i>self</i>)</h3><p>Returns the socket identifier specified to the constructor.</p>
<p><b>See also</b> <a href="qsocketnotifier.html#type">type</a>().</p>
<h3 class="fn"><a name="type" /><a href="qsocketnotifier.html#Type-enum">Type</a> QSocketNotifier.type (<i>self</i>)</h3><p>Returns the socket event type specified to the constructor.</p>
<p><b>See also</b> <a href="qsocketnotifier.html#socket">socket</a>().</p>
<hr /><h2>Qt Signal Documentation</h2><h3 class="fn"><a name="activated" />void activated (int)</h3><p>This is the default overload of this signal.</p><p>This signal is emitted whenever the socket notifier is enabled
and a socket event corresponding to its <a href="qsocketnotifier.html#Type-enum">type</a> occurs.</p>
<p>The socket identifier is passed in the <i>socket</i>
parameter.</p>
<p><b>See also</b> <a href="qsocketnotifier.html#type">type</a>()
and <a href="qsocketnotifier.html#socket">socket</a>().</p>
<address><hr /><div align="center"><table border="0" cellspacing="0" width="100%"><tr class="address"><td align="left" width="25%">PyQt 4.10.3 for X11</td><td align="center" width="50%">Copyright © <a href="http://www.riverbankcomputing.com">Riverbank Computing Ltd</a> and <a href="http://www.qtsoftware.com">Nokia</a> 2012</td><td align="right" width="25%">Qt 4.8.5</td></tr></table></div></address></body></html>
