![[Contents]](../images/toc_d.gif)
![[Index]](../images/index_d.gif)
![[Help]](../images/help_d.gif)
![[Retrace]](../images/retrace_d.gif)
![[browse <]](../images/prev.gif)
![[Browse >]](../images/next.gif)
TABLE OF CONTENTS
HookEntry
iffparse.library/AllocIFF
iffparse.library/AllocLocalItem
iffparse.library/CloseClipboard
iffparse.library/CloseIFF
iffparse.library/CollectionChunk
iffparse.library/CollectionChunks
iffparse.library/CurrentChunk
iffparse.library/EntryHandler
iffparse.library/ExitHandler
iffparse.library/FindCollection
iffparse.library/FindLocalItem
iffparse.library/FindProp
iffparse.library/FindPropContext
iffparse.library/FreeIFF
iffparse.library/FreeLocalItem
iffparse.library/GoodID
iffparse.library/GoodType
iffparse.library/IDtoStr
iffparse.library/InitIFF
iffparse.library/InitIFFasClip
iffparse.library/InitIFFasDOS
iffparse.library/LocalItemData
iffparse.library/OpenClipboard
iffparse.library/OpenIFF
iffparse.library/ParentChunk
iffparse.library/ParseIFF
iffparse.library/PopChunk
iffparse.library/PropChunk
iffparse.library/PropChunks
iffparse.library/PushChunk
iffparse.library/ReadChunkBytes
iffparse.library/ReadChunkRecords
iffparse.library/SetLocalItemPurge
iffparse.library/StopChunk
iffparse.library/StopChunks
iffparse.library/StopOnExit
iffparse.library/StoreItemInContext
iffparse.library/StoreLocalItem
iffparse.library/WriteChunkBytes
iffparse.library/WriteChunkRecords
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(), ExitHandler(), InitIFF(), SetLocalItemPurge(),
utility/hooks.h (A must-read; LOTS of details in there)
iffparse.library/AllocIFF iffparse.library/AllocIFF
NAME
AllocIFF -- Create a new IFFHandle structure.
SYNOPSIS
iff = AllocIFF ()
d0
struct IFFHandle *iff;
FUNCTION
Allocates a new IFFHandle structure and initializes the basic values.
This function is the only supported way to create an IFFHandle
structure since there are private fields that need to be initialized.
INPUTS
RESULT
iff - pointer to IFFHandle structure or NULL if the allocation
failed.
EXAMPLE
NOTES
BUGS
SEE ALSO
FreeIFF()
iffparse.library/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 *item;
LONG type, id, ident, usize;
FUNCTION
Allocates and initializes a LocalContextItem 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 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 or NULL if the
allocation failed.
EXAMPLE
NOTES
BUGS
SEE ALSO
FreeLocalItem(), LocalItemData(), StoreLocalItem(),
StoreItemInContext(), SetLocalItemPurge()
iffparse.library/CloseClipboard iffparse.library/CloseClipboard
NAME
CloseClipboard -- Close and free an open ClipboardHandle.
SYNOPSIS
CloseClipboard (clip)
a0
struct ClipboardHandle *clip;
FUNCTION
Closes the clipboard.device and frees the ClipboardHandle structure.
INPUTS
clip - pointer to ClipboardHandle struct created with
OpenClipboard.
RESULT
EXAMPLE
NOTES
BUGS
SEE ALSO
OpenClipboard(), InitIFFasClip()
iffparse.library/CloseIFF iffparse.library/CloseIFF
NAME
CloseIFF -- Close an IFF context.
SYNOPSIS
CloseIFF (iff)
a0
struct IFFHandle *iff;
FUNCTION
Completes an IFF read or write operation by closing the IFF context
established for this IFFHandle struct. The IFFHandle struct itself
is left ready for re-use and a new context can be opened with
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 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 struct previously opened with
OpenIFF().
RESULT
EXAMPLE
NOTES
BUGS
SEE ALSO
OpenIFF(), InitIFF()
iffparse.library/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 *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() except that more than one
chunk of this type can be stored in lists which can be returned by
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 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(), FindCollection(), PropChunk()
iffparse.library/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 *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() n times.
INPUTS
iff - pointer to IFFHandle 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()
iffparse.library/CurrentChunk iffparse.library/CurrentChunk
NAME
CurrentChunk -- Get context node for current chunk.
SYNOPSIS
top = CurrentChunk (iff)
d0 a0
struct ContextNode *top;
struct IFFHandle *iff;
FUNCTION
Returns top context node for the given IFFHandle 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 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 struct.
RESULT
top - pointer to top context node or NULL if none.
EXAMPLE
NOTES
BUGS
SEE ALSO
PushChunk(), PopChunk(), ParseIFF(), ParentChunk()
iffparse.library/EntryHandler iffparse.library/EntryHandler
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
iffparse.library/ExitHandler iffparse.library/ExitHandler
NAME
ExitHandler -- Add an exit handler to the IFFHandle context.
SYNOPSIS
error = ExitHandler (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 exit 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
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(). 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_EXIT.
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 - identifier 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
EntryHandler(), StoreLocalItem(), StoreItemInContext(),
utility/hooks.h
iffparse.library/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 *ci;
struct IFFHandle *iff;
LONG type, id;
FUNCTION
Returns a pointer to a list of CollectionItem 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 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(), CollectionChunks()
iffparse.library/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 *lci;
struct IFFHandle *iff;
LONG type, id, ident;
FUNCTION
Searches the context stack of the given IFFHandle 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 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()
iffparse.library/FindProp iffparse.library/FindProp
NAME
FindProp -- Search for a stored property chunk.
SYNOPSIS
sp = FindProp (iff, type, id)
d0 a0 d0 d1
struct StoredProperty *sp;
struct IFFHandle *iff;
LONG type, id;
FUNCTION
Searches for the stored property which is valid in the given context.
Property chunks are automatically stored by ParseIFF() when
pre-declared by PropChunk() or PropChunks(). The StoredProperty
struct, if found, contains a pointer to a data buffer containing the
contents of the stored property.
INPUTS
iff - pointer to IFFHandle 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(), PropChunks()
iffparse.library/FindPropContext iffparse.library/FindPropContext
NAME
FindPropContext -- Get the property context for the current state.
SYNOPSIS
cn = FindPropContext (iff)
d0 a0
struct ContextNode *cn;
struct IFFHandle *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 struct.
RESULT
cn - ContextNode of property scoping chunk.
EXAMPLE
NOTES
BUGS
SEE ALSO
CurrentChunk(), ParentChunk(), StoreItemInContext()
iffparse.library/FreeIFF iffparse.library/FreeIFF
NAME
FreeIFF -- Deallocate an IFFHandle struct.
SYNOPSIS
FreeIFF (iff)
a0
struct IFFHandle *iff;
FUNCTION
Deallocates all resources associated with this IFFHandle struct. The
struct MUST have already been closed with CloseIFF().
INPUTS
iff - pointer to IFFHandle struct to free.
RESULT
EXAMPLE
NOTES
BUGS
SEE ALSO
AllocIFF(), CloseIFF()
iffparse.library/FreeLocalItem iffparse.library/FreeLocalItem
NAME
FreeLocalItem -- Deallocate a local context item structure.
SYNOPSIS
FreeLocalItem (lci)
a0
struct LocalContextItem *lci;
FUNCTION
Frees the memory for the local context item and any associated user
memory as allocated with 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 created with AllocLocalItem.
RESULT
EXAMPLE
NOTES
BUGS
SEE ALSO
AllocLocalItem()
iffparse.library/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()
iffparse.library/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()
iffparse.library/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
iffparse.library/InitIFF iffparse.library/InitIFF
NAME
InitIFF -- Initialize an IFFHandle struct as a user stream.
SYNOPSIS
InitIFF (iff, flags, streamhook)
a0 d0 a1
struct IFFHandle *iff;
LONG flags;
struct Hook *streamhook;
FUNCTION
Initializes an IFFHandle 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 struct.
A1: pointer to IFFStreamCmd struct.
The IFFStreamCmd 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
structure.
INPUTS
iff - pointer to IFFHandle structure to initialize.
flags - stream I/O flags for the IFFHandle.
hook - pointer to Hook structure.
RESULT
EXAMPLE
NOTES
BUGS
SEE ALSO
utility/hooks.h
iffparse.library/InitIFFasClip iffparse.library/InitIFFasClip
NAME
InitIFFasClip -- Initialize an IFFHandle as a clipboard stream.
SYNOPSIS
InitIFFasClip (iff)
a0
struct IFFHandle *iff;
FUNCTION
Initializes the given IFFHandle to be a clipboard stream. The
function initializes the stream processing vectors to operate on
streams of the ClipboardHandle type. The iff_Stream field will still
need to be initialized to point to a ClipboardHandle as returned from
OpenClipboard().
INPUTS
iff - pointer to IFFHandle struct.
RESULT
EXAMPLE
NOTES
BUGS
SEE ALSO
OpenClipboard()
iffparse.library/InitIFFasDOS iffparse.library/InitIFFasDOS
NAME
InitIFFasDOS -- Initialize an IFFHandle as a DOS stream.
SYNOPSIS
InitIFFasDOS (iff)
a0
struct IFFHandle *iff;
FUNCTION
The function initializes the given IFFHandle to operate on DOS
streams. The iff_Stream field will need to be initialized as a BPTR
returned from the DOS function Open().
INPUTS
iff - pointer to IFFHandle struct.
RESULT
EXAMPLE
NOTES
BUGS
SEE ALSO
iffparse.library/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 *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(), FreeLocalItem()
iffparse.library/OpenClipboard iffparse.library/OpenClipboard
NAME
OpenClipboard -- Create a handle on a clipboard unit.
SYNOPSIS
ch = OpenClipboard (unit)
d0 d0
struct ClipboardHandle *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().
INPUTS
unit - clipboard unit number (usually PRIMARY_CLIP).
RESULT
ch - pointer to ClipboardHandle structure or NULL if
unsuccessful.
EXAMPLE
NOTES
BUGS
SEE ALSO
InitIFFasClip(), CloseClipboard()
iffparse.library/OpenIFF iffparse.library/OpenIFF
NAME
OpenIFF -- Prepare an IFFHandle to read or write a new IFF stream.
SYNOPSIS
error = OpenIFF (iff, rwmode)
d0 a0 d0
LONG error;
struct IFFHandle *iff;
LONG rwmode;
FUNCTION
Initializes an IFFHandle 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 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 struct.
rwmode - IFFF_READ or IFFF_WRITE
RESULT
error - contains an error code or 0 if successful.
EXAMPLE
NOTES
BUGS
SEE ALSO
CloseIFF(), InitIFF()
iffparse.library/ParentChunk iffparse.library/ParentChunk
NAME
ParentChunk -- Get the nesting context node for the given chunk.
SYNOPSIS
parent = ParentChunk (cn)
d0 a0
struct ContextNode *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 pointer for the enclosing FORM chunk while reading a data
chunk, use: ParentChunk (CurrentChunk (iff)) to find this pointer.
The ContextNode 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()
iffparse.library/ParseIFF iffparse.library/ParseIFF
NAME
ParseIFF -- Parse an IFF file from an IFFHandle struct stream.
SYNOPSIS
error = ParseIFF (iff, control)
d0 a0 d0
LONG error;
struct IFFHandle *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 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(), PopChunk(), EntryHandler(), ExitHandler(),
PropChunk[s](), CollectionChunk[s](), StopChunk(), StopOnExit()
iffparse.library/PopChunk iffparse.library/PopChunk
NAME
PopChunk -- Pop top context node off context stack.
SYNOPSIS
error = PopChunk (iff)
d0 a0
LONG error;
struct IFFHandle *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 struct.
RESULT
error - 0 if successful or an IFFERR_#? error code if not
successful.
EXAMPLE
NOTES
BUGS
SEE ALSO
PushChunk()
iffparse.library/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 *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() will be the valid property for
the current context.
INPUTS
iff - pointer to IFFHandle 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(), FindProp(), CollectionChunk()
iffparse.library/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 *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() n times.
INPUTS
iff - pointer to IFFHandle 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()
iffparse.library/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 *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 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(), WriteChunkRecords(), WriteChunkBytes()
iffparse.library/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 *iff;
UBYTE *buf;
LONG size;
FUNCTION
Reads the IFFHandle 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 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(), ParseIFF(), WriteChunkBytes()
iffparse.library/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 *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()).
INPUTS
iff - pointer to IFFHandle 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(), ParseIFF(), WriteChunkRecords()
iffparse.library/SetLocalItemPurge iffparse.library/SetLocalItemPurge
NAME
SetLocalItemPurge -- Set purge vector for a local context item.
SYNOPSIS
SetLocalItemPurge (item, purgehook)
a0 a1
struct LocalContextItem *item;
struct Hook *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 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
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 to be freed.
A1: pointer to a LONG containing the value
IFFCMD_PURGELCI.
The user purge vector is then responsible for calling 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 structure.
RESULT
EXAMPLE
NOTES
BUGS
SEE ALSO
AllocLocalItem(), FreeLocalItem(), utility/hooks.h
iffparse.library/StopChunk iffparse.library/StopChunk
NAME
StopChunk -- Declare a chunk which should cause ParseIFF to return.
SYNOPSIS
error = StopChunk (iff, type, id)
d0 a0 d0 d1
LONG error;
struct IFFHandle *iff;
LONG type;
LONG id;
FUNCTION
Installs an entry handler for the specified chunk which will cause
the ParseIFF() function to return control to the caller when this
chunk is encountered. This is only of value when ParseIFF() is
called with the IFFPARSE_SCAN control code.
INPUTS
iff - pointer to IFFHandle 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(), ParseIFF()
iffparse.library/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 *iff;
LONG *list;
LONG n;
FUNCTION
(is to StopChunk() as PropChunks() is to PropChunk().)
INPUTS
iff - pointer to IFFHandle 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()
iffparse.library/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 *iff;
LONG type;
LONG id;
FUNCTION
Installs an exit handler for the specified chunk which will cause the
ParseIFF() function to return control to the caller when this chunk
is exhausted. ParseIFF() will return IFFERR_EOC when the declared
chunk is about to be popped. This is only of value when ParseIFF()
is called with the IFFPARSE_SCAN control code.
INPUTS
iff - pointer to IFFHandle 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()
iffparse.library/StoreItemInContext iffparse.library/StoreItemInContext
NAME
StoreItemInContext -- Store local context item in given context node.
SYNOPSIS
StoreItemInContext (iff, item, cn)
a0 a1 a2
struct IFFHandle *iff;
struct LocalContextItem *item;
struct ContextNode *cn;
FUNCTION
Adds the LocalContextItem 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, it will be purged and replaced with the
new one. This is a raw form of StoreLocalItem.
INPUTS
iff - pointer to IFFHandle struct for this context.
item - pointer to a LocalContextItem to be stored.
cn - pointer to context node in which to store item.
RESULT
EXAMPLE
NOTES
BUGS
SEE ALSO
StoreLocalItem()
iffparse.library/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 *iff;
struct LocalContextItem *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 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
struct itself is deleted with FreeIFF(). This means that handlers
installed in the root context will still be there after an IFFHandle
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 struct.
item - pointer to LocalContextItem 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(), StoreItemInContext(), EntryHandler(), ExitHandler()
iffparse.library/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 *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 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(), PopChunk(), WriteChunkRecords()
iffparse.library/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 *iff;
UBYTE *buf;
LONG recsize, numrec;
FUNCTION
Writes record elements from the buffer into the top chunk. This
function operates much like ReadChunkBytes().
INPUTS
iff - pointer to IFFHandle 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()