@database "iffparse"
@master "ADCD_v1.2:Inc&AD2.1/Includes/doc/iffparse.doc"

@Node Main "iffparse.doc"
@TOC 2.1Includes_Autodocs/Autodocs

@{" HookEntry() " Link "HookEntry()"}           @{" FreeIFF() " Link "FreeIFF()"}          @{" PropChunk() " Link "PropChunk()"}
@{" AllocIFF() " Link "AllocIFF()"}            @{" FreeLocalItem() " Link "FreeLocalItem()"}    @{" PropChunks() " Link "PropChunks()"}
@{" AllocLocalItem() " Link "AllocLocalItem()"}      @{" GoodID() " Link "GoodID()"}           @{" PushChunk() " Link "PushChunk()"}
@{" CloseClipboard() " Link "CloseClipboard()"}      @{" GoodType() " Link "GoodType()"}         @{" ReadChunkBytes() " Link "ReadChunkBytes()"}
@{" CloseIFF() " Link "CloseIFF()"}            @{" IDtoStr() " Link "IDtoStr()"}          @{" ReadChunkRecords() " Link "ReadChunkRecords()"}
@{" CollectionChunk() " Link "CollectionChunk()"}     @{" InitIFF() " Link "InitIFF()"}          @{" SetLocalItemPurge() " Link "SetLocalItemPurge()"}
@{" CollectionChunks() " Link "CollectionChunks()"}    @{" InitIFFasClip() " Link "InitIFFasClip()"}    @{" StopChunk() " Link "StopChunk()"}
@{" CurrentChunk() " Link "CurrentChunk()"}        @{" InitIFFasDOS() " Link "InitIFFasDOS()"}     @{" StopChunks() " Link "StopChunks()"}
@{" EntryHandler() " Link "EntryHandler()"}        @{" LocalItemData() " Link "LocalItemData()"}    @{" StopOnExit() " Link "StopOnExit()"}
@{" ExitHandler() " Link "ExitHandler()"}         @{" OpenClipboard() " Link "OpenClipboard()"}    @{" StoreItemInContext() " Link "StoreItemInContext()"}
@{" FindCollection() " Link "FindCollection()"}      @{" OpenIFF() " Link "OpenIFF()"}          @{" StoreLocalItem() " Link "StoreLocalItem()"}
@{" FindLocalItem() " Link "FindLocalItem()"}       @{" ParentChunk() " Link "ParentChunk()"}      @{" WriteChunkBytes() " Link "WriteChunkBytes()"}
@{" FindProp() " Link "FindProp()"}            @{" ParseIFF() " Link "ParseIFF()"}         @{" WriteChunkRecords() " Link "WriteChunkRecords()"}
@{" FindPropContext() " Link "FindPropContext()"}     @{" PopChunk() " Link "PopChunk()"}

@EndNode

@Node "HookEntry()" "HookEntry"

NAME
    HookEntry -- call-back stub vector (LANGUAGE SPECIFIC LINK ROUTINE)

SYNOPSIS
    This function is never called directly by the client.

FUNCTION
    HookEntry's purpose is to do language-specific setup and conversion
    of parameters passed from a library to a client call-back routine.
    Under Kickstart 2.0, a standard for call-backs has been established.
    The registers will contain the following items:

            A0:     pointer to hook that enabled us to get here.
            A2:     pointer to "object."
            A1:     pointer to "message packet."

    In iffparse, the "object" will vary from routine to routine.  The
    "message packet" is also specific to the operation involved (RTFM!).

    THIS ROUTINE IS NOT PART OF IFFPARSE.  It, or something similar, is
    part of the compiler vendor's link library.  (If it's not there,
    cobbling up your own isn't too hard.)

SEE ALSO
    @{"EntryHandler()" Link "EntryHandler()"}, @{"ExitHandler()" Link "ExitHandler()"}, @{"InitIFF()" Link "InitIFF()"}, @{"SetLocalItemPurge()" Link "SetLocalItemPurge()"},
    @{"utility/hooks.h" Link "ADCD_v1.2:Inc&AD2.1/Includes/utility/hooks.h/Main" 0}   (A must-read;  LOTS of details in there)

@EndNode

@Node "AllocIFF()" "iffparse.library/AllocIFF"

NAME
    AllocIFF -- Create a new @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} structure.

SYNOPSIS
    iff = AllocIFF ()
    d0

    struct @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} *iff;

FUNCTION
    Allocates a new @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} structure and initializes the basic values.
    This function is the only supported way to create an @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32}
    structure since there are private fields that need to be initialized.

INPUTS

RESULT
    iff     - pointer to @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} structure or NULL if the allocation
              failed.

EXAMPLE

NOTES

BUGS

SEE ALSO
    @{"FreeIFF()" Link "FreeIFF()"}

@EndNode

@Node "AllocLocalItem()" "iffparse.library/AllocLocalItem"

NAME
    AllocLocalItem -- Create a local context item structure.

SYNOPSIS
    item = AllocLocalItem (type, id, ident, usize)
     d0                     d0   d1   d2     d3

    struct @{"LocalContextItem" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 80} *item;
    LONG                    type, id, ident, usize;

FUNCTION
    Allocates and initializes a @{"LocalContextItem" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 80} structure with "usize"
    bytes of associated user data.  This is the only supported way to
    create such an item.  The user data can be accessed with the
    @{"LocalItemData" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/iffparse/LocalItemData()"} function.  An item created with this function
    automatically has its purge vectors set up correctly to dispose of
    itself and its associated user data area.  Any additional cleanup
    should be done with a user-supplied purge vector.

INPUTS
    type,id - additional longword identification values.
    ident   - longword identifier for class of context item.
    usize   - number of bytes of user data to allocate for this item.

RESULT
    item    - pointer to initialized @{"LocalContextItem" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 80} or NULL if the
              allocation failed.

EXAMPLE

NOTES

BUGS

SEE ALSO
    @{"FreeLocalItem()" Link "FreeLocalItem()"}, @{"LocalItemData()" Link "LocalItemData()"}, @{"StoreLocalItem()" Link "StoreLocalItem()"},
    @{"StoreItemInContext()" Link "StoreItemInContext()"}, @{"SetLocalItemPurge()" Link "SetLocalItemPurge()"}

@EndNode

@Node "CloseClipboard()" "iffparse.library/CloseClipboard"

NAME
    CloseClipboard -- Close and free an open @{"ClipboardHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 113}.

SYNOPSIS
    CloseClipboard (clip)
                     a0

    struct @{"ClipboardHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 113} *clip;

FUNCTION
    Closes the clipboard.device and frees the @{"ClipboardHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 113} structure.

INPUTS
    clip    - pointer to @{"ClipboardHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 113} struct created with
              @{"OpenClipboard" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/iffparse/OpenClipboard()"}.

RESULT

EXAMPLE

NOTES

BUGS

SEE ALSO
    @{"OpenClipboard()" Link "OpenClipboard()"}, @{"InitIFFasClip()" Link "InitIFFasClip()"}

@EndNode

@Node "CloseIFF()" "iffparse.library/CloseIFF"

NAME
    CloseIFF -- Close an IFF context.

SYNOPSIS
    CloseIFF (iff)
              a0

    struct @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} *iff;

FUNCTION
    Completes an IFF read or write operation by closing the IFF context
    established for this @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} struct.  The @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} struct itself
    is left ready for re-use and a new context can be opened with
    @{"OpenIFF()" Link "OpenIFF()"}.  This function can be used for cleanup if a read or write
    fails partway through.

    As part of its cleanup operation, CloseIFF() calls the client-
    supplied stream hook vector.  The @{"IFFStreamCmd" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 53} packet will be set
    as follows:

            sc_Command:     IFFCMD_CLEANUP
            sc_Buf:         (Not applicable)
            sc_NBytes:      (Not applicable)

    This operation is NOT permitted to fail;  any error code returned
    will be ignored (best to return 0, though).  DO NOT write to this
    structure.

INPUTS
    iff     - pointer to @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} struct previously opened with
              @{"OpenIFF()" Link "OpenIFF()"}.

RESULT

EXAMPLE

NOTES

BUGS

SEE ALSO
    @{"OpenIFF()" Link "OpenIFF()"}, @{"InitIFF()" Link "InitIFF()"}

@EndNode

@Node "CollectionChunk()" "iffparse.library/CollectionChunk"

NAME
    CollectionChunk -- declare a chunk type for collection.

SYNOPSIS
    error = CollectionChunk (iff, type, id)
     d0                      a0    d0   d1

    LONG             error;
    struct @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} *iff;
    LONG             type;
    LONG             id;

FUNCTION
    Installs an entry handler for chunks with the given type and id so
    that the contents of those chunks will be stored as they are
    encountered.  This is like @{"PropChunk()" Link "PropChunk()"} except that more than one
    chunk of this type can be stored in lists which can be returned by
    @{"FindCollection()" Link "FindCollection()"}.  The storage of these chunks still follows the
    property chunk scoping rules for IFF files so that at any given
    point, stored collection chunks will be valid in the current context.

INPUTS
    iff     - pointer to @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} struct (does not need to be open).
    type    - type code for the chunk to declare (ex. "ILBM").
    id      - identifier for the chunk to declare (ex. "CRNG").

RESULT
    error   - 0 if successful or an IFFERR_#? error code if not
              successful.

EXAMPLE

NOTES

BUGS

SEE ALSO
    @{"CollectionChunks()" Link "CollectionChunks()"}, @{"FindCollection()" Link "FindCollection()"}, @{"PropChunk()" Link "PropChunk()"}

@EndNode

@Node "CollectionChunks()" "iffparse.library/CollectionChunks"

NAME
    CollectionChunks -- Declare many collection chunks at once.

SYNOPSIS
    error = CollectionChunks (iff, list, n)
     d0                       a0    a1  d0

    LONG             error;
    struct @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} *iff;
    LONG             *list;
    LONG             n;

FUNCTION
    Declares multiple collection chunks from a list.  The list argument
    is a pointer to an array of long words arranged in pairs.  The format
    for the list is as follows:

            TYPE1, ID1, TYPE2, ID2, ..., TYPEn, IDn

    The argument n is the number of pairs.  CollectionChunks() just calls
    @{"CollectionChunk()" Link "CollectionChunk()"} n times.

INPUTS
    iff     - pointer to @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} struct.
    list    - pointer to array of longword chunk types and identifiers.
    n       - number of chunks to declare.

RESULT
    error   - 0 if successful or an IFFERR_#? error code if not
              successful.

EXAMPLE

NOTES

BUGS

SEE ALSO
    @{"CollectionChunk()" Link "CollectionChunk()"}

@EndNode

@Node "CurrentChunk()" "iffparse.library/CurrentChunk"

NAME
    CurrentChunk -- Get context node for current chunk.

SYNOPSIS
    top = CurrentChunk (iff)
    d0                  a0

    struct @{"ContextNode" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 66}  *top;
    struct @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32}    *iff;

FUNCTION
    Returns top context node for the given @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} struct.  The top
    context node corresponds to the chunk most recently pushed on the
    stack, which is the chunk where the stream is currently positioned.
    The @{"ContextNode" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 66} structure contains information on the type of chunk
    currently being parsed (or written), its size and the current
    position within the chunk.

INPUTS
    iff     - pointer to @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} struct.

RESULT
    top     - pointer to top context node or NULL if none.

EXAMPLE

NOTES

BUGS

SEE ALSO
    @{"PushChunk()" Link "PushChunk()"}, @{"PopChunk()" Link "PopChunk()"}, @{"ParseIFF()" Link "ParseIFF()"}, @{"ParentChunk()" Link "ParentChunk()"}

@EndNode

@Node "EntryHandler()" "iffparse.library/EntryHandler"

NAME
    EntryHandler -- Add an entry handler to the @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} context.

SYNOPSIS
    error = EntryHandler (iff, type, id, position, hook, object)
     d0                   a0    d0   d1    d2       a1     a2

    LONG             error;
    struct @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} *iff;
    LONG             type, id, position;
    struct @{"Hook" Link "ADCD_v1.2:Inc&AD2.1/Includes/utility/hooks.h/Main" 21}       *hook;
    APTR             object;

FUNCTION
    Installs an entry handler vector for a specific type of chunk into
    the context for the given @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} struct.  Type and id are the
    longword identifiers for the chunk to handle.  The hook is a client-
    supplied standard 2.0 @{"Hook" Link "ADCD_v1.2:Inc&AD2.1/Includes/utility/hooks.h/Main" 21} structure, properly initialized.  Position
    tells where to put the handler in the context.  The handler will be
    called whenever the parser enters a chunk of the given type, so the
    IFF stream will be positioned to read the first data byte in the
    chunk.  The handler will execute in the same context as whoever
    called @{"ParseIFF()" Link "ParseIFF()"}.  The handler will be called (through the hook)
    with the following arguments:

            A0:     the @{"Hook" Link "ADCD_v1.2:Inc&AD2.1/Includes/utility/hooks.h/Main" 21} pointer you passed.
            A2:     the 'object' pointer you passed.
            A1:     pointer to a LONG containing the value
                    IFFCMD_ENTRY.

    The error code your call-back routine returns will affect the parser
    in three different ways:

    Return value            Result
    ------------            ------
    0:                      Normal success;  @{"ParseIFF()" Link "ParseIFF()"} will continue
                            through the file.
    IFF_RETURN2CLIENT:      @{"ParseIFF()" Link "ParseIFF()"} will stop and return the value 0.
                            (StopChunk() is internally implemented using
                            this return value.)
    Any other value:        @{"ParseIFF()" Link "ParseIFF()"} will stop and return the value
                            you supplied.  This is how errors should be
                            returned.

INPUTS
    iff     - pointer to @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} struct.
    type    - type code for chunk to handle (ex. "ILBM").
    id      - ID code for chunk to handle (ex. "CMAP").
    position- Local context item position.  One of the IFFSLI_#? codes.
    hook    - pointer to @{"Hook" Link "ADCD_v1.2:Inc&AD2.1/Includes/utility/hooks.h/Main" 21} structure.
    object  - a client-defined pointer which is passed in A2 during call-
              back.

RESULT
    error   - 0 if successful or an IFFERR_#? error code if not
              successful.

EXAMPLE

NOTES

BUGS
    Returning the values IFFERR_EOF or IFFERR_EOC from the call-back
    routine *may* confuse the parser.

    There is no way to explicitly remove a handler once installed.
    However, by installing a do-nothing handler using IFFSLI_TOP,
    previous handlers will be overridden until the context expires.

SEE ALSO
    @{"ExitHandler()" Link "ExitHandler()"}, @{"StoreLocalItem()" Link "StoreLocalItem()"}, @{"StoreItemInContext()" Link "StoreItemInContext()"},
    @{"utility/hooks.h" Link "ADCD_v1.2:Inc&AD2.1/Includes/utility/hooks.h/Main" 0}

@EndNode

@Node "ExitHandler()" "iffparse.library/ExitHandler"

NAME
    ExitHandler -- Add an exit handler to the @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} context.

SYNOPSIS
    error = ExitHandler (iff, type, id, position, hook, object)
     d0                  a0    d0   d1    d2       a1     a2

    LONG             error;
    struct @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} *iff;
    LONG             type, id, position;
    struct @{"Hook" Link "ADCD_v1.2:Inc&AD2.1/Includes/utility/hooks.h/Main" 21}       *hook;
    APTR             object;

FUNCTION
    Installs an exit handler vector for a specific type of chunk into the
    context for the given @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} struct.  Type and id are the longword
    identifiers for the chunk to handle.  The hook is a client-supplied
    standard 2.0 @{"Hook" Link "ADCD_v1.2:Inc&AD2.1/Includes/utility/hooks.h/Main" 21} structure, properly initialized.  Position tells
    where to put the handler in the context.  The handler will be called
    just before the parser exits the given chunk in the "pause" parse
    state.  The IFF stream may not be positioned predictably within the
    chunk.  The handler will execute in the same context as whoever
    called @{"ParseIFF()" Link "ParseIFF()"}.  The handler will be called (through the hook)
    with the following arguments:

            A0:     the @{"Hook" Link "ADCD_v1.2:Inc&AD2.1/Includes/utility/hooks.h/Main" 21} pointer you passed.
            A2:     the 'object' pointer you passed.
            A1:     pointer to a LONG containing the value
                    IFFCMD_EXIT.

    The error code your call-back routine returns will affect the parser
    in three different ways:

    Return value            Result
    ------------            ------
    0:                      Normal success;  @{"ParseIFF()" Link "ParseIFF()"} will continue
                            through the file.
    IFF_RETURN2CLIENT:      @{"ParseIFF()" Link "ParseIFF()"} will stop and return the value 0.
                            (StopChunk() is internally implemented using
                            this return value.)
    Any other value:        @{"ParseIFF()" Link "ParseIFF()"} will stop and return the value
                            you supplied.  This is how errors should be
                            returned.

INPUTS
    iff     - pointer to @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} struct.
    type    - type code for chunk to handle (ex. "ILBM").
    id      - identifier code for chunk to handle (ex. "CMAP").
    position- local context item position.  One of the IFFSLI_#? codes.
    hook    - pointer to @{"Hook" Link "ADCD_v1.2:Inc&AD2.1/Includes/utility/hooks.h/Main" 21} structure.
    object  - a client-defined pointer which is passed in A2 during call-
              back.

RESULT
    error   - 0 if successful or an IFFERR_#? error code if not
              successful.

EXAMPLE

NOTES

BUGS
    Returning the values IFFERR_EOF or IFFERR_EOC from the call-back
    routine *may* confuse the parser.

    There is no way to explicitly remove a handler once installed.
    However, by installing a do-nothing handler using IFFSLI_TOP,
    previous handlers will be overridden until the context expires.

SEE ALSO
    @{"EntryHandler()" Link "EntryHandler()"}, @{"StoreLocalItem()" Link "StoreLocalItem()"}, @{"StoreItemInContext()" Link "StoreItemInContext()"},
    @{"utility/hooks.h" Link "ADCD_v1.2:Inc&AD2.1/Includes/utility/hooks.h/Main" 0}

@EndNode

@Node "FindCollection()" "iffparse.library/FindCollection"

NAME
    FindCollection -- Get a pointer to the current list of collection
                      items.

SYNOPSIS
    ci = FindCollection (iff, type, id)
    d0                   a0    d0   d1

    struct @{"CollectionItem" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 102}      *ci;
    struct @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32}    *iff;
    LONG                    type, id;

FUNCTION
    Returns a pointer to a list of @{"CollectionItem" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 102} structures for each of
    the collection chunks of the given type encountered so far in the
    course of parsing this IFF file.  The items appearing first in the
    list will be the ones encountered most recently.

INPUTS
    iff     - pointer to @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} struct.
    type    - type code to search for.
    id      - identifier code to search for.

RESULT
    ci      - pointer to last collection chunk encountered with
              links to previous ones.

EXAMPLE

NOTES

BUGS

SEE ALSO
    @{"CollectionChunk()" Link "CollectionChunk()"}, @{"CollectionChunks()" Link "CollectionChunks()"}

@EndNode

@Node "FindLocalItem()" "iffparse.library/FindLocalItem"

NAME
    FindLocalItem -- Return a local context item from the context stack.

SYNOPSIS
    lci = FindLocalItem (iff, type, id, ident)
    d0                   a0    d0   d1   d2

    struct @{"LocalContextItem" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 80}     *lci;
    struct @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32}    *iff;
    LONG                    type, id, ident;

FUNCTION
    Searches the context stack of the given @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} struct for a local
    context item which matches the given ident, type and id.  This
    function searches the context stack from the most current context
    backwards, so that the item found (if any) will be the one with
    greatest precedence in the context stack.

INPUTS
    iff     - pointer to @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} struct.
    type    - type code to search for.
    id      - ID code to search for.
    ident   - ident code for the class of context item to search for
              (ex. "exhd" -- exit handler).

RESULT
    lci     - pointer local context item if found, or NULL if nothing
              matched.

EXAMPLE

NOTES

BUGS
    It really should have some sort of wildcarding capability.

SEE ALSO
    @{"StoreLocalItem()" Link "StoreLocalItem()"}

@EndNode

@Node "FindProp()" "iffparse.library/FindProp"

NAME
    FindProp -- Search for a stored property chunk.

SYNOPSIS
    sp = FindProp (iff, type, id)
    d0             a0    d0   d1

    struct @{"StoredProperty" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 92}       *sp;
    struct @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32}    *iff;
    LONG                    type, id;

FUNCTION
    Searches for the stored property which is valid in the given context.
    Property chunks are automatically stored by @{"ParseIFF()" Link "ParseIFF()"} when
    pre-declared by @{"PropChunk()" Link "PropChunk()"} or @{"PropChunks()" Link "PropChunks()"}.  The @{"StoredProperty" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 92}
    struct, if found, contains a pointer to a data buffer containing the
    contents of the stored property.

INPUTS
    iff     - pointer to @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} struct.
    type    - type code for chunk to search for (ex. "ILBM").
    id      - identifier code for chunk to search for (ex. "CMAP").

RESULT
    sp      - pointer to stored property, if found, or NULL if none
              found.

EXAMPLE

NOTES

BUGS

SEE ALSO
    @{"PropChunk()" Link "PropChunk()"}, @{"PropChunks()" Link "PropChunks()"}

@EndNode

@Node "FindPropContext()" "iffparse.library/FindPropContext"

NAME
    FindPropContext -- Get the property context for the current state.

SYNOPSIS
    cn = FindPropContext (iff)
    d0                    a0

    struct @{"ContextNode" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 66}  *cn;
    struct @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32}    *iff;

FUNCTION
    Locates the context node which would be the scoping chunk for
    properties in the current parsing state.  (Huh?)  This is used for
    locating the proper scoping context for property chunks i.e. the
    scope from which a property would apply.  This is usually the FORM
    or LIST with the highest precedence in the context stack.

    If you don't understand this, read the IFF spec a couple more times.

INPUTS
    iff     - pointer to @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} struct.

RESULT
    cn      - @{"ContextNode" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 66} of property scoping chunk.

EXAMPLE

NOTES

BUGS

SEE ALSO
    @{"CurrentChunk()" Link "CurrentChunk()"}, @{"ParentChunk()" Link "ParentChunk()"}, @{"StoreItemInContext()" Link "StoreItemInContext()"}

@EndNode

@Node "FreeIFF()" "iffparse.library/FreeIFF"

NAME
    FreeIFF -- Deallocate an @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} struct.

SYNOPSIS
    FreeIFF (iff)
             a0

    struct @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} *iff;

FUNCTION
    Deallocates all resources associated with this @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} struct.  The
    struct MUST have already been closed with @{"CloseIFF()" Link "CloseIFF()"}.

INPUTS
    iff     - pointer to @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} struct to free.

RESULT

EXAMPLE

NOTES

BUGS

SEE ALSO
    @{"AllocIFF()" Link "AllocIFF()"}, @{"CloseIFF()" Link "CloseIFF()"}

@EndNode

@Node "FreeLocalItem()" "iffparse.library/FreeLocalItem"

NAME
    FreeLocalItem -- Deallocate a local context item structure.

SYNOPSIS
    FreeLocalItem (lci)
                   a0

    struct @{"LocalContextItem" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 80} *lci;

FUNCTION
    Frees the memory for the local context item and any associated user
    memory as allocated with @{"AllocLocalItem" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/iffparse/AllocLocalItem()"}.  User purge vectors should
    call this function after they have freed any other resources
    associated with this item.

    Note that FreeLocalItem() does NOT call the custom purge vector set
    up through SetLocalItemPurge(); all it does is free the local context
    item.  (This implies that your custom purge vector would want to call
    this to ultimately free the LocalContextItem.)  (This description
    still seems muddy; how to clear it up?)

INPUTS
    lci     - pointer to @{"LocalContextItem" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 80} created with @{"AllocLocalItem" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/iffparse/AllocLocalItem()"}.

RESULT

EXAMPLE

NOTES

BUGS

SEE ALSO
    @{"AllocLocalItem()" Link "AllocLocalItem()"}

@EndNode

@Node "GoodID()" "iffparse.library/GoodID"

NAME
    GoodID -- Test if an identifier follows the IFF 85 specification.

SYNOPSIS
    isok = GoodID (id)
     d0            d0

    LONG isok, id;

FUNCTION
    Tests the given longword identifier to see if it meets all the EA IFF
    85 specifications for a chunk ID.  If so, it returns non-zero,
    otherwise 0.

INPUTS
    id      - potential 32 bit identifier.

RESULT
    isok    - non-zero if this is a valid ID, 0 otherwise.

EXAMPLE

NOTES

BUGS

SEE ALSO
    @{"GoodType()" Link "GoodType()"}

@EndNode

@Node "GoodType()" "iffparse.library/GoodType"

NAME
    GoodType -- Test if a type follows the IFF 85 specification.

SYNOPSIS
    isok = GoodType (type)
     d0               d0

    LONG isok, type;

FUNCTION
    Tests the given longword type identifier to see if it meets all the
    EA IFF 85 specifications for a FORM type (requirements for a FORM
    type are more stringent than those for a simple chunk ID).  If it
    complies, GoodType() returns non-zero, otherwise 0.

INPUTS
    type    - potential 32 bit format type identifier.

RESULT
    isok    - non-zero if this is a valid type id, 0 otherwise.

EXAMPLE

NOTES

BUGS

SEE ALSO
    @{"GoodID()" Link "GoodID()"}

@EndNode

@Node "IDtoStr()" "iffparse.library/IDtoStr"

NAME
    IDtoStr -- Convert a longword identifier to a null-terminated string.

SYNOPSIS
    str = IDtoStr (id, buf)
    d0             d0  a0

    STRPTR  str;
    LONG    id;
    STRPTR  buf;

FUNCTION
    Writes the ASCII equivalent of the given longword ID into buf as a
    null-terminated string.

INPUTS
    id      - longword ID.
    buf     - character buffer to accept string (at least 5 chars).

RESULT
    str     - the value of 'buf'.

EXAMPLE

NOTES

BUGS

SEE ALSO

@EndNode

@Node "InitIFF()" "iffparse.library/InitIFF"

NAME
    InitIFF -- Initialize an @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} struct as a user stream.

SYNOPSIS
    InitIFF (iff, flags, streamhook)
             a0    d0        a1

    struct @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} *iff;
    LONG             flags;
    struct @{"Hook" Link "ADCD_v1.2:Inc&AD2.1/Includes/utility/hooks.h/Main" 21}       *streamhook;

FUNCTION
    Initializes an @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} as a general user-defined stream by
    allowing the user to declare a hook that the library will call to
    accomplish the low-level reading, writing, and seeking of the stream.
    Flags are the stream I/O flags for the specified stream; typically a
    combination of the IFFF_?SEEK flags.

    The stream vector is called with the following arguments:

            A0:     pointer to streamhook.
            A2:     pointer to @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} struct.
            A1:     pointer to @{"IFFStreamCmd" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 53} struct.

    The @{"IFFStreamCmd" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 53} packet appears as follows:

            sc_Command:     Contains an IFFCMD_#? value
            sc_Buf:         Pointer to memory buffer
            sc_NBytes:      Number of bytes involved in operation

    The values taken on by sc_Command, and their meaning, are as follows:

    IFFCMD_INIT:
            Prepare your stream for reading.  This is used for certain
            streams that can't be read immediately upon opening, and need
            further preparation.  (The clipboard.device is an example of
            such a stream.)  This operation is allowed to fail;  any
            error code will be returned directly to the client.  sc_Buf
            and sc_NBytes have no meaning here.
    IFFCMD_CLEANUP:
            Terminate the transaction with the associated stream.  This
            is used with streams that can't simply be closed.  (Again,
            the clipboard is an example of such a stream.)  This
            operation is not permitted to fail;  any error returned will
            be ignored (best to return 0, though).  sc_Buf and sc_NBytes
            have no meaning here.
    IFFCMD_READ:
            Read from the stream.  You are to read sc_NBytes from the
            stream and place them in the buffer pointed to by sc_Buf.
            Any (non-zero) error returned will be remapped by the parser
            into IFFERR_READ.
    IFFCMD_WRITE:
            Write to the stream.  You are to write sc_NBytes to the
            stream from the buffer pointed to by sc_Buf.  Any (non-zero)
            error returned will be remapped by the parser into
            IFFERR_WRITE.
    IFFCMD_SEEK:
            Seek on the stream.  You are to perform a seek on the stream
            relative to the current position.  sc_NBytes is signed;
            negative values mean seek backward, positive values mean seek
            forward.  sc_Buf has no meaning here.  Any (non-zero) error
            returned will be remapped by the parser into IFFERR_SEEK.

    All errors are returned in D0.  A return of 0 indicates success.
    UNDER NO CIRCUMSTANCES are you permitted to write to the @{"IFFStreamCmd" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 53}
    structure.

INPUTS
    iff     - pointer to @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} structure to initialize.
    flags   - stream I/O flags for the @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32}.
    hook    - pointer to @{"Hook" Link "ADCD_v1.2:Inc&AD2.1/Includes/utility/hooks.h/Main" 21} structure.

RESULT

EXAMPLE

NOTES

BUGS

SEE ALSO
    @{"utility/hooks.h" Link "ADCD_v1.2:Inc&AD2.1/Includes/utility/hooks.h/Main" 0}

@EndNode

@Node "InitIFFasClip()" "iffparse.library/InitIFFasClip"

NAME
    InitIFFasClip -- Initialize an @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} as a clipboard stream.

SYNOPSIS
    InitIFFasClip (iff)
                   a0

    struct @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} *iff;

FUNCTION
    Initializes the given @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} to be a clipboard stream.  The
    function initializes the stream processing vectors to operate on
    streams of the @{"ClipboardHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 113} type.  The iff_Stream field will still
    need to be initialized to point to a @{"ClipboardHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 113} as returned from
    @{"OpenClipboard()" Link "OpenClipboard()"}.

INPUTS
    iff     - pointer to @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} struct.

RESULT

EXAMPLE

NOTES

BUGS

SEE ALSO
    @{"OpenClipboard()" Link "OpenClipboard()"}

@EndNode

@Node "InitIFFasDOS()" "iffparse.library/InitIFFasDOS"

NAME
    InitIFFasDOS -- Initialize an @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} as a DOS stream.

SYNOPSIS
    InitIFFasDOS (iff)
                  a0

    struct @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} *iff;

FUNCTION
    The function initializes the given @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} to operate on DOS
    streams.  The iff_Stream field will need to be initialized as a BPTR
    returned from the DOS function @{"Open()" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/dos/Open()"}.

INPUTS
    iff     - pointer to @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} struct.

RESULT

EXAMPLE

NOTES

BUGS

SEE ALSO

@EndNode

@Node "LocalItemData()" "iffparse.library/LocalItemData"

NAME
    LocalItemData -- Get pointer to user data for local context item.

SYNOPSIS
    data = LocalItemData (lci)
     d0                   a0

    UBYTE                   *data;
    struct @{"LocalContextItem" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 80}     *lci;

FUNCTION
    Returns pointer to the user data associated with the given local
    context item.  The size of the data area depends on the "usize"
    argument used when allocating this item.  If the pointer to the item
    given (lci) is NULL, the function also returns NULL.

INPUTS
    lci     - pointer to local context item or NULL.

RESULT
    data    - pointer to user data area or NULL if lci is NULL.

EXAMPLE

NOTES

BUGS
    Currently, there is no way to determine the size of the user data
    area; you have to 'know'.

SEE ALSO
    @{"AllocLocalItem()" Link "AllocLocalItem()"}, @{"FreeLocalItem()" Link "FreeLocalItem()"}

@EndNode

@Node "OpenClipboard()" "iffparse.library/OpenClipboard"

NAME
    OpenClipboard -- Create a handle on a clipboard unit.

SYNOPSIS
    ch = OpenClipboard (unit)
    d0                   d0

    struct @{"ClipboardHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 113}     *ch;
    LONG                    unit;

FUNCTION
    Opens the clipboard.device and opens a stream for the specified unit
    (usually PRIMARY_CLIP).  This handle structure will be used as the
    clipboard stream for IFFHandles initialized as clipboard streams by
    @{"InitIFFasClip()" Link "InitIFFasClip()"}.

INPUTS
    unit    - clipboard unit number (usually PRIMARY_CLIP).

RESULT
    ch      - pointer to @{"ClipboardHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 113} structure or NULL if
              unsuccessful.

EXAMPLE

NOTES

BUGS

SEE ALSO
    @{"InitIFFasClip()" Link "InitIFFasClip()"}, @{"CloseClipboard()" Link "CloseClipboard()"}

@EndNode

@Node "OpenIFF()" "iffparse.library/OpenIFF"

NAME
    OpenIFF -- Prepare an @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} to read or write a new IFF stream.

SYNOPSIS
    error = OpenIFF (iff, rwmode)
     d0              a0     d0

    LONG             error;
    struct @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} *iff;
    LONG             rwmode;

FUNCTION
    Initializes an @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} struct for a new read or write.  The
    direction of the I/O is given by the value of rwmode, which can be
    either IFFF_READ or IFFF_WRITE.

    As part of its initialization procedure, OpenIFF() calls the client-
    supplied stream hook vector.  The @{"IFFStreamCmd" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 53} packet will contain
    the following:

            sc_Command:     IFFCMD_INIT
            sc_Buf:         (Not applicable)
            sc_NBytes:      (Not applicable)

    This operation is permitted to fail.  DO NOT write to this structure.

INPUTS
    iff     - pointer to @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} struct.
    rwmode  - IFFF_READ or IFFF_WRITE

RESULT
    error   - contains an error code or 0 if successful.

EXAMPLE

NOTES

BUGS

SEE ALSO
    @{"CloseIFF()" Link "CloseIFF()"}, @{"InitIFF()" Link "InitIFF()"}

@EndNode

@Node "ParentChunk()" "iffparse.library/ParentChunk"

NAME
    ParentChunk -- Get the nesting context node for the given chunk.

SYNOPSIS
    parent = ParentChunk (cn)
      d0                  a0

    struct @{"ContextNode" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 66} *parent, *cn;

FUNCTION
    Returns a context node for the chunk containing the chunk for the
    given context node.  This function effectively moves down the context
    stack into previously pushed contexts.  For example, to get a
    @{"ContextNode" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 66} pointer for the enclosing FORM chunk while reading a data
    chunk, use: ParentChunk (CurrentChunk (iff)) to find this pointer.
    The @{"ContextNode" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 66} structure contains information on the type of chunk
    and its size.

INPUTS
    cn      - pointer to a context node.

RESULT
    parent  - pointer to the enclosing context node or NULL if none.

EXAMPLE

NOTES

BUGS

SEE ALSO
    @{"CurrentChunk()" Link "CurrentChunk()"}

@EndNode

@Node "ParseIFF()" "iffparse.library/ParseIFF"

NAME
    ParseIFF -- Parse an IFF file from an @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} struct stream.

SYNOPSIS
    error = ParseIFF (iff, control)
     d0               a0     d0

    LONG             error;
    struct @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} *iff;
    LONG             control;

FUNCTION
    This is the biggie.

    Traverses a file opened for read by pushing chunks onto the context
    stack and popping them off directed by the generic syntax of IFF
    files.  As it pushes each new chunk, it searches the context stack
    for handlers to apply to chunks of that type.  If it finds an entry
    handler it will invoke it just after entering the chunk.  If it finds
    an exit handler it will invoke it just before leaving the chunk.
    Standard handlers include entry handlers for pre-declared
    property chunks and collection chunks and entry and exit handlers for
    for stop chunks - that is, chunks which will cause the ParseIFF()
    function to return control to the client.  Client programs can also
    provide their own custom handlers.

    The control flag can have three values:

    IFFPARSE_SCAN:
            In this normal mode, ParseIFF() will only return control to
            the caller when either:
                    1) an error is encountered,
                    2) a stop chunk is encountered, or a user handler
                       returns the special IFF_RETURN2CLIENT code, or
                    3) the end of the logical file is reached, in which
                       case IFFERR_EOF is returned.

            ParseIFF() will continue pushing and popping chunks until one
            of these conditions occurs.  If ParseIFF() is called again
            after returning, it will continue to parse the file where it
            left off.

    IFFPARSE_STEP and _RAWSTEP:
            In these two modes, ParseIFF() will return control to the
            caller after every step in the parse, specifically, after
            each push of a context node and just before each pop.  If
            returning just before a pop, ParseIFF() will return
            IFFERR_EOC, which is not an error, per se, but is just an
            indication that the most recent context is ending.  In STEP
            mode, ParseIFF() will invoke the handlers for chunks, if
            any, before returning.  In RAWSTEP mode, ParseIFF() will not
            invoke any handlers and will return right away.  In both
            cases the function can be called multiple times to step
            through the parsing of the IFF file.

INPUTS
    iff     - pointer to @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} struct.
    control - control code (IFFPARSE_SCAN, _STEP or _RAWSTEP).

RESULT
    error   - 0 or IFFERR_#? value or return value from user handler.

EXAMPLE

NOTES

BUGS

SEE ALSO
    @{"PushChunk()" Link "PushChunk()"}, @{"PopChunk()" Link "PopChunk()"}, @{"EntryHandler()" Link "EntryHandler()"}, @{"ExitHandler()" Link "ExitHandler()"},
    PropChunk[s](), CollectionChunk[s](), @{"StopChunk()" Link "StopChunk()"}, @{"StopOnExit()" Link "StopOnExit()"}

@EndNode

@Node "PopChunk()" "iffparse.library/PopChunk"

NAME
    PopChunk -- Pop top context node off context stack.

SYNOPSIS
    error = PopChunk (iff)
     d0               a0

    LONG             error;
    struct @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} *iff;

FUNCTION
    Pops top context chunk and frees all associated local context items.
    The function is normally called only for writing files and signals
    the end of a chunk.

INPUTS
    iff     - pointer to @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} struct.

RESULT
    error   - 0 if successful or an IFFERR_#? error code if not
              successful.

EXAMPLE

NOTES

BUGS

SEE ALSO
    @{"PushChunk()" Link "PushChunk()"}

@EndNode

@Node "PropChunk()" "iffparse.library/PropChunk"

NAME
    PropChunk -- Specify a property chunk to store.

SYNOPSIS
    error = PropChunk (iff, type, id)
     d0                a0    d0   d1

    LONG             error;
    struct @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} *iff;
    LONG             type;
    LONG             id;

FUNCTION
    Installs an entry handler for chunks with the given type and ID so
    that the contents of those chunks will be stored as they are
    encountered.  The storage of these chunks follows the property chunk
    scoping rules for IFF files so that at any given point, a stored
    property chunk returned by @{"FindProp()" Link "FindProp()"} will be the valid property for
    the current context.

INPUTS
    iff     - pointer to @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} struct (does not need to be open).
    type    - type code for the chunk to declare (ex. "ILBM").
    id      - identifier for the chunk to declare (ex. "CMAP").

RESULT
    error   - 0 if successful or an IFFERR_#? error code if not
              successful.

EXAMPLE

NOTES

BUGS

SEE ALSO
    @{"PropChunks()" Link "PropChunks()"}, @{"FindProp()" Link "FindProp()"}, @{"CollectionChunk()" Link "CollectionChunk()"}

@EndNode

@Node "PropChunks()" "iffparse.library/PropChunks"

NAME
    PropChunks -- Declare many property chunks at once.

SYNOPSIS
    error = PropChunks (iff, list, n)
     d0                 a0    a1  d0

    LONG             error;
    struct @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} *iff;
    LONG             *list;
    LONG             n;

FUNCTION
    Declares multiple property chunks from a list.  The list argument is
    a pointer to an array of long words arranged in pairs, and has the
    following format:

            TYPE1, ID1, TYPE2, ID2, ..., TYPEn, IDn

    The argument n is the number of pairs.  PropChunks() just calls
    @{"PropChunk()" Link "PropChunk()"} n times.

INPUTS
    iff     - pointer to @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} struct.
    list    - pointer to array of longword chunk types and identifiers.
    n       - number of chunks to declare.

RESULT
    error   - 0 if successful or an IFFERR_#? error code if not
              successful.

EXAMPLE

NOTES

BUGS

SEE ALSO
    @{"PropChunk()" Link "PropChunk()"}

@EndNode

@Node "PushChunk()" "iffparse.library/PushChunk"

NAME
    PushChunk -- Push a new context node on the context stack.

SYNOPSIS
    error = PushChunk (iff, type, id, size)
     d0                a0    d0   d1   d2

    LONG             error;
    struct @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} *iff;
    LONG             type, id, size;

FUNCTION
    Pushes a new context node on the context stack by reading it from the
    stream if this is a read file, or by creating it from the passed
    parameters if this is a write file.  Normally this function is only
    called in write mode, where the type and id codes specify the new
    chunk to create.  If this is a leaf chunk, i.e. a local chunk inside
    a FORM or PROP chunk, then the type argument is ignored.  If the size
    is specified then the chunk writing functions will enforce this size.
    If the size is given as IFFSIZE_UNKNOWN, the chunk will expand to
    accommodate whatever is written into it.

INPUTS
    iff     - pointer to @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} struct.
    type    - chunk type specifier (ex. ILBM) (ignored for read mode or
              leaf chunks).
    id      - chunk id specifier (ex. CMAP) (ignored for read mode).
    size    - size of the chunk to create or IFFSIZE_UNKNOWN (ignored for
              read mode).

RESULT
    error   - 0 if successful or an IFFERR_#? error code if not
              successful.

EXAMPLE

NOTES

BUGS

SEE ALSO
    @{"PopChunk()" Link "PopChunk()"}, @{"WriteChunkRecords()" Link "WriteChunkRecords()"}, @{"WriteChunkBytes()" Link "WriteChunkBytes()"}

@EndNode

@Node "ReadChunkBytes()" "iffparse.library/ReadChunkBytes"

NAME
    ReadChunkBytes -- Read bytes from the current chunk into a buffer.

SYNOPSIS
    actual = ReadChunkBytes (iff, buf, size)
      d0                     a0   a1    d0

    LONG             actual;
    struct @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} *iff;
    UBYTE            *buf;
    LONG             size;

FUNCTION
    Reads the @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} stream into the buffer for the specified number
    of bytes.  Reads are limited to the size of the current chunk and
    attempts to read past the end of the chunk will truncate.  Function
    returns positive number of bytes read or a negative error code.

INPUTS
    iff     - pointer to @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} struct.
    buf     - pointer to buffer area to receive data.
    size    - number of bytes to read.

RESULT
    actual  - (positive) number of bytes read if successful or a
              (negative) IFFERR_#? error code if not successful.

EXAMPLE

NOTES

BUGS

SEE ALSO
    @{"ReadChunkRecords()" Link "ReadChunkRecords()"}, @{"ParseIFF()" Link "ParseIFF()"}, @{"WriteChunkBytes()" Link "WriteChunkBytes()"}

@EndNode

@Node "ReadChunkRecords()" "iffparse.library/ReadChunkRecords"

NAME
    ReadChunkRecords -- Read record elements from the current chunk into
                        a buffer.

SYNOPSIS
    actual = ReadChunkRecords (iff, buf, recsize, numrec)
      d0                       a0   a1     d0       d1

    LONG             actual;
    struct @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} *iff;
    UBYTE            *buf;
    LONG             recsize, numrec;

FUNCTION
    Reads records from the current chunk into buffer.  Truncates attempts
    to read past end of chunk (only whole records are read; remaining
    bytes that are not of a whole record size are left unread and
    available for @{"ReadChunkBytes()" Link "ReadChunkBytes()"}).

INPUTS
    iff     - pointer to @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} struct.
    buf     - pointer to buffer area to receive data.
    recsize - size of data records to read.
    numrec  - number of data records to read.

RESULT
    actual  - (positive) number of whole records read if successful or a
              (negative) IFFERR_#? error code if not successful.

EXAMPLE

NOTES

BUGS

SEE ALSO
    @{"ReadChunkBytes()" Link "ReadChunkBytes()"}, @{"ParseIFF()" Link "ParseIFF()"}, @{"WriteChunkRecords()" Link "WriteChunkRecords()"}

@EndNode

@Node "SetLocalItemPurge()" "iffparse.library/SetLocalItemPurge"

NAME
    SetLocalItemPurge -- Set purge vector for a local context item.

SYNOPSIS
    SetLocalItemPurge (item, purgehook)
                        a0      a1

    struct @{"LocalContextItem" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 80}     *item;
    struct @{"Hook" Link "ADCD_v1.2:Inc&AD2.1/Includes/utility/hooks.h/Main" 21}              *purgehook;

FUNCTION
    Sets a local context item to use a client-supplied cleanup (purge)
    vector for disposal when its context is popped.  The purge vector
    will be called when the @{"ContextNode" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 66} containing this local item is
    popped off the context stack and is about to be deleted itself.  If
    the purge vector has not been set, the parser will use @{"FreeLocalItem" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/iffparse/FreeLocalItem()"}
    to delete the item, but if this function is used to set the purge
    vector, the supplied vector will be called with the following
    arguments:

            A0:     pointer to purgehook.
            A2:     pointer to @{"LocalContextItem" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 80} to be freed.
            A1:     pointer to a LONG containing the value
                    IFFCMD_PURGELCI.

    The user purge vector is then responsible for calling @{"FreeLocalItem()" Link "FreeLocalItem()"}
    as part of its own cleanup.  Although the purge vector can return a
    value, it will be ignored -- purge vectors must always work (best to
    return 0, though).

INPUTS
    item      - pointer to local context item.
    purgehook - pointer to a @{"Hook" Link "ADCD_v1.2:Inc&AD2.1/Includes/utility/hooks.h/Main" 21} structure.

RESULT

EXAMPLE

NOTES

BUGS

SEE ALSO
    @{"AllocLocalItem()" Link "AllocLocalItem()"}, @{"FreeLocalItem()" Link "FreeLocalItem()"}, @{"utility/hooks.h" Link "ADCD_v1.2:Inc&AD2.1/Includes/utility/hooks.h/Main" 0}

@EndNode

@Node "StopChunk()" "iffparse.library/StopChunk"

NAME
    StopChunk -- Declare a chunk which should cause @{"ParseIFF" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/iffparse/ParseIFF()"} to return.

SYNOPSIS
    error = StopChunk (iff, type, id)
     d0                a0    d0   d1

    LONG             error;
    struct @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} *iff;
    LONG             type;
    LONG             id;

FUNCTION
    Installs an entry handler for the specified chunk which will cause
    the @{"ParseIFF()" Link "ParseIFF()"} function to return control to the caller when this
    chunk is encountered.  This is only of value when @{"ParseIFF()" Link "ParseIFF()"} is
    called with the IFFPARSE_SCAN control code.

INPUTS
    iff     - pointer to @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} struct (need not be open).
    type    - type code for chunk to declare (ex. "ILBM").
    id      - identifier for chunk to declare (ex. "BODY").

RESULT
    error   - 0 if successful or an IFFERR_#? error code if not
              successful.

EXAMPLE

NOTES

BUGS

SEE ALSO
    @{"StopChunks()" Link "StopChunks()"}, @{"ParseIFF()" Link "ParseIFF()"}

@EndNode

@Node "StopChunks()" "iffparse.library/StopChunks"

NAME
    StopChunks -- Declare many stop chunks at once.

SYNOPSIS
    error = StopChunks (iff, list, n)
     d0                 a0    a1  d0

    LONG             error;
    struct @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} *iff;
    LONG             *list;
    LONG             n;

FUNCTION
    (is to @{"StopChunk()" Link "StopChunk()"} as @{"PropChunks()" Link "PropChunks()"} is to PropChunk().)

INPUTS
    iff     - pointer to @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} struct.
    list    - pointer to array of longword chunk types and identifiers.
    n       - number of chunks to declare.

RESULT
    error   - 0 if successful or an IFFERR_#? error code if not
              successful.

EXAMPLE

NOTES

BUGS

SEE ALSO
    @{"StopChunk()" Link "StopChunk()"}

@EndNode

@Node "StopOnExit()" "iffparse.library/StopOnExit"

NAME
    StopOnExit -- Declare a stop condition for exiting a chunk.

SYNOPSIS
    error = StopOnExit (iff, type, id)
     d0                 a0    d0   d1

    LONG             error;
    struct @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} *iff;
    LONG             type;
    LONG             id;

FUNCTION
    Installs an exit handler for the specified chunk which will cause the
    @{"ParseIFF()" Link "ParseIFF()"} function to return control to the caller when this chunk
    is exhausted.  @{"ParseIFF()" Link "ParseIFF()"} will return IFFERR_EOC when the declared
    chunk is about to be popped.  This is only of value when @{"ParseIFF()" Link "ParseIFF()"}
    is called with the IFFPARSE_SCAN control code.

INPUTS
    iff     - pointer to @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} struct (need not be open).
    type    - type code for chunk to declare (ex. "ILBM").
    id      - identifier for chunk to declare (ex. "BODY").

RESULT
    error   - 0 if successful or an IFFERR_#? error code if not
              successful.

EXAMPLE

NOTES

BUGS

SEE ALSO
    @{"ParseIFF()" Link "ParseIFF()"}

@EndNode

@Node "StoreItemInContext()" "iffparse.library/StoreItemInContext"

NAME
    StoreItemInContext -- Store local context item in given context node.

SYNOPSIS
    StoreItemInContext (iff, item, cn)
                        a0    a1   a2

    struct @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32}    *iff;
    struct @{"LocalContextItem" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 80}     *item;
    struct @{"ContextNode" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 66}  *cn;

FUNCTION
    Adds the @{"LocalContextItem" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 80} to the list of items for the given context
    node.  If an LCI with the same Type, ID, and Ident is already
    present in the @{"ContextNode" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 66}, it will be purged and replaced with the
    new one.  This is a raw form of @{"StoreLocalItem" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/iffparse/StoreLocalItem()"}.

INPUTS
    iff     - pointer to @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} struct for this context.
    item    - pointer to a @{"LocalContextItem" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 80} to be stored.
    cn      - pointer to context node in which to store item.

RESULT

EXAMPLE

NOTES

BUGS

SEE ALSO
    @{"StoreLocalItem()" Link "StoreLocalItem()"}

@EndNode

@Node "StoreLocalItem()" "iffparse.library/StoreLocalItem"

NAME
    StoreLocalItem -- Insert a local context item into the context stack.

SYNOPSIS
    error = StoreLocalItem (iff, item, position)
     d0                     a0    a1      d0

    LONG                    error;
    struct @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32}    *iff;
    struct @{"LocalContextItem" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 80}     *item;
    LONG                    position;

FUNCTION
    Adds the local context item to the list of items for one of the
    context nodes on the context stack and purges any other item in the
    same context with the same ident, type and id.  The position argument
    determines where in the stack to add the item:

    IFFSLI_ROOT:
            Add item to list at root (default) stack position.
    IFFSLI_TOP:
            Add item to the top (current) context node.
    IFFSLI_PROP:
            Add element in top property context.  Top property context is
            either the top FORM chunk, or the top LIST chunk, whichever
            is closer to the top of the stack.

    Items added to the root context, or added to the top context before
    the @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} has been opened or after it has been closed, are put in
    the default context.  That is, they will be the local items found
    only after all other context nodes have been searched.  Items in the
    default context are also immune to being purged until the @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32}
    struct itself is deleted with @{"FreeIFF()" Link "FreeIFF()"}.  This means that handlers
    installed in the root context will still be there after an @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32}
    struct has been opened and closed.  (Note that this implies that
    items stored in a higher context will be deleted when that context
    ends.)

INPUTS
    iff     - pointer to @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} struct.
    item    - pointer to @{"LocalContextItem" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 80} struct to insert.
    position- where to store the item (IFFSLI_ROOT, _TOP or _PROP).

RESULT
    error   - 0 if successful or an IFFERR_#? error code if not
              successful.

EXAMPLE

NOTES

BUGS

SEE ALSO
    @{"FindLocalItem()" Link "FindLocalItem()"}, @{"StoreItemInContext()" Link "StoreItemInContext()"}, @{"EntryHandler()" Link "EntryHandler()"}, @{"ExitHandler()" Link "ExitHandler()"}

@EndNode

@Node "WriteChunkBytes()" "iffparse.library/WriteChunkBytes"

NAME
    WriteChunkBytes -- Write data from a buffer into the current chunk.

SYNOPSIS
    error = WriteChunkBytes (iff, buf, size)
     d0                      a0   a1    d0

    LONG             error;
    struct @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} *iff;
    UBYTE            *buf;
    LONG             size;

FUNCTION
    Writes "size" bytes from the specified buffer into the current chunk.
    If the current chunk was pushed with IFFSIZE_UNKNOWN, the size of the
    chunk gets increased by the size of the buffer written.  If the size
    was specified for this chunk, attempts to write past the end of the
    chunk will be truncated.

INPUTS
    iff     - pointer to @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} struct.
    buf     - pointer to buffer area with bytes to be written.
    size    - number of bytes to write.

RESULT
    error   - (positive) number of bytes written if successful or a
              (negative) IFFERR_#? error code if not successful.

EXAMPLE

NOTES

BUGS

SEE ALSO
    @{"PushChunk()" Link "PushChunk()"}, @{"PopChunk()" Link "PopChunk()"}, @{"WriteChunkRecords()" Link "WriteChunkRecords()"}

@EndNode

@Node "WriteChunkRecords()" "iffparse.library/WriteChunkRecords"

NAME
    WriteChunkRecords -- Write records from a buffer to the current
                         chunk.

SYNOPSIS
    error = WriteChunkRecords (iff, buf, recsize, numrec)
     d0                        a0   a1     d0      d1

    LONG             error;
    struct @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} *iff;
    UBYTE            *buf;
    LONG             recsize, numrec;

FUNCTION
    Writes record elements from the buffer into the top chunk.  This
    function operates much like @{"ReadChunkBytes()" Link "ReadChunkBytes()"}.

INPUTS
    iff     - pointer to @{"IFFHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/iffparse.h/Main" 32} struct.
    buf     - pointer to buffer area containing data.
    recsize - size of data records to write.
    numrec  - number of data records to write.

RESULT
    error   - (positive) number of whole records written if successful
              or a (negative) IFFERR_#? error code if not successful.

EXAMPLE

NOTES

BUGS

SEE ALSO
    @{"WriteChunkBytes()" Link "WriteChunkBytes()"}

@EndNode

