[Contents] [Index] [Help] [Retrace] [Browse <] [Browse >]


NAME
    EntryHandler -- Add an entry handler to the IFFHandle context.

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

    LONG             error;
    struct IFFHandle *iff;
    LONG             type, id, position;
    struct Hook     *hook;
    APTR             object;

FUNCTION
    Installs an entry handler vector for a specific type of chunk into
    the context for the given IFFHandle struct.  Type and id are the
    longword identifiers for the chunk to handle.  The hook is a client-
    supplied standard 2.0 Hook 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().  The handler will be called (through the hook)
    with the following arguments:

            A0:     the Hook 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() will continue
                            through the file.
    IFF_RETURN2CLIENT:      ParseIFF() will stop and return the value 0.
                            (StopChunk() is internally implemented using
                            this return value.)
    Any other value:        ParseIFF() will stop and return the value
                            you supplied.  This is how errors should be
                            returned.

INPUTS
    iff     - pointer to IFFHandle 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 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(), StoreLocalItem(), StoreItemInContext(),
    utility/hooks.h