 |
Vault
4.1
|
|
Vault
4.1
|
VStream is an abstract base class that defines a stream-oriented i/o API. More...
#include <vstream.h>
Public Member Functions | |
| VStream () | |
| Default constructor. | |
| VStream (const VString &name) | |
| Constructor that gives the stream a name for debugging purposes. | |
| virtual | ~VStream () |
| 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. | |
| virtual Vs64 | read (Vu8 *targetBuffer, Vs64 numBytesToRead)=0 |
| Attempts to read a specified number of bytes from the stream. | |
| virtual Vs64 | write (const Vu8 *buffer, Vs64 numBytesToWrite)=0 |
| Writes bytes to the stream. | |
| virtual void | flush ()=0 |
| Flushes any pending or buffered write data to the stream. | |
| virtual bool | skip (Vs64 numBytesToSkip)=0 |
| Skips forward in the stream a specified number of bytes. | |
| virtual bool | seek (Vs64 offset, int whence)=0 |
| Seeks in the stream using Unix seek() semantics. | |
| bool | seek0 () |
| This is a convenience function that means seek(0, SEEK_SET). | |
| virtual Vs64 | getIOOffset () const =0 |
| Returns the "current" "offset" in the stream. | |
| virtual Vs64 | available () const =0 |
| Returns the number of bytes that are available to be read from this stream. | |
| const VString & | getName () const |
| Returns the name of the stream that it was given when constructed. | |
| void | setName (const VString &name) |
| Sets the stream name. | |
Static Public Member Functions | |
| static Vs64 | streamCopy (VStream &fromStream, VStream &toStream, Vs64 numBytesToCopy, Vs64 tempBufferSize=16384) |
| Efficiently copies bytes from one stream to another, no matter which concrete stream types are being used. | |
| static Vs64 | streamCopy (VIOStream &fromStream, VIOStream &toStream, Vs64 numBytesToCopy, Vs64 tempBufferSize=16384) |
| static Vs64 | streamCopy (VIOStream &fromStream, VStream &toStream, Vs64 numBytesToCopy, Vs64 tempBufferSize=16384) |
| static Vs64 | streamCopy (VStream &fromStream, VIOStream &toStream, Vs64 numBytesToCopy, Vs64 tempBufferSize=16384) |
| static bool | needSizeConversion (Vs64 sizeValue) |
| Returns true if the specified size value requires conversion given the compiler's definition of size_t and the actual value given. | |
| static void | copyMemory (Vu8 *toBuffer, const Vu8 *fromBuffer, Vs64 numBytesToCopy) |
| A direct replacement for memcpy() that allows for 64-bit lengths that we use everywhere, and deals with situations where the native sizes used by memcpy() are smaller. | |
| static Vu8 * | newNewBuffer (Vs64 bufferSize) |
| The compiler- and size-safe way to do new[bufferSize] when the buffer size is a Vs64. | |
| static Vu8 * | mallocNewBuffer (Vs64 bufferSize) |
| This is provided for consistency with newNewBuffer() when a buffer needs to be allocated with malloc() instead of operator new. | |
Protected Member Functions | |
| virtual Vu8 * | _getReadIOPtr () const |
| Returns a pointer to the current read i/o position in the stream's buffer, or NULL if the stream does not have a buffer or support direct copying from that buffer (for example, a file or socket stream). | |
| virtual Vu8 * | _getWriteIOPtr () const |
| Returns a pointer to the current write i/o position in the stream's buffer, or NULL if the stream does not have a buffer or support direct copying to that buffer (for example, a file or socket stream). | |
| virtual Vs64 | _prepareToRead (Vs64 numBytesToRead) const |
| Returns the number of bytes available for reading from the stream's buffer, or zero by default for streams without buffers. | |
| virtual void | _prepareToWrite (Vs64 numBytesToWrite) |
| Preflights the stream's buffer so that it can have the specified number of bytes written to it subsequently. | |
| virtual void | _finishRead (Vs64 numBytesRead) |
| Postflights a copy by advancing the i/o offset to reflect the specified number of bytes having just been read. | |
| virtual void | _finishWrite (Vs64 numBytesWritten) |
| Postflights a copy by advancing the i/o offset to reflect the specified number of bytes having just been written. | |
Protected Attributes | |
| VString | mName |
| A name for use when debugging stream. | |
Friends | |
| class | VWriteBufferedStream |
VStream is an abstract base class that defines a stream-oriented i/o API.
You will generally use VSocketStream for socket i/o, VBufferedFileStream for file i/o, and VMemoryStream for memory i/o. VStream also defines and implements a static function streamCopy() for efficiently copying data between any two streams, no matter their types; this is useful for doing zero-copy file and socket i/o, or buffering such i/o, without having to specialize the code.
However, it is generally better to use one of the VIOStream-derived classes to do your actual i/o and avoid calling VStream methods directly. The VIOStream classes take a VStream in their constructors and use that stream, letting you do more well-typed i/o, as well as the same operations provided here. For binary data you will use VBinaryIOStream, and for text data (such as a text file or a line-oriented wire protocol) you will use VTextIOStream.
There are two ways to read raw bytes. The readGuaranteed() method will throw an exception if the stream does not contain the requested number of bytes. The read() method will return the actual number of bytes that were read. readGuaranteed() is implemented by calling read() and throwing if it returns an unsatisfactory number of bytes.
You can also write raw bytes. After you have completed your sequence of writes, you should call flush to allow special classes to clean up or write whatever they may have buffered.
Depending on the actual type of stream, you may be able to seek around in the stream. Here are some examples of which streams allow what kind of seeks. Really, the only limitations are obvious: on socket streams you cannot seek anywhere but forward relative to the current position. If you need to do some kind of pseudo-random-access i/o on a socket stream, then you'll just need to buffer it (using a VMemoryStream would make this very easy).
| 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 |
If you just want to skip over some bytes while reading, use the skip() method, which is equivalent to SEEK_CUR forward, and works on all streams. Unfortunately, because of how the different underlying native implementations differ, you can only get a boolean return value indicating whether you could succesfully seek to the desired location.
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 25 of file vstream.cpp.
References read().
| Vu8 VStream::readGuaranteedByte | ( | ) |
Reads one byte from the stream, and throws a VException if it cannot be read.
Definition at line 33 of file vstream.cpp.
References readGuaranteed().
Attempts to read a specified number of bytes from the stream.
| targetBuffer | the buffer to read into |
| numBytesToRead | the number of bytes to read |
Implemented in VMemoryStream, VBufferedFileStream, VDirectIOFileStream, VSocketStream, and VWriteBufferedStream.
Writes bytes to the stream.
| buffer | the buffer containing the data |
| numBytesToWrite | the number of bytes to write to the stream |
Implemented in VReadOnlyMemoryStream, VMemoryStream, VBufferedFileStream, VDirectIOFileStream, and VSocketStream.
| virtual void VStream::flush | ( | ) | [pure virtual] |
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.
Implemented in VReadOnlyMemoryStream, VMemoryStream, VBufferedFileStream, VDirectIOFileStream, VSocketStream, and VWriteBufferedStream.
| virtual bool VStream::skip | ( | Vs64 | numBytesToSkip | ) | [pure virtual] |
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 |
Implemented in VBufferedFileStream, VDirectIOFileStream, VMemoryStream, VSocketStream, and VWriteBufferedStream.
| virtual bool VStream::seek | ( | Vs64 | offset, |
| int | whence | ||
| ) | [pure virtual] |
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 |
Implemented in VBufferedFileStream, VDirectIOFileStream, VMemoryStream, and VSocketStream.
| bool VStream::seek0 | ( | ) | [inline] |
| virtual Vs64 VStream::getIOOffset | ( | ) | const [pure virtual] |
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 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, which have no buffer, the current offset is simply the accumulated number of bytes that have been read; 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).
Implemented in VBufferedFileStream, VDirectIOFileStream, VMemoryStream, and VSocketStream.
| virtual Vs64 VStream::available | ( | ) | const [pure virtual] |
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).
Implemented in VBufferedFileStream, VDirectIOFileStream, VMemoryStream, and VSocketStream.
| Vs64 VStream::streamCopy | ( | VStream & | fromStream, |
| VStream & | toStream, | ||
| Vs64 | numBytesToCopy, | ||
| Vs64 | tempBufferSize = 16384 |
||
| ) | [static] |
Efficiently copies bytes from one stream to another, no matter which concrete stream types are being used.
Some examples of using it include reading a file into memory (fromStream is VAbstractFileStream-derived, toStream is a VMemoryStream), writing from memory to a socket (fromStream is a VMemoryStream, toStream is a VSocketStream), and transferring a file to a socket (fromStream is VAbstractFileStream-derived, toStream is a VSocketStream).
If either of the streams is a VMemoryStream, the copy is made directly with no extra copying. If neither stream is a VMemoryStream, a temporary buffer is used to transfer the data with just a single copy.
Of course, this method does not actually know the stream classes, but simply asks the to and from streams about their capabilities.
| fromStream | the source stream that is read |
| toStream | the target stream that is written |
| numBytesToCopy | the number of bytes read from fromStream and write to toStream |
| tempBufferSize | the size of temporary buffer to create, if one is needed |
Definition at line 40 of file vstream.cpp.
References _finishRead(), _finishWrite(), _getReadIOPtr(), _getWriteIOPtr(), _prepareToRead(), _prepareToWrite(), copyMemory(), newNewBuffer(), NULL, read(), V_MIN, and write().
| const VString& VStream::getName | ( | ) | const [inline] |
| void VStream::setName | ( | const VString & | name | ) | [inline] |
| bool VStream::needSizeConversion | ( | Vs64 | sizeValue | ) | [static] |
Returns true if the specified size value requires conversion given the compiler's definition of size_t and the actual value given.
If size_t is 64 bits, or if the given value fits in 32 bits, then no conversion is necessary, and an operation that takes a size_t can be called with a simple cast; otherwise the caller needs to perform the operation in a loop, processing 32 bits worth of data at a time. This is used internally by various Code Vault stream and i/o functions that provide a consistent 64-bit wide size parameter interface, but need to work on OS's and compilers that might only provide 32 bits of size for certain functions such as read, write, copy, etc.
| sizeValue | the value that is being used to describe a size |
Definition at line 149 of file vstream.cpp.
A direct replacement for memcpy() that allows for 64-bit lengths that we use everywhere, and deals with situations where the native sizes used by memcpy() are smaller.
This could even have optimized versions per platform if the platform supports a native API that is better than memcpy().
Definition at line 154 of file vstream.cpp.
References needSizeConversion(), and V_MIN.
The compiler- and size-safe way to do new[bufferSize] when the buffer size is a Vs64.
If size_t is 64 bits then it just does new. Otherwise, if the requested buffer size fits in 32 bits the it also does new. Otherwise, (size_t is 32 bits but requested size needs 64 bits) then it throws a std::bad_alloc just like new would if it ran out of memory.
| bufferSize | the requested buffer size |
Definition at line 191 of file vstream.cpp.
| Vu8 * VStream::_getReadIOPtr | ( | ) | const [protected, virtual] |
Returns a pointer to the current read i/o position in the stream's buffer, or NULL if the stream does not have a buffer or support direct copying from that buffer (for example, a file or socket stream).
Reimplemented in VMemoryStream.
Definition at line 216 of file vstream.cpp.
References NULL.
| Vu8 * VStream::_getWriteIOPtr | ( | ) | const [protected, virtual] |
Returns a pointer to the current write i/o position in the stream's buffer, or NULL if the stream does not have a buffer or support direct copying to that buffer (for example, a file or socket stream).
Reimplemented in VMemoryStream.
Definition at line 221 of file vstream.cpp.
References NULL.
Returns the number of bytes available for reading from the stream's buffer, or zero by default for streams without buffers.
| numBytesToRead | the number of bytes that will be read |
Reimplemented in VMemoryStream.
Definition at line 226 of file vstream.cpp.
| void VStream::_prepareToWrite | ( | Vs64 | numBytesToWrite | ) | [protected, virtual] |
Preflights the stream's buffer so that it can have the specified number of bytes written to it subsequently.
Throws a VException if the buffer cannot be expanded to accomodate the data.
| numBytesToWrite | the number of bytes that will be written |
Reimplemented in VMemoryStream.
Definition at line 231 of file vstream.cpp.
| void VStream::_finishRead | ( | Vs64 | numBytesRead | ) | [protected, virtual] |
Postflights a copy by advancing the i/o offset to reflect the specified number of bytes having just been read.
| numBytesRead | the number of bytes that were previously read |
Reimplemented in VMemoryStream.
Definition at line 235 of file vstream.cpp.
| void VStream::_finishWrite | ( | Vs64 | numBytesWritten | ) | [protected, virtual] |
Postflights a copy by advancing the i/o offset to reflect the specified number of bytes having just been written.
| numBytesWritten | the number of bytes that were previously written |
Reimplemented in VMemoryStream.
Definition at line 239 of file vstream.cpp.