 |
Vault
4.1
|
|
Vault
4.1
|
VIOStream is an abstract base class from which classes derive that perform well-typed I/O on raw streams. More...
#include <viostream.h>
Public Member Functions | |
| VIOStream (VStream &rawStream) | |
| Constructs the object with an underlying raw stream. | |
| virtual | ~VIOStream () |
| Destructor. | |
| void | readGuaranteed (Vu8 *targetBuffer, Vs64 numBytesToRead) |
| Reads a specified number of bytes from the stream, and throws a VException if they cannot be read. | |
| Vu8 | readGuaranteedByte () |
| Reads one byte from the stream, and throws a VException if it cannot be read. | |
| Vs64 | read (Vu8 *targetBuffer, Vs64 numBytesToRead) |
| Attempts to read a specified number of bytes from the stream. | |
| Vs64 | write (const Vu8 *buffer, Vs64 numBytesToWrite) |
| Writes bytes to the stream. | |
| void | flush () |
| Flushes any pending or buffered write data to the stream. | |
| bool | skip (Vs64 numBytesToSkip) |
| Skips forward in the stream a specified number of bytes. | |
| bool | seek (Vs64 offset, int whence) |
| Seeks in the stream using Unix seek() semantics. | |
| bool | seek0 () |
| This is a convenience function that means seek(0, SEEK_SET). | |
| Vs64 | getIOOffset () const |
| Returns the "current" "offset" in the stream. | |
| Vs64 | available () const |
| Returns the number of bytes that are available to be read from this stream. | |
| VStream & | getRawStream () |
| Returns a reference to the underlying raw stream; used by the friend function streamCopy() so it can call through to the corresponding VStream friend function and supply it the raw streams. | |
Static Public Member Functions | |
| static Vs16 | streamCompare (VIOStream &streamA, VIOStream &streamB, Vs64 numBytesToCompare) |
| Compare 2 streams by ascii values. | |
Protected Attributes | |
| VStream & | mRawStream |
| The underlying raw stream. | |
VIOStream is an abstract base class from which classes derive that perform well-typed I/O on raw streams.
This base class merely delegates its methods to the underlying raw stream. Subclasses provide well-typed read and write APIs that call the base class methods. So you will typically not instantiate a VIOStream (there is no point to doing so!) and will instead instantiate a VBinaryIOStream or a VTextIOStream.
Definition at line 43 of file viostream.h.
| VIOStream::VIOStream | ( | VStream & | rawStream | ) |
Constructs the object with an underlying raw stream.
| rawStream | the raw stream on which I/O will be performed |
Definition at line 14 of file viostream.cpp.
Reads a specified number of bytes from the stream, and throws a VException if they cannot be read.
| targetBuffer | the buffer to read into |
| numBytesToRead | the number of bytes to read |
Definition at line 19 of file viostream.cpp.
References mRawStream, and VStream::readGuaranteed().
| Vu8 VIOStream::readGuaranteedByte | ( | ) |
Reads one byte from the stream, and throws a VException if it cannot be read.
Definition at line 23 of file viostream.cpp.
References mRawStream, and VStream::readGuaranteedByte().
Attempts to read a specified number of bytes from the stream.
| targetBuffer | the buffer to read into |
| numBytesToRead | the number of bytes to read |
Definition at line 27 of file viostream.cpp.
References mRawStream, and VStream::read().
Writes bytes to the stream.
| buffer | the buffer containing the data |
| numBytesToWrite | the number of bytes to write to the stream |
Definition at line 31 of file viostream.cpp.
References mRawStream, and VStream::write().
| void VIOStream::flush | ( | ) |
Flushes any pending or buffered write data to the stream.
Until you call flush, you cannot guarantee that your data has actually been written to the underlying physical stream.
Definition at line 35 of file viostream.cpp.
References VStream::flush(), and mRawStream.
| bool VIOStream::skip | ( | Vs64 | numBytesToSkip | ) |
Skips forward in the stream a specified number of bytes.
For memory and file streams, this means advancing the i/o offset by the specified number of bytes; for socket streams, this means reading and discarding the specified number of bytes.
| numBytesToSkip | the number of bytes to skip |
Definition at line 39 of file viostream.cpp.
References mRawStream, and VStream::skip().
| bool VIOStream::seek | ( | Vs64 | offset, |
| int | whence | ||
| ) |
Seeks in the stream using Unix seek() semantics.
VSocketStream has some restrictions in the kinds of seek that are allowed; if you specify an illegal socket seek operation, a VException is thrown.
The following table shows the valid seek parameters for the different stream types:
| SEEK_SET | SEEK_CUR offset>=0 | SEEK_CUR offset<0 | SEEK_END | |
| VMemoryStream | yes | yes | yes | yes |
| VAbstractFileStream-derived | yes | yes | yes | yes |
| VSocketStream | no | yes | no | no |
| offset | the offset, meaning depends on whence value |
| whence | SEEK_SET, SEEK_CUR, or SEEK_END |
Definition at line 43 of file viostream.cpp.
References mRawStream, and VStream::seek().
| bool VIOStream::seek0 | ( | ) |
This is a convenience function that means seek(0, SEEK_SET).
In other words, seek to the start of the stream. It has the same restrictions as noted in seek() above.
Definition at line 47 of file viostream.cpp.
References mRawStream, and VStream::seek0().
| Vs64 VIOStream::getIOOffset | ( | ) | const |
Returns the "current" "offset" in the stream.
Those scare quotes are there because those terms do not quite have consistent or uniform meaning and behavior for all stream types, so you need to be a little careful in using this feature. For buffered file streams, the current offset is simply the i/o mark relative to the start of the file. For memory streams, the current offset is also the i/o mark, relative to the start of the buffer. But for socket streams and unbuffered file streams, there are limitations. Socket streams have no buffer, so the current offset is simply the accumulated number of bytes that have been read and/or written; when used with a socket stream, this function is most useful as a way to determine how much data you have read since last looking at the offset, without having to keep track of each individual read operation (which you might not be able to). Unbuffered file streams have no ability to determine the current i/o mark, yet allow seeking; so there is no way for the class to keep track of the current offset on its own; so, for unbuffered file streams, getIOOffset() throws an exception because it is an illegal operation.
Definition at line 51 of file viostream.cpp.
References VStream::getIOOffset(), and mRawStream.
| Vs64 VIOStream::available | ( | ) | const |
Returns the number of bytes that are available to be read from this stream.
For file and memory streams, this means the number of bytes from the current i/o mark until the end of the file or buffer. For socket streams, this means the number of bytes that can be read without blocking (that is, the number of bytes that are waiting to be read on the socket at this time).
Definition at line 55 of file viostream.cpp.
References VStream::available(), and mRawStream.
| VStream & VIOStream::getRawStream | ( | ) |
Returns a reference to the underlying raw stream; used by the friend function streamCopy() so it can call through to the corresponding VStream friend function and supply it the raw streams.
Also used by some debugging functions.
Definition at line 59 of file viostream.cpp.
References mRawStream.
| Vs16 VIOStream::streamCompare | ( | VIOStream & | streamA, |
| VIOStream & | streamB, | ||
| Vs64 | numBytesToCompare | ||
| ) | [static] |
Compare 2 streams by ascii values.
The streams will be restored to their current positions upon return.
Definition at line 64 of file viostream.cpp.
References CONST_S64, getIOOffset(), read(), and seek().