QIODevice(3qt)

1QIODevice(3qt)                                                  QIODevice(3qt)
2
3
4

NAME

6       QIODevice - The base class of I/O devices
7

SYNOPSIS

9       All the functions in this class are reentrant when Qt is built with
10       thread support.</p>
11
12       #include <qiodevice.h>
13
14       Inherited by QBuffer, QFile, QSocket, and QSocketDevice.
15
16   Public Members
17       typedef Q_ULONG Offset
18       QIODevice ()
19       virtual ~QIODevice ()
20       int flags () const
21       int mode () const
22       int state () const
23       bool isDirectAccess () const
24       bool isSequentialAccess () const
25       bool isCombinedAccess () const
26       bool isBuffered () const
27       bool isRaw () const
28       bool isSynchronous () const
29       bool isAsynchronous () const
30       bool isTranslated () const
31       bool isReadable () const
32       bool isWritable () const
33       bool isReadWrite () const
34       bool isInactive () const
35       bool isOpen () const
36       int status () const
37       void resetStatus ()
38       virtual bool open ( int mode ) = 0
39       virtual void close () = 0
40       virtual void flush () = 0
41       virtual Offset size () const = 0
42       virtual Offset at () const
43       virtual bool at ( Offset pos )
44       virtual bool atEnd () const
45       bool reset ()
46       virtual Q_LONG readBlock ( char * data, Q_ULONG maxlen ) = 0
47       virtual Q_LONG writeBlock ( const char * data, Q_ULONG len ) = 0
48       virtual Q_LONG readLine ( char * data, Q_ULONG maxlen )
49       Q_LONG writeBlock ( const QByteArray & data )
50       virtual QByteArray readAll ()
51       virtual int getch () = 0
52       virtual int putch ( int ch ) = 0
53       virtual int ungetch ( int ch ) = 0
54
55   Protected Members
56       void setFlags ( int flags )
57       void setType ( int type )
58       void setMode ( int mode )
59       void setState ( int state )
60       void setStatus ( int s )
61

DESCRIPTION

63       The QIODevice class is the base class of I/O devices.
64
65       An I/O device represents a medium that one can read bytes from and/or
66       write bytes to. The QIODevice class is the abstract superclass of all
67       such devices; classes such as QFile, QBuffer and QSocket inherit
68       QIODevice and implement virtual functions such as write()
69       appropriately.
70
71       Although applications sometimes use QIODevice directly, it is usually
72       better to use QTextStream and QDataStream, which provide stream
73       operations on any QIODevice subclass. QTextStream provides text-
74       oriented stream functionality (for human-readable ASCII files, for
75       example), whereas QDataStream deals with binary data in a totally
76       platform-independent manner.
77
78       The public member functions in QIODevice roughly fall into two groups:
79       the action functions and the state access functions. The most important
80       action functions are:
81
82       open() opens a device for reading and/or writing, depending on the mode
83       argument.
84
85       close() closes the device and tidies up (e.g. flushes buffered data)
86
87       readBlock() reads a block of data from the device.
88
89       writeBlock() writes a block of data to the device.
90
91       readLine() reads a line (of text, usually) from the device.
92
93       flush() ensures that all buffered data are written to the real device.
94
95       There are also some other, less used, action functions:
96
97       getch() reads a single character.
98
99       ungetch() forgets the last call to getch(), if possible.
100
101       putch() writes a single character.
102
103       size() returns the size of the device, if there is one.
104
105       at() returns the current read/write pointer's position, if there is one
106       for this device, or it moves the pointer if given an offset.
107
108       atEnd() indicates whether there is more to read, if this is meaningful
109       for this device.
110
111       reset() moves the read/write pointer to the start of the device, if
112       that is possible for this device.
113
114       The state access are all "get" functions. The QIODevice subclass calls
115       setState() to update the state, and simple access functions tell the
116       user of the device what the device's state is. Here are the settings,
117       and their associated access functions:
118
119       Access type. Some devices are direct access (it is possible to
120       read/write anywhere), whereas others are sequential. QIODevice provides
121       the access functions (isDirectAccess(), isSequentialAccess(), and
122       isCombinedAccess()) to tell users what a given I/O device supports.
123
124       Buffering. Some devices are accessed in raw mode, whereas others are
125       buffered. Buffering usually provides greater efficiency, particularly
126       for small read/write operations. isBuffered() tells the user whether a
127       given device is buffered. (This can often be set by the application in
128       the call to open().)
129
130       Synchronicity. Synchronous devices work immediately (for example,
131       files). When you read from a file, the file delivers its data straight
132       away. Other kinds of device, such as a socket connected to a HTTP
133       server, may not deliver the data until seconds after you ask to read
134       it. isSynchronous() and isAsynchronous() tell the user how this device
135       operates.
136
137       CR/LF translation. For simplicity, applications often like to see just
138       a single CR/LF style, and QIODevice subclasses can provide this.
139       isTranslated() returns TRUE if this object translates CR/LF to just LF.
140       (This can often be set by the application in the call to open().)
141
142       Permissions. Some files cannot be written. For example, isReadable(),
143       isWritable() and isReadWrite() tell the application whether it can read
144       from and write to a given device. (This can often be set by the
145       application in the call to open().)
146
147       Finally, isOpen() returns TRUE if the device is open, i.e. after an
148       open() call.
149
150       QIODevice provides numerous pure virtual functions that you need to
151       implement when subclassing it. Here is a skeleton subclass with all the
152       members you are sure to need and some that you will probably need:
153
154           class MyDevice : public QIODevice
155           {
156           public:
157               MyDevice();
158               ~MyDevice();
159               bool open( int mode );
160               void close();
161               void flush();
162               uint size() const;
163               int  at() const;        // non-pure virtual
164               bool at( int );         // non-pure virtual
165               bool atEnd() const;     // non-pure virtual
166               int readBlock( char *data, uint maxlen );
167               int writeBlock( const char *data, uint len );
168               int readLine( char *data, uint maxlen );
169               int getch();
170               int putch( int );
171               int ungetch( int );
172           };
173
174       The three non-pure virtual functions need not be reimplemented for
175       sequential devices.
176
177       See also QDataStream, QTextStream, and Input/Output and Networking.
178
179   Member Type Documentation

QIODevice::Offset

181       The offset within the device.
182

MEMBER FUNCTION DOCUMENTATION

QIODevice::QIODevice ()

185       Constructs an I/O device.
186

QIODevice::~QIODevice () [virtual]

188       Destroys the I/O device.
189

Offset QIODevice::at () const [virtual]

191       Virtual function that returns the current I/O device position.
192
193       This is the position of the data read/write head of the I/O device.
194
195       See also size().
196
197       Example: distributor/distributor.ui.h.
198
199       Reimplemented in QSocket.
200

bool QIODevice::at ( Offset pos ) [virtual]

202       Virtual function that sets the I/O device position to pos. Returns TRUE
203       if the position was successfully set, i.e. pos is within range and the
204       seek was successful; otherwise returns FALSE.
205
206       See also size().
207
208       Reimplemented in QSocket.
209

bool QIODevice::atEnd () const [virtual]

211       Virtual function that returns TRUE if the I/O device position is at the
212       end of the input; otherwise returns FALSE.
213
214       Reimplemented in QFile and QSocket.
215

void QIODevice::close () [pure virtual]

217       Closes the I/O device.
218
219       This virtual function must be reimplemented by all subclasses.
220
221       See also open().
222
223       Example: grapher/grapher.cpp.
224
225       Reimplemented in QFile and QSocket.
226

int QIODevice::flags () const

228       Returns the current I/O device flags setting.
229
230       Flags consists of mode flags and state flags.
231
232       See also mode() and state().
233

void QIODevice::flush () [pure virtual]

235       Flushes an open I/O device.
236
237       This virtual function must be reimplemented by all subclasses.
238
239       Reimplemented in QFile and QSocket.
240

int QIODevice::getch () [pure virtual]

242       Reads a single byte/character from the I/O device.
243
244       Returns the byte/character read, or -1 if the end of the I/O device has
245       been reached.
246
247       This virtual function must be reimplemented by all subclasses.
248
249       See also putch() and ungetch().
250
251       Reimplemented in QFile and QSocket.
252

bool QIODevice::isAsynchronous () const

254       Returns TRUE if the device is an asynchronous device; otherwise returns
255       FALSE, i.e. if the device is a synchronous device.
256
257       This mode is currently not in use.
258
259       See also isSynchronous().
260

bool QIODevice::isBuffered () const

262       Returns TRUE if the I/O device is a buffered device; otherwise returns
263       FALSE, i.e. the device is a raw device.
264
265       See also isRaw().
266

bool QIODevice::isCombinedAccess () const

268       Returns TRUE if the I/O device is a combined access (both direct and
269       sequential) device; otherwise returns FALSE.
270
271       This access method is currently not in use.
272

bool QIODevice::isDirectAccess () const

274       Returns TRUE if the I/O device is a direct access device; otherwise
275       returns FALSE, i.e. if the device is a sequential access device.
276
277       See also isSequentialAccess().
278

bool QIODevice::isInactive () const

280       Returns TRUE if the I/O device state is 0, i.e. the device is not open;
281       otherwise returns FALSE.
282
283       See also isOpen().
284

bool QIODevice::isOpen () const

286       Returns TRUE if the I/O device has been opened; otherwise returns
287       FALSE.
288
289       See also isInactive().
290
291       Example: network/networkprotocol/nntp.cpp.
292

bool QIODevice::isRaw () const

294       Returns TRUE if the device is a raw device; otherwise returns FALSE,
295       i.e. if the device is a buffered device.
296
297       See also isBuffered().
298

bool QIODevice::isReadWrite () const

300       Returns TRUE if the I/O device was opened using IO_ReadWrite mode;
301       otherwise returns FALSE.
302
303       See also isReadable() and isWritable().
304

bool QIODevice::isReadable () const

306       Returns TRUE if the I/O device was opened using IO_ReadOnly or
307       IO_ReadWrite mode; otherwise returns FALSE.
308
309       See also isWritable() and isReadWrite().
310

bool QIODevice::isSequentialAccess () const

312       Returns TRUE if the device is a sequential access device; otherwise
313       returns FALSE, i.e. if the device is a direct access device.
314
315       Operations involving size() and at(int) are not valid on sequential
316       devices.
317
318       See also isDirectAccess().
319

bool QIODevice::isSynchronous () const

321       Returns TRUE if the I/O device is a synchronous device; otherwise
322       returns FALSE, i.e. the device is an asynchronous device.
323
324       See also isAsynchronous().
325

bool QIODevice::isTranslated () const

327       Returns TRUE if the I/O device translates carriage-return and linefeed
328       characters; otherwise returns FALSE.
329
330       A QFile is translated if it is opened with the IO_Translate mode flag.
331

bool QIODevice::isWritable () const

333       Returns TRUE if the I/O device was opened using IO_WriteOnly or
334       IO_ReadWrite mode; otherwise returns FALSE.
335
336       See also isReadable() and isReadWrite().
337

int QIODevice::mode () const

339       Returns bits OR'ed together that specify the current operation mode.
340
341       These are the flags that were given to the open() function.
342
343       The flags are IO_ReadOnly, IO_WriteOnly, IO_ReadWrite, IO_Append,
344       IO_Truncate and IO_Translate.
345

bool QIODevice::open ( int mode ) [pure virtual]

347       Opens the I/O device using the specified mode. Returns TRUE if the
348       device was successfully opened; otherwise returns FALSE.
349
350       The mode parameter mode must be an OR'ed combination of the following
351       flags. <center>.nf
352
353       </center>
354
355       This virtual function must be reimplemented by all subclasses.
356
357       See also close().
358
359       Example: grapher/grapher.cpp.
360
361       Reimplemented in QFile and QSocket.
362

int QIODevice::putch ( int ch ) [pure virtual]

364       Writes the character ch to the I/O device.
365
366       Returns ch, or -1 if an error occurred.
367
368       This virtual function must be reimplemented by all subclasses.
369
370       See also getch() and ungetch().
371
372       Example: grapher/grapher.cpp.
373
374       Reimplemented in QFile and QSocket.
375

QByteArray QIODevice::readAll () [virtual]

377       This convenience function returns all of the remaining data in the
378       device.
379

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

381       Reads at most maxlen bytes from the I/O device into data and returns
382       the number of bytes actually read.
383
384       This function should return -1 if a fatal error occurs and should
385       return 0 if there are no bytes to read.
386
387       The device must be opened for reading, and data must not be 0.
388
389       This virtual function must be reimplemented by all subclasses.
390
391       See also writeBlock(), isOpen(), and isReadable().
392
393       Example: distributor/distributor.ui.h.
394
395       Reimplemented in QSocket and QSocketDevice.
396

Q_LONG QIODevice::readLine ( char * data, Q_ULONG maxlen ) [virtual]

398       Reads a line of text, (or up to maxlen bytes if a newline isn't
399       encountered) plus a terminating '&#92;0' into data. If there is a
400       newline at the end if the line, it is not stripped.
401
402       Returns the number of bytes read including the terminating '&#92;0', or
403       -1 if an error occurred.
404
405       This virtual function can be reimplemented much more efficiently by the
406       most subclasses.
407
408       See also readBlock() and QTextStream::readLine().
409
410       Reimplemented in QFile.
411

bool QIODevice::reset ()

413       Sets the device index position to 0.
414
415       See also at().
416

void QIODevice::resetStatus ()

418       Sets the I/O device status to IO_Ok.
419
420       See also status().
421

void QIODevice::setFlags ( int flags ) [protected]

423       Used by subclasses to set the device flags to the flags specified.
424

void QIODevice::setMode ( int mode ) [protected]

426       Used by subclasses to set the device mode to the mode specified.
427

void QIODevice::setState ( int state ) [protected]

429       Used by subclasses to set the device state to the state specified.
430

void QIODevice::setStatus ( int s ) [protected]

432       Used by subclasses to set the device status (not state) to s.
433

void QIODevice::setType ( int type ) [protected]

435       Used by subclasses to set the device type to the type specified.
436

Offset QIODevice::size () const [pure virtual]

438       Virtual function that returns the size of the I/O device.
439
440       See also at().
441
442       Reimplemented in QFile and QSocket.
443

int QIODevice::state () const

445       Returns bits OR'ed together that specify the current state.
446
447       The flags are: IO_Open.
448
449       Subclasses may define additional flags.
450

int QIODevice::status () const

452       Returns the I/O device status.
453
454       The I/O device status returns an error code. If open() returns FALSE or
455       readBlock() or writeBlock() return -1, this function can be called to
456       find out the reason why the operation failed.
457
458       The status codes are: <center>.nf
459
460       </center>
461
462       See also resetStatus().
463

int QIODevice::ungetch ( int ch ) [pure virtual]

465       Puts the character ch back into the I/O device and decrements the index
466       position if it is not zero.
467
468       This function is normally called to "undo" a getch() operation.
469
470       Returns ch, or -1 if an error occurred.
471
472       This virtual function must be reimplemented by all subclasses.
473
474       See also getch() and putch().
475
476       Reimplemented in QFile and QSocket.
477

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

479
480       Writes len bytes from data to the I/O device and returns the number of
481       bytes actually written.
482
483       This function should return -1 if a fatal error occurs.
484
485       This virtual function must be reimplemented by all subclasses.
486
487       See also readBlock().
488
489       Example: distributor/distributor.ui.h.
490
491       Reimplemented in QBuffer, QSocket, and QSocketDevice.
492

Q_LONG QIODevice::writeBlock ( const QByteArray & data )

494       This is an overloaded member function, provided for convenience. It
495       behaves essentially like the above function.
496
497       This convenience function is the same as calling writeBlock(
498       data.data(), data.size() ).
499
500

COPYRIGHT

506       Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
507       license file included in the distribution for a complete license
508       statement.
509

AUTHOR

511       Generated automatically from the source code.
512

BUGS

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