Chameleon

Chameleon Svn Source Tree

Root/branches/xZenu/src/util/doxygen/qtools/qiodevice.cpp

Source at commit 1322 created 9 years 5 months ago.
By meklort, Add doxygen to utils folder
1/****************************************************************************
2**
3**
4** Implementation of QIODevice class
5**
6** Created : 940913
7**
8** Copyright (C) 1992-2000 Trolltech AS. All rights reserved.
9**
10** This file is part of the tools module of the Qt GUI Toolkit.
11**
12** This file may be distributed under the terms of the Q Public License
13** as defined by Trolltech AS of Norway and appearing in the file
14** LICENSE.QPL included in the packaging of this file.
15**
16** This file may be distributed and/or modified under the terms of the
17** GNU General Public License version 2 as published by the Free Software
18** Foundation and appearing in the file LICENSE.GPL included in the
19** packaging of this file.
20**
21** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition
22** licenses may use this file in accordance with the Qt Commercial License
23** Agreement provided with the Software.
24**
25** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
26** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
27**
28** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for
29** information about Qt Commercial License Agreements.
30** See http://www.trolltech.com/qpl/ for QPL licensing information.
31** See http://www.trolltech.com/gpl/ for GPL licensing information.
32**
33** Contact info@trolltech.com if any conditions of this licensing are
34** not clear to you.
35**
36**********************************************************************/
37
38#include "qiodevice.h"
39
40// NOT REVISED
41/*!
42 \class QIODevice qiodevice.h
43
44 \brief The QIODevice class is the base class of I/O devices.
45
46 \ingroup io
47
48 An I/O device represents a medium that one can read bytes from
49 and/or write bytes to. The QIODevice class is the abstract
50 superclass of all such devices; classes like QFile, QBuffer and
51 QSocket inherit QIODevice and implement virtual functions like
52 write() appropriately.
53
54 While applications sometimes use QIODevice directly, mostly it is
55 better to go through QTextStream and QDataStream, which provide
56 stream operations on any QIODevice subclass. QTextStream provides
57 text-oriented stream functionality (for human-readable ASCII files,
58 for example), while QDataStream deals with binary data in a totally
59 platform-independent manner.
60
61 The public member functions in QIODevice roughly fall into two
62 groups: The action functions and the state access functions. The
63 most important action functions are: <ul>
64
65 <li> open() opens a device for reading and/or writing, depending on
66 the argument to open().
67
68 <li> close() closes the device and tidies up.
69
70 <li> readBlock() reads a block of data from the device.
71
72 <li> writeBlock() writes a block of data to the device.
73
74 <li> readLine() reads a line (of text, usually) from the device.
75
76 <li> flush() ensures that all buffered data are written to the real device.
77
78 </ul>There are also some other, less used, action functions: <ul>
79
80 <li> getch() reads a single character.
81
82 <li> ungetch() forgets the last call to getch(), if possible.
83
84 <li> putch() writes a single character.
85
86 <li> size() returns the size of the device, if there is one.
87
88 <li> at() returns the current read/write pointer, if there is one
89 for this device, or it moves the pointer.
90
91 <li> atEnd() says whether there is more to read, if that is a
92 meaningful question for this device.
93
94 <li> reset() moves the read/write pointer to the start of the
95 device, if that is possible for this device.
96
97 </ul>The state access are all "get" functions. The QIODevice subclass
98 calls setState() to update the state, and simple access functions
99 tell the user of the device what the device's state is. Here are
100 the settings, and their associated access functions: <ul>
101
102 <li> Access type. Some devices are direct access (it is possible to
103 read/write anywhere) while others are sequential. QIODevice
104 provides the access functions isDirectAccess(), isSequentialAccess()
105 and isCombinedAccess() to tell users what a given I/O device
106 supports.
107
108 <li> Buffering. Some devices are accessed in raw mode while others
109 are buffered. Buffering usually provides greater efficiency,
110 particularly for small read/write operations. isBuffered() tells
111 the user whether a given device is buffered. (This can often be set
112 by the application in the call to open().)
113
114 <li> Synchronicity. Synchronous devices work there and then, for
115 example files. When you read from a file, the file delivers its
116 data right away. Others, such as a socket connected to a HTTP
117 server, may not deliver the data until seconds after you ask to read
118 it. isSynchronous() and isAsynchronous() tells the user how this
119 device operates.
120
121 <li> CR/LF translation. For simplicity, applications often like to
122 see just a single CR/LF style, and QIODevice subclasses can provide
123 that. isTranslated() returns TRUE if this object translates CR/LF
124 to just LF. (This can often be set by the application in the call
125 to open().)
126
127 <li> Accessibility. Some files cannot be written, for example.
128 isReadable(), isWritable and isReadWrite() tells the application
129 whether it can read from and write to a given device. (This can
130 often be set by the application in the call to open().)
131
132 <li> Finally, isOpen() returns TRUE if the device is open. This can
133 quite obviously be set using open() :)
134
135 </ul>
136
137 QIODevice provides numerous pure virtual functions you need to
138 implement when subclassing it. Here is a skeleton subclass with all
139 the members you are certain to need, and some it's likely that you
140 will need:
141
142 \code
143 class YourDevice : public QIODevice
144 {
145 public:
146YourDevice();
147 ~YourDevice();
148
149bool open( int mode );
150void close();
151void flush();
152
153uint size() const;
154int at() const;// not a pure virtual function
155bool at( int );// not a pure virtual function
156bool atEnd() const;// not a pure virtual function
157
158int readBlock( char *data, uint maxlen );
159int writeBlock( const char *data, uint len );
160int readLine( char *data, uint maxlen );
161
162int getch();
163int putch( int );
164int ungetch( int );
165 };
166 \endcode
167
168 The three non-pure virtual functions can be ignored if your device
169 is sequential (e.g. an RS-232 port).
170
171 \sa QDataStream, QTextStream
172*/
173
174
175/*!
176 Constructs an I/O device.
177*/
178
179QIODevice::QIODevice()
180{
181 ioMode = 0;// initial mode
182 ioSt = IO_Ok;
183 ioIndex = 0;
184}
185
186/*!
187 Destructs the I/O device.
188*/
189
190QIODevice::~QIODevice()
191{
192}
193
194
195/*!
196 \fn int QIODevice::flags() const
197 Returns the current I/O device flags setting.
198
199 Flags consists of mode flags and state flags.
200
201 \sa mode(), state()
202*/
203
204/*!
205 \fn int QIODevice::mode() const
206 Returns bits OR'ed together that specify the current operation mode.
207
208 These are the flags that were given to the open() function.
209
210 The flags are: \c IO_ReadOnly, \c IO_WriteOnly, \c IO_ReadWrite,
211 \c IO_Append, \c IO_Truncate and \c IO_Translate.
212*/
213
214/*!
215 \fn int QIODevice::state() const
216 Returns bits OR'ed together that specify the current state.
217
218 The flags are: \c IO_Open.
219
220 Subclasses may define more flags.
221*/
222
223/*!
224 \fn bool QIODevice::isDirectAccess() const
225 Returns TRUE if the I/O device is a direct access (not sequential) device,
226 otherwise FALSE.
227 \sa isSequentialAccess()
228*/
229
230/*!
231 \fn bool QIODevice::isSequentialAccess() const
232 Returns TRUE if the I/O device is a sequential access (not direct) device,
233 otherwise FALSE. Operations involving size() and at(int) are not valid
234 on sequential devices.
235 \sa isDirectAccess()
236*/
237
238/*!
239 \fn bool QIODevice::isCombinedAccess() const
240 Returns TRUE if the I/O device is a combined access (both direct and
241 sequential) device, otherwise FALSE.
242
243 This access method is currently not in use.
244*/
245
246/*!
247 \fn bool QIODevice::isBuffered() const
248 Returns TRUE if the I/O device is a buffered (not raw) device, otherwise
249 FALSE.
250 \sa isRaw()
251*/
252
253/*!
254 \fn bool QIODevice::isRaw() const
255 Returns TRUE if the I/O device is a raw (not buffered) device, otherwise
256 FALSE.
257 \sa isBuffered()
258*/
259
260/*!
261 \fn bool QIODevice::isSynchronous() const
262 Returns TRUE if the I/O device is a synchronous device, otherwise
263 FALSE.
264 \sa isAsynchronous()
265*/
266
267/*!
268 \fn bool QIODevice::isAsynchronous() const
269 Returns TRUE if the I/O device is a asynchronous device, otherwise
270 FALSE.
271
272 This mode is currently not in use.
273
274 \sa isSynchronous()
275*/
276
277/*!
278 \fn bool QIODevice::isTranslated() const
279 Returns TRUE if the I/O device translates carriage-return and linefeed
280 characters.
281
282 A QFile is translated if it is opened with the \c IO_Translate mode
283 flag.
284*/
285
286/*!
287 \fn bool QIODevice::isReadable() const
288 Returns TRUE if the I/O device was opened using \c IO_ReadOnly or
289 \c IO_ReadWrite mode.
290 \sa isWritable(), isReadWrite()
291*/
292
293/*!
294 \fn bool QIODevice::isWritable() const
295 Returns TRUE if the I/O device was opened using \c IO_WriteOnly or
296 \c IO_ReadWrite mode.
297 \sa isReadable(), isReadWrite()
298*/
299
300/*!
301 \fn bool QIODevice::isReadWrite() const
302 Returns TRUE if the I/O device was opened using \c IO_ReadWrite mode.
303 \sa isReadable(), isWritable()
304*/
305
306/*!
307 \fn bool QIODevice::isInactive() const
308 Returns TRUE if the I/O device state is 0, i.e. the device is not open.
309 \sa isOpen()
310*/
311
312/*!
313 \fn bool QIODevice::isOpen() const
314 Returns TRUE if the I/O device state has been opened, otherwise FALSE.
315 \sa isInactive()
316*/
317
318
319/*!
320 \fn int QIODevice::status() const
321 Returns the I/O device status.
322
323 The I/O device status returns an error code.If open() returns FALSE
324 or readBlock() or writeBlock() return -1, this function can be called to
325 get the reason why the operation did not succeed.
326
327 The status codes are:
328 <ul>
329 <li>\c IO_Ok The operation was successful.
330 <li>\c IO_ReadError Could not read from the device.
331 <li>\c IO_WriteError Could not write to the device.
332 <li>\c IO_FatalError A fatal unrecoverable error occurred.
333 <li>\c IO_OpenError Could not open the device.
334 <li>\c IO_ConnectError Could not connect to the device.
335 <li>\c IO_AbortError The operation was unexpectedly aborted.
336 <li>\c IO_TimeOutError The operation timed out.
337 <li>\c IO_OnCloseError An unspecified error happened on close.
338 </ul>
339
340 \sa resetStatus()
341*/
342
343/*!
344 \fn void QIODevice::resetStatus()
345
346 Sets the I/O device status to \c IO_Ok.
347
348 \sa status()
349*/
350
351
352/*!
353 \fn void QIODevice::setFlags( int f )
354 \internal
355 Used by subclasses to set the device flags.
356*/
357
358/*!
359 \internal
360 Used by subclasses to set the device type.
361*/
362
363void QIODevice::setType( int t )
364{
365#if defined(CHECK_RANGE)
366 if ( (t & IO_TypeMask) != t )
367qWarning( "QIODevice::setType: Specified type out of range" );
368#endif
369 ioMode &= ~IO_TypeMask;// reset type bits
370 ioMode |= t;
371}
372
373/*!
374 \internal
375 Used by subclasses to set the device mode.
376*/
377
378void QIODevice::setMode( int m )
379{
380#if defined(CHECK_RANGE)
381 if ( (m & IO_ModeMask) != m )
382qWarning( "QIODevice::setMode: Specified mode out of range" );
383#endif
384 ioMode &= ~IO_ModeMask;// reset mode bits
385 ioMode |= m;
386}
387
388/*!
389 \internal
390 Used by subclasses to set the device state.
391*/
392
393void QIODevice::setState( int s )
394{
395#if defined(CHECK_RANGE)
396 if ( ((uint)s & IO_StateMask) != (uint)s )
397qWarning( "QIODevice::setState: Specified state out of range" );
398#endif
399 ioMode &= ~IO_StateMask;// reset state bits
400 ioMode |= (uint)s;
401}
402
403/*!
404 \internal
405 Used by subclasses to set the device status (not state).
406*/
407
408void QIODevice::setStatus( int s )
409{
410 ioSt = s;
411}
412
413
414/*!
415 \fn bool QIODevice::open( int mode )
416 Opens the I/O device using the specified \e mode.
417 Returns TRUE if successful, or FALSE if the device could not be opened.
418
419 The mode parameter \e m must be a combination of the following flags.
420 <ul>
421 <li>\c IO_Raw specified raw (unbuffered) file access.
422 <li>\c IO_ReadOnly opens a file in read-only mode.
423 <li>\c IO_WriteOnly opens a file in write-only mode.
424 <li>\c IO_ReadWrite opens a file in read/write mode.
425 <li>\c IO_Append sets the file index to the end of the file.
426 <li>\c IO_Truncate truncates the file.
427 <li>\c IO_Translate enables carriage returns and linefeed translation
428 for text files under MS-DOS, Window, OS/2 and Macintosh. On Unix systems
429 this flag has no effect. Use with caution as it will also transform every linefeed
430 written to the file into a CRLF pair. This is likely to corrupt your file when
431 writing binary data to it. Cannot be combined with \c IO_Raw.
432 </ul>
433
434 This virtual function must be reimplemented by all subclasses.
435
436 \sa close()
437*/
438
439/*!
440 \fn void QIODevice::close()
441 Closes the I/O device.
442
443 This virtual function must be reimplemented by all subclasses.
444
445 \sa open()
446*/
447
448/*!
449 \fn void QIODevice::flush()
450
451 Flushes an open I/O device.
452
453 This virtual function must be reimplemented by all subclasses.
454*/
455
456
457/*!
458 \fn uint QIODevice::size() const
459 Virtual function that returns the size of the I/O device.
460 \sa at()
461*/
462
463/*!
464 Virtual function that returns the current I/O device index.
465
466 This index is the data read/write head of the I/O device.
467
468 \sa size()
469*/
470
471int QIODevice::at() const
472{
473 return ioIndex;
474}
475
476/*!
477 Virtual function that sets the I/O device index to \e pos.
478 \sa size()
479*/
480
481bool QIODevice::at( int pos )
482{
483#if defined(CHECK_RANGE)
484 if ( (uint)pos > size() ) {
485qWarning( "QIODevice::at: Index %d out of range", pos );
486return FALSE;
487 }
488#endif
489 ioIndex = pos;
490 return TRUE;
491}
492
493/*!
494 Virtual function that returns TRUE if the I/O device index is at the
495 end of the input.
496*/
497
498bool QIODevice::atEnd() const
499{
500 if ( isSequentialAccess() || isTranslated() ) {
501QIODevice* that = (QIODevice*)this;
502int c = that->getch();
503bool result = c < 0;
504that->ungetch(c);
505return result;
506 } else {
507return at() == (int)size();
508 }
509}
510
511/*!
512 \fn bool QIODevice::reset()
513 Sets the device index to 0.
514 \sa at()
515*/
516
517
518/*!
519 \fn int QIODevice::readBlock( char *data, uint maxlen )
520 Reads at most \e maxlen bytes from the I/O device into \e data and
521 returns the number of bytes actually read.
522
523 This virtual function must be reimplemented by all subclasses.
524
525 \sa writeBlock()
526*/
527
528/*!
529 This convenience function returns all of the remaining data in the
530 device. Note that this only works for direct access devices, such
531 as QFile.
532
533 \sa isDirectAccess()
534*/
535QByteArray QIODevice::readAll()
536{
537 int n = size()-at();
538 QByteArray ba(size()-at());
539 char* c = ba.data();
540 while ( n ) {
541int r = readBlock( c, n );
542if ( r < 0 )
543 return QByteArray();
544n -= r;
545c += r;
546 }
547 return ba;
548}
549
550/*!
551 \fn int QIODevice::writeBlock( const char *data, uint len )
552 Writes \e len bytes from \e p to the I/O device and returns the number of
553 bytes actually written.
554
555 This virtual function must be reimplemented by all subclasses.
556
557 \sa readBlock()
558*/
559
560/*!
561 This convenience function is the same as calling
562 writeBlock( data.data(), data.size() ).
563*/
564int QIODevice::writeBlock( const QByteArray& data )
565{
566 return writeBlock( data.data(), data.size() );
567}
568
569/*!
570 Reads a line of text, up to \e maxlen bytes including a terminating
571 \0. If there is a newline at the end if the line, it is not stripped.
572
573 Returns the number of bytes read, or -1 in case of error.
574
575 This virtual function can be reimplemented much more efficiently by
576 the most subclasses.
577
578 \sa readBlock(), QTextStream::readLine()
579*/
580
581int QIODevice::readLine( char *data, uint maxlen )
582{
583 if ( maxlen == 0 )// application bug?
584return 0;
585 int pos = at();// get current position
586 int s = (int)size();// size of I/O device
587 char *p = data;
588 if ( pos >= s )
589return 0;
590 while ( pos++ < s && --maxlen ) {// read one byte at a time
591readBlock( p, 1 );
592if ( *p++ == '\n' )// end of line
593 break;
594 }
595 *p++ = '\0';
596 return (int)((long)p - (long)data);
597}
598
599
600/*!
601 \fn int QIODevice::getch()
602
603 Reads a single byte/character from the I/O device.
604
605 Returns the byte/character read, or -1 if the end of the I/O device has been
606 reached.
607
608 This virtual function must be reimplemented by all subclasses.
609
610 \sa putch(), ungetch()
611*/
612
613/*!
614 \fn int QIODevice::putch( int ch )
615
616 Writes the character \e ch to the I/O device.
617
618 Returns \e ch, or -1 if some error occurred.
619
620 This virtual function must be reimplemented by all subclasses.
621
622 \sa getch(), ungetch()
623*/
624
625/*!
626 \fn int QIODevice::ungetch( int ch )
627
628 Puts the character \e ch back into the I/O device and decrements the
629 index if it is not zero.
630
631 This function is normally called to "undo" a getch() operation.
632
633 Returns \e ch, or -1 if some error occurred.
634
635 This virtual function must be reimplemented by all subclasses.
636
637 \sa getch(), putch()
638*/
639

Archive Download this file

Revision: 1322