<?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>QIODevice 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">QIODevice Class Reference<br /><sup><sup>[<a href="qtcore.html">QtCore</a> module]</sup></sup></h1><p>The QIODevice class is the base interface class of all I/O
devices in Qt. <a href="#details">More...</a></p>
<p>Inherits <a href="qobject.html">QObject</a>.</p><p>Inherited by <a href="qabstractsocket.html">QAbstractSocket</a>, <a href="qbuffer.html">QBuffer</a>, <a href="qfile.html">QFile</a>, <a href="qlocalsocket.html">QLocalSocket</a>, <a href="qnetworkreply.html">QNetworkReply</a> and <a href="qprocess.html">QProcess</a>.</p><h3>Types</h3><ul><li><div class="fn" />class <b><a href="qiodevice-openmode.html">OpenMode</a></b></li><li><div class="fn" />enum <b><a href="qiodevice.html#OpenModeFlag-enum">OpenModeFlag</a></b> { NotOpen, ReadOnly, WriteOnly, ReadWrite, ..., Unbuffered }</li></ul><h3>Methods</h3><ul><li><div class="fn" /><b><a href="qiodevice.html#QIODevice">__init__</a></b> (<i>self</i>)</li><li><div class="fn" /><b><a href="qiodevice.html#QIODevice-2">__init__</a></b> (<i>self</i>, QObject <i>parent</i>)</li><li><div class="fn" />bool <b><a href="qiodevice.html#atEnd">atEnd</a></b> (<i>self</i>)</li><li><div class="fn" />int <b><a href="qiodevice.html#bytesAvailable">bytesAvailable</a></b> (<i>self</i>)</li><li><div class="fn" />int <b><a href="qiodevice.html#bytesToWrite">bytesToWrite</a></b> (<i>self</i>)</li><li><div class="fn" />bool <b><a href="qiodevice.html#canReadLine">canReadLine</a></b> (<i>self</i>)</li><li><div class="fn" /><b><a href="qiodevice.html#close">close</a></b> (<i>self</i>)</li><li><div class="fn" />QString <b><a href="qiodevice.html#errorString">errorString</a></b> (<i>self</i>)</li><li><div class="fn" />(bool, str <i>c</i>) <b><a href="qiodevice.html#getChar">getChar</a></b> (<i>self</i>)</li><li><div class="fn" />bool <b><a href="qiodevice.html#isOpen">isOpen</a></b> (<i>self</i>)</li><li><div class="fn" />bool <b><a href="qiodevice.html#isReadable">isReadable</a></b> (<i>self</i>)</li><li><div class="fn" />bool <b><a href="qiodevice.html#isSequential">isSequential</a></b> (<i>self</i>)</li><li><div class="fn" />bool <b><a href="qiodevice.html#isTextModeEnabled">isTextModeEnabled</a></b> (<i>self</i>)</li><li><div class="fn" />bool <b><a href="qiodevice.html#isWritable">isWritable</a></b> (<i>self</i>)</li><li><div class="fn" />bool <b><a href="qiodevice.html#open">open</a></b> (<i>self</i>, OpenMode <i>mode</i>)</li><li><div class="fn" />OpenMode <b><a href="qiodevice.html#openMode">openMode</a></b> (<i>self</i>)</li><li><div class="fn" />QByteArray <b><a href="qiodevice.html#peek">peek</a></b> (<i>self</i>, int <i>maxlen</i>)</li><li><div class="fn" />int <b><a href="qiodevice.html#pos">pos</a></b> (<i>self</i>)</li><li><div class="fn" />bool <b><a href="qiodevice.html#putChar">putChar</a></b> (<i>self</i>, str <i>c</i>)</li><li><div class="fn" />str <b><a href="qiodevice.html#read">read</a></b> (<i>self</i>, int <i>maxlen</i>)</li><li><div class="fn" />QByteArray <b><a href="qiodevice.html#readAll">readAll</a></b> (<i>self</i>)</li><li><div class="fn" />str <b><a href="qiodevice.html#readData">readData</a></b> (<i>self</i>, int <i>maxlen</i>)</li><li><div class="fn" />str <b><a href="qiodevice.html#readLine">readLine</a></b> (<i>self</i>, int <i>maxlen</i> = 0)</li><li><div class="fn" />str <b><a href="qiodevice.html#readLineData">readLineData</a></b> (<i>self</i>, int <i>maxlen</i>)</li><li><div class="fn" />bool <b><a href="qiodevice.html#reset">reset</a></b> (<i>self</i>)</li><li><div class="fn" />bool <b><a href="qiodevice.html#seek">seek</a></b> (<i>self</i>, int <i>pos</i>)</li><li><div class="fn" /><b><a href="qiodevice.html#setErrorString">setErrorString</a></b> (<i>self</i>, QString <i>errorString</i>)</li><li><div class="fn" /><b><a href="qiodevice.html#setOpenMode">setOpenMode</a></b> (<i>self</i>, OpenMode <i>openMode</i>)</li><li><div class="fn" /><b><a href="qiodevice.html#setTextModeEnabled">setTextModeEnabled</a></b> (<i>self</i>, bool <i>enabled</i>)</li><li><div class="fn" />int <b><a href="qiodevice.html#size">size</a></b> (<i>self</i>)</li><li><div class="fn" /><b><a href="qiodevice.html#ungetChar">ungetChar</a></b> (<i>self</i>, str <i>c</i>)</li><li><div class="fn" />bool <b><a href="qiodevice.html#waitForBytesWritten">waitForBytesWritten</a></b> (<i>self</i>, int <i>msecs</i>)</li><li><div class="fn" />bool <b><a href="qiodevice.html#waitForReadyRead">waitForReadyRead</a></b> (<i>self</i>, int <i>msecs</i>)</li><li><div class="fn" />int <b><a href="qiodevice.html#write">write</a></b> (<i>self</i>, QByteArray <i>data</i>)</li><li><div class="fn" />int <b><a href="qiodevice.html#writeData">writeData</a></b> (<i>self</i>, str <i>data</i>)</li></ul><h3>Qt Signals</h3><ul><li><div class="fn" />void <b><a href="qiodevice.html#aboutToClose">aboutToClose</a></b> ()</li><li><div class="fn" />void <b><a href="qiodevice.html#bytesWritten">bytesWritten</a></b> (qint64)</li><li><div class="fn" />void <b><a href="qiodevice.html#readChannelFinished">readChannelFinished</a></b> ()</li><li><div class="fn" />void <b><a href="qiodevice.html#readyRead">readyRead</a></b> ()</li></ul><a name="details" /><hr /><h2>Detailed Description</h2><p>The QIODevice class is the base interface class of all I/O
devices in Qt.</p>
<p>QIODevice provides both a common implementation and an abstract
interface for devices that support reading and writing of blocks of
data, such as <a href="qfile.html">QFile</a>, <a href="qbuffer.html">QBuffer</a> and <a href="qtcpsocket.html">QTcpSocket</a>. QIODevice is abstract and can not
be instantiated, but it is common to use the interface it defines
to provide device-independent I/O features. For example, Qt's XML
classes operate on a QIODevice pointer, allowing them to be used
with various devices (such as files and buffers).</p>
<p>Before accessing the device, <a href="qiodevice.html#open">open</a>() must be called to set the correct
<a href="qiodevice.html#OpenModeFlag-enum">OpenMode</a> (such as
<a href="qiodevice.html#OpenModeFlag-enum">ReadOnly</a> or <a href="qiodevice.html#OpenModeFlag-enum">ReadWrite</a>). You can then
write to the device with <a href="qiodevice.html#write">write</a>()
or <a href="qiodevice.html#putChar">putChar</a>(), and read by
calling either <a href="qiodevice.html#read">read</a>(), <a href="qiodevice.html#readLine">readLine</a>(), or <a href="qiodevice.html#readAll">readAll</a>(). Call <a href="qiodevice.html#close">close</a>() when you are done with the
device.</p>
<p>QIODevice distinguishes between two types of devices:
random-access devices and sequential devices.</p>
<ul>
<li>Random-access devices support seeking to arbitrary positions
using <a href="qiodevice.html#seek">seek</a>(). The current
position in the file is available by calling <a href="qiodevice.html#pos">pos</a>(). <a href="qfile.html">QFile</a> and
<a href="qbuffer.html">QBuffer</a> are examples of random-access
devices.</li>
<li>Sequential devices don't support seeking to arbitrary
positions. The data must be read in one pass. The functions
<a href="qiodevice.html#pos">pos</a>() and <a href="qiodevice.html#size">size</a>() don't work for sequential devices.
<a href="qtcpsocket.html">QTcpSocket</a> and <a href="qprocess.html">QProcess</a> are examples of sequential
devices.</li>
</ul>
<p>You can use <a href="qiodevice.html#isSequential">isSequential</a>() to determine the
type of device.</p>
<p>QIODevice emits <a href="qiodevice.html#readyRead">readyRead</a>() when new data is
available for reading; for example, if new data has arrived on the
network or if additional data is appended to a file that you are
reading from. You can call <a href="qiodevice.html#bytesAvailable">bytesAvailable</a>() to determine
the number of bytes that are currently available for reading. It's
common to use <a href="qiodevice.html#bytesAvailable">bytesAvailable</a>() together with
the <a href="qiodevice.html#readyRead">readyRead</a>() signal when
programming with asynchronous devices such as <a href="qtcpsocket.html">QTcpSocket</a>, where fragments of data can
arrive at arbitrary points in time. QIODevice emits the <a href="qiodevice.html#bytesWritten">bytesWritten</a>() signal every time
a payload of data has been written to the device. Use <a href="qiodevice.html#bytesToWrite">bytesToWrite</a>() to determine the
current amount of data waiting to be written.</p>
<p>Certain subclasses of QIODevice, such as <a href="qtcpsocket.html">QTcpSocket</a> and <a href="qprocess.html">QProcess</a>, are asynchronous. This means that I/O
functions such as <a href="qiodevice.html#write">write</a>() or
<a href="qiodevice.html#read">read</a>() always return immediately,
while communication with the device itself may happen when control
goes back to the event loop. QIODevice provides functions that
allow you to force these operations to be performed immediately,
while blocking the calling thread and without entering the event
loop. This allows QIODevice subclasses to be used without an event
loop, or in a separate thread:</p>
<ul>
<li><a href="qiodevice.html#waitForReadyRead">waitForReadyRead</a>() - This
function suspends operation in the calling thread until new data is
available for reading.</li>
<li><a href="qiodevice.html#waitForBytesWritten">waitForBytesWritten</a>() -
This function suspends operation in the calling thread until one
payload of data has been written to the device.</li>
<li>waitFor....() - Subclasses of QIODevice implement blocking
functions for device-specific operations. For example, <a href="qprocess.html">QProcess</a> has a function called waitForStarted()
which suspends operation in the calling thread until the process
has started.</li>
</ul>
<p>Calling these functions from the main, GUI thread, may cause
your user interface to freeze. Example:</p>
<pre class="cpp">
<span class="type"><a href="qprocess.html">QProcess</a></span> gzip;
gzip<span class="operator">.</span>start(<span class="string">"gzip"</span><span class="operator">,</span> <span class="type"><a href="qstringlist.html">QStringList</a></span>() <span class="operator"><</span><span class="operator"><</span> <span class="string">"-c"</span>);
<span class="keyword">if</span> (<span class="operator">!</span>gzip<span class="operator">.</span>waitForStarted())
<span class="keyword">return</span> <span class="keyword">false</span>;
gzip<span class="operator">.</span><a href="qiodevice.html#write">write</a>(<span class="string">"uncompressed data"</span>);
<span class="type"><a href="qbytearray.html">QByteArray</a></span> compressed;
<span class="keyword">while</span> (gzip<span class="operator">.</span>waitForReadyRead())
compressed <span class="operator">+</span><span class="operator">=</span> gzip<span class="operator">.</span><a href="qiodevice.html#readAll">readAll</a>();
</pre>
<p>By subclassing QIODevice, you can provide the same interface to
your own I/O devices. Subclasses of QIODevice are only required to
implement the protected <a href="qiodevice.html#readData">readData</a>() and <a href="qiodevice.html#writeData">writeData</a>() functions. QIODevice
uses these functions to implement all its convenience functions,
such as <a href="qiodevice.html#getChar">getChar</a>(), <a href="qiodevice.html#readLine">readLine</a>() and <a href="qiodevice.html#write">write</a>(). QIODevice also handles access
control for you, so you can safely assume that the device is opened
in write mode if <a href="qiodevice.html#writeData">writeData</a>()
is called.</p>
<p>Some subclasses, such as <a href="qfile.html">QFile</a> and
<a href="qtcpsocket.html">QTcpSocket</a>, are implemented using a
memory buffer for intermediate storing of data. This reduces the
number of required device accessing calls, which are often very
slow. Buffering makes functions like <a href="qiodevice.html#getChar">getChar</a>() and <a href="qiodevice.html#putChar">putChar</a>() fast, as they can operate on
the memory buffer instead of directly on the device itself. Certain
I/O operations, however, don't work well with a buffer. For
example, if several users open the same device and read it
character by character, they may end up reading the same data when
they meant to read a separate chunk each. For this reason,
QIODevice allows you to bypass any buffering by passing the
Unbuffered flag to <a href="qiodevice.html#open">open</a>(). When
subclassing QIODevice, remember to bypass any buffer you may use
when the device is open in Unbuffered mode.</p>
<hr /><h2>Type Documentation</h2><h3 class="fn"><a name="OpenModeFlag-enum" />QIODevice.OpenModeFlag</h3><p>This enum is used with <a href="qiodevice.html#open">open</a>()
to describe the mode in which a device is opened. It is also
returned by <a href="qiodevice.html#openMode">openMode</a>().</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>QIODevice.NotOpen</tt></td>
<td class="topAlign"><tt>0x0000</tt></td>
<td class="topAlign">The device is not open.</td>
</tr>
<tr>
<td class="topAlign"><tt>QIODevice.ReadOnly</tt></td>
<td class="topAlign"><tt>0x0001</tt></td>
<td class="topAlign">The device is open for reading.</td>
</tr>
<tr>
<td class="topAlign"><tt>QIODevice.WriteOnly</tt></td>
<td class="topAlign"><tt>0x0002</tt></td>
<td class="topAlign">The device is open for writing.</td>
</tr>
<tr>
<td class="topAlign"><tt>QIODevice.ReadWrite</tt></td>
<td class="topAlign"><tt>ReadOnly | WriteOnly</tt></td>
<td class="topAlign">The device is open for reading and
writing.</td>
</tr>
<tr>
<td class="topAlign"><tt>QIODevice.Append</tt></td>
<td class="topAlign"><tt>0x0004</tt></td>
<td class="topAlign">The device is opened in append mode, so that
all data is written to the end of the file.</td>
</tr>
<tr>
<td class="topAlign"><tt>QIODevice.Truncate</tt></td>
<td class="topAlign"><tt>0x0008</tt></td>
<td class="topAlign">If possible, the device is truncated before it
is opened. All earlier contents of the device are lost.</td>
</tr>
<tr>
<td class="topAlign"><tt>QIODevice.Text</tt></td>
<td class="topAlign"><tt>0x0010</tt></td>
<td class="topAlign">When reading, the end-of-line terminators are
translated to '\n'. When writing, the end-of-line terminators are
translated to the local encoding, for example '\r\n' for
Win32.</td>
</tr>
<tr>
<td class="topAlign"><tt>QIODevice.Unbuffered</tt></td>
<td class="topAlign"><tt>0x0020</tt></td>
<td class="topAlign">Any buffer in the device is bypassed.</td>
</tr>
</table>
<p>Certain flags, such as <tt>Unbuffered</tt> and
<tt>Truncate</tt>, are meaningless when used with some subclasses.
Some of these restrictions are implied by the type of device that
is represented by a subclass. In other cases, the restriction may
be due to the implementation, or may be imposed by the underlying
platform; for example, <a href="qtcpsocket.html">QTcpSocket</a>
does not support <tt>Unbuffered</tt> mode, and limitations in the
native API prevent <a href="qfile.html">QFile</a> from supporting
<tt>Unbuffered</tt> on Windows.</p>
<p>The OpenMode type is a typedef for <a href="qflags.html">QFlags</a><OpenModeFlag>. It stores an OR
combination of OpenModeFlag values.</p>
<hr /><h2>Method Documentation</h2><h3 class="fn"><a name="QIODevice" />QIODevice.__init__ (<i>self</i>)</h3><p>Constructs a <a href="qiodevice.html">QIODevice</a> object.</p>
<h3 class="fn"><a name="QIODevice-2" />QIODevice.__init__ (<i>self</i>, <a href="qobject.html">QObject</a> <i>parent</i>)</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 <a href="qiodevice.html">QIODevice</a> object with
the given <i>parent</i>.</p>
<h3 class="fn"><a name="atEnd" />bool QIODevice.atEnd (<i>self</i>)</h3><p>Returns true if the current read and write position is at the
end of the device (i.e. there is no more data available for reading
on the device); otherwise returns false.</p>
<p>For some devices, atEnd() can return true even though there is
more data to read. This special case only applies to devices that
generate data in direct response to you calling <a href="qiodevice.html#read">read</a>() (e.g., <tt>/dev</tt> or
<tt>/proc</tt> files on Unix and Mac OS X, or console input /
<tt>stdin</tt> on all platforms).</p>
<p><b>See also</b> <a href="qiodevice.html#bytesAvailable">bytesAvailable</a>(), <a href="qiodevice.html#read">read</a>(), and <a href="qiodevice.html#isSequential">isSequential</a>().</p>
<h3 class="fn"><a name="bytesAvailable" />int QIODevice.bytesAvailable (<i>self</i>)</h3><p>Returns the number of bytes that are available for reading. This
function is commonly used with sequential devices to determine the
number of bytes to allocate in a buffer before reading.</p>
<p>Subclasses that reimplement this function must call the base
implementation in order to include the size of QIODevices' buffer.
Example:</p>
<pre class="cpp">
<span class="type"><a href="qtcore.html#qint64-typedef">long</a></span> CustomDevice<span class="operator">.</span>bytesAvailable() <span class="keyword">const</span>
{
<span class="keyword">return</span> buffer<span class="operator">.</span>size() <span class="operator">+</span> <span class="type"><a href="qiodevice.html">QIODevice</a></span><span class="operator">.</span>bytesAvailable();
}
</pre>
<p><b>See also</b> <a href="qiodevice.html#bytesToWrite">bytesToWrite</a>(), <a href="qiodevice.html#readyRead">readyRead</a>(), and <a href="qiodevice.html#isSequential">isSequential</a>().</p>
<h3 class="fn"><a name="bytesToWrite" />int QIODevice.bytesToWrite (<i>self</i>)</h3><p>For buffered devices, this function returns the number of bytes
waiting to be written. For devices with no buffer, this function
returns 0.</p>
<p><b>See also</b> <a href="qiodevice.html#bytesAvailable">bytesAvailable</a>(), <a href="qiodevice.html#bytesWritten">bytesWritten</a>(), and <a href="qiodevice.html#isSequential">isSequential</a>().</p>
<h3 class="fn"><a name="canReadLine" />bool QIODevice.canReadLine (<i>self</i>)</h3><p>Returns true if a complete line of data can be read from the
device; otherwise returns false.</p>
<p>Note that unbuffered devices, which have no way of determining
what can be read, always return false.</p>
<p>This function is often called in conjunction with the <a href="qiodevice.html#readyRead">readyRead</a>() signal.</p>
<p>Subclasses that reimplement this function must call the base
implementation in order to include the contents of the <a href="qiodevice.html">QIODevice</a>'s buffer. Example:</p>
<pre class="cpp">
<span class="type">bool</span> CustomDevice<span class="operator">.</span>canReadLine() <span class="keyword">const</span>
{
<span class="keyword">return</span> buffer<span class="operator">.</span>contains(<span class="char">'\n'</span>) <span class="operator">|</span><span class="operator">|</span> <span class="type"><a href="qiodevice.html">QIODevice</a></span><span class="operator">.</span>canReadLine();
}
</pre>
<p><b>See also</b> <a href="qiodevice.html#readyRead">readyRead</a>() and <a href="qiodevice.html#readLine">readLine</a>().</p>
<h3 class="fn"><a name="close" />QIODevice.close (<i>self</i>)</h3><p>First emits <a href="qiodevice.html#aboutToClose">aboutToClose</a>(), then closes the
device and sets its <a href="qiodevice.html#OpenModeFlag-enum">OpenMode</a> to <a href="qiodevice.html#OpenModeFlag-enum">NotOpen</a>. The error string is
also reset.</p>
<p><b>See also</b> <a href="qiodevice.html#setOpenMode">setOpenMode</a>() and <a href="qiodevice.html#OpenModeFlag-enum">OpenMode</a>.</p>
<h3 class="fn"><a name="errorString" />QString QIODevice.errorString (<i>self</i>)</h3><p>Returns a human-readable description of the last device error
that occurred.</p>
<p><b>See also</b> <a href="qiodevice.html#setErrorString">setErrorString</a>().</p>
<h3 class="fn"><a name="getChar" />(bool, str <i>c</i>) QIODevice.getChar (<i>self</i>)</h3><p>Reads one character from the device and stores it in <i>c</i>.
If <i>c</i> is 0, the character is discarded. Returns true on
success; otherwise returns false.</p>
<p><b>See also</b> <a href="qiodevice.html#read">read</a>(),
<a href="qiodevice.html#putChar">putChar</a>(), and <a href="qiodevice.html#ungetChar">ungetChar</a>().</p>
<h3 class="fn"><a name="isOpen" />bool QIODevice.isOpen (<i>self</i>)</h3><p>Returns true if the device is open; otherwise returns false. A
device is open if it can be read from and/or written to. By
default, this function returns false if <a href="qiodevice.html#openMode">openMode</a>() returns
<tt>NotOpen</tt>.</p>
<p><b>See also</b> <a href="qiodevice.html#openMode">openMode</a>()
and <a href="qiodevice.html#OpenModeFlag-enum">OpenMode</a>.</p>
<h3 class="fn"><a name="isReadable" />bool QIODevice.isReadable (<i>self</i>)</h3><p>Returns true if data can be read from the device; otherwise
returns false. Use <a href="qiodevice.html#bytesAvailable">bytesAvailable</a>() to determine
how many bytes can be read.</p>
<p>This is a convenience function which checks if the <a href="qiodevice.html#OpenModeFlag-enum">OpenMode</a> of the device
contains the <a href="qiodevice.html#OpenModeFlag-enum">ReadOnly</a> flag.</p>
<p><b>See also</b> <a href="qiodevice.html#openMode">openMode</a>()
and <a href="qiodevice.html#OpenModeFlag-enum">OpenMode</a>.</p>
<h3 class="fn"><a name="isSequential" />bool QIODevice.isSequential (<i>self</i>)</h3><p>Returns true if this device is sequential; otherwise returns
false.</p>
<p>Sequential devices, as opposed to a random-access devices, have
no concept of a start, an end, a size, or a current position, and
they do not support seeking. You can only read from the device when
it reports that data is available. The most common example of a
sequential device is a network socket. On Unix, special files such
as /dev/zero and fifo pipes are sequential.</p>
<p>Regular files, on the other hand, do support random access. They
have both a size and a current position, and they also support
seeking backwards and forwards in the data stream. Regular files
are non-sequential.</p>
<p>The <a href="qiodevice.html">QIODevice</a> implementation
returns false.</p>
<p><b>See also</b> <a href="qiodevice.html#bytesAvailable">bytesAvailable</a>().</p>
<h3 class="fn"><a name="isTextModeEnabled" />bool QIODevice.isTextModeEnabled (<i>self</i>)</h3><p>Returns true if the <a href="qiodevice.html#OpenModeFlag-enum">Text</a> flag is enabled;
otherwise returns false.</p>
<p><b>See also</b> <a href="qiodevice.html#setTextModeEnabled">setTextModeEnabled</a>().</p>
<h3 class="fn"><a name="isWritable" />bool QIODevice.isWritable (<i>self</i>)</h3><p>Returns true if data can be written to the device; otherwise
returns false.</p>
<p>This is a convenience function which checks if the <a href="qiodevice.html#OpenModeFlag-enum">OpenMode</a> of the device
contains the <a href="qiodevice.html#OpenModeFlag-enum">WriteOnly</a> flag.</p>
<p><b>See also</b> <a href="qiodevice.html#openMode">openMode</a>()
and <a href="qiodevice.html#OpenModeFlag-enum">OpenMode</a>.</p>
<h3 class="fn"><a name="open" />bool QIODevice.open (<i>self</i>, <a href="qiodevice-openmode.html">OpenMode</a> <i>mode</i>)</h3><p>Opens the device and sets its <a href="qiodevice.html#OpenModeFlag-enum">OpenMode</a> to <i>mode</i>.
Returns true if successful; otherwise returns false. This function
should be called from any reimplementations of open() or other
functions that open the device.</p>
<p><b>See also</b> <a href="qiodevice.html#openMode">openMode</a>()
and <a href="qiodevice.html#OpenModeFlag-enum">OpenMode</a>.</p>
<h3 class="fn"><a name="openMode" /><a href="qiodevice-openmode.html">OpenMode</a> QIODevice.openMode (<i>self</i>)</h3><p>Returns the mode in which the device has been opened; i.e.
<a href="qiodevice.html#OpenModeFlag-enum">ReadOnly</a> or <a href="qiodevice.html#OpenModeFlag-enum">WriteOnly</a>.</p>
<p><b>See also</b> <a href="qiodevice.html#setOpenMode">setOpenMode</a>() and <a href="qiodevice.html#OpenModeFlag-enum">OpenMode</a>.</p>
<h3 class="fn"><a name="peek" /><a href="qbytearray.html">QByteArray</a> QIODevice.peek (<i>self</i>, int <i>maxlen</i>)</h3><p>Reads at most <i>maxSize</i> bytes from the device into
<i>data</i>, without side effects (i.e., if you call <a href="qiodevice.html#read">read</a>() after peek(), you will get the
same data). Returns the number of bytes read. If an error occurs,
such as when attempting to peek a device opened in <a href="qiodevice.html#OpenModeFlag-enum">WriteOnly</a> mode, this
function returns -1.</p>
<p>0 is returned when no more data is available for reading.</p>
<p>Example:</p>
<pre class="cpp">
<span class="type">bool</span> isExeFile(<span class="type"><a href="qfile.html">QFile</a></span> <span class="operator">*</span>file)
{
<span class="type">char</span> buf<span class="operator">[</span><span class="number">2</span><span class="operator">]</span>;
<span class="keyword">if</span> (file<span class="operator">-</span><span class="operator">></span>peek(buf<span class="operator">,</span> <span class="keyword">sizeof</span>(buf)) <span class="operator">=</span><span class="operator">=</span> <span class="keyword">sizeof</span>(buf))
<span class="keyword">return</span> (buf<span class="operator">[</span><span class="number">0</span><span class="operator">]</span> <span class="operator">=</span><span class="operator">=</span> <span class="char">'M'</span> <span class="operator">&</span><span class="operator">&</span> buf<span class="operator">[</span><span class="number">1</span><span class="operator">]</span> <span class="operator">=</span><span class="operator">=</span> <span class="char">'Z'</span>);
<span class="keyword">return</span> <span class="keyword">false</span>;
}
</pre>
<p>This function was introduced in Qt 4.1.</p>
<p><b>See also</b> <a href="qiodevice.html#read">read</a>().</p>
<h3 class="fn"><a name="pos" />int QIODevice.pos (<i>self</i>)</h3><p>For random-access devices, this function returns the position
that data is written to or read from. For sequential devices or
closed devices, where there is no concept of a "current position",
0 is returned.</p>
<p>The current read/write position of the device is maintained
internally by <a href="qiodevice.html">QIODevice</a>, so
reimplementing this function is not necessary. When subclassing
<a href="qiodevice.html">QIODevice</a>, use <a href="qiodevice.html#seek">QIODevice.seek</a>() to notify <a href="qiodevice.html">QIODevice</a> about changes in the device
position.</p>
<p><b>See also</b> <a href="qiodevice.html#isSequential">isSequential</a>() and <a href="qiodevice.html#seek">seek</a>().</p>
<h3 class="fn"><a name="putChar" />bool QIODevice.putChar (<i>self</i>, str <i>c</i>)</h3><p>Writes the character <i>c</i> to the device. Returns true on
success; otherwise returns false.</p>
<p><b>See also</b> <a href="qiodevice.html#write">write</a>(),
<a href="qiodevice.html#getChar">getChar</a>(), and <a href="qiodevice.html#ungetChar">ungetChar</a>().</p>
<h3 class="fn"><a name="read" />str QIODevice.read (<i>self</i>, int <i>maxlen</i>)</h3><p>Reads at most <i>maxSize</i> bytes from the device into
<i>data</i>, and returns the number of bytes read. If an error
occurs, such as when attempting to read from a device opened in
<a href="qiodevice.html#OpenModeFlag-enum">WriteOnly</a> mode, this
function returns -1.</p>
<p>0 is returned when no more data is available for reading.
However, reading past the end of the stream is considered an error,
so this function returns -1 in those cases (that is, reading on a
closed socket or after a process has died).</p>
<p><b>See also</b> <a href="qiodevice.html#readData">readData</a>(), <a href="qiodevice.html#readLine">readLine</a>(), and <a href="qiodevice.html#write">write</a>().</p>
<h3 class="fn"><a name="readAll" /><a href="qbytearray.html">QByteArray</a> QIODevice.readAll (<i>self</i>)</h3><p>This is an overloaded function.</p>
<p>Reads all available data from the device, and returns it as a
<a href="qbytearray.html">QByteArray</a>.</p>
<p>This function has no way of reporting errors; returning an empty
QByteArray() can mean either that no data was currently available
for reading, or that an error occurred.</p>
<h3 class="fn"><a name="readData" />str QIODevice.readData (<i>self</i>, int <i>maxlen</i>)</h3><p>This method is abstract and should be reimplemented in any sub-class.</p><p>Reads up to <i>maxSize</i> bytes from the device into
<i>data</i>, and returns the number of bytes read or -1 if an error
occurred.</p>
<p>If there are no bytes to be read and there can never be more
bytes available (examples include socket closed, pipe closed,
sub-process finished), this function returns -1.</p>
<p>This function is called by <a href="qiodevice.html">QIODevice</a>. Reimplement this function when
creating a subclass of <a href="qiodevice.html">QIODevice</a>.</p>
<p>When reimplementing this function it is important that this
function reads all the required data before returning. This is
required in order for <a href="qdatastream.html">QDataStream</a> to
be able to operate on the class. <a href="qdatastream.html">QDataStream</a> assumes all the requested
information was read and therefore does not retry reading if there
was a problem.</p>
<p><b>See also</b> <a href="qiodevice.html#read">read</a>(),
<a href="qiodevice.html#readLine">readLine</a>(), and <a href="qiodevice.html#writeData">writeData</a>().</p>
<h3 class="fn"><a name="readLine" />str QIODevice.readLine (<i>self</i>, int <i>maxlen</i> = 0)</h3><p>This function reads a line of ASCII characters from the device,
up to a maximum of <i>maxSize</i> - 1 bytes, stores the characters
in <i>data</i>, and returns the number of bytes read. If a line
could not be read but no error ocurred, this function returns 0. If
an error occurs, this function returns the length of what could be
read, or -1 if nothing was read.</p>
<p>A terminating '\0' byte is always appended to <i>data</i>, so
<i>maxSize</i> must be larger than 1.</p>
<p>Data is read until either of the following conditions are
met:</p>
<ul>
<li>The first '\n' character is read.</li>
<li><i>maxSize</i> - 1 bytes are read.</li>
<li>The end of the device data is detected.</li>
</ul>
<p>For example, the following code reads a line of characters from
a file:</p>
<pre class="cpp">
<span class="type"><a href="qfile.html">QFile</a></span> file(<span class="string">"box.txt"</span>);
<span class="keyword">if</span> (file<span class="operator">.</span>open(<span class="type"><a href="qfile.html">QFile</a></span><span class="operator">.</span>ReadOnly)) {
<span class="type">char</span> buf<span class="operator">[</span><span class="number">1024</span><span class="operator">]</span>;
<span class="type"><a href="qtcore.html#qint64-typedef">long</a></span> lineLength <span class="operator">=</span> file<span class="operator">.</span>readLine(buf<span class="operator">,</span> <span class="keyword">sizeof</span>(buf));
<span class="keyword">if</span> (lineLength <span class="operator">!</span><span class="operator">=</span> <span class="operator">-</span><span class="number">1</span>) {
<span class="comment">// the line is available in buf</span>
}
}
</pre>
<p>The newline character ('\n') is included in the buffer. If a
newline is not encountered before maxSize - 1 bytes are read, a
newline will not be inserted into the buffer. On windows newline
characters are replaced with '\n'.</p>
<p>This function calls <a href="qiodevice.html#readLineData">readLineData</a>(), which is
implemented using repeated calls to <a href="qiodevice.html#getChar">getChar</a>(). You can provide a more
efficient implementation by reimplementing <a href="qiodevice.html#readLineData">readLineData</a>() in your own
subclass.</p>
<p><b>See also</b> <a href="qiodevice.html#getChar">getChar</a>(),
<a href="qiodevice.html#read">read</a>(), and <a href="qiodevice.html#write">write</a>().</p>
<h3 class="fn"><a name="readLineData" />str QIODevice.readLineData (<i>self</i>, int <i>maxlen</i>)</h3><p>Reads up to <i>maxSize</i> characters into <i>data</i> and
returns the number of characters read.</p>
<p>This function is called by <a href="qiodevice.html#readLine">readLine</a>(), and provides its base
implementation, using <a href="qiodevice.html#getChar">getChar</a>(). Buffered devices can
improve the performance of <a href="qiodevice.html#readLine">readLine</a>() by reimplementing this
function.</p>
<p><a href="qiodevice.html#readLine">readLine</a>() appends a '\0'
byte to <i>data</i>; readLineData() does not need to do this.</p>
<p>If you reimplement this function, be careful to return the
correct value: it should return the number of bytes read in this
line, including the terminating newline, or 0 if there is no line
to be read at this point. If an error occurs, it should return -1
if and only if no bytes were read. Reading past EOF is considered
an error.</p>
<h3 class="fn"><a name="reset" />bool QIODevice.reset (<i>self</i>)</h3><p>Seeks to the start of input for random-access devices. Returns
true on success; otherwise returns false (for example, if the
device is not open).</p>
<p>Note that when using a <a href="qtextstream.html">QTextStream</a> on a <a href="qfile.html">QFile</a>, calling reset() on the <a href="qfile.html">QFile</a> will not have the expected result because
<a href="qtextstream.html">QTextStream</a> buffers the file. Use
the <a href="qtextstream.html#seek">QTextStream.seek</a>()
function instead.</p>
<p><b>See also</b> <a href="qiodevice.html#seek">seek</a>().</p>
<h3 class="fn"><a name="seek" />bool QIODevice.seek (<i>self</i>, int <i>pos</i>)</h3><p>For random-access devices, this function sets the current
position to <i>pos</i>, returning true on success, or false if an
error occurred. For sequential devices, the default behavior is to
do nothing and return false.</p>
<p>When subclassing <a href="qiodevice.html">QIODevice</a>, you
must call QIODevice.seek() at the start of your function to ensure
integrity with <a href="qiodevice.html">QIODevice</a>'s built-in
buffer. The base implementation always returns true.</p>
<p><b>See also</b> <a href="qiodevice.html#pos">pos</a>() and
<a href="qiodevice.html#isSequential">isSequential</a>().</p>
<h3 class="fn"><a name="setErrorString" />QIODevice.setErrorString (<i>self</i>, QString <i>errorString</i>)</h3><p>Sets the human readable description of the last device error
that occurred to <i>str</i>.</p>
<p><b>See also</b> <a href="qiodevice.html#errorString">errorString</a>().</p>
<h3 class="fn"><a name="setOpenMode" />QIODevice.setOpenMode (<i>self</i>, <a href="qiodevice-openmode.html">OpenMode</a> <i>openMode</i>)</h3><p>Sets the <a href="qiodevice.html#OpenModeFlag-enum">OpenMode</a>
of the device to <i>openMode</i>. Call this function to set the
open mode if the flags change after the device has been opened.</p>
<p><b>See also</b> <a href="qiodevice.html#openMode">openMode</a>()
and <a href="qiodevice.html#OpenModeFlag-enum">OpenMode</a>.</p>
<h3 class="fn"><a name="setTextModeEnabled" />QIODevice.setTextModeEnabled (<i>self</i>, bool <i>enabled</i>)</h3><p>If <i>enabled</i> is true, this function sets the <a href="qiodevice.html#OpenModeFlag-enum">Text</a> flag on the device;
otherwise the <a href="qiodevice.html#OpenModeFlag-enum">Text</a>
flag is removed. This feature is useful for classes that provide
custom end-of-line handling on a <a href="qiodevice.html">QIODevice</a>.</p>
<p>The IO device should be opened before calling this function.</p>
<p><b>See also</b> <a href="qiodevice.html#isTextModeEnabled">isTextModeEnabled</a>(),
<a href="qiodevice.html#open">open</a>(), and <a href="qiodevice.html#setOpenMode">setOpenMode</a>().</p>
<h3 class="fn"><a name="size" />int QIODevice.size (<i>self</i>)</h3><p>For open random-access devices, this function returns the size
of the device. For open sequential devices, <a href="qiodevice.html#bytesAvailable">bytesAvailable</a>() is
returned.</p>
<p>If the device is closed, the size returned will not reflect the
actual size of the device.</p>
<p><b>See also</b> <a href="qiodevice.html#isSequential">isSequential</a>() and <a href="qiodevice.html#pos">pos</a>().</p>
<h3 class="fn"><a name="ungetChar" />QIODevice.ungetChar (<i>self</i>, str <i>c</i>)</h3><p>Puts the character <i>c</i> back into the device, and decrements
the current position unless the position is 0. This function is
usually called to "undo" a <a href="qiodevice.html#getChar">getChar</a>() operation, such as when
writing a backtracking parser.</p>
<p>If <i>c</i> was not previously read from the device, the
behavior is undefined.</p>
<h3 class="fn"><a name="waitForBytesWritten" />bool QIODevice.waitForBytesWritten (<i>self</i>, int <i>msecs</i>)</h3><p>For buffered devices, this function waits until a payload of
buffered written data has been written to the device and the
<a href="qiodevice.html#bytesWritten">bytesWritten</a>() signal has
been emitted, or until <i>msecs</i> milliseconds have passed. If
msecs is -1, this function will not time out. For unbuffered
devices, it returns immediately.</p>
<p>Returns true if a payload of data was written to the device;
otherwise returns false (i.e. if the operation timed out, or if an
error occurred).</p>
<p>This function can operate without an event loop. It is useful
when writing non-GUI applications and when performing I/O
operations in a non-GUI thread.</p>
<p>If called from within a slot connected to the <a href="qiodevice.html#bytesWritten">bytesWritten</a>() signal, <a href="qiodevice.html#bytesWritten">bytesWritten</a>() will not be
reemitted.</p>
<p>Reimplement this function to provide a blocking API for a custom
device. The default implementation does nothing, and returns
false.</p>
<p><b>Warning:</b> Calling this function from the main (GUI) thread
might cause your user interface to freeze.</p>
<p><b>See also</b> <a href="qiodevice.html#waitForReadyRead">waitForReadyRead</a>().</p>
<h3 class="fn"><a name="waitForReadyRead" />bool QIODevice.waitForReadyRead (<i>self</i>, int <i>msecs</i>)</h3><p>Blocks until new data is available for reading and the <a href="qiodevice.html#readyRead">readyRead</a>() signal has been emitted,
or until <i>msecs</i> milliseconds have passed. If msecs is -1,
this function will not time out.</p>
<p>Returns true if new data is available for reading; otherwise
returns false (if the operation timed out or if an error
occurred).</p>
<p>This function can operate without an event loop. It is useful
when writing non-GUI applications and when performing I/O
operations in a non-GUI thread.</p>
<p>If called from within a slot connected to the <a href="qiodevice.html#readyRead">readyRead</a>() signal, <a href="qiodevice.html#readyRead">readyRead</a>() will not be
reemitted.</p>
<p>Reimplement this function to provide a blocking API for a custom
device. The default implementation does nothing, and returns
false.</p>
<p><b>Warning:</b> Calling this function from the main (GUI) thread
might cause your user interface to freeze.</p>
<p><b>See also</b> <a href="qiodevice.html#waitForBytesWritten">waitForBytesWritten</a>().</p>
<h3 class="fn"><a name="write" />int QIODevice.write (<i>self</i>, <a href="qbytearray.html">QByteArray</a> <i>data</i>)</h3><p>Writes at most <i>maxSize</i> bytes of data from <i>data</i> to
the device. Returns the number of bytes that were actually written,
or -1 if an error occurred.</p>
<p><b>See also</b> <a href="qiodevice.html#read">read</a>() and
<a href="qiodevice.html#writeData">writeData</a>().</p>
<h3 class="fn"><a name="writeData" />int QIODevice.writeData (<i>self</i>, str <i>data</i>)</h3><p>This method is abstract and should be reimplemented in any sub-class.</p><p>Writes up to <i>maxSize</i> bytes from <i>data</i> to the
device. Returns the number of bytes written, or -1 if an error
occurred.</p>
<p>This function is called by <a href="qiodevice.html">QIODevice</a>. Reimplement this function when
creating a subclass of <a href="qiodevice.html">QIODevice</a>.</p>
<p>When reimplementing this function it is important that this
function writes all the data available before returning. This is
required in order for <a href="qdatastream.html">QDataStream</a> to
be able to operate on the class. <a href="qdatastream.html">QDataStream</a> assumes all the information was
written and therefore does not retry writing if there was a
problem.</p>
<p><b>See also</b> <a href="qiodevice.html#read">read</a>() and
<a href="qiodevice.html#write">write</a>().</p>
<hr /><h2>Qt Signal Documentation</h2><h3 class="fn"><a name="aboutToClose" />void aboutToClose ()</h3><p>This is the default overload of this signal.</p><p>This signal is emitted when the device is about to close.
Connect this signal if you have operations that need to be
performed before the device closes (e.g., if you have data in a
separate buffer that needs to be written to the device).</p>
<h3 class="fn"><a name="bytesWritten" />void bytesWritten (qint64)</h3><p>This is the default overload of this signal.</p><p>This signal is emitted every time a payload of data has been
written to the device. The <i>bytes</i> argument is set to the
number of bytes that were written in this payload.</p>
<p>bytesWritten() is not emitted recursively; if you reenter the
event loop or call <a href="qiodevice.html#waitForBytesWritten">waitForBytesWritten</a>()
inside a slot connected to the bytesWritten() signal, the signal
will not be reemitted (although <a href="qiodevice.html#waitForBytesWritten">waitForBytesWritten</a>() may
still return true).</p>
<p><b>See also</b> <a href="qiodevice.html#readyRead">readyRead</a>().</p>
<h3 class="fn"><a name="readChannelFinished" />void readChannelFinished ()</h3><p>This is the default overload of this signal.</p><p>This signal is emitted when the input (reading) stream is closed
in this device. It is emitted as soon as the closing is detected,
which means that there might still be data available for reading
with <a href="qiodevice.html#read">read</a>().</p>
<p>This function was introduced in Qt 4.4.</p>
<p><b>See also</b> <a href="qiodevice.html#atEnd">atEnd</a>() and
<a href="qiodevice.html#read">read</a>().</p>
<h3 class="fn"><a name="readyRead" />void readyRead ()</h3><p>This is the default overload of this signal.</p><p>This signal is emitted once every time new data is available for
reading from the device. It will only be emitted again once new
data is available, such as when a new payload of network data has
arrived on your network socket, or when a new block of data has
been appended to your device.</p>
<p>readyRead() is not emitted recursively; if you reenter the event
loop or call <a href="qiodevice.html#waitForReadyRead">waitForReadyRead</a>() inside a
slot connected to the readyRead() signal, the signal will not be
reemitted (although <a href="qiodevice.html#waitForReadyRead">waitForReadyRead</a>() may still
return true).</p>
<p>Note for developers implementing classes derived from <a href="qiodevice.html">QIODevice</a>: you should always emit readyRead()
when new data has arrived (do not emit it only because there's data
still to be read in your buffers). Do not emit readyRead() in other
conditions.</p>
<p><b>See also</b> <a href="qiodevice.html#bytesWritten">bytesWritten</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>
