IFFByteStream Class Reference
#include <IFFByteStream.h>
Inheritance diagram for IFFByteStream:
Detailed Description
ByteStream interface for an IFF file.Class IFFByteStream# augments the ByteStream# interface with functions for navigating from chunk to chunk. It works in relation with a ByteStream specified at construction time.
{ Reading an IFF file} --- You can read an IFF file by constructing an IFFByteStream# object attached to the ByteStream containing the IFF file. Calling function get_chunk} positions the file pointer at the beginning of the first chunk. You can then use ByteStream::read} to access the chunk data. Function read# will return #0# if you attempt to read past the end of the chunk, just as if you were trying to read past the end of a file. You can at any time call function close_chunk} to terminate reading data in this chunk. The following chunks can be accessed by calling get_chunk# and close_chunk# repeatedly until you reach the end of the file. Function read# is not very useful when accessing a composite chunk. You can instead make nested calls to functions get_chunk# and close_chunk# in order to access the chunks located inside the composite chunk.
{ Writing an IFF file} --- You can write an IFF file by constructing an IFFByteStream# object attached to the seekable ByteStream object that will contain the IFF file. Calling function put_chunk} creates a first chunk header and positions the file pointer at the beginning of the chunk. You can then use ByteStream::write} to store the chunk data. Calling function close_chunk} terminates the current chunk. You can append more chunks by calling put_chunk# and close_chunk# repeatedly. Function write# is not very useful for writing a composite chunk. You can instead make nested calls to function put_chunk# and close_chunk# in order to create chunks located inside the composite chunk.
Writing an IFF file requires a seekable ByteStream (see ByteStream::is_seekable}). This is not much of a problem because you can always create the IFF file into a MemoryByteStream} and then use ByteStream::copy} to transfer the IFF file into a non seekable ByteStream.
Definition at line 181 of file IFFByteStream.h.
Public Member Functions | |
| ~IFFByteStream () | |
| virtual size_t | read (void *buffer, size_t size) |
| virtual size_t | write (const void *buffer, size_t size) |
| virtual long | tell (void) const |
| int | get_chunk (GUTF8String &chkid, int *rawoffsetptr=0, int *rawsizeptr=0) |
| void | put_chunk (const char *chkid, int insertmagic=0) |
| void | close_chunk () |
| void | seek_close_chunk () |
| int | ready () |
| int | composite () |
| void | short_id (GUTF8String &chkid) |
| void | full_id (GUTF8String &chkid) |
| GP< ByteStream > | get_bytestream (void) |
| size_t | copy (ByteStream &bsfrom, size_t size=0) |
| virtual void | flush (void) |
| bool | compare (IFFByteStream &iff) |
Static Public Member Functions | |
| static GP< IFFByteStream > | create (const GP< ByteStream > &bs) |
| static int | check_id (const char *id) |
Public Attributes | |
| bool | has_magic |
Protected Member Functions | |
| IFFByteStream (const GP< ByteStream > &bs, const int pos) | |
Member Function Documentation
| int IFFByteStream::check_id | ( | const char * | id | ) | [static] |
Checks a potential chunk identifier.
This function categorizes the chunk identifier formed by the first four characters of string chkid#. It returns #0# if this is a legal identifier for a regular chunk. It returns #+1# if this is a reserved composite chunk identifier. It returns #-1# if this is an illegal or otherwise reserved identifier which should not be used.
Definition at line 140 of file IFFByteStream.cpp.
| void IFFByteStream::close_chunk | ( | ) |
Leaves the current chunk.
This function leaves the chunk previously entered by a matching call to get_chunk# and put_chunk#. The IFFByteStream is then ready to process the next chunk at the same hierarchical level.
Definition at line 380 of file IFFByteStream.cpp.
| bool IFFByteStream::compare | ( | IFFByteStream & | iff | ) |
This is a simple compare method.
The IFFByteStream may be read for the sake of the comparison. Since IFFByteStreams are non-seekable, the stream is not valid for use after comparing, regardless of the result.
Definition at line 509 of file IFFByteStream.cpp.
| int IFFByteStream::composite | ( | ) |
Returns true when the current chunk is a composite chunk.
Definition at line 125 of file IFFByteStream.cpp.
| size_t IFFByteStream::copy | ( | ByteStream & | bsfrom, | |
| size_t | size = 0 | |||
| ) | [inline] |
Copy data from another ByteStream.
A maximum of size# bytes are read from the ByteStream bsfrom# and are written to the ByteStream #*this# at the current position. Less than size# bytes may be written if an end-of-file mark is reached on bsfrom#. This function returns the total number of bytes copied. Setting argument size# to zero (the default value) has a special meaning: the copying process will continue until reaching the end-of-file mark on ByteStream bsfrom#, regardless of the number of bytes transferred.
Reimplemented from ByteStream.
Definition at line 264 of file IFFByteStream.h.
| GP< IFFByteStream > IFFByteStream::create | ( | const GP< ByteStream > & | bs | ) | [static] |
Constructs an IFFByteStream object attached to ByteStream bs#.
Any ByteStream can be used when reading an IFF file. Writing an IFF file however requires a seekable ByteStream.
Definition at line 98 of file IFFByteStream.cpp.
| virtual void IFFByteStream::flush | ( | void | ) | [inline, virtual] |
Flushes all buffers in the ByteStream.
Calling this function guarantees that pending data have been actually written (i.e. passed to the operating system). Class ByteStream# provides a default implementation which does nothing.
Reimplemented from ByteStream::Wrapper.
Definition at line 270 of file IFFByteStream.h.
| void IFFByteStream::full_id | ( | GUTF8String & | chkid | ) |
Returns the qualified chunk identifier of the current chunk.
String chkid# is overwritten with the {qualified chunk identifier} of the current chunk. The qualified chunk identifier of a composite chunk is equal to the extended chunk identifier. The qualified chunk identifier of a regular chunk is composed by concatenating the secondary chunk identifier of the closest #"FORM"# or #"PROP"# composite chunk containing the current chunk, a dot #"."#, and the current chunk identifier, as in #"DJVU.INFO"#. According to the EA IFF 85 identifier scoping rules, the qualified chunk identifier uniquely defines how the chunk data should be interpreted.
Definition at line 442 of file IFFByteStream.cpp.
| int IFFByteStream::get_chunk | ( | GUTF8String & | chkid, | |
| int * | rawoffsetptr = 0, |
|||
| int * | rawsizeptr = 0 | |||
| ) |
Enters a chunk for reading.
Function get_chunk# returns zero when the last chunk has already been accessed. Otherwise it parses a chunk header, positions the IFFByteStream at the beginning of the chunk data, stores the extended chunk identifier into string chkid#, and returns the non zero chunk size. The file offset of the chunk data may be retrieved using function tell#. The chunk data can then be read using function read# until reaching the end of the chunk. Advanced users may supply two pointers to integer variables using arguments rawoffsetptr# and rawsizeptr#. These variables will be overwritten with the offset and the length of the file segment containing both the chunk header and the chunk data.
Definition at line 167 of file IFFByteStream.cpp.
| void IFFByteStream::put_chunk | ( | const char * | chkid, | |
| int | insertmagic = 0 | |||
| ) |
Enters a chunk for writing.
Function put_chunk# prepares a chunk header and positions the IFFByteStream at the beginning of the chunk data. Argument chkid# defines a extended chunk identifier for this chunk. The chunk data can then be written using function write#. The chunk is terminated by a matching call to function close_chunk#. When insertmagic# is non zero, function put_chunk# inserts the bytes: 0x41, 0x54, 0x26, 0x54 before the chunk header, as discussed in IFFByteStream.h}.
Definition at line 299 of file IFFByteStream.cpp.
| size_t IFFByteStream::read | ( | void * | buffer, | |
| size_t | size | |||
| ) | [virtual] |
Reads data from a ByteStream.
This function {must} be implemented by each subclass of ByteStream#. At most size# bytes are read from the ByteStream and stored in the memory area pointed to by buffer#. Function read# returns immediately if size# is zero. The actual number of bytes read is returned. Function read# returns a number of bytes smaller than size# if the end-of-file mark is reached before filling the buffer. Subsequent invocations will always return value #0#. Function read# may also return a value greater than zero but smaller than size# for internal reasons. Programs must be ready to handle these cases or use function readall}. Exception GException} is thrown with a plain text error message whenever an error occurs.
Reimplemented from ByteStream::Wrapper.
Definition at line 463 of file IFFByteStream.cpp.
| int IFFByteStream::ready | ( | ) |
Returns true when it is legal to call read# or write#.
Definition at line 110 of file IFFByteStream.cpp.
| void IFFByteStream::seek_close_chunk | ( | ) |
This is identical to the above, plus it adds a seek to the start of the next chunk.
This way we catch EOF errors with the current chunk.
Definition at line 413 of file IFFByteStream.cpp.
| void IFFByteStream::short_id | ( | GUTF8String & | chkid | ) |
Returns the current chunk identifier of the current chunk.
String chkid# is overwritten with the {extended chunk identifier} of the current chunk. The extended chunk identifier of a regular chunk is simply the chunk identifier, as in #"PM44"#. The extended chunk identifier of a composite chunk is the concatenation of the chunk identifier, of a semicolon #":"#, and of the secondary chunk identifier, as in #"FORM:DJVU"#.
Definition at line 427 of file IFFByteStream.cpp.
| long IFFByteStream::tell | ( | void | ) | const [virtual] |
Returns the offset of the current position in the ByteStream.
This function {must} be implemented by each subclass of ByteStream#.
Reimplemented from ByteStream::Wrapper.
Definition at line 503 of file IFFByteStream.cpp.
| size_t IFFByteStream::write | ( | const void * | buffer, | |
| size_t | size | |||
| ) | [virtual] |
Writes data to a ByteStream.
This function {must} be implemented by each subclass of ByteStream#. At most size# bytes from buffer buffer# are written to the ByteStream. Function write# returns immediately if size# is zero. The actual number of bytes written is returned. Function write# may also return a value greater than zero but smaller than size# for internal reasons. Programs must be ready to handle these cases or use function writall}. Exception GException} is thrown with a plain text error message whenever an error occurs.
Reimplemented from ByteStream::Wrapper.
Definition at line 488 of file IFFByteStream.cpp.
Member Data Documentation
has_magic# is true if the stream has the DjVu file magic.
Definition at line 279 of file IFFByteStream.h.
The documentation for this class was generated from the following files:
