@database "iffparse"

@Node Main "iffparse.doc"
@toc "Includes_&_Autodocs/Main"
    @{" AllocIFF() " Link "AllocIFF()"}
    @{" AllocLocalItem() " Link "AllocLocalItem()"}
    @{" CloseClipboard() " Link "CloseClipboard()"}
    @{" CloseIFF() " Link "CloseIFF()"}
    @{" CollectionChunk() " Link "CollectionChunk()"}
    @{" CollectionChunks() " Link "CollectionChunks()"}
    @{" CurrentChunk() " Link "CurrentChunk()"}
    @{" EntryHandler() " Link "EntryHandler()"}
    @{" ExitHandler() " Link "ExitHandler()"}
    @{" FindCollection() " Link "FindCollection()"}
    @{" FindLocalItem() " Link "FindLocalItem()"}
    @{" FindProp() " Link "FindProp()"}
    @{" FindPropContext() " Link "FindPropContext()"}
    @{" FreeIFF() " Link "FreeIFF()"}
    @{" FreeLocalItem() " Link "FreeLocalItem()"}
    @{" GoodID() " Link "GoodID()"}
    @{" GoodType() " Link "GoodType()"}
    @{" IDtoStr() " Link "IDtoStr()"}
    @{" InitIFF() " Link "InitIFF()"}
    @{" InitIFFasClip() " Link "InitIFFasClip()"}
    @{" InitIFFasDOS() " Link "InitIFFasDOS()"}
    @{" LocalItemData() " Link "LocalItemData()"}
    @{" OpenClipboard() " Link "OpenClipboard()"}
    @{" OpenIFF() " Link "OpenIFF()"}
    @{" ParentChunk() " Link "ParentChunk()"}
    @{" ParseIFF() " Link "ParseIFF()"}
    @{" PopChunk() " Link "PopChunk()"}
    @{" PropChunk() " Link "PropChunk()"}
    @{" PropChunks() " Link "PropChunks()"}
    @{" PushChunk() " Link "PushChunk()"}
    @{" ReadChunkBytes() " Link "ReadChunkBytes()"}
    @{" ReadChunkRecords() " Link "ReadChunkRecords()"}
    @{" SetLocalItemPurge() " Link "SetLocalItemPurge()"}
    @{" StopChunk() " Link "StopChunk()"}
    @{" StopChunks() " Link "StopChunks()"}
    @{" StopOnExit() " Link "StopOnExit()"}
    @{" StoreItemInContext() " Link "StoreItemInContext()"}
    @{" StoreLocalItem() " Link "StoreLocalItem()"}
    @{" WriteChunkBytes() " Link "WriteChunkBytes()"}
    @{" WriteChunkRecords() " Link "WriteChunkRecords()"}
@EndNode

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

@{b}   NAME@{ub}
	AllocIFF -- create a new @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure. (V36)

@{b}   SYNOPSIS@{ub}
	iff = AllocIFF()
	D0

	struct @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} *AllocIFF(VOID);

@{b}   FUNCTION@{ub}
	Allocates and initializes a new @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure.
	This function is the only supported way to create an @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43}
	structure since there are private fields that need to be initialized.

@{b}   RESULT@{ub}
	iff - pointer to @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure or NULL if the allocation failed.

@{b}   SEE ALSO@{ub}
	@{"FreeIFF()" Link "FreeIFF()"}, @{"<libraries/iffparse.h>" Link "includes/libraries/iffparse.h/Main" 0}

@EndNode

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

@{b}   NAME@{ub}
	AllocLocalItem -- create a local context item structure. (V36)

@{b}   SYNOPSIS@{ub}
	item = AllocLocalItem(type, id, ident, dataSize);
	D0                    D0    D1  D2     D3

	struct @{"LocalContextItem" Link "includes/libraries/iffparse.h/Main" 103} *AllocLocalItem(LONG, @{"LONG" Link "includes/exec/types.h/Main" 35}, @{"LONG" Link "includes/exec/types.h/Main" 35}, LONG);

@{b}   FUNCTION@{ub}
	Allocates and initializes a @{"LocalContextItem" Link "includes/libraries/iffparse.h/Main" 103} structure with "dataSize"
	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 "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.

@{b}   INPUTS@{ub}
	type,id - additional longword identification values
	ident - longword identifier for class of context item
	dataSize - number of bytes of user data to allocate for this item

@{b}   RESULT@{ub}
	item - pointer to initialized @{"LocalContextItem" Link "includes/libraries/iffparse.h/Main" 103} or NULL if the
	       allocation failed.

@{b}   SEE ALSO@{ub}
	@{"FreeLocalItem()" Link "FreeLocalItem()"}, @{"LocalItemData()" Link "LocalItemData()"}, @{"StoreLocalItem()" Link "StoreLocalItem()"},
	@{"StoreItemInContext()" Link "StoreItemInContext()"}, @{"SetLocalItemPurge()" Link "SetLocalItemPurge()"}, @{"<libraries/iffparse.h>" Link "includes/libraries/iffparse.h/Main" 0}

@EndNode

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

@{b}   NAME@{ub}
	CloseClipboard -- close and free an open @{"ClipboardHandle" Link "includes/libraries/iffparse.h/Main" 147}. (V36)

@{b}   SYNOPSIS@{ub}
	CloseClipboard(clipHandle);
	               A0

	VOID CloseClipboard(struct @{"ClipboardHandle" Link "includes/libraries/iffparse.h/Main" 147} *);

@{b}   FUNCTION@{ub}
	Closes the clipboard.device and frees the @{"ClipboardHandle" Link "includes/libraries/iffparse.h/Main" 147} structure.

@{b}   INPUTS@{ub}
	clipHandle - pointer to @{"ClipboardHandle" Link "includes/libraries/iffparse.h/Main" 147} struct created with
	             @{"OpenClipboard()" Link "OpenClipboard()"}. Starting with V39, this may be NULL.

@{b}   SEE ALSO@{ub}
	@{"OpenClipboard()" Link "OpenClipboard()"}, @{"InitIFFasClip()" Link "InitIFFasClip()"}, @{"<libraries/iffparse.h>" Link "includes/libraries/iffparse.h/Main" 0}

@EndNode

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

@{b}   NAME@{ub}
	CloseIFF -- close an IFF context. (V36)

@{b}   SYNOPSIS@{ub}
	CloseIFF(iff);
	         A0

	VOID CloseIFF(struct @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} *);

@{b}   FUNCTION@{ub}
	Completes an IFF read or write operation by closing the IFF context
	established for this @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure. The @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure
	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 "includes/libraries/iffparse.h/Main" 65} 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.

@{b}   INPUTS@{ub}
	iff - pointer to @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure previously opened with
	      @{"OpenIFF()" Link "OpenIFF()"}. Starting with V39, this may be NULL.

@{b}   SEE ALSO@{ub}
	@{"OpenIFF()" Link "OpenIFF()"}, @{"InitIFF()" Link "InitIFF()"}, @{"<libraries/iffparse.h>" Link "includes/libraries/iffparse.h/Main" 0}

@EndNode

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

@{b}   NAME@{ub}
	CollectionChunk -- declare a chunk type for collection. (V36)

@{b}   SYNOPSIS@{ub}
	error = CollectionChunk(iff, type, id);
	D0                      A0   D0    D1

	@{"LONG" Link "includes/exec/types.h/Main" 35} CollectionChunk(struct @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} *, @{"LONG" Link "includes/exec/types.h/Main" 35}, LONG);

@{b}   FUNCTION@{ub}
	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.

@{b}   INPUTS@{ub}
	iff - pointer to @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure (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")

@{b}   RESULT@{ub}
	error - 0 if successful or an IFFERR_#? error code if unsuccessful.

@{b}   SEE ALSO@{ub}
	@{"CollectionChunks()" Link "CollectionChunks()"}, @{"FindCollection()" Link "FindCollection()"}, @{"PropChunk()" Link "PropChunk()"},
	@{"<libraries/iffparse.h>" Link "includes/libraries/iffparse.h/Main" 0}

@EndNode

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

@{b}   NAME@{ub}
	CollectionChunks -- declare many collection chunks at once. (V36)

@{b}   SYNOPSIS@{ub}
	error = CollectionChunks(iff, propArray, numPairs);
	D0                       A0   A1         D0

	@{"LONG" Link "includes/exec/types.h/Main" 35} CollectionChunks(struct @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} *, @{"LONG" Link "includes/exec/types.h/Main" 35} *, LONG);

@{b}   FUNCTION@{ub}
	Declares multiple collection chunks from a list. The propArray argument
	is a pointer to an array of longwords arranged in pairs. The format
	for the list is as follows:

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

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

@{b}   INPUTS@{ub}
	iff - pointer to @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure (does not need to be open)
	propArray - pointer to array of longword chunk types and identifiers
	numPairs - number of pairs in array.

@{b}   RESULT@{ub}
	error - 0 if successful or an IFFERR_#? error code if unsuccessful

@{b}   SEE ALSO@{ub}
	@{"CollectionChunk()" Link "CollectionChunk()"}, @{"<libraries/iffparse.h>" Link "includes/libraries/iffparse.h/Main" 0}

@EndNode

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

@{b}   NAME@{ub}
	CurrentChunk -- get context node for current chunk. (V36)

@{b}   SYNOPSIS@{ub}
	top = CurrentChunk(iff);
	D0                 A0

	struct @{"ContextNode" Link "includes/libraries/iffparse.h/Main" 84} *CurrentChunk(struct @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} *);

@{b}   FUNCTION@{ub}
	Returns the top context node for the given @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure. 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 "includes/libraries/iffparse.h/Main" 84} structure contains information on the type of chunk
	currently being parsed (or written), its size and the current
	position within the chunk.

@{b}   INPUTS@{ub}
	iff - pointer to @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure

@{b}   RESULT@{ub}
	top - pointer to top context node or NULL if none

@{b}   SEE ALSO@{ub}
	@{"PushChunk()" Link "PushChunk()"}, @{"PopChunk()" Link "PopChunk()"}, @{"ParseIFF()" Link "ParseIFF()"}, @{"ParentChunk()" Link "ParentChunk()"},
	@{"<libraries/iffparse.h>" Link "includes/libraries/iffparse.h/Main" 0}

@EndNode

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

@{b}   NAME@{ub}
	EntryHandler -- add an entry handler to the @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} context. (V36)

@{b}   SYNOPSIS@{ub}
	error = EntryHandler(iff, type, id, position, handler, object);
	D0                   A0   D0    D1  D2        A1       A2

	@{"LONG" Link "includes/exec/types.h/Main" 35} EntryHandler(struct @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} *, @{"LONG" Link "includes/exec/types.h/Main" 35}, @{"LONG" Link "includes/exec/types.h/Main" 35}, @{"LONG" Link "includes/exec/types.h/Main" 35},
	                  struct @{"Hook" Link "includes/utility/hooks.h/Main" 27} *, APTR);

@{b}   FUNCTION@{ub}
	Installs an entry handler vector for a specific type of chunk into
	the context for the given @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure. Type and id are the
	longword identifiers for the chunk to handle. The handler is a client-
	supplied standard @{"Hook" Link "includes/utility/hooks.h/Main" 27} 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 "includes/utility/hooks.h/Main" 27} pointer you passed.
		A2:	the 'object' pointer you passed.
		A1:	pointer to a @{"LONG" Link "includes/exec/types.h/Main" 35} 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.

@{b}   INPUTS@{ub}
	iff - pointer to @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure.
	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.
	handler - pointer to @{"Hook" Link "includes/utility/hooks.h/Main" 27} structure.
	object - a client-defined pointer which is passed in A2 during call-
		 back.

@{b}   RESULT@{ub}
	error - 0 if successful or an IFFERR_#? error code if unsuccessful.

@{b}   BUGS@{ub}
	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.

@{b}   SEE ALSO@{ub}
	@{"ExitHandler()" Link "ExitHandler()"}, @{"StoreLocalItem()" Link "StoreLocalItem()"}, @{"StoreItemInContext()" Link "StoreItemInContext()"},
	@{"<utility/hooks.h>" Link "includes/utility/hooks.h/Main" 0}, @{"<libraries/iffparse.h>" Link "includes/libraries/iffparse.h/Main" 0}

@EndNode

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

@{b}   NAME@{ub}
	ExitHandler -- add an exit handler to the @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} context. (V36)

@{b}   SYNOPSIS@{ub}
	error = ExitHandler(iff, type, id, position, handler, object);
	D0                  A0   D0    D1  D2        A1       A2

	@{"LONG" Link "includes/exec/types.h/Main" 35} ExitHandler(struct @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} *, @{"LONG" Link "includes/exec/types.h/Main" 35}, @{"LONG" Link "includes/exec/types.h/Main" 35}, @{"LONG" Link "includes/exec/types.h/Main" 35},
	                 struct @{"Hook" Link "includes/utility/hooks.h/Main" 27} *, @{"APTR" Link "includes/exec/types.h/Main" 33} object(;

@{b}   FUNCTION@{ub}
	Installs an exit handler vector for a specific type of chunk into the
	context for the given @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure. Type and id are the longword
	identifiers for the chunk to handle. The handler is a client-supplied
	standard @{"Hook" Link "includes/utility/hooks.h/Main" 27} 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 "includes/utility/hooks.h/Main" 27} pointer you passed.
		A2:	the 'object' pointer you passed.
		A1:	pointer to a @{"LONG" Link "includes/exec/types.h/Main" 35} 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.

@{b}   INPUTS@{ub}
	iff - pointer to @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure.
	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.
	handler - pointer to @{"Hook" Link "includes/utility/hooks.h/Main" 27} structure.
	object - a client-defined pointer which is passed in A2 during call-
		 back.

@{b}   RESULT@{ub}
	error - 0 if successful or an IFFERR_#? error code if unsuccessful.

@{b}   BUGS@{ub}
	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.

@{b}   SEE ALSO@{ub}
	@{"EntryHandler()" Link "EntryHandler()"}, @{"StoreLocalItem()" Link "StoreLocalItem()"}, @{"StoreItemInContext()" Link "StoreItemInContext()"},
	@{"<utility/hooks.h>" Link "includes/utility/hooks.h/Main" 0}, @{"<libraries/iffparse.h>" Link "includes/libraries/iffparse.h/Main" 0}

@EndNode

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

@{b}   NAME@{ub}
	FindCollection -- get a pointer to the current list of collection
			  items. (V36)

@{b}   SYNOPSIS@{ub}
	ci = FindCollection(iff, type, id);
	D0                  A0   D0    D1

	struct @{"CollectionItem" Link "includes/libraries/iffparse.h/Main" 132} *FindCollection(struct @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} *, @{"LONG" Link "includes/exec/types.h/Main" 35}, LONG);

@{b}   FUNCTION@{ub}
	Returns a pointer to a list of @{"CollectionItem" Link "includes/libraries/iffparse.h/Main" 132} 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.

@{b}   INPUTS@{ub}
	iff - pointer to @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure.
	type - type code to search for.
	id - identifier code to search for.

@{b}   RESULT@{ub}
	ci - pointer to last collection chunk encountered with
	     links to previous ones.

@{b}   SEE ALSO@{ub}
	@{"CollectionChunk()" Link "CollectionChunk()"}, @{"CollectionChunks()" Link "CollectionChunks()"}, @{"<libraries/iffparse.h>" Link "includes/libraries/iffparse.h/Main" 0}

@EndNode

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

@{b}   NAME@{ub}
	FindLocalItem -- return a local context item from the context stack.
	                 (V36)

@{b}   SYNOPSIS@{ub}
	lci = FindLocalItem(iff, type, id, ident);
	D0                  A0   D0    D1  D2

	struct @{"LocalContextItem" Link "includes/libraries/iffparse.h/Main" 103}	*FindLocalItem(struct @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43}	*,
	                                       @{"LONG" Link "includes/exec/types.h/Main" 35}, @{"LONG" Link "includes/exec/types.h/Main" 35}, LONG);

@{b}   FUNCTION@{ub}
	Searches the context stack of the given @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure 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.

@{b}   INPUTS@{ub}
	iff - pointer to @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure.
	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).

@{b}   RESULT@{ub}
	lci - pointer to local context item, or NULL if nothing matched.

@{b}   SEE ALSO@{ub}
	@{"StoreLocalItem()" Link "StoreLocalItem()"}, @{"<libraries/iffparse.h>" Link "includes/libraries/iffparse.h/Main" 0}

@EndNode

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

@{b}   NAME@{ub}
	FindProp -- search for a stored property chunk. (V36)

@{b}   SYNOPSIS@{ub}
	sp = FindProp(iff, type, id);
	D0            A0   D0    D1

	struct @{"StoredProperty" Link "includes/libraries/iffparse.h/Main" 118} *FindProp(struct @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} *, @{"LONG" Link "includes/exec/types.h/Main" 35}, LONG);

@{b}   FUNCTION@{ub}
	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 "includes/libraries/iffparse.h/Main" 118}
	struct, if found, contains a pointer to a data buffer containing the
	contents of the stored property.

@{b}   INPUTS@{ub}
	iff - pointer to @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure.
	type - type code for chunk to search for (ex. "ILBM").
	id - identifier code for chunk to search for (ex. "CMAP").

@{b}   RESULT@{ub}
	sp - pointer to stored property, or NULL if none found.

@{b}   SEE ALSO@{ub}
	@{"PropChunk()" Link "PropChunk()"}, @{"PropChunks()" Link "PropChunks()"}, @{"<libraries/iffparse.h>" Link "includes/libraries/iffparse.h/Main" 0}

@EndNode

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

@{b}   NAME@{ub}
	FindPropContext -- get the property context for the current state.
	                   (V36)

@{b}   SYNOPSIS@{ub}
	cn = FindPropContext(iff);
	D0                   A0

	struct @{"ContextNode" Link "includes/libraries/iffparse.h/Main" 84} *FindPropContext(struct @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} *);

@{b}   FUNCTION@{ub}
	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.

@{b}   INPUTS@{ub}
	iff - pointer to @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure.

@{b}   RESULT@{ub}
	cn - @{"ContextNode" Link "includes/libraries/iffparse.h/Main" 84} of property scoping chunk.

@{b}   SEE ALSO@{ub}
	@{"CurrentChunk()" Link "CurrentChunk()"}, @{"ParentChunk()" Link "ParentChunk()"}, @{"StoreItemInContext()" Link "StoreItemInContext()"},
	@{"<libraries/iffparse.h>" Link "includes/libraries/iffparse.h/Main" 0}

@EndNode

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

@{b}   NAME@{ub}
	FreeIFF -- deallocate an @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure. (V36)

@{b}   SYNOPSIS@{ub}
	FreeIFF(iff);
	        A0

	VOID FreeIFF(struct @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} *);

@{b}   FUNCTION@{ub}
	Deallocates all resources associated with this @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure.
	The structure MUST have already been closed with @{"CloseIFF()" Link "CloseIFF()"}.

@{b}   INPUTS@{ub}
	iff - pointer to @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure to free. Starting with V39,
	      this may be NULL.

@{b}   SEE ALSO@{ub}
	@{"AllocIFF()" Link "AllocIFF()"}, @{"CloseIFF()" Link "CloseIFF()"}, @{"<libraries/iffparse.h>" Link "includes/libraries/iffparse.h/Main" 0}

@EndNode

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

@{b}   NAME@{ub}
	FreeLocalItem -- deallocate a local context item structure. (V36)

@{b}   SYNOPSIS@{ub}
	FreeLocalItem(localItem);
	              A0

	VOID FreeLocalItem(struct @{"LocalContextItem" Link "includes/libraries/iffparse.h/Main" 103} *);

@{b}   FUNCTION@{ub}
	Frees the memory for the local context item and any associated user
	memory as allocated with @{"AllocLocalItem()" Link "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.)

@{b}   INPUTS@{ub}
	localItem - pointer to @{"LocalContextItem" Link "includes/libraries/iffparse.h/Main" 103} created with @{"AllocLocalItem" Link "iffparse/AllocLocalItem()"}.
	            Starting with V39, this may be NULL.

@{b}   SEE ALSO@{ub}
	@{"AllocLocalItem()" Link "AllocLocalItem()"}, @{"<libraries/iffparse.h>" Link "includes/libraries/iffparse.h/Main" 0}

@EndNode

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

@{b}   NAME@{ub}
	GoodID -- test if an identifier follows the IFF 85 specification. (V36)

@{b}   SYNOPSIS@{ub}
	isok = GoodID(id);
	D0            D0

	@{"LONG" Link "includes/exec/types.h/Main" 35} GoodID(LONG);

@{b}   FUNCTION@{ub}
	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.

@{b}   INPUTS@{ub}
	id - potential 32 bit identifier.

@{b}   RESULT@{ub}
	isok - non-zero if this is a valid ID, 0 otherwise.

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

@EndNode

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

@{b}   NAME@{ub}
	GoodType -- test if a type follows the IFF 85 specification. (V36)

@{b}   SYNOPSIS@{ub}
	isok = GoodType(type)
	D0              D0

	@{"LONG" Link "includes/exec/types.h/Main" 35} GoodType(LONG);

@{b}   FUNCTION@{ub}
	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.

@{b}   INPUTS@{ub}
	type - potential 32 bit format type identifier.

@{b}   RESULT@{ub}
	isok - non-zero if this is a valid type id, 0 otherwise.

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

@EndNode

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

@{b}   NAME@{ub}
	IDtoStr -- convert a longword identifier to a null-terminated string.
	           (V36)

@{b}   SYNOPSIS@{ub}
	str = IDtoStr(id, buf);
	D0            D0  A0

	@{"STRPTR" Link "includes/exec/types.h/Main" 53} IDtoStr(LONG, STRPTR);

@{b}   FUNCTION@{ub}
	Writes the ASCII equivalent of the given longword ID into buf as a
	null-terminated string.

@{b}   INPUTS@{ub}
	id - longword ID.
	buf - character buffer to accept string (at least 5 chars).

@{b}   RESULT@{ub}
	str - the value of 'buf'.

@EndNode

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

@{b}   NAME@{ub}
	InitIFF -- initialize an @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure as a user stream. (V36)

@{b}   SYNOPSIS@{ub}
	InitIFF(iff, flags, streamHook);
	        A0   D0     A1

	VOID InitIFF(struct @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} *, @{"LONG" Link "includes/exec/types.h/Main" 35}, struct @{"Hook" Link "includes/utility/hooks.h/Main" 27} *);

@{b}   FUNCTION@{ub}
	Initializes an @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} 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 "includes/libraries/iffparse.h/Main" 43} structure.
		A1:	pointer to @{"IFFStreamCmd" Link "includes/libraries/iffparse.h/Main" 65} structure.

	The @{"IFFStreamCmd" Link "includes/libraries/iffparse.h/Main" 65} 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 "includes/libraries/iffparse.h/Main" 65}
	structure.

@{b}   INPUTS@{ub}
	iff - pointer to @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure to initialize.
	flags - stream I/O flags for the @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43}.
	streamHook - pointer to @{"Hook" Link "includes/utility/hooks.h/Main" 27} structure.

@{b}   SEE ALSO@{ub}
	@{"<utility/hooks.h>" Link "includes/utility/hooks.h/Main" 0}, @{"<libraries/iffparse.h>" Link "includes/libraries/iffparse.h/Main" 0}

@EndNode

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

@{b}   NAME@{ub}
	InitIFFasClip -- initialize an @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} as a clipboard stream. (V36)

@{b}   SYNOPSIS@{ub}
	InitIFFasClip(iff);
	              A0

	VOID InitIFFasClip(struct @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} *);

@{b}   FUNCTION@{ub}
	Initializes the given @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} to be a clipboard stream. The
	function initializes the stream processing vectors to operate on
	streams of the @{"ClipboardHandle" Link "includes/libraries/iffparse.h/Main" 147} type. The iff_Stream field will still
	need to be initialized to point to a @{"ClipboardHandle" Link "includes/libraries/iffparse.h/Main" 147} as returned from
	@{"OpenClipboard()" Link "OpenClipboard()"}.

@{b}   INPUTS@{ub}
	iff - pointer to @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure.

@{b}   SEE ALSO@{ub}
	@{"InitIFF()" Link "InitIFF()"}, @{"OpenClipboard()" Link "OpenClipboard()"}, @{"<libraries/iffparse.h>" Link "includes/libraries/iffparse.h/Main" 0}

@EndNode

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

@{b}   NAME@{ub}
	InitIFFasDOS -- initialize an @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} as a DOS stream. (V36)

@{b}   SYNOPSIS@{ub}
	InitIFFasDOS(iff)
	             A0

	InitIFFasDOS(struct @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} *);

@{b}   FUNCTION@{ub}
	The function initializes the given @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} to operate on DOS
	streams. The iff_Stream field will need to be initialized as a @{"BPTR" Link "includes/dos/dos.h/Main" 129}
	returned from the DOS function @{"Open()" Link "dos/Open()"}.

@{b}   INPUTS@{ub}
	iff - pointer to @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure.

@{b}   SEE ALSO@{ub}
	@{"InitIFF()" Link "InitIFF()"}

@EndNode

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

@{b}   NAME@{ub}
	LocalItemData -- get pointer to user data for local context item. (V36)

@{b}   SYNOPSIS@{ub}
	data = LocalItemData(localItem);
	D0                   A0

	@{"APTR" Link "includes/exec/types.h/Main" 33} LocalItemData(struct @{"LocalContextItem" Link "includes/libraries/iffparse.h/Main" 103} *);

@{b}   FUNCTION@{ub}
	Returns pointer to the user data associated with the given local
	context item. The size of the data area depends on the "dataSize"
	argument used when allocating this item. If the pointer to the item
	given (localItem) is NULL, this function returns NULL.

@{b}   INPUTS@{ub}
	localItem - pointer to local context item or NULL.

@{b}   RESULT@{ub}
	data - pointer to user data area or NULL if localItem is NULL.

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

@{b}   SEE ALSO@{ub}
	@{"AllocLocalItem()" Link "AllocLocalItem()"}, @{"FreeLocalItem()" Link "FreeLocalItem()"}, @{"<libraries/iffparse.h>" Link "includes/libraries/iffparse.h/Main" 0}

@EndNode

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

@{b}   NAME@{ub}
	OpenClipboard -- create a handle on a clipboard unit. (V36)

@{b}   SYNOPSIS@{ub}
	ch = OpenClipboard(unitNumber)
	D0                 D0

	struct @{"ClipboardHandle" Link "includes/libraries/iffparse.h/Main" 147} *OpenClipboard(LONG);

@{b}   FUNCTION@{ub}
	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()"}.

@{b}   INPUTS@{ub}
	unitNumber - clipboard unit number (usually PRIMARY_CLIP).

@{b}   RESULT@{ub}
	ch - pointer to @{"ClipboardHandle" Link "includes/libraries/iffparse.h/Main" 147} structure or NULL if unsuccessful.

@{b}   BUGS@{ub}
	This function had several bugs prior to V39.

       First bug was that if the clipboard.device couldn't open, two calls
	to @{"FreeSignal()" Link "exec/FreeSignal()"} were made with uninitialized values as parameters.
	The result of this was a corrupt signal mask in the @{"Task" Link "includes/exec/tasks.h/Main" 23} field.

	Second bug was that @{"OpenDevice()" Link "serial/OpenDevice()"} was called with an IO request that
	didn't have a valid @{"MsgPort" Link "includes/exec/ports.h/Main" 27} pointer in it.

	Third bug was that the two message ports allocated by the function
	(ClipboardHandle->cbh_CBport and ClipboardHandle->cbh_SatisfyPort)
	were not being initialized correctly and would cause a system crash
	if a message ever got to either of them.

@{b}   SEE ALSO@{ub}
	@{"InitIFFasClip()" Link "InitIFFasClip()"}, @{"CloseClipboard()" Link "CloseClipboard()"}, @{"<libraries/iffparse.h>" Link "includes/libraries/iffparse.h/Main" 0}

@EndNode

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

@{b}   NAME@{ub}
	OpenIFF -- prepare an @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} to read or write a new IFF stream.
	           (V36)

@{b}   SYNOPSIS@{ub}
	error = OpenIFF(iff, rwMode);
	D0              A0   D0

	@{"LONG" Link "includes/exec/types.h/Main" 35} OpenIFF(struct @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} *, LONG);

@{b}   FUNCTION@{ub}
	Initializes an @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure 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 "includes/libraries/iffparse.h/Main" 65} 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.

@{b}   INPUTS@{ub}
	iff - pointer to @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure. Starting with V39, this may be
	      NULL, in which case IFFERR_NOMEM is returned.
	rwMode - IFFF_READ or IFFF_WRITE

@{b}   RESULT@{ub}
	error - contains an error code or 0 if successful

@{b}   SEE ALSO@{ub}
	@{"CloseIFF()" Link "CloseIFF()"}, @{"InitIFF()" Link "InitIFF()"}, @{"<libraries/iffparse.h>" Link "includes/libraries/iffparse.h/Main" 0}

@EndNode

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

@{b}   NAME@{ub}
	ParentChunk -- get the nesting context node for the given chunk. (V36)

@{b}   SYNOPSIS@{ub}
	parent = ParentChunk(contextNode);
	D0                   A0

	struct @{"ContextNode" Link "includes/libraries/iffparse.h/Main" 84} *ParentChunk(struct @{"ContextNode" Link "includes/libraries/iffparse.h/Main" 84} *);

@{b}   FUNCTION@{ub}
	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 "includes/libraries/iffparse.h/Main" 84} pointer for the enclosing FORM chunk while reading a data
	chunk, use: ParentChunk(CurrentChunk(iff)) to find this pointer.
	The @{"ContextNode" Link "includes/libraries/iffparse.h/Main" 84} structure contains information on the type of chunk
	and its size.

@{b}   INPUTS@{ub}
	contextNode - pointer to a context node.

@{b}   RESULT@{ub}
	parent - pointer to the enclosing context node or NULL if none.

@{b}   SEE ALSO@{ub}
	@{"CurrentChunk()" Link "CurrentChunk()"}, @{"<libraries/iffparse.h>" Link "includes/libraries/iffparse.h/Main" 0}

@EndNode

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

@{b}   NAME@{ub}
	ParseIFF -- parse an IFF file from an @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure stream. (V36)

@{b}   SYNOPSIS@{ub}
	error = ParseIFF(iff, control);
	D0               A0   D0

	@{"LONG" Link "includes/exec/types.h/Main" 35} ParseIFF(struct @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} *, LONG);

@{b}   FUNCTION@{ub}
	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.

@{b}   INPUTS@{ub}
	iff - pointer to @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure.
	control	- control code (IFFPARSE_SCAN, _STEP or _RAWSTEP).

@{b}   RESULT@{ub}
	error - 0 or IFFERR_#? value or return value from user handler.

@{b}   SEE ALSO@{ub}
	@{"PushChunk()" Link "PushChunk()"}, @{"PopChunk()" Link "PopChunk()"}, @{"EntryHandler()" Link "EntryHandler()"}, @{"ExitHandler()" Link "ExitHandler()"},
	@{"PropChunk()" Link "PropChunk()"}, @{"CollectionChunk()" Link "CollectionChunk()"}, @{"StopChunk()" Link "StopChunk()"}, @{"StopOnExit()" Link "StopOnExit()"},
	@{"<libraries/iffparse.h>" Link "includes/libraries/iffparse.h/Main" 0}

@EndNode

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

@{b}   NAME@{ub}
	PopChunk -- pop top context node off context stack. (V36)

@{b}   SYNOPSIS@{ub}
	error = PopChunk(iff);
	D0               A0

	@{"LONG" Link "includes/exec/types.h/Main" 35} PopChunk(struct @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} *);

@{b}   FUNCTION@{ub}
	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.

@{b}   INPUTS@{ub}
	iff - pointer to @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure.

@{b}   RESULT@{ub}
	error - 0 if successful or an IFFERR_#? error code if unsuccessful.

@{b}   SEE ALSO@{ub}
	@{"PushChunk()" Link "PushChunk()"}, @{"<libraries/iffparse.h>" Link "includes/libraries/iffparse.h/Main" 0}

@EndNode

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

@{b}   NAME@{ub}
	PropChunk -- specify a property chunk to store. (V36)

@{b}   SYNOPSIS@{ub}
	error = PropChunk(iff, type, id);
	D0                A0   D0    D1

	@{"LONG" Link "includes/exec/types.h/Main" 35} PropChunk(struct @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} *, @{"LONG" Link "includes/exec/types.h/Main" 35}, LONG);

@{b}   FUNCTION@{ub}
	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.

@{b}   INPUTS@{ub}
	iff - pointer to @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure (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").

@{b}   RESULT@{ub}
	error - 0 if successful or an IFFERR_#? error code if unsuccessful.

@{b}   SEE ALSO@{ub}
	@{"PropChunks()" Link "PropChunks()"}, @{"FindProp()" Link "FindProp()"}, @{"CollectionChunk()" Link "CollectionChunk()"}, @{"<libraries/iffparse.h>" Link "includes/libraries/iffparse.h/Main" 0}

@EndNode

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

@{b}   NAME@{ub}
	PropChunks -- declare many property chunks at once. (V36)

@{b}   SYNOPSIS@{ub}
	error = PropChunks(iff, propArray, numPairs);
	D0                 A0   A1         D0

	@{"LONG" Link "includes/exec/types.h/Main" 35} PropChunks(struct @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} *, @{"LONG" Link "includes/exec/types.h/Main" 35} *, LONG);

@{b}   FUNCTION@{ub}
	Declares multiple property chunks from a list. The propArray argument
	if a pointer to an array of longwords arranged in pairs, and has the
	following format:

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

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

@{b}   INPUTS@{ub}
	iff - pointer to @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure.
	propArray - pointer to array of longword chunk types and identifiers.
	numPairs - number of pairs in the array.

@{b}   RESULT@{ub}
	error - 0 if successful or an IFFERR_#? error code if unsuccessful.

@{b}   SEE ALSO@{ub}
	@{"PropChunk()" Link "PropChunk()"}, @{"<libraries/iffparse.h>" Link "includes/libraries/iffparse.h/Main" 0}

@EndNode

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

@{b}   NAME@{ub}
	PushChunk -- push a new context node on the context stack. (V36)

@{b}   SYNOPSIS@{ub}
	error = PushChunk(iff, type, id, size);
	D0                A0   D0    D1  D2

	@{"LONG" Link "includes/exec/types.h/Main" 35} PushChunk(struct @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} *, @{"LONG" Link "includes/exec/types.h/Main" 35}, @{"LONG" Link "includes/exec/types.h/Main" 35}, LONG);

@{b}   FUNCTION@{ub}
	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.

@{b}   INPUTS@{ub}
	iff - pointer to @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure.
	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).

@{b}   RESULT@{ub}
	error - 0 if successful or an IFFERR_#? error code if not unsuccessful.

@{b}   SEE ALSO@{ub}
	@{"PopChunk()" Link "PopChunk()"}, @{"WriteChunkRecords()" Link "WriteChunkRecords()"}, @{"WriteChunkBytes()" Link "WriteChunkBytes()"},
	@{"<libraries/iffparse.h>" Link "includes/libraries/iffparse.h/Main" 0}

@EndNode

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

@{b}   NAME@{ub}
	ReadChunkBytes -- read bytes from the current chunk into a buffer.
	                  (V36)

@{b}   SYNOPSIS@{ub}
	actual = ReadChunkBytes(iff, buf, numBytes);
	D0                      A0   A1   D0

	@{"LONG" Link "includes/exec/types.h/Main" 35} ReadChunkBytes(struct @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} *, @{"APTR" Link "includes/exec/types.h/Main" 33} buf, LONG);

@{b}   FUNCTION@{ub}
	Reads the @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} 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. This
	function returns positive number of bytes read or a negative error
	code.

@{b}   INPUTS@{ub}
	iff - pointer to @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure.
	buf - pointer to buffer area to receive data.
	numBytes - number of bytes to read.

@{b}   RESULT@{ub}
	actual - (positive) number of bytes read if successful or a
		 (negative) IFFERR_#? error code if unsuccessful.

@{b}   SEE ALSO@{ub}
	@{"ReadChunkRecords()" Link "ReadChunkRecords()"}, @{"ParseIFF()" Link "ParseIFF()"}, @{"WriteChunkBytes()" Link "WriteChunkBytes()"},
	@{"<libraries/iffparse.h>" Link "includes/libraries/iffparse.h/Main" 0}

@EndNode

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

@{b}   NAME@{ub}
	ReadChunkRecords -- read record elements from the current chunk into
			    a buffer. (V36)

@{b}   SYNOPSIS@{ub}
	actual = ReadChunkRecords(iff, buf, bytesPerRecord, numRecords);
	D0                        A0   A1   D0              D1

	@{"LONG" Link "includes/exec/types.h/Main" 35} ReadChunkRecords(struct @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} *, @{"APTR" Link "includes/exec/types.h/Main" 33}, @{"LONG" Link "includes/exec/types.h/Main" 35}, LONG);

@{b}   FUNCTION@{ub}
	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()"}).

@{b}   INPUTS@{ub}
	iff - pointer to @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure.
	buf - pointer to buffer area to receive data.
	bytesPerRecord	- size of data records to read.
	numRecords - number of data records to read.

@{b}   RESULT@{ub}
	actual - (positive) number of whole records read if successful or a
		 (negative) IFFERR_#? error code if unsuccessful.

@{b}   SEE ALSO@{ub}
	@{"ReadChunkBytes()" Link "ReadChunkBytes()"}, @{"ParseIFF()" Link "ParseIFF()"}, @{"WriteChunkRecords()" Link "WriteChunkRecords()"},
	@{"<libraries/iffparse.h>" Link "includes/libraries/iffparse.h/Main" 0}

@EndNode

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

@{b}   NAME@{ub}
	SetLocalItemPurge -- set purge vector for a local context item. (V36)

@{b}   SYNOPSIS@{ub}
	SetLocalItemPurge(localItem, purgeHook);
	                  A0         A1

	VOID SetLocalItemPurge(struct @{"LocalContextItem" Link "includes/libraries/iffparse.h/Main" 103} *, struct @{"Hook" Link "includes/utility/hooks.h/Main" 27} *);

@{b}   FUNCTION@{ub}
	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 "includes/libraries/iffparse.h/Main" 84} 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 "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 "includes/libraries/iffparse.h/Main" 103} to be freed.
		A1:	pointer to a @{"LONG" Link "includes/exec/types.h/Main" 35} 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).

@{b}   INPUTS@{ub}
	localItem - pointer to a local context item.
	purgeHook - pointer to a @{"Hook" Link "includes/utility/hooks.h/Main" 27} structure.

@{b}   SEE ALSO@{ub}
	@{"AllocLocalItem()" Link "AllocLocalItem()"}, @{"FreeLocalItem()" Link "FreeLocalItem()"}, @{"<utility/hooks.h>" Link "includes/utility/hooks.h/Main" 0}
	@{"<libraries/iffparse.h>" Link "includes/libraries/iffparse.h/Main" 0}

@EndNode

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

@{b}   NAME@{ub}
	StopChunk -- declare a chunk which should cause @{"ParseIFF" Link "iffparse/ParseIFF()"} to return.
	             (V36)

@{b}   SYNOPSIS@{ub}
	error = StopChunk(iff, type, id);
	D0                A0   D0    D1

	@{"LONG" Link "includes/exec/types.h/Main" 35} StopChunk(struct @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} *, @{"LONG" Link "includes/exec/types.h/Main" 35}, LONG);		 type;

@{b}   FUNCTION@{ub}
	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.

@{b}   INPUTS@{ub}
	iff - pointer to @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure (need not be open).
	type - type code for chunk to declare (ex. "ILBM").
	id - identifier for chunk to declare (ex. "BODY").

@{b}   RESULT@{ub}
	error - 0 if successful or an IFFERR_#? error code if unsuccessful.

@{b}   SEE ALSO@{ub}
	@{"StopChunks()" Link "StopChunks()"}, @{"ParseIFF()" Link "ParseIFF()"}, @{"<libraries/iffparse.h>" Link "includes/libraries/iffparse.h/Main" 0}

@EndNode

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

@{b}   NAME@{ub}
	StopChunks -- declare many stop chunks at once. (V36)

@{b}   SYNOPSIS@{ub}
	error = StopChunks(iff, propArray, numPairs);
	D0                 A0   A1         D0

	@{"LONG" Link "includes/exec/types.h/Main" 35} StopChunks(struct @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} *, @{"LONG" Link "includes/exec/types.h/Main" 35} *, LONG);

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

@{b}   INPUTS@{ub}
	iff - pointer to @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure.
	propArray - pointer to array of longword chunk types and identifiers.
	numPairs - number of pairs in the array.

@{b}   RESULT@{ub}
	error - 0 if successful or an IFFERR_#? error code if unsuccessful.

@{b}   SEE ALSO@{ub}
	@{"StopChunk()" Link "StopChunk()"}, @{"<libraries/iffparse.h>" Link "includes/libraries/iffparse.h/Main" 0}

@EndNode

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

@{b}   NAME@{ub}
	StopOnExit -- declare a stop condition for exiting a chunk. (V36)

@{b}   SYNOPSIS@{ub}
	error = StopOnExit(iff, type, id);
	D0                 A0   D0    D1

	@{"LONG" Link "includes/exec/types.h/Main" 35} StopOnExit(struct @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} *, @{"LONG" Link "includes/exec/types.h/Main" 35}, LONG);

@{b}   FUNCTION@{ub}
	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.

@{b}   INPUTS@{ub}
	iff - pointer to @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure (need not be open).
	type - type code for chunk to declare (ex. "ILBM").
	id - identifier for chunk to declare (ex. "BODY").

@{b}   RESULT@{ub}
	error - 0 if successful or an IFFERR_#? error code if unsuccessful.

@{b}   SEE ALSO@{ub}
	@{"ParseIFF()" Link "ParseIFF()"}, @{"<libraries/iffparse.h>" Link "includes/libraries/iffparse.h/Main" 0}

@EndNode

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

@{b}   NAME@{ub}
	StoreItemInContext -- store local context item in given context node.
	                      (V36)

@{b}   SYNOPSIS@{ub}
	StoreItemInContext(iff, localItem, contextNode);
	                   A0   A1         A2

	VOID StoreItemInContext(struct @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} *, struct @{"LocalContextItem" Link "includes/libraries/iffparse.h/Main" 103} *,
                               struct @{"ContextNode" Link "includes/libraries/iffparse.h/Main" 84} *);

@{b}   FUNCTION@{ub}
	Adds the @{"LocalContextItem" Link "includes/libraries/iffparse.h/Main" 103} 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 "includes/libraries/iffparse.h/Main" 84}, it will be purged and replaced with the
	new one. This is a raw form of @{"StoreLocalItem()" Link "StoreLocalItem()"}.

@{b}   INPUTS@{ub}
	iff - pointer to @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure for this context.
	localItem - pointer to a @{"LocalContextItem" Link "includes/libraries/iffparse.h/Main" 103} to be stored.
	contextNode - pointer to context node in which to store item.

@{b}   SEE ALSO@{ub}
	@{"StoreLocalItem()" Link "StoreLocalItem()"}, @{"<libraries/iffparse.h>" Link "includes/libraries/iffparse.h/Main" 0}

@EndNode

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

@{b}   NAME@{ub}
	StoreLocalItem -- insert a local context item into the context stack.
	                  (V36)

@{b}   SYNOPSIS@{ub}
	error = StoreLocalItem(iff, localItem, position);
	D0                     A0   A1         D0

	@{"LONG" Link "includes/exec/types.h/Main" 35} StoreLocalItem(struct @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} *, struct @{"LocalContextItem" Link "includes/libraries/iffparse.h/Main" 103}	*,
	                    LONG);

@{b}   FUNCTION@{ub}
	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 "includes/libraries/iffparse.h/Main" 43} 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 "includes/libraries/iffparse.h/Main" 43}
	structure itself is deleted with @{"FreeIFF()" Link "FreeIFF()"}. This means that handlers
	installed in the root context will still be there after an @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43}
	structure has been opened and closed. (Note that this implies that
	items stored in a higher context will be deleted when that context
	ends.)

@{b}   INPUTS@{ub}
	iff - pointer to @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure.
	localItem - pointer to @{"LocalContextItem" Link "includes/libraries/iffparse.h/Main" 103} struct to insert.
	position - where to store the item (IFFSLI_ROOT, _TOP or _PROP).

@{b}   RESULT@{ub}
	error - 0 if successful or an IFFERR_#? error code if unsuccessful.

@{b}   SEE ALSO@{ub}
	@{"FindLocalItem()" Link "FindLocalItem()"}, @{"StoreItemInContext()" Link "StoreItemInContext()"}, @{"EntryHandler()" Link "EntryHandler()"}, @{"ExitHandler()" Link "ExitHandler()"},
	@{"<libraries/iffparse.h>" Link "includes/libraries/iffparse.h/Main" 0}

@EndNode

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

@{b}   NAME@{ub}
	WriteChunkBytes -- write data from a buffer into the current chunk.
	                   (V36)

@{b}   SYNOPSIS@{ub}
	error = WriteChunkBytes(iff, buf, numBytes);
	D0                      A0   A1   D0

	@{"LONG" Link "includes/exec/types.h/Main" 35} WriteChunkBytes(struct @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} *, @{"APTR" Link "includes/exec/types.h/Main" 33}, LONG);

@{b}   FUNCTION@{ub}
	Writes "numBytes" 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.

@{b}   INPUTS@{ub}
	iff - pointer to @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure.
	buf - pointer to buffer area with bytes to be written.
	numBytes - number of bytes to write.

@{b}   RESULT@{ub}
	error - (positive) number of bytes written if successful or a
		(negative) IFFERR_#? error code if unsuccessful.

@{b}   SEE ALSO@{ub}
	@{"PushChunk()" Link "PushChunk()"}, @{"PopChunk()" Link "PopChunk()"}, @{"WriteChunkRecords()" Link "WriteChunkRecords()"}, @{"<libraries/iffparse.h>" Link "includes/libraries/iffparse.h/Main" 0}

@EndNode

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

@{b}   NAME@{ub}
	WriteChunkRecords -- write records from a buffer to the current
			     chunk. (V36)

@{b}   SYNOPSIS@{ub}
	error = WriteChunkRecords(iff, buf, recsize, numrec);
	D0                        A0   A1   D0       D1

	@{"LONG" Link "includes/exec/types.h/Main" 35} WriteChunkRecords(struct @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} *, @{"APTR" Link "includes/exec/types.h/Main" 33}, @{"LONG" Link "includes/exec/types.h/Main" 35}, LONG);

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

@{b}   INPUTS@{ub}
	iff - pointer to @{"IFFHandle" Link "includes/libraries/iffparse.h/Main" 43} structure.
	buf - pointer to buffer area containing data.
	recsize	- size of data records to write.
	numrec - number of data records to write.

@{b}   RESULT@{ub}
	error - (positive) number of whole records written if successful
		or a (negative) IFFERR_#? error code if unsuccessful.

@{b}   SEE ALSO@{ub}
	@{"WriteChunkBytes()" Link "WriteChunkBytes()"}, @{"<libraries/iffparse.h>" Link "includes/libraries/iffparse.h/Main" 0}

@EndNode

