
 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>*
 - *<NIFFIO Register>*

 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:
 <strParser> is a string that identifies a parser in case there
 is more than one parser in a program.

 <nLevel> is the nesting depth of the current chunk or tag.
 It is the number of chunks above the current object. For example, the
 the NIFF form chunk has an <nLevel> == 0.

 <strFormat> is a vprintf compatible format string that reflects the 
 following variable argument list to the NIFFIOParserTracer.
 

| 

 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); 
| 
