class IFFByteStream: public ByteStream

ByteStream interface for an IFF file.

Inheritance:


Public Methods

[more] IFFByteStream(ByteStream &bs)
Constructs an IFFByteStream object attached to ByteStream bs.
[more]int get_chunk(GString &chkid, int *rawoffsetptr=0, int *rawsizeptr=0)
Enters a chunk for reading.
[more]void put_chunk(const char *chkid, int insertatt=0)
Enters a chunk for writing.
[more]void close_chunk()
Leaves the current chunk.
[more]int ready()
Returns true when it is legal to call read or write.
[more]int composite()
Returns true when the current chunk is a composite chunk.
[more]void short_id(GString &chkid)
Returns the current chunk identifier of the current chunk.
[more]void full_id(GString &chkid)
Returns the qualified chunk identifier of the current chunk.
[more]int check_id(const char *id)
Checks a potential chunk identifier.


Inherited from ByteStream:

Public

Virtual Functions.

[more]virtual ~ByteStream()
Virtual destructor.
[more]virtual size_t read(void *buffer, size_t size)
Reads data from a ByteStream.
[more]virtual size_t write(const void *buffer, size_t size)
Writes data to a ByteStream.
[more]virtual long tell(void)
Returns the offset of the current position in the ByteStream.
[more]virtual int is_seekable(void) const
Tests whether function seek can seek backwards.
[more]virtual void seek(long offset, int whence = SEEK_SET)
Sets the current position for reading or writing the ByteStream.
[more]virtual void flush()
Flushes all buffers in the ByteStream.

Utility Functions.

[more]size_t readall(void *buffer, size_t size)
Reads data and blocks until everything has been read.
[more]size_t writall(const void *buffer, size_t size)
Writes data and blocks until everything has been written.
[more]size_t copy(ByteStream &bsfrom, size_t size=0)
Copy data from another ByteStream.
[more]void write8(unsigned int card8)
Writes a one-byte integer to a ByteStream.
[more]void write16(unsigned int card16)
Writes a two-bytes integer to a ByteStream.
[more]void write32(unsigned int card32)
Writes a four-bytes integer to a ByteStream.
[more]unsigned int read8()
Reads a one-byte integer from a ByteStream.
[more]unsigned int read16()
Reads a two-bytes integer from a ByteStream.
[more]unsigned int read32()
Reads a four-bytes integer from a ByteStream.


Documentation

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 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 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 is_seekable). This is not much of a problem because you can always create the IFF file into a MemoryByteStream and then use copy to transfer the IFF file into a non seekable ByteStream.

o IFFByteStream(ByteStream &bs)
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.

oint get_chunk(GString &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.

ovoid put_chunk(const char *chkid, int insertatt=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

0x41, 0x54, 0x26, 0x54 before the chunk header, as discussed in IFFByteStream.h.

ovoid 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.

oint ready()
Returns true when it is legal to call read or write.

oint composite()
Returns true when the current chunk is a composite chunk.

ovoid short_id(GString &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".

ovoid full_id(GString &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.

oint check_id(const char *id)
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.


This class has no child classes.

Alphabetic index HTML hierarchy of classes or Java