niffio


NAME

niffio - Data types of the NIFFIO API

NIFFIO provides data types and functions to manipulate NIFF-specific features of NIFF files (eg. tags, chunk length tables). Because NIFF files are also RIFF files, NIFFIO makes heavy use of the RIFFIO API for ordinary RIFF features (eg. chunks).


NIFF Specification

Where is NIFF described?

The NIFF file format is described in the NIFF specification.

Notation Interchange File Format URL ftp://blackbox.cartah.washington.edu


NIFF Version

Which version of NIFF does NIFFIO support?

NIFFIO supports NIFF 6b.


NIFFIOChunkLengthTable

How are chunk length tables represented?

NIFFIO provides chunk length table routines that operate on a pointer to a NIFFIOChunkLengthTable structure.

A NIFFIOChunkLengthTable is not necessarily stored in memory the same way as a chunk length table is stored in a NIFF file.

All of the members of a NIFFIOChunkLengthTable are private.


NIFFIOTag

How are tags supported?

A NIFFIOTag holds tag id, size, and file location information about a tag in a NIFF file.

typedef struct { /* Public - users need to read and set these members */ BYTE tagid; /* type of tag */ BYTE tagsizeData; /* size of tag's data * (does not include possible pad byte) */ /* Other Private members - not for NIFFIO users */ } NIFFIOTag;


NIFFIOFile

How are NIFF files represented?

Operations on NIFF files take pointers to a NIFFIOFile structure.

Represents a NIFF file, including I/O operations and its chunk length table.

There are no public members of a NIFFIOFile.

Because NIFF files are also RIFF files, all of the I/O operations defined for RIFFIO files have RIFFIO equivalents. (see *<NIFFIO Inherit>*)


NIFFIOStbl

How is the NIFF String Table (stbl) represented?

Operations on the String Table take a pointer to a NIFFIOStbl structure.

This structure represents a single string item, including a pointer to its value and its offset into the NIFF file's string table. It is used by the NIFF writing program.

When writing a NIFF file, the user supplies an array of type NIFFIOStbl, with the pointers to each of the strings placed into the <*str> fields. The user then calls NIFFIOchunkStringTable with this array and the number of strings supplied. NIFFIOStoreStbl() puts the strings into string table format, calculating the offsets and storing each offset into the matching position for its string, and then stores the whole string table into the file. The string offsets can be thus be obtained and used by the writing program when writing out chunks which refer to the string later in the file.

typedef struct { STROFFSET offset; /* Offset of string relative to chunk data start */ char *str; } NIFFIOStbl;


NIFFIOParser

How does NIFFIO know how to parse a NIFF file?

NIFFIO uses a NIFFIOParser structure to store parsing information for NIFF files. A NIFFIOParser remembers user-supplied callbacks to process selected NIFF chunks and tags.

See Also: - *<NIFFIO Parse>*

A user may choose to trace the operation of a NIFFIOParser..The default tracer uses the Standard C Library to print to <stderr>. Alternatively, the user may supply their own routine to handle tracing output.

NIFFIOParserTracer

Callback to handle parser tracing output.

typedef void (*NIFFIOParserTracer)(const char *strParser, const unsigned nLevel, const char *strFormat, ...);

PARAMETERS:

NIFFIOUserContext

User-defined parser state information provided by parent chunk callbacks.

typedef void *NIFFIOUserContext;

While parsing a NIFF file, users may keep track of their own parsing information by supplying pointers to custom, user-defined data structures. In turn, the NIFFIO parser will pass chunk and tag callbacks the ``context'' of their enclosing (parent) chunk.

NIFFIOUserContexts are solely for the user's use. NIFFIO will never dereference any NIFFIOUserContext. User contexts may be safely ignored by any user who does not wish to use them. It is safe to assign a null pointer to a NIFFIOUserContext.

In addition to the NIFFIOUserContext of its parent chunk, a chunk callback routine also gets information about the chunk it is processing through a NIFFIOChunkContext structure.

NIFFIOChunkContext

Parser state information provided to chunk callbacks.

typedef struct { unsigned nLevel; /* chunk depth */ NIFFIOFile *pnf; /* NIFF file that contains the chunk */ RIFFIOChunk *pchunk; /* Chunk information from file */ NIFFIOUserContext ctxParent; /* Parent chunk user context */ NIFFIOUserContext ctxMe; /* Child user context, to be filled in * by chunk start callback */ } NIFFIOChunkContext;

NIFFIOTagContext

Parser state information provided to tag callbacks.

typedef struct { unsigned nLevel; /* tag depth */ NIFFIOFile *pnf; /* NIFF file that contains the chunk */ NIFFIOTag *ptag; /* Tag information from file */ RIFFIOChunk *pchunkParent; /* Parent chunk information from file */ NIFFIOUserContext ctxParent; /* Parent chunk user context */ } NIFFIOTagContext;


Parser Callbacks

Here are the types of functions that the user needs to define to use as callbacks.

NIFFIOChunkCallback

Process a chunk encountered by the parser.

typedef RIFFIOSuccess (*NIFFIOChunkCallback)(NIFFIOChunkContext *pchunkctx);

NIFFIOTagCallback

Process a tag encountered by the parser.

typedef RIFFIOSuccess (*NIFFIOTagCallback)(NIFFIOTagContext *ptagctx);