AmigaOS Documentation Wiki - User contributions [en]

Date Functions

2020-05-22T13:31:05Z

Fredrik Wikstrom: Fixed Printf() statements in example code

= Date Functions =

To ease date-related calculations, the utility library has some functions to convert a date, specified in a ClockData structure, in the number of seconds since 00:00:00 01-Jan-78 and vice versa.

To indicate the date, the ClockData structure (in <utility/date.h>) is used.

<syntaxhighlight>
struct ClockData
{
UWORD sec; /* seconds (0 - 59) */
UWORD min; /* minutes (0 - 59) */
UWORD hour; /* hour (0 - 23) */
UWORD mday; /* day of the month (1 - 31) */
UWORD month; /* month of the year (1 - 12) */
UWORD year; /* 1978 - */
UWORD wday; /* day of the week (0 - 6, where 0 is Sunday) */
};
</syntaxhighlight>

The following functions are available to operate on ClockData:

{| class="wikitable"
|+ Utility Library Date Functions
| Amiga2Date() || Calculate the date from the specified timestamp (in seconds).
|-
| CheckDate() || Check the legality of a date.
|-
| Date2Amiga() || Calculate the timestamp from the specified date.
|}

Amiga2Date() takes a number of seconds from 01-Jan-78 as argument and fills in the supplied ClockData structure with the date and time.

CheckDate() checks if the supplied ClockData structure is valid, and returns the number of seconds from 01-Jan-78 if it is. Note that this function currently does not take the supplied day of the week in account.

Date2Amiga() takes a ClockData structure as argument and returns the number of seconds since 01-Jan-78. The supplied ClockData structure ''must'' be valid, since no checking is done.

The following example shows various uses of the utility library date functions.

<syntaxhighlight>
// a2d.c
#include <exec/types.h>
#include <exec/memory.h>
#include <dos/datetime.h>
#include <devices/timer.h>

// Note these three libraries are opened by newlib startup code.
#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/utility.h>

#include <proto/timer.h>

struct TimerIFace *ITimer = NULL;

int main()
{
struct MsgPort *mp = IExec->AllocSysObject(ASOT_PORT, NULL);

if (mp != NULL)
{
struct TimeRequest *tr = IExec->AllocSysObjectTags(ASOT_IOREQUEST,
ASOIOR_Size, sizeof(struct TimeRequest),
ASOIOR_ReplyPort, mp,
TAG_END);

if (tr != NULL)
{
if (!IExec->OpenDevice("timer.device", UNIT_VBLANK, (struct IORequest *)tr, 0))
{
struct Library *TimerBase = (struct Library *)tr->Request.io_Device;
ITimer = (struct TimerIFace*)IExec->GetInterface(TimerBase, "main", 1, NULL);

if (ITimer != NULL)
{
struct TimeVal tv;
ITimer->GetSysTime(&tv);

IDOS->Printf("GetSysTime():\t%lu %lu\n", tv.Seconds, tv.Microseconds);

struct ClockData clockdata;
IUtility->Amiga2Date(tv.Seconds, &clockdata);

IDOS->Printf("Amiga2Date(): sec %lu min %lu hour %lu\n",
clockdata.sec, clockdata.min, clockdata.hour);

IDOS->Printf(" mday %lu month %lu year %lu wday %lu\n",
clockdata.mday, clockdata.month, clockdata.year, clockdata.wday);

uint32 seconds = IUtility->CheckDate(&clockdata);

IDOS->Printf("CheckDate():\t%lu\n", seconds);

seconds = IUtility->Date2Amiga(&clockdata);

IDOS->Printf("Date2Amiga():\t%lu\n", seconds);

IExec->DropInterface((struct Interface*)ITimer);
}

IExec->CloseDevice((struct IORequest *)tr);
}

IExec->FreeSysObject(ASOT_IOREQUEST, tr);
}

IExec->FreeSysObject(ASOT_PORT, mp);
}

return RETURN_OK;
}
</syntaxhighlight>

= Date Function Reference =

The following are brief descriptions of the utility library functions which pertain to date conversion. See the SDK for details on each function call.

{| class="wikitable"
! Function
! Description
|-
| CheckDate()
| Check the legality of a date.
|-
| Amiga2Date()
| Calculate the date from a specified timestamp.
|-
| Date2Amiga()
| Calculate the timestamp from a specified date.
|}

Date Functions

2020-05-17T21:08:53Z

Fredrik Wikstrom: Fixed to use struct TimeRequest instead of timerequest

= Date Functions =

To ease date-related calculations, the utility library has some functions to convert a date, specified in a ClockData structure, in the number of seconds since 00:00:00 01-Jan-78 and vice versa.

To indicate the date, the ClockData structure (in <utility/date.h>) is used.

<syntaxhighlight>
struct ClockData
{
UWORD sec; /* seconds (0 - 59) */
UWORD min; /* minutes (0 - 59) */
UWORD hour; /* hour (0 - 23) */
UWORD mday; /* day of the month (1 - 31) */
UWORD month; /* month of the year (1 - 12) */
UWORD year; /* 1978 - */
UWORD wday; /* day of the week (0 - 6, where 0 is Sunday) */
};
</syntaxhighlight>

The following functions are available to operate on ClockData:

{| class="wikitable"
|+ Utility Library Date Functions
| Amiga2Date() || Calculate the date from the specified timestamp (in seconds).
|-
| CheckDate() || Check the legality of a date.
|-
| Date2Amiga() || Calculate the timestamp from the specified date.
|}

Amiga2Date() takes a number of seconds from 01-Jan-78 as argument and fills in the supplied ClockData structure with the date and time.

CheckDate() checks if the supplied ClockData structure is valid, and returns the number of seconds from 01-Jan-78 if it is. Note that this function currently does not take the supplied day of the week in account.

Date2Amiga() takes a ClockData structure as argument and returns the number of seconds since 01-Jan-78. The supplied ClockData structure ''must'' be valid, since no checking is done.

The following example shows various uses of the utility library date functions.

<syntaxhighlight>
// a2d.c
#include <exec/types.h>
#include <exec/memory.h>
#include <dos/datetime.h>
#include <devices/timer.h>

// Note these three libraries are opened by newlib startup code.
#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/utility.h>

#include <proto/timer.h>

struct TimerIFace *ITimer = NULL;

int main()
{
struct MsgPort *mp = IExec->AllocSysObject(ASOT_PORT, NULL);

if (mp != NULL)
{
struct TimeRequest *tr = IExec->AllocSysObjectTags(ASOT_IOREQUEST,
ASOIOR_Size, sizeof(struct TimeRequest),
ASOIOR_ReplyPort, mp,
TAG_END);

if (tr != NULL)
{
if (!IExec->OpenDevice("timer.device", UNIT_VBLANK, (struct IORequest *)tr, 0))
{
struct Library *TimerBase = (struct Library *)tr->Request.io_Device;
ITimer = (struct TimerIFace*)IExec->GetInterface(TimerBase, "main", 1, NULL);

if (ITimer != NULL)
{
struct TimeVal tv;
ITimer->GetSysTime(&tv);

IDOS->Printf("GetSysTime():\t%d %d\n", tv.Seconds, tv.Microseconds);

struct ClockData clockdata;
IUtility->Amiga2Date(tv.Seconds, &clockdata);

IDOS->Printf("Amiga2Date(): sec %d min %d hour %d\n",
clockdata.sec, clockdata.min, clockdata.hour);

IDOS->Printf(" mday %d month %d year %d wday %d\n",
clockdata.mday, clockdata.month, clockdata.year, clockdata.wday);

int32 seconds = IUtility->CheckDate(&clockdata);

IDOS->Printf("CheckDate():\t%ld\n", seconds);

seconds = IUtility->Date2Amiga(&clockdata);

IDOS->Printf("Date2Amiga():\t%ld\n", seconds);

IEXec->DropInterface((struct Interface*)ITimer);
}

IExec->CloseDevice((struct IORequest *)tr);
}

IExec->FreeSysObject(ASOT_IOREQUEST, tr);
}

IExec->FreeSysObject(ASOT_PORT, mp);
}

return RETURN_OK;
}
</syntaxhighlight>

= Date Function Reference =

The following are brief descriptions of the utility library functions which pertain to date conversion. See the SDK for details on each function call.

{| class="wikitable"
! Function
! Description
|-
| CheckDate()
| Check the legality of a date.
|-
| Amiga2Date()
| Calculate the date from a specified timestamp.
|-
| Date2Amiga()
| Calculate the timestamp from a specified date.
|}

Date Functions

2020-05-17T21:03:55Z

Fredrik Wikstrom: Added missing message port allocation/freeing

= Date Functions =

To ease date-related calculations, the utility library has some functions to convert a date, specified in a ClockData structure, in the number of seconds since 00:00:00 01-Jan-78 and vice versa.

To indicate the date, the ClockData structure (in <utility/date.h>) is used.

<syntaxhighlight>
struct ClockData
{
UWORD sec; /* seconds (0 - 59) */
UWORD min; /* minutes (0 - 59) */
UWORD hour; /* hour (0 - 23) */
UWORD mday; /* day of the month (1 - 31) */
UWORD month; /* month of the year (1 - 12) */
UWORD year; /* 1978 - */
UWORD wday; /* day of the week (0 - 6, where 0 is Sunday) */
};
</syntaxhighlight>

The following functions are available to operate on ClockData:

{| class="wikitable"
|+ Utility Library Date Functions
| Amiga2Date() || Calculate the date from the specified timestamp (in seconds).
|-
| CheckDate() || Check the legality of a date.
|-
| Date2Amiga() || Calculate the timestamp from the specified date.
|}

Amiga2Date() takes a number of seconds from 01-Jan-78 as argument and fills in the supplied ClockData structure with the date and time.

CheckDate() checks if the supplied ClockData structure is valid, and returns the number of seconds from 01-Jan-78 if it is. Note that this function currently does not take the supplied day of the week in account.

Date2Amiga() takes a ClockData structure as argument and returns the number of seconds since 01-Jan-78. The supplied ClockData structure ''must'' be valid, since no checking is done.

The following example shows various uses of the utility library date functions.

<syntaxhighlight>
// a2d.c
#include <exec/types.h>
#include <exec/memory.h>
#include <dos/datetime.h>
#include <devices/timer.h>

// Note these three libraries are opened by newlib startup code.
#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/utility.h>

#include <proto/timer.h>

struct TimerIFace *ITimer = NULL;

int main()
{
struct MsgPort *mp = IExec->AllocSysObject(ASOT_PORT, NULL);

if (mp != NULL)
{
struct timerequest *tr = IExec->AllocSysObjectTags(ASOT_IOREQUEST,
ASOIOR_Size, sizeof(struct TimeRequest),
ASOIOR_ReplyPort, mp,
TAG_END);

if (tr != NULL)
{
if (!IExec->OpenDevice("timer.device", UNIT_VBLANK, (struct IORequest *)tr, 0))
{
struct Library *TimerBase = tr->tr_node.io_Device;
ITimer = (struct TimerIFace*)IExec->GetInterface(TimerBase, "main", 1, NULL);

if (ITimer != NULL)
{
struct TimeVal tv;
ITimer->GetSysTime(&tv);

IDOS->Printf("GetSysTime():\t%d %d\n", tv.Seconds, tv.Microseconds);

struct ClockData clockdata;
IUtility->Amiga2Date(tv.Seconds, &clockdata);

IDOS->Printf("Amiga2Date(): sec %d min %d hour %d\n",
clockdata.sec, clockdata.min, clockdata.hour);

IDOS->Printf(" mday %d month %d year %d wday %d\n",
clockdata.mday, clockdata.month, clockdata.year, clockdata.wday);

int32 seconds = IUtility->CheckDate(&clockdata);

IDOS->Printf("CheckDate():\t%ld\n", seconds);

seconds = IUtility->Date2Amiga(&clockdata);

IDOS->Printf("Date2Amiga():\t%ld\n", seconds);

IEXec->DropInterface((struct Interface*)ITimer);
}

IExec->CloseDevice((struct IORequest *)tr);
}

IExec->FreeSysObject(ASOT_IOREQUEST, tr);
}

IExec->FreeSysObject(ASOT_PORT, mp);
}

return RETURN_OK;
}
</syntaxhighlight>

= Date Function Reference =

The following are brief descriptions of the utility library functions which pertain to date conversion. See the SDK for details on each function call.

{| class="wikitable"
! Function
! Description
|-
| CheckDate()
| Check the legality of a date.
|-
| Amiga2Date()
| Calculate the date from a specified timestamp.
|-
| Date2Amiga()
| Calculate the timestamp from a specified date.
|}

IFFParse Library

2017-10-18T07:24:13Z

Fredrik Wikstrom: Fixed indentation.

== IFFParse Library ==

The ''iffparse.library'' was created to help simplify the job of parsing IFF files. Unlike other IFF libraries, iffparse.library is not form-specific. This means that the job of interpreting the structure and contents of the IFF file is up to you. Previous IFF file parsers were either simple but not general, or general but not simple. IFFParse tries to be both simple ''and'' general.

== The Structure of IFF Files ==

Many people have a misconception that IFF means image files. This is not the case. IFF (short for Interchange File Format) is a method of portably storing structured information in machine-readable form. The actual information can be anything, but the manner in which it is stored is very specifically detailed. This specification is the IFF standard.

The IFF standard was originally designed in 1985 by Electronic Arts in conjunction with a committee of developers. The full standard along with file descriptions and sample code is available at [[IFF_Standard|IFF Standard]].

The goal of the IFF standard is to allow customers to move their own data between independently developed software products. The types of data objects to exchange are open-ended and currently include plain and formatted text, raster and structured graphics, fonts, music, sound effects, musical instrument descriptions, and animation. IFF addresses these needs by defining a standard for self-identifying file structures and rules for accessing these files.

=== Chunks: The Building Blocks of IFF ===

IFF files contain various types and amounts of data grouped in data ''chunks'', each starting with a four-letter ASCII identifier (the chunk ID) followed by a 32-bit length count (the chunk size). The identifier and length count make it possible for IFF readers to skip over chunks that they don’t understand or don’t care about, and extract only the information they need. It may be helpful to think of these chunks as the building blocks of an IFF file.

[[File:LibFig33-1.png|frame|center|The Chunk - The Building Block of IFF]]

The ‘CKID’ (chunk ID) characters of a real chunk will be a four letter identifier such as ‘BODY’ or ‘CMAP’, specifying the type and format of data stored in the chunk. Most chunks contain a simple defined grouping of byte, word, and long variables similar to the contents of a C structure. Others such as sound sample and bitmap image body chunks, contain a stream of compressed data.

Chunk writing is fairly straightforward with the one caveat that all chunks must be word-aligned. Therefore an odd-length chunk must be followed by a pad byte of zero (which is not counted in the size of the chunk). When chunks are nested, the enclosing chunk must state the total size of its composite contents (including any pad bytes).

{{Note|title=About Chunk Length|text=Every IFF data chunk begins with a 4-character identifier field followed by a 32-bit size field (these 8 bytes are sometimes referred to as the chunk header). The size field is a count of the rest of the data bytes in the chunk, ''not'' including any pad byte. Hence, the total space occupied by a chunk is given by its size field (rounded to the nearest even number) + 8 bytes for the chunk header}}

=== Composite Data Types ===

Standard IFF files generally contain a variable number of chunks within one of the standard IFF composite data types (which may be thought of as chunks which contain other chunks). The IFF specification defines three basic composite data types, ‘FORM’, ‘CAT ’, and ‘LIST’. A special composite data type, the ‘PROP’, is found only inside a LIST.

Usage of Composite IFF Types

{| class="wikitable"
| FORM || A grouping of chunks which describe one set of data
|-
| LIST || A grouping of the same type of FORMs with shared properties in a PROP
|-
| PROP || May appear in a LIST to define chunks shared by several FORMs
|-
| CAT || A concatenation of related FORMs or LISTs
|}

The special IFF composite data types, like simple chunks, start with a 4-character identifier (such as ‘FORM’), followed by a 32-bit length. But their data begins with a second 4-character identifier that tells you what type of data is in the composite. For example, a FORM ILBM contains chunks describing a bitmap image, and a FORM FTXT contains chunks describing formatted text.

It may help to think of each composite data type as a box containing chunks, the IFF building blocks. The following figure shows a diagram of a typical composite.

[[File:LibFig33-2.png|frame|center|The FORM – The Most Common IFF File Type]]

The example FORM in the previous figure is outlined below showing the size of chunks within the FORM. Notice that the size of a composite ''includes'' its second 4-character identifier (shown below as ‘NAME’).

. FORM 72 NAME (72 is the size of the FORM starting with the “N” of NAME)
. . CKID 22 (then 22 bytes of data, so chunk header + chunk size is 30)
. . CKID 10 (then 10 bytes of data, so chunk header + chunk size is 18)
. . CKID 12 (then 12 bytes of data, so chunk header + chunk size is 20)

{{Note|text=In the example above, indentation represents the nesting of the chunks within the FORM. Real FORMs and chunks would have different four-character identifiers rather than ‘NAME’ and ‘CKID’.}}

Any odd-length chunks must have a pad byte of zero at the end of the chunk. As shown below, this pad byte is not counted in the size of the chunk but ''is'' counted in the size of any composite types (such as FORM) that contain an odd-length chunk. '''Warning:''' some IFF readers and writers do not deal with this properly.

. FORM 72 NAME (72 is the size of the FORM starting with the “N” of NAME)
. . CKID 21 (then 21 bytes of data, so chunk header + chunk size is 29)
. . 0 (pad byte of zero, size 1)
. . CKID 10 (then 10 bytes of data, so chunk header + chunk size is 18)
. . CKID 12 (then 12 bytes of data, so chunk header + chunk size is 20)

Most IFF files are of the composite type FORM. Generally, a FORM is a simple grouping of chunks that provide information about some data, and the data itself. Although some standard chunks have common usage within different FORMS, the identity and format of most chunks within a FORM are relative to the definition and specification of the FORM. For example, a CRNG chunk in a FORM ILBM may have a totally different format and contents than a chunk named CRNG in a different type of FORM.

One of the most popular IFF FORMs that has been defined is the ILBM standard. This is how most Amiga bitmap imagery is stored. Since this is the most common IFF file, it is used frequently as an example.

Here is the output of a program called “Sift.c” that displays a text description of the contents of an IFF file ([[#IFF Scanner Example|Sift.c]] is listed at the end of this article). The file shown below is a fairly simple ILBM.

. FORM 11068 ILBM
. . BMHD 20
. . CAMG 4
. . CMAP 12
. . BODY 10995

{{Note|title=Computing the Size of a FORM|text=The size of the FORM (11,068 bytes) is equal to the sum of the sizes stated in each chunk contained within the FORM, plus 8 bytes for the overhead of each chunk header (4 bytes for the 4-character chunk ID, and 4 bytes for the 32-bit chunk size), plus 4 bytes for the FORM’s own 4-character ID (‘ILBM’), plus 1 byte more for each pad byte that follow any odd-length chunks.}}

== Parsing an IFF File ==

Chunk reading requires a parser to scan each chunk and dispatch the proper access/conversion procedure. For a simple IFF file, such parsing may be relatively easy, consisting mainly reading in the data of desired chunks, and seeking over unwanted chunks (and the pad byte after odd-length chunks). Interpreting nested chunks is more complex, and requires a method for keeping track of the current context, i.e., the data which is still relevant at any particular depth into the nest. The original IFF specifications compare an IFF file to a C program. Such a metaphor can be useful in understanding the scope of of the chunks in an IFF file.

The IFFParse library addresses general IFF parsing requirements by providing a run-time library which can extract the chunks you want from an IFF file, with the ability to pass control to you when it reaches a chunk that requires special processing such as decompression. IFFParse also understands complex nested IFF formats and will keep track of the context for you.

=== Basic Functions and Structures of IFFParse Library ===

The structures and flags of the IFFParse library are defined in the include files <libraries/iffparse.h> and <libraries/iffparse.i>. IFF files are manipulated through a structure called an IFFHandle. Only some of the fields in the IFFHandle are publicly documented. The rest are managed internally by IFFParse. This handle is passed to all IFFParse functions, and contains the current parse state and position in the file. An IFFHandle is obtained by calling AllocIFF(), and freed through FreeIFF(). This is the only legal way to obtain and dispose of an IFFHandle.

The public portion of if IFFHandle is defined as follows:

<syntaxhighlight>
/*
* Structure associated with an active IFF stream.
* "iff_Stream" is a value used by the client's read/write/seek functions -
* it will not be accessed by the library itself and can have any value
* (could even be a pointer or a BPTR).
*/
struct IFFHandle {
ULONG iff_Stream;
ULONG iff_Flags;
LONG iff_Depth; /* Depth of context stack. */
/* There are private fields hiding here. */
};
</syntaxhighlight>

== Stream Management ==

A stream is a linear array of bytes that may be accessed sequentially or randomly. DOS files are streams. IFFParse uses Hook structures (defined in <utility/hooks.h>) to implement a general stream management facility. This allows the IFFParse library to read, write, and seek any type of file handle or device by using an application-provided hook function to open, read, write, seek and close the stream.

Built on top of this facility, IFFParse has two internal stream managers: one for unbuffered DOS files (AmigaDOS filehandles), and one for the Clipboard.

=== Initialization ===

As shown above, the IFFHandle structure contains the public field iff_Stream. This is a longword that must be initialized to contain something meaningful to the stream manager. IFFParse never looks at this field itself (at least not directly). Your iff_Stream may be an AmigaDOS filehandle, or an IFFParse ClipboardHandle, or a custom stream of any type if you provide your own custom stream handler (see the section on [[#Custom Stream Handlers|Custom Stream Handlers]]). You must initialize your IFFHandle structure’s iff_Stream to your stream, and then initialize the IFFHandle’s flags and stream hook.

Three sample initializations are shown here. In the case of the internal DOS stream manager, iff_Stream is an AmigaDOS filehandle as returned by Open():

<syntaxhighlight>
iff->iff_Stream = (ULONG) IDOS->Open ("filename", MODE_OLDFILE);
if(iff->iff_Stream) IIFFParse->InitIFFasDOS (iff); /* use internal DOS stream manager */
</syntaxhighlight>

In the case of the internal Clipboard stream manager, iff_Stream is a pointer to an IFFParse ClipboardHandle structure (the OpenClipboard() call used here is a function of iffparse.library, not the clipboard.device):

<syntaxhighlight>
iff->iff_Stream = (ULONG) IIFFParse->OpenClipboard (PRIMARY_CLIP);
IIFFParse->InitIFFasClip (iff); /* use internal Clipboard stream manager */
</syntaxhighlight>

When using a custom handle such as an fopen() file handle, or a device other than the clipboard, you must provide your own flags and stream handler:

<syntaxhighlight>
iff->iff_Stream = (ULONG) OpenMyCustomStream("foo");
IIFFParse->InitIFF (iff, IFFF_FSEEK | IFFF_RSEEK, &mystreamhook);
</syntaxhighlight>

IFFParse “knows” the seek capabilities of DOS and ClipboardHandle streams, so InitIFFasDOS() and InitIFFasClip() set the flags for you.

{{Note|title=You May Change the Seek Bits in iff_Flags|text=IFFParse sets IFFF_FSEEK | IFFF_RSEEK for DOS files. This is not always true (e.g., pipes). If you know that a DOS file has different seek characteristics, your application may correct the seek bits in iff_Flags after calling InitIFFasDOS().}}

When using InitIFF() to provide a custom handler, you must also provide flags to tell IFFParse the capabilities of your stream. The flags are:

; IFFF_FSEEK
: This stream has forward-seek capability only.

; IFFF_RSEEK
: This stream has random-seek capability. IFFF_RSEEK tends to imply IFFF_FSEEK, but it’s best to specify both.

If neither flag is specified, you’re telling IFFParse that it can’t seek through the stream.

After your stream is initialized, call OpenIFF():

<syntaxhighlight>
error = IIFFParse->OpenIFF (iff, IFFF_READ);
</syntaxhighlight>

Once you establish a read/write mode (by passing IFFF_READ or IFFF_WRITE), you remain in that mode until you call CloseIFF().

=== Termination ===

Termination is simple. Just call CloseIFF(iff). This may be called at any time, and terminates IFFParse’s transaction with the stream. The stream itself is not closed. The IFFHandle may be reused; you may safely call OpenIFF() on it again. You are responsible for closing the streams you opened. A stream used in an IFFHandle must generally remain open until you CloseIFF().

=== Custom Streams ===

A custom stream handler can allow you (and iffparse.library) to use your compiler’s own file I/O functions such as fopen(), fread() and fwrite(), rather than the lower-level AmigaDOS equivalents Open(), Read(), and Write(). A custom stream handler could also be used to read or write IFF files from an Exec device or an unusual handler or file system.

If you install your own stream handler function, iffparse.library will call your function whenever it needs to read, write, or seek on your file. Your stream handler function will then perform these stream actions for iffparse.library. See the “Custom Stream Handlers” section for more information on custom stream handlers.

== Parsing and Writing IFF ==

For information on parsing IFF see [[Parsing_IFF|Parsing IFF]].

For information on writing IFF see [[Writing_IFF|Writing IFF]].

== Context Functions ==

Internally, IFFParse maintains IFF nesting and scoping context via a ''context stack''. The PushChunk() and PopChunk() functions get their names from this basic idea of the iffparse.library. Direct access to this stack is not allowed. However, many functions are provided to assist in examining and manipulating the context stack.

{{Note|title=About the Context Stack|text=It is probably easier to think of a stack of blocks on a table in front of you when reading this discussion.}}

As the nesting level increases (as would happen when parsing a nested LIST or FORM), the depth of the context stack increases; new elements are added to the top. When these contexts expire, the ContextNodes are deleted and the stack shrinks.

=== Context Nodes ===

The current context is said to be the top element on the stack. Contextual information is stored in a structure called a ContextNode:

<syntaxhighlight>
struct ContextNode {
struct MinNode cn_Node;
LONG cn_ID;
LONG cn_Type;
LONG cn_Size; /* Size of this chunk */
LONG cn_Scan; /* # of bytes read/written so far */
/* There are private fields hiding here. */
};
</syntaxhighlight>

==== CurrentChunk() ====

You can obtain a pointer to the current ContextNode through the function CurrentChunk():

<syntaxhighlight>
currentnode = IIFFParse->CurrentChunk (iff);
</syntaxhighlight>

The ContextNode tells you the type, ID, and size of the currently active chunk. If there is no currently active context, NULL is returned.

==== ParentChunk() ====

To find the parent of a context, you call ParentChunk() on the relevant ContextNode:

<syntaxhighlight>
parentnode = IIFFParse->ParentChunk(currentnode);
</syntaxhighlight>

If there is no parent context, NULL is returned.

=== The Default Context ===

When you first obtain an IFFHandle through AllocIFF(), a hidden default context node is created. You cannot get direct access to this node through CurrentChunk() or ParentChunk(). However, using StoreLocalItem(), you can store information in this context.

=== Context-Specific Data: LocalContextItems ===

ContextNodes can contain application data specific to that context. These data objects are called LocalContextItems. LocalContextItems (LCIs) are a grey-box structure which contain a type, ID and identification field. LCIs are used to store context-sensitive data. The format of this data is application-defined. A ContextNode can contain as many LCIs as you want.

[[File:LibFig33-3.png|frame|center|IFFParse Context Stack]]

The previous figure shows the relationship between the IFFHandle, the ContextNodes, and the LCIs. The IFFHandle is the root of the tree, so to speak. ContextNodes “grow” out of the IFFHandle. In turn, LCIs "grow" out of the ContextNodes. What grows out of an LCI is client-defined.

==== AllocLocalItem() ====

To create an LCI, you use the function AllocLocalItem():

<syntaxhighlight>
lci = IIFFParse->AllocLocalItem (type, id, ident, datasize);
</syntaxhighlight>

If successful, you will be returned a pointer to an LCI having the specified type, ID, and identification values; and with datasize bytes of buffer space for your application to use.

==== LocalItemData() ====

To get a pointer to an LCIs data buffer, you use LocalItemData():

<syntaxhighlight>
buf = IIFFParse->LocalItemData (lci);
</syntaxhighlight>

You may read and write the buffer to your heart’s content; it is yours. You should not, however, write beyond the end of the buffer. The size of the buffer is what you asked for when you called AllocLocalItem().

=== Storing LCIs ===

Once you’ve created and initialized an LCI, you’ll want to attach it to a ContextNode. Though a ContextNode can have many LCIs, a given LCI can be linked to only one ContextNode. Once linked, an LCI cannot be removed from a ContextNode (this may change in the future). Storing an LCI in a ContextNode is done with the functions StoreLocalItem() and StoreItemInContext().

==== StoreLocalItem() ====

The StoreLocalItem() function is called as follows:

<syntaxhighlight>
error = StoreLocalItem (iff, lci, position);
</syntaxhighlight>

The position argument determines where the LCI is stored. The possible values are IFFSLI_ROOT, IFFSLI_TOP, and IFFSLI_PROP.

; IFFSLI_ROOT
: causes StoreLocalItem() to store your LCI in the default ContextNode.

; IFFSLI_TOP
: gets your LCI stored in the top (current) ContextNode.

{{Note|title=The LCI Ends When the Current Context Ends|text=When the current context expires, your LCI will be deleted by the parser.}}

IFFSLI_PROP causes your LCI to be stored in the topmost context from which a property would apply. This is usually the topmost FORM or LIST chunk. For example, suppose you had a deeply nested ILBM FORM, and you wanted to store the BMHD property in its correct context such that, when the current FORM context expired, the BMHD property would be deleted. IFFSLI_PROP will cause StoreLocalItem() to locate the proper context for such scoping, and store the LCI there. See the section on "Finding the Prop Context" for additional information on the scope of properties.

==== StoreItemInContext() ====

StoreItemInContext() is used when you already have a pointer to the ContextNode to which you want to attach your LCI. It is called like so:

<syntaxhighlight>
IIFFParse->StoreItemInContext (iff, lci, contextnode);
</syntaxhighlight>

StoreItemInContext() links your LCI into the specified ContextNode. Then it searches the ContextNode to see if there is another LCI with the same type, ID, and identification values. If so, the old one is deleted.

==== FindLocalItem() ====

After you’ve stored your LCI in a ContextNode, you will no doubt want to be able to find it again later. You do this with the function FindLocalItem(), which is called as follows:

<syntaxhighlight>
lci = IIFFParse->FindLocalItem (iff, type, id, ident);
</syntaxhighlight>

FindLocalItem() attempts to locate an LCI having the specified type, ID, and identification values. The search proceeds as follows (refer to the previous figure to understand this better).

FindLocalItem() starts at the top (current) ContextNode and searches all LCIs in that context. If no matching LCIs are found, it proceeds down the context stack to the next ContextNode and searches all its LCIs. The process repeats until it finds the desired LCI (whereupon it returns a pointer to it), or reaches the end without finding anything (where it returns NULL).

{{Note|title=Context Stack Position|text=LCIs higher in the stack will "override" lower LCIs with the same type, ID, and identification field. This is how property scoping is handled. As ContextNodes are popped off the context stack, all its LCIs are deleted as well. See the section on “Freeing LCIs” below for additional information on deleting LCIs.}}

=== Some Interesting Internal Details ===

{{Note|title=Warning|text=This section details some internal implementation details of iffparse.library which may help you to understand it better. Use of the following information to do “clever” things in an application is forbidden and unsupportable. Don’t even think about it.}}

It turns out that StoredProperties, CollectionItems, and entry and exit handlers are all implemented using LCIs. For example, when you call FindProp(), you are actually calling a front-end to FindLocalItem(). The mysterious identification value (which has heretofore never been discussed) is a value which permits you to differentiate between LCIs having the same type and ID.

For instance, suppose you called PropChunk(), asking it to store an ILBM BMHD. PropChunk() will install an entry handler in the form of an LCI, having type equal to ‘ILBM’, ID equal to ‘BMHD’, and an identification value of IFFLCI_ENTRYHANDLER.

When an ILBM BMHD is encountered, the entry handler is called, and it creates and stores another LCI having type equal to ‘ILBM’, ID equal to ‘BMHD’ and an identification value of IFFLCI_PROP.

Thus, when you call FindProp(), it merely calls FindLocalItem() with your type and ID, and supplies IFFLCI_PROP for the identification value.

Therefore, handlers, StoredProperties, CollectionItems and your own custom LCIs can never be confused with each other, since they all have unique identification values. Since they are all handled (and searched for) in the same way, they all “override” each other in a consistent way. Just as StoredProperties higher in the context stack will be found and returned before identical ones in lower contexts, so will chunk handlers be found and invoked before ones lower on the context stack (recall FindLocalItem()’s search procedure).

This means you can temporarily override a chunk handler by installing an identical handler in a higher context. The handler will persist until the context in which it is stored expires, after which, the original one regains scope.

== Error Handling ==

If at any time during reading or writing you encounter an error, the IFFHandle is left in an undefined state. Upon detection of an error, you should perform an abort sequence and CloseIFF() the IFFHandle. Once CloseIFF() has been called, the IFFHandle is restored to normalcy and may be reused.

== Advanced Topics ==

This section discusses customizing of IFFParse data handling. For applications with special needs, IFFParse supports both custom stream handlers and custom chunk handlers.

=== Custom Stream Handlers ===

As discussed earlier, IFFParse contains built-in stream handlers for AmigaDOS file handles as returned by Open(), and for the clipboard.device. If you are using AmigaDOS filehandles or the clipboard.device, you need not supply a custom stream handler.

If you wish to use your compiler’s own file I/O functions (such as fread() ) or need to read or write to an unusual handler or Exec device, you must provide a custom stream handler for your IFFHandle. Your custom stream handler will be called to perform all reads, writes, and seeks on your custom stream. The allows you to use compiler file I/O functions, Exec device commands, or any other method to perform the requested stream operations.

If you are implementing your own custom stream handler, you will need to know the mechanics of hook call-backs, and how to interpret the parameters. An IFFParse custom stream handler is simply a function in your code that follows hook function conventions (Hook functions are also known as callback functions. See [[Utility_Library|Utility Library]] for more details).

==== Installing a Custom Stream Handler ====

To initialize your IFFHandle to point to your custom stream and stream handler, you must open your stream and place a pointer to the stream in your IFFHandle’s iff_Stream field. This pointer could be the return from fopen(), or an Exec device I/O request, or any other type of pointer which will provide your custom stream handler with a way to manage your stream. For example:

<syntaxhighlight>
iff->iff_Stream = (ULONG) fopen("foo");
</syntaxhighlight>

Next, you must install your custom handler for this stream, and also tell IFFParse the seek capabilities of your stream. To install your custom stream handler, you must first set up a Hook structure (<utility/hooks.h>) to point to your stream handling function. Then use InitIFF() to install your stream handler and also tell IFFParse the seek capabilities of your stream. There is “some assembly required”.

For an IFFParse custom stream hook the function prototype looks like this:

<syntaxhighlight>
int32 mystreamhandler(struct Hook *hook, struct IFFHandle *iff, struct IFFStreamCmd *actionpkt);
</syntaxhighlight>

A return of 0 indicates success. A non-zero return indicates an error.

For example,

<syntaxhighlight>
static int32 mystreamhandler
(
struct Hook *hook,
struct IFFHandle *iff,
struct IFFStreamCmd *actionpkt
)
{
/*
* Code to handle the stream commands - see end this section
* for a complete example custom stream handler function.
*
*/
}

/* Initialization of Hook structure for registerized handler function */
struct Hook mystreamhook
{
{ NULL },
(HOOKFUNC) mystreamhandler, /* h_Entry, registerized function entry */
NULL,
NULL
};

/* Open custom stream and InitIFF to custom stream handler */
if ( iff->iff_Stream = (ULONG) myopen("foo") )
{
IIFFParse->InitIFF (iff, IFFF_FSEEK | IFFF_RSEEK, &mystreamhook);
}
</syntaxhighlight>

==== Inside a Custom Stream Handler ====

When the library calls your stream handler, you’ll be passed a pointer to the Hook structure (hook in the example used here), a pointer to the IFFHandle (iff), and a pointer to an IFFStreamCmd structure (actionpkt). Your stream pointer may be found in iff->iff_Stream where you previously stored it. The IFFStreamCmd (actionpkt) will describe the action that IFFParse needs you to perform on your stream:

<syntaxhighlight>
/* Custom stream handler is passed struct IFFStreamCmd *actionpkt */
struct IFFStreamCmd {
LONG sc_Command; /* Operation to be performed (IFFCMD_) */
APTR sc_Buf; /* Pointer to data buffer */
LONG sc_NBytes; /* Number of bytes to be affected */
};

/* Possible call-back command values. (Using 0 as the value for IFFCMD_INIT
* was, in retrospect, probably a bad idea.)
*/
#define IFFCMD_INIT 0 /* Prepare the stream for a session */
#define IFFCMD_CLEANUP 1 /* Terminate stream session */
#define IFFCMD_READ 2 /* Read bytes from stream */
#define IFFCMD_WRITE 3 /* Write bytes to stream */
#define IFFCMD_SEEK 4 /* Seek on stream */
#define IFFCMD_ENTRY 5 /* You just entered a new context */
#define IFFCMD_EXIT 6 /* You're about to leave a context */
#define IFFCMD_PURGELCI 7 /* Purge a LocalContextItem */
</syntaxhighlight>

Your custom stream handler should perform the requested action on your custom stream, and then return 0 for success or an IFFParse error if an error occurred. The following code demonstrates a sample stream handler for a stream which was opened with a compiler’s fopen() buffered file I/O function:

<syntaxhighlight>
static int32 mystreamhandler ( struct Hook *hook,
struct IFFHandle *iff,
struct IFFStreamCmd *actionpkt )
{
FILE *stream;
int32 nbytes, error;
uint8 *buf;

stream = (FILE *) iff->iff_Stream; /* get your stream pointer */
nbytes = actionpkt->sc_NBytes; /* length for command */
buf = (uint8 *) actionpkt->sc_Buf; /* buffer for the command */

/* Now perform the action specified by the actionpkt->sc_Command */

switch (actionpkt->sc_Command) {
case IFFCMD_READ:
/*
* IFFCMD_READ means read sc_NBytes from the stream and place
* it in the memory pointed to by sc_Buf. Be aware that
* sc_NBytes may be larger than can be contained in an int.
* This is important if you plan on recompiling this for
* 16-bit ints, since fread() takes int arguments.
*
* Any error code returned will be remapped by IFFParse into
* IFFERR_READ.
*/
error = (fread (buf, 1, nbytes, stream) != nbytes);
break;

case IFFCMD_WRITE:
/*
* IFFCMD_WRITE is analogous to IFFCMD_READ.
*
* Any error code returned will be remapped by IFFParse into
* IFFERR_WRITE.
*/
error = (fwrite (buf, 1, nbytes, stream) != nbytes);
break;

case IFFCMD_SEEK:
/*
* IFFCMD_SEEK asks that you performs a seek relative to the
* current position. sc_NBytes is a signed number,
* indicating seek direction (positive for forward, negative
* for backward). sc_Buf has no meaning here.
*
* Any error code returned will be remapped by IFFParse into
* IFFERR_SEEK.
*/
error = (fseek (stream, nbytes, 1) == -1);
break;

case IFFCMD_INIT:
/*
* IFFCMD_INIT means to prepare your stream for reading.
* This is used for certain streams that can't be read
* immediately upon opening, and need further preparation.
* This operation is allowed to fail; the error code placed
* in D0 will be returned directly to the client.
*
* An example of such a stream is the clipboard. The
* clipboard.device requires you to set the io_ClipID and
* io_Offset to zero before starting a read. You would
* perform such a sequence here. (Stdio files need no such
* preparation, so we simply return zero for success.)
*/
case IFFCMD_CLEANUP:
/*
* IFFCMD_CLEANUP means to terminate the transaction with
* the associated stream. This is used for streams that
* can't simply be closed. This operation is not allowed to
* fail; any error returned will be ignored.
*
* An example of such a stream is (surprise!) the clipboard.
* It requires you to explicitly end reads by CMD_READing
* past the end of a clip, and end writes by sending a
* CMD_UPDATE. You would perform such a sequence here.
* (Again, stdio needs no such sequence.)
*/
error = 0;
break;
}
return (error);
}
</syntaxhighlight>

=== Custom Chunk Handlers ===

Like custom stream handlers, custom chunk handlers are implemented using Hook structures. See the previous section for details on how a handler function may be interfaced using a Hook structure.

There are two types of chunk handlers: entry handlers and exit handlers. Entry handlers are invoked just after the parser enters the chunk; the stream will be positioned to read the first byte in the chunk. (If the chunk is a FORM, LIST, CAT, or PROP, the longword type will be read by the parser; the stream will be positioned to read the byte immediately following the type.) Exit handlers are invoked just before the parser leaves the chunk; the stream is not positioned predictably within the chunk.

==== Installing a Custom Chunk Handler ====

To install an entry handler, you call EntryHandler() in the following manner:

<syntaxhighlight>
error = IIFFParse->EntryHandler (iff, type, id, position, hookptr, object);
</syntaxhighlight>

An exit handler is installed by saying:

<syntaxhighlight>
error = IIFFParse->ExitHandler (iff, type, id, position, hookptr, object);
</syntaxhighlight>

In both cases, a handler is installed for chunks having the specified type and id. The position argument specifies in what context to install the handler, and is identical to the position argument used by StoreLocalItem(). The hookptr argument given above is a pointer to your Hook structure.

==== Inside a Custom Chunk Handler ====

The mechanics of receiving parameters through the Hook are covered in the “Custom Stream Handlers” section, and are not duplicated here. Refer to the EntryHandler() and ExitHandler() Autodocs for the contents of the registers upon entry.

Once inside your handler, you can call nearly all functions in the iffparse.library, however, you should avoid calling ParseIFF() from within chunk handlers.

Your handler runs in the same environment as whoever called ParseIFF(). The propagation sequence is:

'''mainline''' --''calls''--> '''ParseIFF()''' --''calls''--> '''your_handler()'''

Thus, your handler runs on your mainline’s stack, and can call any OS functions the mainline code can. (Your handler will have to set the global base pointer if your code uses base-relative addressing.)

The return code will affect the parser in a number of ways:

* If you return zero (a normal, uneventful return), ParseIFF() will continue normally. If you return the value IFFERR_RETURN2CLIENT, ParseIFF() will stop and return the value zero to the mainline code.

* If you return any other value, ParseIFF() will stop and return that value to the mainline code. This is how you should return error conditions to the client code.

==== The Object Parameter ====

The object parameter supplied to EntryHandler() and ExitHandler() is a pointer which will be passed to your handler when invoked. This pointer can be anything; the parser doesn’t use it directly. As an example, you might pass the pointer to the IFFHandle. This way, when your handler is called, you’ll be able to easily perform operations on the IFFHandle within your handler. Such code might appear as follows:

<syntaxhighlight>
error = EntryHandler (iff, ID_ILBM, ID_BMHD, IFFSLI_ROOT, hook, iff);
</syntaxhighlight>

And your handler would be declared as follows:

<syntaxhighlight>
int32 MyHandler (struct Hook *hook,
int32 *cmd,
struct IFFHandle *iff)

</syntaxhighlight>

From within your handler, you could then call CurrentChunk(), ReadChunkBytes(), or nearly any other operation on the IFFHandle. Please refer to the EntryHandler() and ExitHandler() Autodocs for additional information on the use of chunk handlers.

=== Finding the Prop Context ===

Earlier it was mentioned that supplying a position value of IFFSLI_PROP to StoreLocalItem() would store it in the topmost property scope. FindPropContext() is the routine that finds that topmost context.

Property chunks (such as the BMHD, CMAP, and others) have dominion over the FORM that contains them; they are said to be “in scope” and their definition persists until the FORM’s context ends. Thus, a property chunk has a scoping level equal to the FORM that contains it; when the FORM ends, the property dies with it.

Consider a more complicated example. Suppose you have a LIST with a PROP in it. PROPs are the global variables of LISTs; thus a property chunk declared in a PROP will persist until the LIST’s context ends.

This is what FindPropContext() is looking for; a context level in which a property chunk may be installed.

FindPropContext() starts at the parent of the current context (second from the top of the context stack) and starts searching downward, looking for the first FORM or LIST context it finds. If it finds one, it returns a pointer to that ContextNode. If it can’t find a suitable context level, it returns NULL.

FindPropContext() is called as follows:

<syntaxhighlight>
struct ContextNode *cn = IFFParse->FindPropContext (iff);
</syntaxhighlight>

=== Freeing LCIs ===

Ordinarily, the parser will automatically delete LCIs you have allocated and installed. However, you may have a case where simply FreeVec()ing your LCI is not enough; you may need to free some ancillary memory, or decrement a counter, or send a signal, or something. This is where SetLocalItemPurge() comes in. It is called as follows:

<syntaxhighlight>
IFFParse->SetLocalItemPurge (lci, hookptr);
</syntaxhighlight>

When the parser is ready to delete your LCI, your purge handler code will be called through the Hook you supplied. You can then perform all your necessary operations. One of these operations should be to free the LCI itself. This is done with FreeLocalItem():

<syntaxhighlight>
IIFFParse->FreeLocalItem (lci);
</syntaxhighlight>

This deallocates the memory used to store the LCI and the client buffer allocated with it. FreeLocalItem() is only called as part of a custom purge handler.

As with custom chunk handlers, your purge handler executes in the same environment as the mainline code that called ParseIFF(). It is recommended that you keep purge handlers short and to the point; super clever stuff should be reserved for custom chunk handlers, or for the client’s mainline code. Custom purge handlers must ''always'' work; failures will be ignored.

== IFF FORM Specifications ==

The specifications for Amiga IFF formats are maintained by the AmigaOS Development Team. The latest specifications are published in the [[IFF_Standard|IFF Standard]]. Updates of the IFF Manual, selected new FORMs and changes to existing FORMs are documented on this wiki.

Some of the most commonly used IFF FORMs are the four that were originally specified in the EA IFF-85 standard:

{| class="wikitable"
| ILBM || Bitmap images and palettes
|-
| FTXT || Simple formatted text
|-
| SMUS || Simple musical scores
|-
| 8SVX || 8-bit sound samples
|}

Of these four, ILBM is the most commonly encountered FORM, and FTXT is becoming increasingly important since the ''conclip'' command passes clipped console text through the clipboard as FTXT. All data clipped to the clipboard must be in an IFF format.

This section will provide a brief summary of the ILBM and FTXT FORMs and their most used common chunks. Please consult the EA-IFF specifications for additional information.

=== FORM ILBM ===

The IFF file format for graphic images on the Amiga is called FORM ILBM (InterLeaved BitMap). It follows a standard parsable IFF format.

==== ILBM.BMHD BitMapHeader Chunk ====

The most important chunk in a FORM ILBM is the BMHD (BitMapHeader) chunk which describes the size and compression of the image:

<syntaxhighlight>
typedef UBYTE Masking; /* Choice of masking technique - Usually 0. */
#define mskNone 0
#define mskHasMask 1
#define mskHasTransparentColor 2
#define mskLasso 3

/* Compression algorithm applied to the rows of all source
* and mask planes. "cmpByteRun1" is byte run encoding.
* Do not compress across rows! Compression is usually 1.
*/
typedef UBYTE Compression;
#define cmpNone 0
#define cmpByteRun1 1

/* The BitMapHeader structure expressed as a C structure */
typedef struct {
UWORD w, h; /* raster width & height in pixels */
WORD x, y; /* pixel position for this image */
UBYTE nPlanes; /* # bitplanes (without mask, if any) */
Masking masking; /* One of the values above. Usually 0 */
Compression compression;/* One of the values above. Usually 1 */
UBYTE reserved1; /* reserved; ignore on read, write as 0 */
UWORD transparentColor; /* transparent color number. Usually 0 */
UBYTE xAspect, yAspect; /* pixel aspect, a ratio width : height */
WORD pageWidth, pageHeight; /* source "page" size in pixels */
} BitMapHeader;
</syntaxhighlight>

{{Note|title=Warning|text=This hex dump is shown only to help the reader understand how IFF chunks appear in a file. You cannot ever depend on any particular ILBM chunk being at any particular offset into the file. IFF files are composed, in their simplest form, of chunks within a FORM. Each chunk starts with a 4-letter chunkID, followed by a 32-bit length of the rest of the chunk. You must ''parse'' IFF files, skipping past unneeded or unknown chunks by seeking their length (+1 if odd length) to the next 4-letter chunk ID. In a real ILBM file, you are likely to encounter additional optional chunks. See the IFF Specification listed in [[IFF_Standard|IFF Standard]] for additional information on such chunks.}}

<pre>
0000: 464F524D 00016418 494C424D 424D4844 FORM..d.ILBMBMHD
0010: 00000014 01400190 00000000 06000100 .....@..........
0020: 00000A0B 01400190 43414D47 00000004 .....@..CAMG....
0030: 00000804 434D4150 00000030 001000E0 ....CMAP...0....
0040: E0E00000 20000050 30303050 50500030 .... ..P000PPP.0
0050: 90805040 70707010 60E02060 E06080D0 ..P@ppp.`. `.`..
0060: A0A0A0A0 90E0C0C0 C0D0A0E0 424F4459 ............BODY
0070: 000163AC F8000F80 148A5544 2ABDEFFF ..c.......UD*... etc.

Interpretation:

'F O R M' length 'I L B M''B M H D'<-start of BitMapHeader chunk
0000: 464F524D 00016418 494C424D 424D4844 FORM..d.ILBMBMHD

length WideHigh XorgYorg PlMkCoRe <- Planes Mask Compression Reserved
0010: 00000014 01400190 00000000 06000100 .....@..........

TranAspt PagwPagh 'C A M G' length <- start of C-AMiGa View modes chunk
0020: 00000A0B 01400190 43414D47 00000004 .....@..CAMG....

dir include:
ViewMode 'C M A P' length R g b R <- ViewMode 800=HAM | 4=LACE
0030: 00000804 434D4150 00000030 001000E0 ....CMAP...0....

g b R g b R g b R g b R g b R g <- Rgb's are for reg0 thru regN
0040: E0E00000 20000050 30303050 50500030 .... ..P000PPP.0

b R g b R g b R g b R g b R g b
0050: 90805040 70707010 60E02060 E06080D0 ..P@ppp.`. `.`..

R g b R g b R g b R g b 'B O D Y'
0060: A0A0A0A0 90E0C0C0 C0D0A000 424F4459 ............BODY

length start of body data <- Compacted (Compression=1 above)
0070: 000163AC F8000F80 148A5544 2ABDEFFF ..c.......UD*...
0080: FFBFF800 0F7FF7FC FF04F85A 77AD5DFE ...........Zw.]. etc.

Simple CAMG ViewModes: HIRES=0x8000 LACE=0x4 HAM=0x800 HALFBRITE=0x80

( ILBMs may contain a LONGWORD ViewPort ModeID in CAMG )
</pre>

==== Interpreting ILBMs ====

ILBM is a fairly simple IFF FORM. All you really need to deal with to extract the image are the following chunks:

Information about the size, depth, compaction method (see interpreted hex dump above).

Optional Amiga ViewModes chunk. Most HAM and HALFBRITE ILBMs should have this chunk. If no CAMG chunk is present, and image is 6 planes deep, assume HAM and you’ll probably be right. Some Amiga ViewModes flags are HIRES=0x8000, LACE=0x4, HAM=0x800, HALFBRITE=0x80. 2.0 ILBM writers should write a full 32-bit mode ID in the CAMG. See the IFF Manual for more information on writing and interpreting 32-bit CAMG values.

RGB values for color registers 0 to N. Previously, 4-bit RGB components each left justified in a byte. These should now be stored as a full 8-bit RGB values by duplicating 4-bit values in the high and low nibble of the byte.

The pixel data, stored in an interleaved fashion as follows (each line individually compacted if BMHD Compression = 1):

<pre>
plane 0 scan line 0
plane 1 scan line 0
plane 2 scan line 0
...
plane n scan line 0
plane 0 scan line 1
plane 1 scan line 1
etc.
</pre>

Also watch for AUTH Author chunks and (c) copyright chunks and preserve any copyright information if you rewrite the ILBM.

==== ILBM BODY Compression ====

The BODY contains pixel data for the image. Width, Height, and depth (Planes) is specified in the BMHD.

If the BMHD Compression byte is 0, then the scan line data is not compressed. If Compression=1, then each scan line is individually compressed as follows:

<pre>while (not produced the desired number of bytes)

/* get a byte, call it N */

if (N >= 0 && N <= 127)
/* copy the next N+1 bytes literally */

if (N >= -127 && N <= -1)
/* repeat the next byte N+1 times */

if (N == -128)
/* skip it, presumably it's padding */</pre>
==== Interpreting the Scan Line Data ====

If the ILBM is not HAM or HALFBRITE, then after parsing and uncompacting if necessary, you will have N planes of pixel data. Color register used for each pixel is specified by looking at each pixel thru the planes. For instance, if you have 5 planes, and the bit for a particular pixel is set in planes 0 and 3:

<pre>
PLANE 4 3 2 1 0
PIXEL 0 1 0 0 1
</pre>

then that pixel uses color register binary 01001 = 9.

The RGB value for each color register is stored in the CMAP chunk of the ILBM, starting with register 0, with each register’s RGB value stored as one byte of R, one byte G, and one byte of B, with each component left justified in the byte. (i.e. Amiga R, G, and B components are each stored in the high nibble of a byte)

But, if the picture is HAM or HALFBRITE, it is interpreted differently. Hopefully, if the picture is HAM or HALFBRITE, the package that saved it properly saved a CAMG chunk (look at a hex dump of your file with ASCII interpretation - you will see the chunks - they all start with a 4-ASCII-char chunk ID). If the picture is 6 planes deep and has no CAMG chunk, it is probably HAM. If you see a CAMG chunk, the ‘CAMG’ is followed by the 32-bit chunk length, and then the 32-bit Amiga view mode flags.

HAM pictures will have the 0x800 bit set in CAMG chunk ViewModes. HALFBRITE pictures will have the 0x80 bit set. See the graphics library articles for more information on HAM and HALFBRITE modes.

==== Other ILBM Notes ====

Amiga ILBMs images must be stored as an even number of bytes in width. However, the ILBM BMHD field w (width) should describe the actual image width, not the rounded up width as stored.

ILBMs created with Electronic Arts IBM or Amiga ''Deluxe Paint II'' packages are compatible (though you may have to use a ‘.lbm’ filename extension on an IBM). The ILBM graphic files may be transferred between the machines (or between the Amiga and IBM sides your Amiga if you have a CBM Bridgeboard card installed) and loaded into either package.

=== FORM FTXT ===

The FTXT (Formatted TeXT) form is the standard format for sharing text on the Amiga. The console device clip and paste functions, in conjunction with the startup-sequence ''conclip'' command, pass clipped console text through the clipboard as FTXT.

By supporting reading and writing of clipboard device FTXT, your application will allow users to cut and paste text between your application, other applications, and Amiga Shell windows.

The FTXT form is very simple. Generally, for clip and paste operations, you will only be concerned with the CHRS (character string) chunks of an FTXT. There may be one or more CHRS chunks, each of which contains a non-NULL-terminated string of ASCII characters whose length is equal to the length (StoredProperty.sp_Size) of the chunk.

Be aware that if you CollectionChunk() the CHRS chunks of an FTXT, the list accumulated by IFFParse will be in reverse order from the chunk order in the file. See the ClipFTXT.c example at the end of this article for a simple example of reading (and optionally writing) FTXT to and from the clipboard. See also the [[Clipboard_Device|Clipboard Device]] and [[Console_Device|Console Device]] for more information on console clip and paste.

== IFFParse Examples ==

Two examples follow: “ClipFTXT.c” and “Sift.c”. These are simple examples that demonstrate the use of the IFFParse library. More complex examples for displaying and saving ILBMs may be found in the [[IFF_Standard|IFF Standard]] section.

=== Clipboard FTXT Example ===

ClipFTXT.c demonstrates reading (and optional writing) of clipboard device FTXT. This example may be used as the basis for supporting console pastes.

<syntaxhighlight>
/*
*
* clipftxt.c: Writes ASCII text to clipboard unit as FTXT
* (All clipboard data must be IFF)
*
* Usage: clipftxt unitnumber
*
* To convert to an example of reading only, comment out #define WRITEREAD
*/

#include <exec/types.h>
#include <exec/memory.h>
#include <libraries/dos.h>
#include <libraries/iffparse.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/iffparse.h>

#include <stdlib.h>
#include <string.h>

/* Causes example to write FTXT first, then read it back
* Comment out to create a reader only
*/
#define WRITEREAD

#define MINARGS 2

CONST_STRPTR usage = "Usage: clipftxt unitnumber (use zero for primary unit)";

/*
* Text error messages for possible IFFERR_#? returns from various
* IFF routines. To get the index into this array, take your IFFERR code,
* negate it, and subtract one.
* idx = -error - 1;
*/
char *errormsgs[] = {
"End of file (not an error).",
"End of context (not an error).",
"No lexical scope.",
"Insufficient memory.",
"Stream read error.",
"Stream write error.",
"Stream seek error.",
"File is corrupt.",
"IFF syntax error.",
"Not an IFF file.",
"Required call-back hook missing.",
"Return to client. You should never see this."
};

#define RBUFSZ 512

#define ID_FTXT MAKE_ID('F','T','X','T')
#define ID_CHRS MAKE_ID('C','H','R','S')

struct IFFParseIFace *IIFFParse;

UBYTE mytext[]="This FTXT written to clipboard by clipftxt example.\n";

int main(int argc, char **argv)
{
struct IFFHandle *iff = NULL;
struct ContextNode *cn;
long error=0, unitnumber=0, rlen;
int textlen;
UBYTE readbuf[RBUFSZ];

/* if not enough args or '?', print usage */
if(((argc)&&(argc<MINARGS))||(argv[argc-1][0]=='?'))
{
IDOS->Printf("%s\n", usage);
return RETURN_WARN;
}

unitnumber = atoi(argv[1]);

struct Library *IFFParseBase = IExec->OpenLibrary("iffparse.library", 50);
IIFFParse = (struct IFFParseIFace*)IExec->GetInterface(IFFParseBase, "main", 1, NULL);

if (IIFFParse == NULL)
{
IDOS->Printf("Can't open iff parsing library.\n");
goto bye;
}

/*
* Allocate IFF_File structure.
*/
if (!(iff = IIFFParse->AllocIFF ()))
{
IDOS->Printf("AllocIFF() failed.\n");
goto bye;
}

/*
* Set up IFF_File for Clipboard I/O.
*/
if (!(iff->iff_Stream = (ULONG) IIFFParse->OpenClipboard (unitnumber)))
{
IDOS->Printf("Clipboard open failed.\n");
goto bye;
}
else IDOS->Printf("Opened clipboard unit %ld\n", unitnumber);

IIFFParse->InitIFFasClip (iff);

#ifdef WRITEREAD

/*
* Start the IFF transaction.
*/
if (error = IIFFParse->OpenIFF (iff, IFFF_WRITE))
{
IDOS->Printf("OpenIFF for write failed.\n");
goto bye;
}

/*
* Write our text to the clipboard as CHRS chunk in FORM FTXT
*
* First, write the FORM ID (FTXT)
*/
if(!(error = IIFFParse->PushChunk(iff, ID_FTXT, ID_FORM, IFFSIZE_UNKNOWN)))
{
/* Now the CHRS chunk ID followed by the chunk data
* We'll just write one CHRS chunk.
* You could write more chunks.
*/
if(!(error = IIFFParse->PushChunk(iff, 0, ID_CHRS, IFFSIZE_UNKNOWN)))
{
/* Now the actual data (the text) */
textlen = strlen(mytext);
if(IIFFParse->WriteChunkBytes(iff, mytext, textlen) != textlen)
{
IDOS->Printf("Error writing CHRS data.\n");
error = IFFERR_WRITE;
}
}
if(!error) error = IIFFParse->PopChunk(iff);
}
if(!error) error = IIFFParse->PopChunk(iff);

if(error)
{
IDOS->Printf("IFF write failed, error %ld: %s\n",
error, errormsgs[-error - 1]);
goto bye;
}
else IDOS->Printf("Wrote text to clipboard as FTXT\n");

/*
* Now let's close it, then read it back
* First close the write handle, then close the clipboard
*/
IIFFParse->CloseIFF(iff);
if (iff->iff_Stream) IIFFParse->CloseClipboard ((struct ClipboardHandle *)
iff->iff_Stream);

if (!(iff->iff_Stream = (ULONG) IIFFParse->OpenClipboard (unitnumber)))
{
IDOS->Printf("Reopen of Clipboard failed.\n");
goto bye;
}
else IDOS->Printf("Reopened clipboard unit %ld\n", unitnumber);

#endif /* WRITEREAD */

if (error = IIFFParse->OpenIFF (iff, IFFF_READ))
{
IDOS->Printf("OpenIFF for read failed.\n");
goto bye;
}

/* Tell iffparse we want to stop on FTXT CHRS chunks */
if (error = IFFParse->StopChunk(iff, ID_FTXT, ID_CHRS))
{
IDOS->Printf("StopChunk failed.\n");
goto bye;
}

/* Find all of the FTXT CHRS chunks */
while(1)
{
error = IIFFParse->ParseIFF(iff,IFFPARSE_SCAN);
if(error == IFFERR_EOC) continue; /* enter next context */
else if(error) break;

/* We only asked to stop at FTXT CHRS chunks
* If no error we've hit a stop chunk
* Read the CHRS chunk data
*/
cn = IIFFParse->CurrentChunk(iff);

if((cn)&&(cn->cn_Type == ID_FTXT)&&(cn->cn_ID == ID_CHRS))
{
IDOS->Printf("CHRS chunk contains:\n");
while((rlen = IIFFParse->ReadChunkBytes(iff,readbuf,RBUFSZ)) > 0)
{
IDOS->Write(Output(),readbuf,rlen);
}
if(rlen < 0) error = rlen;
}
}

if((error)&&(error != IFFERR_EOF))
{
IDOS->Printf ("IFF read failed, error %ld: %s\n",
error, errormsgs[-error - 1]);
}

bye:
if (iff)
{
/*
* Terminate the IFF transaction with the stream. Free
* all associated structures.
*/
IIFFParse->CloseIFF (iff);

/*
* Close the clipboard stream
*/
if (iff->iff_Stream)
IIFFParse->CloseClipboard ((struct ClipboardHandle *)
iff->iff_Stream);
/*
* Free the IFF_File structure itself.
*/
IIFFParse->FreeIFF (iff);
}
IExec->DropInterface((struct Interface*)IIFFParse);
IExec->CloseLibrary (IFFParseBase);

return RETURN_OK;
}
</syntaxhighlight>

=== IFF Scanner Example ===

"Sift.c" lists the type and size of every chunk in an IFF file and, and checks the IFF file for correct syntax. You should use "Sift" to check IFF files created by your programs.

<syntaxhighlight>
/*
*
* sift.c: Takes any IFF file and tells you what's in it. Verifies syntax and all that cool stuff.
*
* Usage: sift -c ; For clipboard scanning
* or sift <file> ; For DOS file scanning
*
* Reads the specified stream and prints an IFFCheck-like listing of the contents of the IFF file, if any.
* Stream is a DOS file for <file> argument, or is the clipboard's primary clip for -c.
* This program must be run from a CLI.
*
*/

#include <exec/types.h>
#include <exec/memory.h>
#include <libraries/dos.h>
#include <libraries/iffparse.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/iffparse.h>

#include <stdlib.h>
#include <string.h>

#define MINARGS 2

CONST_STRPTR usage = "Usage: sift IFFfilename (or -c for clipboard)";

void PrintTopChunk(struct IFFHandle *); /* prototype for our function */

/*
* Text error messages for possible IFFERR_#? returns from various IFF routines. To get the index into
* this array, take your IFFERR code, negate it, and subtract one.
* idx = -error - 1;
*/
char *errormsgs[] = {
"End of file (not an error).", "End of context (not an error).", "No lexical scope.",
"Insufficient memory.", "Stream read error.", "Stream write error.",
"Stream seek error.", "File is corrupt.", "IFF syntax error.",
"Not an IFF file.", "Required call-back hook missing.", "Return to client. You should never see this."
};

struct IFFParseIFace *IIFFParse = NULL;

int main(int argc, char **argv)
{
struct IFFHandle *iff = NULL;
int32 error;
int16 cbio;

/* if not enough args or '?', print usage */
if(((argc)&&(argc<MINARGS))||(argv[argc-1][0]=='?'))
{
IDOS->Printf("%s\n", usage);
goto bye;
}

/* Check to see if we are doing I/O to the Clipboard. */
cbio = (argv[1][0] == '-' && argv[1][1] == 'c');

struct Library *IFFParseBase = IExec->OpenLibrary("iffparse.library", 50);
IIFFParse = (struct IFFParseIFace*)IExec->GetInterface(IFFParseBase, "main", 1, NULL);
if (IIFFParse == NULL)
{
IDOS->Printf("Can't open iff parsing library.\n");
goto bye;
}

/* Allocate IFF_File structure. */
if (!(iff = IIFFParse->AllocIFF()))
{
IDOS->Printf("AllocIFF() failed.\n");
goto bye;
}

/*
* Internal support is provided for both AmigaDOS files, and the clipboard.device. This bizarre
* 'if' statement performs the appropriate machinations for each case.
*/
if (cbio)
{
/*
* Set up IFF_File for Clipboard I/O.
*/
if (!(iff->iff_Stream = (ULONG) IIFFParse->OpenClipboard(PRIMARY_CLIP)))
{
IDOS->Printf("Clipboard open failed.\n");
goto bye;
}
IIFFParse->InitIFFasClip(iff);
}
else
{
/* Set up IFF_File for AmigaDOS I/O. */
if (!(iff->iff_Stream = IDOS->Open(argv[1], MODE_OLDFILE)))
{
IDOS->Printf("File open failed.\n");
goto bye;
}
IIFFParse->InitIFFasDOS(iff);
}

/* Start the IFF transaction. */
if (error = IIFFParse->OpenIFF(iff, IFFF_READ))
{
IDOS->Printf("OpenIFF failed.\n");
goto bye;
}

while (1)
{
/*
* The interesting bit. IFFPARSE_RAWSTEP permits us to have precision monitoring of the
* parsing process, which is necessary if we wish to print the structure of an IFF file.
* ParseIFF() with _RAWSTEP will return the following things for the following reasons:
*
* Return code: Reason:
* 0 Entered new context.
* IFFERR_EOC About to leave a context.
* IFFERR_EOF Encountered end-of-file.
* <anything else> A parsing error.
*/
error = IIFFParse->ParseIFF(iff, IFFPARSE_RAWSTEP);

/*
* Since we're only interested in when we enter a context, we "discard" end-of-context
* (_EOC) events.
*/
if (error == IFFERR_EOC)
continue;
else if (error)
{
/*
* Leave the loop if there is any other error.
*/
break;
}

/* If we get here, error was zero. Print out the current state of affairs. */
PrintTopChunk(iff);
}

/*
* If error was IFFERR_EOF, then the parser encountered the end of
* the file without problems. Otherwise, we print a diagnostic.
*/
if (error == IFFERR_EOF)
IDOS->Printf("File scan complete.\n");
else
IDOS->Printf("File scan aborted, error %ld: %s\n",
error, errormsgs[-error - 1]);

bye:
if (iff)
{
/* Terminate the IFF transaction with the stream. Free all associated structures. */
IIFFParse->CloseIFF(iff);

/*
* Close the stream itself.
*/
if (iff->iff_Stream)
{
if (cbio)
IIFFParse->CloseClipboard((struct ClipboardHandle *)iff->iff_Stream);
else
IDOS->Close(iff->iff_Stream);
}

/* Free the IFF_File structure itself. */
IIFFParse->FreeIFF(iff);
}
IExec->DropInterface((struct Interface*)IIFFParse);
IExec->CloseLibrary(IFFParseBase);

return RETURN_OK;
}

void PrintTopChunk(struct IFFHandle *iff)
{
struct ContextNode *top;
int32 i;
char idbuf[5];

/* Get a pointer to the context node describing the current context. */
if (!(top = IIFFParse->CurrentChunk(iff)))
return;

/*
* Print a series of dots equivalent to the current nesting depth of chunks processed so far.
* This will cause nested chunks to be printed out indented.
*/
for (i = iff->iff_Depth; i--; )
IDOS->Printf(". ");

/* Print out the current chunk's ID and size. */
IDOS->Printf("%s %ld ", IIFFParse->IDtoStr(top->cn_ID, idbuf), top->cn_Size);

/* Print the current chunk's type, with a newline. */
IDOS->Printf(IIFFParse->IDtoStr(top->cn_Type, idbuf));
}
</syntaxhighlight>

== Function Reference ==

The following are brief descriptions of the IFFParse functions discussed in this article. Further information about these and other IFFParse functions can be found in the SDK.

{| class="wikitable"
! Function
! Description
|-
| AllocIFF()
| Creates an IFFHandle structure.
|-
| FreeIFF()
| Frees the IFFHandle structure created with AllocIFF().
|-
| OpenIFF()
| Initialize an IFFHandle structure to read or write an IFF stream.
|-
| CloseIFF()
| Closes an IFF context.
|-
| InitIFF()
| Initialize an IFFHandle as a user-defined stream.
|-
| InitIFFasDOS()
| Initialize an IFFHandle as an AmigaDOS stream.
|-
| InitIFFasClip()
| Initialize an IFFHandle as a clipboard stream.
|-
| OpenClipboard()
| Create a handle on a clipboard unit for InitIFFasClip().
|-
| ParseIFF()
| Parse an IFF file from an IFFHandle stream.
|-
| ReadChunkBytes()
| Read bytes from the current chunk into a buffer.
|-
| ReadChunkRecords()
| Read record elements from the current chunk into a buffer.
|-
| StopChunk()
| Declare a chunk that should cause ParseIFF() to return.
|-
| CurrentChunk()
| Get the context node for the current chunk.
|-
| PropChunk()
| Specify a property chunk to store.
|-
| FindProp()
| Search for a stored property in a given context.
|-
| CollectionChunk()
| Declare a chunk type for collection.
|-
| FindCollection()
| Get a pointer to the current list of collection items.
|-
| StopOnExit()
| Declare a stop condition for exiting a chunk.
|-
| EntryHandler()
| Add an entry handler to the IFFHandle context.
|-
| ExitHandler()
| Add an exit handler to the IFFHandle context.
|-
| PushChunk()
| Push a given context node onto the top of the context stack.
|-
| PopChunk()
| Pop the top context node off of the context stack.
|-
| CurrentChunk()
| Get the top context node for the current chunk.
|-
| ParentChunk()
| Get the nesting context node for a given chunk.
|-
| AllocLocalItem()
| Create a LocalContextItem (LCI) structure.
|-
| LocalItemData()
| Returns a pointer to the user data of a LocalContextItem (LCI).
|-
| StoreLocalItem()
| Insert a LocalContextItem (LCI).
|-
| StoreItemInContext()
| Store a LocalContextItem in a given context node.
|-
| FindPropContext()
| Find the property context for the current state.
|-
| FindLocalItem()
| Return a LocalContextItem from the context stack.
|-
| FreeLocalItem()
| Free a LocalContextItem (LCI) created with AllocLocalItem().
|-
| SetLocalItemPurge()
| Set purge vector for a local context item.
|}

IFFParse Library

2017-10-18T07:18:16Z

Fredrik Wikstrom: Fixed indentation.

== IFFParse Library ==

The ''iffparse.library'' was created to help simplify the job of parsing IFF files. Unlike other IFF libraries, iffparse.library is not form-specific. This means that the job of interpreting the structure and contents of the IFF file is up to you. Previous IFF file parsers were either simple but not general, or general but not simple. IFFParse tries to be both simple ''and'' general.

== The Structure of IFF Files ==

Many people have a misconception that IFF means image files. This is not the case. IFF (short for Interchange File Format) is a method of portably storing structured information in machine-readable form. The actual information can be anything, but the manner in which it is stored is very specifically detailed. This specification is the IFF standard.

The IFF standard was originally designed in 1985 by Electronic Arts in conjunction with a committee of developers. The full standard along with file descriptions and sample code is available at [[IFF_Standard|IFF Standard]].

The goal of the IFF standard is to allow customers to move their own data between independently developed software products. The types of data objects to exchange are open-ended and currently include plain and formatted text, raster and structured graphics, fonts, music, sound effects, musical instrument descriptions, and animation. IFF addresses these needs by defining a standard for self-identifying file structures and rules for accessing these files.

=== Chunks: The Building Blocks of IFF ===

IFF files contain various types and amounts of data grouped in data ''chunks'', each starting with a four-letter ASCII identifier (the chunk ID) followed by a 32-bit length count (the chunk size). The identifier and length count make it possible for IFF readers to skip over chunks that they don’t understand or don’t care about, and extract only the information they need. It may be helpful to think of these chunks as the building blocks of an IFF file.

[[File:LibFig33-1.png|frame|center|The Chunk - The Building Block of IFF]]

The ‘CKID’ (chunk ID) characters of a real chunk will be a four letter identifier such as ‘BODY’ or ‘CMAP’, specifying the type and format of data stored in the chunk. Most chunks contain a simple defined grouping of byte, word, and long variables similar to the contents of a C structure. Others such as sound sample and bitmap image body chunks, contain a stream of compressed data.

Chunk writing is fairly straightforward with the one caveat that all chunks must be word-aligned. Therefore an odd-length chunk must be followed by a pad byte of zero (which is not counted in the size of the chunk). When chunks are nested, the enclosing chunk must state the total size of its composite contents (including any pad bytes).

{{Note|title=About Chunk Length|text=Every IFF data chunk begins with a 4-character identifier field followed by a 32-bit size field (these 8 bytes are sometimes referred to as the chunk header). The size field is a count of the rest of the data bytes in the chunk, ''not'' including any pad byte. Hence, the total space occupied by a chunk is given by its size field (rounded to the nearest even number) + 8 bytes for the chunk header}}

=== Composite Data Types ===

Standard IFF files generally contain a variable number of chunks within one of the standard IFF composite data types (which may be thought of as chunks which contain other chunks). The IFF specification defines three basic composite data types, ‘FORM’, ‘CAT ’, and ‘LIST’. A special composite data type, the ‘PROP’, is found only inside a LIST.

Usage of Composite IFF Types

{| class="wikitable"
| FORM || A grouping of chunks which describe one set of data
|-
| LIST || A grouping of the same type of FORMs with shared properties in a PROP
|-
| PROP || May appear in a LIST to define chunks shared by several FORMs
|-
| CAT || A concatenation of related FORMs or LISTs
|}

The special IFF composite data types, like simple chunks, start with a 4-character identifier (such as ‘FORM’), followed by a 32-bit length. But their data begins with a second 4-character identifier that tells you what type of data is in the composite. For example, a FORM ILBM contains chunks describing a bitmap image, and a FORM FTXT contains chunks describing formatted text.

It may help to think of each composite data type as a box containing chunks, the IFF building blocks. The following figure shows a diagram of a typical composite.

[[File:LibFig33-2.png|frame|center|The FORM – The Most Common IFF File Type]]

The example FORM in the previous figure is outlined below showing the size of chunks within the FORM. Notice that the size of a composite ''includes'' its second 4-character identifier (shown below as ‘NAME’).

. FORM 72 NAME (72 is the size of the FORM starting with the “N” of NAME)
. . CKID 22 (then 22 bytes of data, so chunk header + chunk size is 30)
. . CKID 10 (then 10 bytes of data, so chunk header + chunk size is 18)
. . CKID 12 (then 12 bytes of data, so chunk header + chunk size is 20)

{{Note|text=In the example above, indentation represents the nesting of the chunks within the FORM. Real FORMs and chunks would have different four-character identifiers rather than ‘NAME’ and ‘CKID’.}}

Any odd-length chunks must have a pad byte of zero at the end of the chunk. As shown below, this pad byte is not counted in the size of the chunk but ''is'' counted in the size of any composite types (such as FORM) that contain an odd-length chunk. '''Warning:''' some IFF readers and writers do not deal with this properly.

. FORM 72 NAME (72 is the size of the FORM starting with the “N” of NAME)
. . CKID 21 (then 21 bytes of data, so chunk header + chunk size is 29)
. . 0 (pad byte of zero, size 1)
. . CKID 10 (then 10 bytes of data, so chunk header + chunk size is 18)
. . CKID 12 (then 12 bytes of data, so chunk header + chunk size is 20)

Most IFF files are of the composite type FORM. Generally, a FORM is a simple grouping of chunks that provide information about some data, and the data itself. Although some standard chunks have common usage within different FORMS, the identity and format of most chunks within a FORM are relative to the definition and specification of the FORM. For example, a CRNG chunk in a FORM ILBM may have a totally different format and contents than a chunk named CRNG in a different type of FORM.

One of the most popular IFF FORMs that has been defined is the ILBM standard. This is how most Amiga bitmap imagery is stored. Since this is the most common IFF file, it is used frequently as an example.

Here is the output of a program called “Sift.c” that displays a text description of the contents of an IFF file ([[#IFF Scanner Example|Sift.c]] is listed at the end of this article). The file shown below is a fairly simple ILBM.

. FORM 11068 ILBM
. . BMHD 20
. . CAMG 4
. . CMAP 12
. . BODY 10995

{{Note|title=Computing the Size of a FORM|text=The size of the FORM (11,068 bytes) is equal to the sum of the sizes stated in each chunk contained within the FORM, plus 8 bytes for the overhead of each chunk header (4 bytes for the 4-character chunk ID, and 4 bytes for the 32-bit chunk size), plus 4 bytes for the FORM’s own 4-character ID (‘ILBM’), plus 1 byte more for each pad byte that follow any odd-length chunks.}}

== Parsing an IFF File ==

Chunk reading requires a parser to scan each chunk and dispatch the proper access/conversion procedure. For a simple IFF file, such parsing may be relatively easy, consisting mainly reading in the data of desired chunks, and seeking over unwanted chunks (and the pad byte after odd-length chunks). Interpreting nested chunks is more complex, and requires a method for keeping track of the current context, i.e., the data which is still relevant at any particular depth into the nest. The original IFF specifications compare an IFF file to a C program. Such a metaphor can be useful in understanding the scope of of the chunks in an IFF file.

The IFFParse library addresses general IFF parsing requirements by providing a run-time library which can extract the chunks you want from an IFF file, with the ability to pass control to you when it reaches a chunk that requires special processing such as decompression. IFFParse also understands complex nested IFF formats and will keep track of the context for you.

=== Basic Functions and Structures of IFFParse Library ===

The structures and flags of the IFFParse library are defined in the include files <libraries/iffparse.h> and <libraries/iffparse.i>. IFF files are manipulated through a structure called an IFFHandle. Only some of the fields in the IFFHandle are publicly documented. The rest are managed internally by IFFParse. This handle is passed to all IFFParse functions, and contains the current parse state and position in the file. An IFFHandle is obtained by calling AllocIFF(), and freed through FreeIFF(). This is the only legal way to obtain and dispose of an IFFHandle.

The public portion of if IFFHandle is defined as follows:

<syntaxhighlight>
/*
* Structure associated with an active IFF stream.
* "iff_Stream" is a value used by the client's read/write/seek functions -
* it will not be accessed by the library itself and can have any value
* (could even be a pointer or a BPTR).
*/
struct IFFHandle {
ULONG iff_Stream;
ULONG iff_Flags;
LONG iff_Depth; /* Depth of context stack. */
/* There are private fields hiding here. */
};
</syntaxhighlight>

== Stream Management ==

A stream is a linear array of bytes that may be accessed sequentially or randomly. DOS files are streams. IFFParse uses Hook structures (defined in <utility/hooks.h>) to implement a general stream management facility. This allows the IFFParse library to read, write, and seek any type of file handle or device by using an application-provided hook function to open, read, write, seek and close the stream.

Built on top of this facility, IFFParse has two internal stream managers: one for unbuffered DOS files (AmigaDOS filehandles), and one for the Clipboard.

=== Initialization ===

As shown above, the IFFHandle structure contains the public field iff_Stream. This is a longword that must be initialized to contain something meaningful to the stream manager. IFFParse never looks at this field itself (at least not directly). Your iff_Stream may be an AmigaDOS filehandle, or an IFFParse ClipboardHandle, or a custom stream of any type if you provide your own custom stream handler (see the section on [[#Custom Stream Handlers|Custom Stream Handlers]]). You must initialize your IFFHandle structure’s iff_Stream to your stream, and then initialize the IFFHandle’s flags and stream hook.

Three sample initializations are shown here. In the case of the internal DOS stream manager, iff_Stream is an AmigaDOS filehandle as returned by Open():

<syntaxhighlight>
iff->iff_Stream = (ULONG) IDOS->Open ("filename", MODE_OLDFILE);
if(iff->iff_Stream) IIFFParse->InitIFFasDOS (iff); /* use internal DOS stream manager */
</syntaxhighlight>

In the case of the internal Clipboard stream manager, iff_Stream is a pointer to an IFFParse ClipboardHandle structure (the OpenClipboard() call used here is a function of iffparse.library, not the clipboard.device):

<syntaxhighlight>
iff->iff_Stream = (ULONG) IIFFParse->OpenClipboard (PRIMARY_CLIP);
IIFFParse->InitIFFasClip (iff); /* use internal Clipboard stream manager */
</syntaxhighlight>

When using a custom handle such as an fopen() file handle, or a device other than the clipboard, you must provide your own flags and stream handler:

<syntaxhighlight>
iff->iff_Stream = (ULONG) OpenMyCustomStream("foo");
IIFFParse->InitIFF (iff, IFFF_FSEEK | IFFF_RSEEK, &mystreamhook);
</syntaxhighlight>

IFFParse “knows” the seek capabilities of DOS and ClipboardHandle streams, so InitIFFasDOS() and InitIFFasClip() set the flags for you.

{{Note|title=You May Change the Seek Bits in iff_Flags|text=IFFParse sets IFFF_FSEEK | IFFF_RSEEK for DOS files. This is not always true (e.g., pipes). If you know that a DOS file has different seek characteristics, your application may correct the seek bits in iff_Flags after calling InitIFFasDOS().}}

When using InitIFF() to provide a custom handler, you must also provide flags to tell IFFParse the capabilities of your stream. The flags are:

; IFFF_FSEEK
: This stream has forward-seek capability only.

; IFFF_RSEEK
: This stream has random-seek capability. IFFF_RSEEK tends to imply IFFF_FSEEK, but it’s best to specify both.

If neither flag is specified, you’re telling IFFParse that it can’t seek through the stream.

After your stream is initialized, call OpenIFF():

<syntaxhighlight>
error = IIFFParse->OpenIFF (iff, IFFF_READ);
</syntaxhighlight>

Once you establish a read/write mode (by passing IFFF_READ or IFFF_WRITE), you remain in that mode until you call CloseIFF().

=== Termination ===

Termination is simple. Just call CloseIFF(iff). This may be called at any time, and terminates IFFParse’s transaction with the stream. The stream itself is not closed. The IFFHandle may be reused; you may safely call OpenIFF() on it again. You are responsible for closing the streams you opened. A stream used in an IFFHandle must generally remain open until you CloseIFF().

=== Custom Streams ===

A custom stream handler can allow you (and iffparse.library) to use your compiler’s own file I/O functions such as fopen(), fread() and fwrite(), rather than the lower-level AmigaDOS equivalents Open(), Read(), and Write(). A custom stream handler could also be used to read or write IFF files from an Exec device or an unusual handler or file system.

If you install your own stream handler function, iffparse.library will call your function whenever it needs to read, write, or seek on your file. Your stream handler function will then perform these stream actions for iffparse.library. See the “Custom Stream Handlers” section for more information on custom stream handlers.

== Parsing and Writing IFF ==

For information on parsing IFF see [[Parsing_IFF|Parsing IFF]].

For information on writing IFF see [[Writing_IFF|Writing IFF]].

== Context Functions ==

Internally, IFFParse maintains IFF nesting and scoping context via a ''context stack''. The PushChunk() and PopChunk() functions get their names from this basic idea of the iffparse.library. Direct access to this stack is not allowed. However, many functions are provided to assist in examining and manipulating the context stack.

{{Note|title=About the Context Stack|text=It is probably easier to think of a stack of blocks on a table in front of you when reading this discussion.}}

As the nesting level increases (as would happen when parsing a nested LIST or FORM), the depth of the context stack increases; new elements are added to the top. When these contexts expire, the ContextNodes are deleted and the stack shrinks.

=== Context Nodes ===

The current context is said to be the top element on the stack. Contextual information is stored in a structure called a ContextNode:

<syntaxhighlight>
struct ContextNode {
struct MinNode cn_Node;
LONG cn_ID;
LONG cn_Type;
LONG cn_Size; /* Size of this chunk */
LONG cn_Scan; /* # of bytes read/written so far */
/* There are private fields hiding here. */
};
</syntaxhighlight>

==== CurrentChunk() ====

You can obtain a pointer to the current ContextNode through the function CurrentChunk():

<syntaxhighlight>
currentnode = IIFFParse->CurrentChunk (iff);
</syntaxhighlight>

The ContextNode tells you the type, ID, and size of the currently active chunk. If there is no currently active context, NULL is returned.

==== ParentChunk() ====

To find the parent of a context, you call ParentChunk() on the relevant ContextNode:

<syntaxhighlight>
parentnode = IIFFParse->ParentChunk(currentnode);
</syntaxhighlight>

If there is no parent context, NULL is returned.

=== The Default Context ===

When you first obtain an IFFHandle through AllocIFF(), a hidden default context node is created. You cannot get direct access to this node through CurrentChunk() or ParentChunk(). However, using StoreLocalItem(), you can store information in this context.

=== Context-Specific Data: LocalContextItems ===

ContextNodes can contain application data specific to that context. These data objects are called LocalContextItems. LocalContextItems (LCIs) are a grey-box structure which contain a type, ID and identification field. LCIs are used to store context-sensitive data. The format of this data is application-defined. A ContextNode can contain as many LCIs as you want.

[[File:LibFig33-3.png|frame|center|IFFParse Context Stack]]

The previous figure shows the relationship between the IFFHandle, the ContextNodes, and the LCIs. The IFFHandle is the root of the tree, so to speak. ContextNodes “grow” out of the IFFHandle. In turn, LCIs "grow" out of the ContextNodes. What grows out of an LCI is client-defined.

==== AllocLocalItem() ====

To create an LCI, you use the function AllocLocalItem():

<syntaxhighlight>
lci = IIFFParse->AllocLocalItem (type, id, ident, datasize);
</syntaxhighlight>

If successful, you will be returned a pointer to an LCI having the specified type, ID, and identification values; and with datasize bytes of buffer space for your application to use.

==== LocalItemData() ====

To get a pointer to an LCIs data buffer, you use LocalItemData():

<syntaxhighlight>
buf = IIFFParse->LocalItemData (lci);
</syntaxhighlight>

You may read and write the buffer to your heart’s content; it is yours. You should not, however, write beyond the end of the buffer. The size of the buffer is what you asked for when you called AllocLocalItem().

=== Storing LCIs ===

Once you’ve created and initialized an LCI, you’ll want to attach it to a ContextNode. Though a ContextNode can have many LCIs, a given LCI can be linked to only one ContextNode. Once linked, an LCI cannot be removed from a ContextNode (this may change in the future). Storing an LCI in a ContextNode is done with the functions StoreLocalItem() and StoreItemInContext().

==== StoreLocalItem() ====

The StoreLocalItem() function is called as follows:

<syntaxhighlight>
error = StoreLocalItem (iff, lci, position);
</syntaxhighlight>

The position argument determines where the LCI is stored. The possible values are IFFSLI_ROOT, IFFSLI_TOP, and IFFSLI_PROP.

; IFFSLI_ROOT
: causes StoreLocalItem() to store your LCI in the default ContextNode.

; IFFSLI_TOP
: gets your LCI stored in the top (current) ContextNode.

{{Note|title=The LCI Ends When the Current Context Ends|text=When the current context expires, your LCI will be deleted by the parser.}}

IFFSLI_PROP causes your LCI to be stored in the topmost context from which a property would apply. This is usually the topmost FORM or LIST chunk. For example, suppose you had a deeply nested ILBM FORM, and you wanted to store the BMHD property in its correct context such that, when the current FORM context expired, the BMHD property would be deleted. IFFSLI_PROP will cause StoreLocalItem() to locate the proper context for such scoping, and store the LCI there. See the section on "Finding the Prop Context" for additional information on the scope of properties.

==== StoreItemInContext() ====

StoreItemInContext() is used when you already have a pointer to the ContextNode to which you want to attach your LCI. It is called like so:

<syntaxhighlight>
IIFFParse->StoreItemInContext (iff, lci, contextnode);
</syntaxhighlight>

StoreItemInContext() links your LCI into the specified ContextNode. Then it searches the ContextNode to see if there is another LCI with the same type, ID, and identification values. If so, the old one is deleted.

==== FindLocalItem() ====

After you’ve stored your LCI in a ContextNode, you will no doubt want to be able to find it again later. You do this with the function FindLocalItem(), which is called as follows:

<syntaxhighlight>
lci = IIFFParse->FindLocalItem (iff, type, id, ident);
</syntaxhighlight>

FindLocalItem() attempts to locate an LCI having the specified type, ID, and identification values. The search proceeds as follows (refer to the previous figure to understand this better).

FindLocalItem() starts at the top (current) ContextNode and searches all LCIs in that context. If no matching LCIs are found, it proceeds down the context stack to the next ContextNode and searches all its LCIs. The process repeats until it finds the desired LCI (whereupon it returns a pointer to it), or reaches the end without finding anything (where it returns NULL).

{{Note|title=Context Stack Position|text=LCIs higher in the stack will "override" lower LCIs with the same type, ID, and identification field. This is how property scoping is handled. As ContextNodes are popped off the context stack, all its LCIs are deleted as well. See the section on “Freeing LCIs” below for additional information on deleting LCIs.}}

=== Some Interesting Internal Details ===

{{Note|title=Warning|text=This section details some internal implementation details of iffparse.library which may help you to understand it better. Use of the following information to do “clever” things in an application is forbidden and unsupportable. Don’t even think about it.}}

It turns out that StoredProperties, CollectionItems, and entry and exit handlers are all implemented using LCIs. For example, when you call FindProp(), you are actually calling a front-end to FindLocalItem(). The mysterious identification value (which has heretofore never been discussed) is a value which permits you to differentiate between LCIs having the same type and ID.

For instance, suppose you called PropChunk(), asking it to store an ILBM BMHD. PropChunk() will install an entry handler in the form of an LCI, having type equal to ‘ILBM’, ID equal to ‘BMHD’, and an identification value of IFFLCI_ENTRYHANDLER.

When an ILBM BMHD is encountered, the entry handler is called, and it creates and stores another LCI having type equal to ‘ILBM’, ID equal to ‘BMHD’ and an identification value of IFFLCI_PROP.

Thus, when you call FindProp(), it merely calls FindLocalItem() with your type and ID, and supplies IFFLCI_PROP for the identification value.

Therefore, handlers, StoredProperties, CollectionItems and your own custom LCIs can never be confused with each other, since they all have unique identification values. Since they are all handled (and searched for) in the same way, they all “override” each other in a consistent way. Just as StoredProperties higher in the context stack will be found and returned before identical ones in lower contexts, so will chunk handlers be found and invoked before ones lower on the context stack (recall FindLocalItem()’s search procedure).

This means you can temporarily override a chunk handler by installing an identical handler in a higher context. The handler will persist until the context in which it is stored expires, after which, the original one regains scope.

== Error Handling ==

If at any time during reading or writing you encounter an error, the IFFHandle is left in an undefined state. Upon detection of an error, you should perform an abort sequence and CloseIFF() the IFFHandle. Once CloseIFF() has been called, the IFFHandle is restored to normalcy and may be reused.

== Advanced Topics ==

This section discusses customizing of IFFParse data handling. For applications with special needs, IFFParse supports both custom stream handlers and custom chunk handlers.

=== Custom Stream Handlers ===

As discussed earlier, IFFParse contains built-in stream handlers for AmigaDOS file handles as returned by Open(), and for the clipboard.device. If you are using AmigaDOS filehandles or the clipboard.device, you need not supply a custom stream handler.

If you wish to use your compiler’s own file I/O functions (such as fread() ) or need to read or write to an unusual handler or Exec device, you must provide a custom stream handler for your IFFHandle. Your custom stream handler will be called to perform all reads, writes, and seeks on your custom stream. The allows you to use compiler file I/O functions, Exec device commands, or any other method to perform the requested stream operations.

If you are implementing your own custom stream handler, you will need to know the mechanics of hook call-backs, and how to interpret the parameters. An IFFParse custom stream handler is simply a function in your code that follows hook function conventions (Hook functions are also known as callback functions. See [[Utility_Library|Utility Library]] for more details).

==== Installing a Custom Stream Handler ====

To initialize your IFFHandle to point to your custom stream and stream handler, you must open your stream and place a pointer to the stream in your IFFHandle’s iff_Stream field. This pointer could be the return from fopen(), or an Exec device I/O request, or any other type of pointer which will provide your custom stream handler with a way to manage your stream. For example:

<syntaxhighlight>
iff->iff_Stream = (ULONG) fopen("foo");
</syntaxhighlight>

Next, you must install your custom handler for this stream, and also tell IFFParse the seek capabilities of your stream. To install your custom stream handler, you must first set up a Hook structure (<utility/hooks.h>) to point to your stream handling function. Then use InitIFF() to install your stream handler and also tell IFFParse the seek capabilities of your stream. There is “some assembly required”.

For an IFFParse custom stream hook the function prototype looks like this:

<syntaxhighlight>
int32 mystreamhandler(struct Hook *hook, struct IFFHandle *iff, struct IFFStreamCmd *actionpkt);
</syntaxhighlight>

A return of 0 indicates success. A non-zero return indicates an error.

For example,

<syntaxhighlight>
static int32 mystreamhandler
(
struct Hook *hook,
struct IFFHandle *iff,
struct IFFStreamCmd *actionpkt
)
{
/*
* Code to handle the stream commands - see end this section
* for a complete example custom stream handler function.
*
*/
}

/* Initialization of Hook structure for registerized handler function */
struct Hook mystreamhook
{
{ NULL },
(HOOKFUNC) mystreamhandler, /* h_Entry, registerized function entry */
NULL,
NULL
};

/* Open custom stream and InitIFF to custom stream handler */
if ( iff->iff_Stream = (ULONG) myopen("foo") )
{
IIFFParse->InitIFF (iff, IFFF_FSEEK | IFFF_RSEEK, &mystreamhook);
}
</syntaxhighlight>

==== Inside a Custom Stream Handler ====

When the library calls your stream handler, you’ll be passed a pointer to the Hook structure (hook in the example used here), a pointer to the IFFHandle (iff), and a pointer to an IFFStreamCmd structure (actionpkt). Your stream pointer may be found in iff->iff_Stream where you previously stored it. The IFFStreamCmd (actionpkt) will describe the action that IFFParse needs you to perform on your stream:

<syntaxhighlight>
/* Custom stream handler is passed struct IFFStreamCmd *actionpkt */
struct IFFStreamCmd {
LONG sc_Command; /* Operation to be performed (IFFCMD_) */
APTR sc_Buf; /* Pointer to data buffer */
LONG sc_NBytes; /* Number of bytes to be affected */
};

/* Possible call-back command values. (Using 0 as the value for IFFCMD_INIT
* was, in retrospect, probably a bad idea.)
*/
#define IFFCMD_INIT 0 /* Prepare the stream for a session */
#define IFFCMD_CLEANUP 1 /* Terminate stream session */
#define IFFCMD_READ 2 /* Read bytes from stream */
#define IFFCMD_WRITE 3 /* Write bytes to stream */
#define IFFCMD_SEEK 4 /* Seek on stream */
#define IFFCMD_ENTRY 5 /* You just entered a new context */
#define IFFCMD_EXIT 6 /* You're about to leave a context */
#define IFFCMD_PURGELCI 7 /* Purge a LocalContextItem */
</syntaxhighlight>

Your custom stream handler should perform the requested action on your custom stream, and then return 0 for success or an IFFParse error if an error occurred. The following code demonstrates a sample stream handler for a stream which was opened with a compiler’s fopen() buffered file I/O function:

<syntaxhighlight>
static int32 mystreamhandler ( struct Hook *hook,
struct IFFHandle *iff,
struct IFFStreamCmd *actionpkt )
{
FILE *stream;
int32 nbytes, error;
uint8 *buf;

stream = (FILE *) iff->iff_Stream; /* get your stream pointer */
nbytes = actionpkt->sc_NBytes; /* length for command */
buf = (uint8 *) actionpkt->sc_Buf; /* buffer for the command */

/* Now perform the action specified by the actionpkt->sc_Command */

switch (actionpkt->sc_Command) {
case IFFCMD_READ:
/*
* IFFCMD_READ means read sc_NBytes from the stream and place
* it in the memory pointed to by sc_Buf. Be aware that
* sc_NBytes may be larger than can be contained in an int.
* This is important if you plan on recompiling this for
* 16-bit ints, since fread() takes int arguments.
*
* Any error code returned will be remapped by IFFParse into
* IFFERR_READ.
*/
error = (fread (buf, 1, nbytes, stream) != nbytes);
break;

case IFFCMD_WRITE:
/*
* IFFCMD_WRITE is analogous to IFFCMD_READ.
*
* Any error code returned will be remapped by IFFParse into
* IFFERR_WRITE.
*/
error = (fwrite (buf, 1, nbytes, stream) != nbytes);
break;

case IFFCMD_SEEK:
/*
* IFFCMD_SEEK asks that you performs a seek relative to the
* current position. sc_NBytes is a signed number,
* indicating seek direction (positive for forward, negative
* for backward). sc_Buf has no meaning here.
*
* Any error code returned will be remapped by IFFParse into
* IFFERR_SEEK.
*/
error = (fseek (stream, nbytes, 1) == -1);
break;

case IFFCMD_INIT:
/*
* IFFCMD_INIT means to prepare your stream for reading.
* This is used for certain streams that can't be read
* immediately upon opening, and need further preparation.
* This operation is allowed to fail; the error code placed
* in D0 will be returned directly to the client.
*
* An example of such a stream is the clipboard. The
* clipboard.device requires you to set the io_ClipID and
* io_Offset to zero before starting a read. You would
* perform such a sequence here. (Stdio files need no such
* preparation, so we simply return zero for success.)
*/
case IFFCMD_CLEANUP:
/*
* IFFCMD_CLEANUP means to terminate the transaction with
* the associated stream. This is used for streams that
* can't simply be closed. This operation is not allowed to
* fail; any error returned will be ignored.
*
* An example of such a stream is (surprise!) the clipboard.
* It requires you to explicitly end reads by CMD_READing
* past the end of a clip, and end writes by sending a
* CMD_UPDATE. You would perform such a sequence here.
* (Again, stdio needs no such sequence.)
*/
error = 0;
break;
}
return (error);
}
</syntaxhighlight>

=== Custom Chunk Handlers ===

Like custom stream handlers, custom chunk handlers are implemented using Hook structures. See the previous section for details on how a handler function may be interfaced using a Hook structure.

There are two types of chunk handlers: entry handlers and exit handlers. Entry handlers are invoked just after the parser enters the chunk; the stream will be positioned to read the first byte in the chunk. (If the chunk is a FORM, LIST, CAT, or PROP, the longword type will be read by the parser; the stream will be positioned to read the byte immediately following the type.) Exit handlers are invoked just before the parser leaves the chunk; the stream is not positioned predictably within the chunk.

==== Installing a Custom Chunk Handler ====

To install an entry handler, you call EntryHandler() in the following manner:

<syntaxhighlight>
error = IIFFParse->EntryHandler (iff, type, id, position, hookptr, object);
</syntaxhighlight>

An exit handler is installed by saying:

<syntaxhighlight>
error = IIFFParse->ExitHandler (iff, type, id, position, hookptr, object);
</syntaxhighlight>

In both cases, a handler is installed for chunks having the specified type and id. The position argument specifies in what context to install the handler, and is identical to the position argument used by StoreLocalItem(). The hookptr argument given above is a pointer to your Hook structure.

==== Inside a Custom Chunk Handler ====

The mechanics of receiving parameters through the Hook are covered in the “Custom Stream Handlers” section, and are not duplicated here. Refer to the EntryHandler() and ExitHandler() Autodocs for the contents of the registers upon entry.

Once inside your handler, you can call nearly all functions in the iffparse.library, however, you should avoid calling ParseIFF() from within chunk handlers.

Your handler runs in the same environment as whoever called ParseIFF(). The propagation sequence is:

'''mainline''' --''calls''--> '''ParseIFF()''' --''calls''--> '''your_handler()'''

Thus, your handler runs on your mainline’s stack, and can call any OS functions the mainline code can. (Your handler will have to set the global base pointer if your code uses base-relative addressing.)

The return code will affect the parser in a number of ways:

* If you return zero (a normal, uneventful return), ParseIFF() will continue normally. If you return the value IFFERR_RETURN2CLIENT, ParseIFF() will stop and return the value zero to the mainline code.

* If you return any other value, ParseIFF() will stop and return that value to the mainline code. This is how you should return error conditions to the client code.

==== The Object Parameter ====

The object parameter supplied to EntryHandler() and ExitHandler() is a pointer which will be passed to your handler when invoked. This pointer can be anything; the parser doesn’t use it directly. As an example, you might pass the pointer to the IFFHandle. This way, when your handler is called, you’ll be able to easily perform operations on the IFFHandle within your handler. Such code might appear as follows:

<syntaxhighlight>
error = EntryHandler (iff, ID_ILBM, ID_BMHD, IFFSLI_ROOT, hook, iff);
</syntaxhighlight>

And your handler would be declared as follows:

<syntaxhighlight>
int32 MyHandler (struct Hook *hook,
int32 *cmd,
struct IFFHandle *iff)

</syntaxhighlight>

From within your handler, you could then call CurrentChunk(), ReadChunkBytes(), or nearly any other operation on the IFFHandle. Please refer to the EntryHandler() and ExitHandler() Autodocs for additional information on the use of chunk handlers.

=== Finding the Prop Context ===

Earlier it was mentioned that supplying a position value of IFFSLI_PROP to StoreLocalItem() would store it in the topmost property scope. FindPropContext() is the routine that finds that topmost context.

Property chunks (such as the BMHD, CMAP, and others) have dominion over the FORM that contains them; they are said to be “in scope” and their definition persists until the FORM’s context ends. Thus, a property chunk has a scoping level equal to the FORM that contains it; when the FORM ends, the property dies with it.

Consider a more complicated example. Suppose you have a LIST with a PROP in it. PROPs are the global variables of LISTs; thus a property chunk declared in a PROP will persist until the LIST’s context ends.

This is what FindPropContext() is looking for; a context level in which a property chunk may be installed.

FindPropContext() starts at the parent of the current context (second from the top of the context stack) and starts searching downward, looking for the first FORM or LIST context it finds. If it finds one, it returns a pointer to that ContextNode. If it can’t find a suitable context level, it returns NULL.

FindPropContext() is called as follows:

<syntaxhighlight>
struct ContextNode *cn = IFFParse->FindPropContext (iff);
</syntaxhighlight>

=== Freeing LCIs ===

Ordinarily, the parser will automatically delete LCIs you have allocated and installed. However, you may have a case where simply FreeVec()ing your LCI is not enough; you may need to free some ancillary memory, or decrement a counter, or send a signal, or something. This is where SetLocalItemPurge() comes in. It is called as follows:

<syntaxhighlight>
IFFParse->SetLocalItemPurge (lci, hookptr);
</syntaxhighlight>

When the parser is ready to delete your LCI, your purge handler code will be called through the Hook you supplied. You can then perform all your necessary operations. One of these operations should be to free the LCI itself. This is done with FreeLocalItem():

<syntaxhighlight>
IIFFParse->FreeLocalItem (lci);
</syntaxhighlight>

This deallocates the memory used to store the LCI and the client buffer allocated with it. FreeLocalItem() is only called as part of a custom purge handler.

As with custom chunk handlers, your purge handler executes in the same environment as the mainline code that called ParseIFF(). It is recommended that you keep purge handlers short and to the point; super clever stuff should be reserved for custom chunk handlers, or for the client’s mainline code. Custom purge handlers must ''always'' work; failures will be ignored.

== IFF FORM Specifications ==

The specifications for Amiga IFF formats are maintained by the AmigaOS Development Team. The latest specifications are published in the [[IFF_Standard|IFF Standard]]. Updates of the IFF Manual, selected new FORMs and changes to existing FORMs are documented on this wiki.

Some of the most commonly used IFF FORMs are the four that were originally specified in the EA IFF-85 standard:

{| class="wikitable"
| ILBM || Bitmap images and palettes
|-
| FTXT || Simple formatted text
|-
| SMUS || Simple musical scores
|-
| 8SVX || 8-bit sound samples
|}

Of these four, ILBM is the most commonly encountered FORM, and FTXT is becoming increasingly important since the ''conclip'' command passes clipped console text through the clipboard as FTXT. All data clipped to the clipboard must be in an IFF format.

This section will provide a brief summary of the ILBM and FTXT FORMs and their most used common chunks. Please consult the EA-IFF specifications for additional information.

=== FORM ILBM ===

The IFF file format for graphic images on the Amiga is called FORM ILBM (InterLeaved BitMap). It follows a standard parsable IFF format.

==== ILBM.BMHD BitMapHeader Chunk ====

The most important chunk in a FORM ILBM is the BMHD (BitMapHeader) chunk which describes the size and compression of the image:

<syntaxhighlight>
typedef UBYTE Masking; /* Choice of masking technique - Usually 0. */
#define mskNone 0
#define mskHasMask 1
#define mskHasTransparentColor 2
#define mskLasso 3

/* Compression algorithm applied to the rows of all source
* and mask planes. "cmpByteRun1" is byte run encoding.
* Do not compress across rows! Compression is usually 1.
*/
typedef UBYTE Compression;
#define cmpNone 0
#define cmpByteRun1 1

/* The BitMapHeader structure expressed as a C structure */
typedef struct {
UWORD w, h; /* raster width & height in pixels */
WORD x, y; /* pixel position for this image */
UBYTE nPlanes; /* # bitplanes (without mask, if any) */
Masking masking; /* One of the values above. Usually 0 */
Compression compression;/* One of the values above. Usually 1 */
UBYTE reserved1; /* reserved; ignore on read, write as 0 */
UWORD transparentColor; /* transparent color number. Usually 0 */
UBYTE xAspect, yAspect; /* pixel aspect, a ratio width : height */
WORD pageWidth, pageHeight; /* source "page" size in pixels */
} BitMapHeader;
</syntaxhighlight>

{{Note|title=Warning|text=This hex dump is shown only to help the reader understand how IFF chunks appear in a file. You cannot ever depend on any particular ILBM chunk being at any particular offset into the file. IFF files are composed, in their simplest form, of chunks within a FORM. Each chunk starts with a 4-letter chunkID, followed by a 32-bit length of the rest of the chunk. You must ''parse'' IFF files, skipping past unneeded or unknown chunks by seeking their length (+1 if odd length) to the next 4-letter chunk ID. In a real ILBM file, you are likely to encounter additional optional chunks. See the IFF Specification listed in [[IFF_Standard|IFF Standard]] for additional information on such chunks.}}

<pre>
0000: 464F524D 00016418 494C424D 424D4844 FORM..d.ILBMBMHD
0010: 00000014 01400190 00000000 06000100 .....@..........
0020: 00000A0B 01400190 43414D47 00000004 .....@..CAMG....
0030: 00000804 434D4150 00000030 001000E0 ....CMAP...0....
0040: E0E00000 20000050 30303050 50500030 .... ..P000PPP.0
0050: 90805040 70707010 60E02060 E06080D0 ..P@ppp.`. `.`..
0060: A0A0A0A0 90E0C0C0 C0D0A0E0 424F4459 ............BODY
0070: 000163AC F8000F80 148A5544 2ABDEFFF ..c.......UD*... etc.

Interpretation:

'F O R M' length 'I L B M''B M H D'<-start of BitMapHeader chunk
0000: 464F524D 00016418 494C424D 424D4844 FORM..d.ILBMBMHD

length WideHigh XorgYorg PlMkCoRe <- Planes Mask Compression Reserved
0010: 00000014 01400190 00000000 06000100 .....@..........

TranAspt PagwPagh 'C A M G' length <- start of C-AMiGa View modes chunk
0020: 00000A0B 01400190 43414D47 00000004 .....@..CAMG....

dir include:
ViewMode 'C M A P' length R g b R <- ViewMode 800=HAM | 4=LACE
0030: 00000804 434D4150 00000030 001000E0 ....CMAP...0....

g b R g b R g b R g b R g b R g <- Rgb's are for reg0 thru regN
0040: E0E00000 20000050 30303050 50500030 .... ..P000PPP.0

b R g b R g b R g b R g b R g b
0050: 90805040 70707010 60E02060 E06080D0 ..P@ppp.`. `.`..

R g b R g b R g b R g b 'B O D Y'
0060: A0A0A0A0 90E0C0C0 C0D0A000 424F4459 ............BODY

length start of body data <- Compacted (Compression=1 above)
0070: 000163AC F8000F80 148A5544 2ABDEFFF ..c.......UD*...
0080: FFBFF800 0F7FF7FC FF04F85A 77AD5DFE ...........Zw.]. etc.

Simple CAMG ViewModes: HIRES=0x8000 LACE=0x4 HAM=0x800 HALFBRITE=0x80

( ILBMs may contain a LONGWORD ViewPort ModeID in CAMG )
</pre>

==== Interpreting ILBMs ====

ILBM is a fairly simple IFF FORM. All you really need to deal with to extract the image are the following chunks:

Information about the size, depth, compaction method (see interpreted hex dump above).

Optional Amiga ViewModes chunk. Most HAM and HALFBRITE ILBMs should have this chunk. If no CAMG chunk is present, and image is 6 planes deep, assume HAM and you’ll probably be right. Some Amiga ViewModes flags are HIRES=0x8000, LACE=0x4, HAM=0x800, HALFBRITE=0x80. 2.0 ILBM writers should write a full 32-bit mode ID in the CAMG. See the IFF Manual for more information on writing and interpreting 32-bit CAMG values.

RGB values for color registers 0 to N. Previously, 4-bit RGB components each left justified in a byte. These should now be stored as a full 8-bit RGB values by duplicating 4-bit values in the high and low nibble of the byte.

The pixel data, stored in an interleaved fashion as follows (each line individually compacted if BMHD Compression = 1):

<pre>
plane 0 scan line 0
plane 1 scan line 0
plane 2 scan line 0
...
plane n scan line 0
plane 0 scan line 1
plane 1 scan line 1
etc.
</pre>

Also watch for AUTH Author chunks and (c) copyright chunks and preserve any copyright information if you rewrite the ILBM.

==== ILBM BODY Compression ====

The BODY contains pixel data for the image. Width, Height, and depth (Planes) is specified in the BMHD.

If the BMHD Compression byte is 0, then the scan line data is not compressed. If Compression=1, then each scan line is individually compressed as follows:

<pre>while (not produced the desired number of bytes)

/* get a byte, call it N */

if (N >= 0 && N <= 127)
/* copy the next N+1 bytes literally */

if (N >= -127 && N <= -1)
/* repeat the next byte N+1 times */

if (N == -128)
/* skip it, presumably it's padding */</pre>
==== Interpreting the Scan Line Data ====

If the ILBM is not HAM or HALFBRITE, then after parsing and uncompacting if necessary, you will have N planes of pixel data. Color register used for each pixel is specified by looking at each pixel thru the planes. For instance, if you have 5 planes, and the bit for a particular pixel is set in planes 0 and 3:

<pre>
PLANE 4 3 2 1 0
PIXEL 0 1 0 0 1
</pre>

then that pixel uses color register binary 01001 = 9.

The RGB value for each color register is stored in the CMAP chunk of the ILBM, starting with register 0, with each register’s RGB value stored as one byte of R, one byte G, and one byte of B, with each component left justified in the byte. (i.e. Amiga R, G, and B components are each stored in the high nibble of a byte)

But, if the picture is HAM or HALFBRITE, it is interpreted differently. Hopefully, if the picture is HAM or HALFBRITE, the package that saved it properly saved a CAMG chunk (look at a hex dump of your file with ASCII interpretation - you will see the chunks - they all start with a 4-ASCII-char chunk ID). If the picture is 6 planes deep and has no CAMG chunk, it is probably HAM. If you see a CAMG chunk, the ‘CAMG’ is followed by the 32-bit chunk length, and then the 32-bit Amiga view mode flags.

HAM pictures will have the 0x800 bit set in CAMG chunk ViewModes. HALFBRITE pictures will have the 0x80 bit set. See the graphics library articles for more information on HAM and HALFBRITE modes.

==== Other ILBM Notes ====

Amiga ILBMs images must be stored as an even number of bytes in width. However, the ILBM BMHD field w (width) should describe the actual image width, not the rounded up width as stored.

ILBMs created with Electronic Arts IBM or Amiga ''Deluxe Paint II'' packages are compatible (though you may have to use a ‘.lbm’ filename extension on an IBM). The ILBM graphic files may be transferred between the machines (or between the Amiga and IBM sides your Amiga if you have a CBM Bridgeboard card installed) and loaded into either package.

=== FORM FTXT ===

The FTXT (Formatted TeXT) form is the standard format for sharing text on the Amiga. The console device clip and paste functions, in conjunction with the startup-sequence ''conclip'' command, pass clipped console text through the clipboard as FTXT.

By supporting reading and writing of clipboard device FTXT, your application will allow users to cut and paste text between your application, other applications, and Amiga Shell windows.

The FTXT form is very simple. Generally, for clip and paste operations, you will only be concerned with the CHRS (character string) chunks of an FTXT. There may be one or more CHRS chunks, each of which contains a non-NULL-terminated string of ASCII characters whose length is equal to the length (StoredProperty.sp_Size) of the chunk.

Be aware that if you CollectionChunk() the CHRS chunks of an FTXT, the list accumulated by IFFParse will be in reverse order from the chunk order in the file. See the ClipFTXT.c example at the end of this article for a simple example of reading (and optionally writing) FTXT to and from the clipboard. See also the [[Clipboard_Device|Clipboard Device]] and [[Console_Device|Console Device]] for more information on console clip and paste.

== IFFParse Examples ==

Two examples follow: “ClipFTXT.c” and “Sift.c”. These are simple examples that demonstrate the use of the IFFParse library. More complex examples for displaying and saving ILBMs may be found in the [[IFF_Standard|IFF Standard]] section.

=== Clipboard FTXT Example ===

ClipFTXT.c demonstrates reading (and optional writing) of clipboard device FTXT. This example may be used as the basis for supporting console pastes.

<syntaxhighlight>
/*
*
* clipftxt.c: Writes ASCII text to clipboard unit as FTXT
* (All clipboard data must be IFF)
*
* Usage: clipftxt unitnumber
*
* To convert to an example of reading only, comment out #define WRITEREAD
*/

#include <exec/types.h>
#include <exec/memory.h>
#include <libraries/dos.h>
#include <libraries/iffparse.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/iffparse.h>

#include <stdlib.h>
#include <string.h>

/* Causes example to write FTXT first, then read it back
* Comment out to create a reader only
*/
#define WRITEREAD

#define MINARGS 2

CONST_STRPTR usage = "Usage: clipftxt unitnumber (use zero for primary unit)";

/*
* Text error messages for possible IFFERR_#? returns from various
* IFF routines. To get the index into this array, take your IFFERR code,
* negate it, and subtract one.
* idx = -error - 1;
*/
char *errormsgs[] = {
"End of file (not an error).",
"End of context (not an error).",
"No lexical scope.",
"Insufficient memory.",
"Stream read error.",
"Stream write error.",
"Stream seek error.",
"File is corrupt.",
"IFF syntax error.",
"Not an IFF file.",
"Required call-back hook missing.",
"Return to client. You should never see this."
};

#define RBUFSZ 512

#define ID_FTXT MAKE_ID('F','T','X','T')
#define ID_CHRS MAKE_ID('C','H','R','S')

struct IFFParseIFace *IIFFParse;

UBYTE mytext[]="This FTXT written to clipboard by clipftxt example.\n";

int main(int argc, char **argv)
{
struct IFFHandle *iff = NULL;
struct ContextNode *cn;
long error=0, unitnumber=0, rlen;
int textlen;
UBYTE readbuf[RBUFSZ];

/* if not enough args or '?', print usage */
if(((argc)&&(argc<MINARGS))||(argv[argc-1][0]=='?'))
{
IDOS->Printf("%s\n", usage);
return RETURN_WARN;
}

unitnumber = atoi(argv[1]);

struct Library *IFFParseBase = IExec->OpenLibrary("iffparse.library", 50);
IIFFParse = (struct IFFParseIFace*)IExec->GetInterface(IFFParseBase, "main", 1, NULL);

if (IIFFParse == NULL)
{
IDOS->Printf("Can't open iff parsing library.\n");
goto bye;
}

/*
* Allocate IFF_File structure.
*/
if (!(iff = IIFFParse->AllocIFF ()))
{
IDOS->Printf("AllocIFF() failed.\n");
goto bye;
}

/*
* Set up IFF_File for Clipboard I/O.
*/
if (!(iff->iff_Stream = (ULONG) IIFFParse->OpenClipboard (unitnumber)))
{
IDOS->Printf("Clipboard open failed.\n");
goto bye;
}
else IDOS->Printf("Opened clipboard unit %ld\n", unitnumber);

IIFFParse->InitIFFasClip (iff);

#ifdef WRITEREAD

/*
* Start the IFF transaction.
*/
if (error = IIFFParse->OpenIFF (iff, IFFF_WRITE))
{
IDOS->Printf("OpenIFF for write failed.\n");
goto bye;
}

/*
* Write our text to the clipboard as CHRS chunk in FORM FTXT
*
* First, write the FORM ID (FTXT)
*/
if(!(error = IIFFParse->PushChunk(iff, ID_FTXT, ID_FORM, IFFSIZE_UNKNOWN)))
{
/* Now the CHRS chunk ID followed by the chunk data
* We'll just write one CHRS chunk.
* You could write more chunks.
*/
if(!(error = IIFFParse->PushChunk(iff, 0, ID_CHRS, IFFSIZE_UNKNOWN)))
{
/* Now the actual data (the text) */
textlen = strlen(mytext);
if(IIFFParse->WriteChunkBytes(iff, mytext, textlen) != textlen)
{
IDOS->Printf("Error writing CHRS data.\n");
error = IFFERR_WRITE;
}
}
if(!error) error = IIFFParse->PopChunk(iff);
}
if(!error) error = IIFFParse->PopChunk(iff);

if(error)
{
IDOS->Printf("IFF write failed, error %ld: %s\n",
error, errormsgs[-error - 1]);
goto bye;
}
else IDOS->Printf("Wrote text to clipboard as FTXT\n");

/*
* Now let's close it, then read it back
* First close the write handle, then close the clipboard
*/
IIFFParse->CloseIFF(iff);
if (iff->iff_Stream) IIFFParse->CloseClipboard ((struct ClipboardHandle *)
iff->iff_Stream);

if (!(iff->iff_Stream = (ULONG) IIFFParse->OpenClipboard (unitnumber)))
{
IDOS->Printf("Reopen of Clipboard failed.\n");
goto bye;
}
else IDOS->Printf("Reopened clipboard unit %ld\n", unitnumber);

#endif /* WRITEREAD */

if (error = IIFFParse->OpenIFF (iff, IFFF_READ))
{
IDOS->Printf("OpenIFF for read failed.\n");
goto bye;
}

/* Tell iffparse we want to stop on FTXT CHRS chunks */
if (error = IFFParse->StopChunk(iff, ID_FTXT, ID_CHRS))
{
IDOS->Printf("StopChunk failed.\n");
goto bye;
}

/* Find all of the FTXT CHRS chunks */
while(1)
{
error = IIFFParse->ParseIFF(iff,IFFPARSE_SCAN);
if(error == IFFERR_EOC) continue; /* enter next context */
else if(error) break;

/* We only asked to stop at FTXT CHRS chunks
* If no error we've hit a stop chunk
* Read the CHRS chunk data
*/
cn = IIFFParse->CurrentChunk(iff);

if((cn)&&(cn->cn_Type == ID_FTXT)&&(cn->cn_ID == ID_CHRS))
{
IDOS->Printf("CHRS chunk contains:\n");
while((rlen = IIFFParse->ReadChunkBytes(iff,readbuf,RBUFSZ)) > 0)
{
IDOS->Write(Output(),readbuf,rlen);
}
if(rlen < 0) error = rlen;
}
}

if((error)&&(error != IFFERR_EOF))
{
IDOS->Printf ("IFF read failed, error %ld: %s\n",
error, errormsgs[-error - 1]);
}

bye:
if (iff)
{
/*
* Terminate the IFF transaction with the stream. Free
* all associated structures.
*/
IIFFParse->CloseIFF (iff);

/*
* Close the clipboard stream
*/
if (iff->iff_Stream)
IIFFParse->CloseClipboard ((struct ClipboardHandle *)
iff->iff_Stream);
/*
* Free the IFF_File structure itself.
*/
IIFFParse->FreeIFF (iff);
}
IExec->DropInterface((struct Interface*)IIFFParse);
IExec->CloseLibrary (IFFParseBase);

return RETURN_OK;
}
</syntaxhighlight>

=== IFF Scanner Example ===

"Sift.c" lists the type and size of every chunk in an IFF file and, and checks the IFF file for correct syntax. You should use "Sift" to check IFF files created by your programs.

<syntaxhighlight>
/*
*
* sift.c: Takes any IFF file and tells you what's in it. Verifies syntax and all that cool stuff.
*
* Usage: sift -c ; For clipboard scanning
* or sift <file> ; For DOS file scanning
*
* Reads the specified stream and prints an IFFCheck-like listing of the contents of the IFF file, if any.
* Stream is a DOS file for <file> argument, or is the clipboard's primary clip for -c.
* This program must be run from a CLI.
*
*/

#include <exec/types.h>
#include <exec/memory.h>
#include <libraries/dos.h>
#include <libraries/iffparse.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/iffparse.h>

#include <stdlib.h>
#include <string.h>

#define MINARGS 2

CONST_STRPTR usage = "Usage: sift IFFfilename (or -c for clipboard)";

void PrintTopChunk(struct IFFHandle *); /* prototype for our function */

/*
* Text error messages for possible IFFERR_#? returns from various IFF routines. To get the index into
* this array, take your IFFERR code, negate it, and subtract one.
* idx = -error - 1;
*/
char *errormsgs[] = {
"End of file (not an error).", "End of context (not an error).", "No lexical scope.",
"Insufficient memory.", "Stream read error.", "Stream write error.",
"Stream seek error.", "File is corrupt.", "IFF syntax error.",
"Not an IFF file.", "Required call-back hook missing.", "Return to client. You should never see this."
};

struct IFFParseIFace *IIFFParse = NULL;

int main(int argc, char **argv)
{
struct IFFHandle *iff = NULL;
int32 error;
int16 cbio;

/* if not enough args or '?', print usage */
if(((argc)&&(argc<MINARGS))||(argv[argc-1][0]=='?'))
{
IDOS->Printf("%s\n", usage);
goto bye;
}

/* Check to see if we are doing I/O to the Clipboard. */
cbio = (argv[1][0] == '-' && argv[1][1] == 'c');

struct Library *IFFParseBase = IExec->OpenLibrary("iffparse.library", 50);
IIFFParse = (struct IFFParseIFace*)IExec->GetInterface(IFFParseBase, "main", 1, NULL);
if (IIFFParse == NULL)
{
IDOS->Printf("Can't open iff parsing library.\n");
goto bye;
}

/* Allocate IFF_File structure. */
if (!(iff = IIFFParse->AllocIFF()))
{
IDOS->Printf("AllocIFF() failed.\n");
goto bye;
}

/*
* Internal support is provided for both AmigaDOS files, and the clipboard.device. This bizarre
* 'if' statement performs the appropriate machinations for each case.
*/
if (cbio)
{
/*
* Set up IFF_File for Clipboard I/O.
*/
if (!(iff->iff_Stream = (ULONG) IIFFParse->OpenClipboard(PRIMARY_CLIP)))
{
IDOS->Printf("Clipboard open failed.\n");
goto bye;
}
IIFFParse->InitIFFasClip(iff);
}
else
{
/* Set up IFF_File for AmigaDOS I/O. */
if (!(iff->iff_Stream = IDOS->Open(argv[1], MODE_OLDFILE)))
{
IDOS->Printf("File open failed.\n");
goto bye;
}
IIFFParse->InitIFFasDOS(iff);
}

/* Start the IFF transaction. */
if (error = IIFFParse->OpenIFF(iff, IFFF_READ))
{
IDOS->Printf("OpenIFF failed.\n");
goto bye;
}

while (1)
{
/*
* The interesting bit. IFFPARSE_RAWSTEP permits us to have precision monitoring of the
* parsing process, which is necessary if we wish to print the structure of an IFF file.
* ParseIFF() with _RAWSTEP will return the following things for the following reasons:
*
* Return code: Reason:
* 0 Entered new context.
* IFFERR_EOC About to leave a context.
* IFFERR_EOF Encountered end-of-file.
* <anything else> A parsing error.
*/
error = IIFFParse->ParseIFF(iff, IFFPARSE_RAWSTEP);

/*
* Since we're only interested in when we enter a context, we "discard" end-of-context
* (_EOC) events.
*/
if (error == IFFERR_EOC)
continue;
else if (error)
/*
* Leave the loop if there is any other error.
*/
break;

/* If we get here, error was zero. Print out the current state of affairs. */
PrintTopChunk(iff);
}

/*
* If error was IFFERR_EOF, then the parser encountered the end of
* the file without problems. Otherwise, we print a diagnostic.
*/
if (error == IFFERR_EOF)
IDOS->Printf("File scan complete.\n");
else
IDOS->Printf("File scan aborted, error %ld: %s\n",
error, errormsgs[-error - 1]);

bye:
if (iff) {
/* Terminate the IFF transaction with the stream. Free all associated structures. */
IIFFParse->CloseIFF(iff);

/*
* Close the stream itself.
*/
if (iff->iff_Stream)
if (cbio)
IIFFParse->CloseClipboard((struct ClipboardHandle *)iff->iff_Stream);
else
IDOS->Close(iff->iff_Stream);

/* Free the IFF_File structure itself. */
IIFFParse->FreeIFF(iff);
}
IExec->DropInterface((struct Interface*)IIFFParse);
IExec->CloseLibrary(IFFParseBase);

return RETURN_OK;
}

void PrintTopChunk(struct IFFHandle *iff)
{
struct ContextNode *top;
int32 i;
char idbuf[5];

/* Get a pointer to the context node describing the current context. */
if (!(top = IIFFParse->CurrentChunk(iff)))
return;

/*
* Print a series of dots equivalent to the current nesting depth of chunks processed so far.
* This will cause nested chunks to be printed out indented.
*/
for (i = iff->iff_Depth; i--; )
IDOS->Printf(". ");

/* Print out the current chunk's ID and size. */
IDOS->Printf("%s %ld ", IIFFParse->IDtoStr(top->cn_ID, idbuf), top->cn_Size);

/* Print the current chunk's type, with a newline. */
IDOS->Printf(IIFFParse->IDtoStr(top->cn_Type, idbuf));
}
</syntaxhighlight>

== Function Reference ==

The following are brief descriptions of the IFFParse functions discussed in this article. Further information about these and other IFFParse functions can be found in the SDK.

{| class="wikitable"
! Function
! Description
|-
| AllocIFF()
| Creates an IFFHandle structure.
|-
| FreeIFF()
| Frees the IFFHandle structure created with AllocIFF().
|-
| OpenIFF()
| Initialize an IFFHandle structure to read or write an IFF stream.
|-
| CloseIFF()
| Closes an IFF context.
|-
| InitIFF()
| Initialize an IFFHandle as a user-defined stream.
|-
| InitIFFasDOS()
| Initialize an IFFHandle as an AmigaDOS stream.
|-
| InitIFFasClip()
| Initialize an IFFHandle as a clipboard stream.
|-
| OpenClipboard()
| Create a handle on a clipboard unit for InitIFFasClip().
|-
| ParseIFF()
| Parse an IFF file from an IFFHandle stream.
|-
| ReadChunkBytes()
| Read bytes from the current chunk into a buffer.
|-
| ReadChunkRecords()
| Read record elements from the current chunk into a buffer.
|-
| StopChunk()
| Declare a chunk that should cause ParseIFF() to return.
|-
| CurrentChunk()
| Get the context node for the current chunk.
|-
| PropChunk()
| Specify a property chunk to store.
|-
| FindProp()
| Search for a stored property in a given context.
|-
| CollectionChunk()
| Declare a chunk type for collection.
|-
| FindCollection()
| Get a pointer to the current list of collection items.
|-
| StopOnExit()
| Declare a stop condition for exiting a chunk.
|-
| EntryHandler()
| Add an entry handler to the IFFHandle context.
|-
| ExitHandler()
| Add an exit handler to the IFFHandle context.
|-
| PushChunk()
| Push a given context node onto the top of the context stack.
|-
| PopChunk()
| Pop the top context node off of the context stack.
|-
| CurrentChunk()
| Get the top context node for the current chunk.
|-
| ParentChunk()
| Get the nesting context node for a given chunk.
|-
| AllocLocalItem()
| Create a LocalContextItem (LCI) structure.
|-
| LocalItemData()
| Returns a pointer to the user data of a LocalContextItem (LCI).
|-
| StoreLocalItem()
| Insert a LocalContextItem (LCI).
|-
| StoreItemInContext()
| Store a LocalContextItem in a given context node.
|-
| FindPropContext()
| Find the property context for the current state.
|-
| FindLocalItem()
| Return a LocalContextItem from the context stack.
|-
| FreeLocalItem()
| Free a LocalContextItem (LCI) created with AllocLocalItem().
|-
| SetLocalItemPurge()
| Set purge vector for a local context item.
|}

IFFParse Library

2017-10-16T13:43:53Z

Fredrik Wikstrom: Added missing interface pointer in OpenClipboard() and CloseClipboard() calls.

== IFFParse Library ==

The ''iffparse.library'' was created to help simplify the job of parsing IFF files. Unlike other IFF libraries, iffparse.library is not form-specific. This means that the job of interpreting the structure and contents of the IFF file is up to you. Previous IFF file parsers were either simple but not general, or general but not simple. IFFParse tries to be both simple ''and'' general.

== The Structure of IFF Files ==

Many people have a misconception that IFF means image files. This is not the case. IFF (short for Interchange File Format) is a method of portably storing structured information in machine-readable form. The actual information can be anything, but the manner in which it is stored is very specifically detailed. This specification is the IFF standard.

The IFF standard was originally designed in 1985 by Electronic Arts in conjunction with a committee of developers. The full standard along with file descriptions and sample code is available at [[IFF_Standard|IFF Standard]].

The goal of the IFF standard is to allow customers to move their own data between independently developed software products. The types of data objects to exchange are open-ended and currently include plain and formatted text, raster and structured graphics, fonts, music, sound effects, musical instrument descriptions, and animation. IFF addresses these needs by defining a standard for self-identifying file structures and rules for accessing these files.

=== Chunks: The Building Blocks of IFF ===

IFF files contain various types and amounts of data grouped in data ''chunks'', each starting with a four-letter ASCII identifier (the chunk ID) followed by a 32-bit length count (the chunk size). The identifier and length count make it possible for IFF readers to skip over chunks that they don’t understand or don’t care about, and extract only the information they need. It may be helpful to think of these chunks as the building blocks of an IFF file.

[[File:LibFig33-1.png|frame|center|The Chunk - The Building Block of IFF]]

The ‘CKID’ (chunk ID) characters of a real chunk will be a four letter identifier such as ‘BODY’ or ‘CMAP’, specifying the type and format of data stored in the chunk. Most chunks contain a simple defined grouping of byte, word, and long variables similar to the contents of a C structure. Others such as sound sample and bitmap image body chunks, contain a stream of compressed data.

Chunk writing is fairly straightforward with the one caveat that all chunks must be word-aligned. Therefore an odd-length chunk must be followed by a pad byte of zero (which is not counted in the size of the chunk). When chunks are nested, the enclosing chunk must state the total size of its composite contents (including any pad bytes).

{{Note|title=About Chunk Length|text=Every IFF data chunk begins with a 4-character identifier field followed by a 32-bit size field (these 8 bytes are sometimes referred to as the chunk header). The size field is a count of the rest of the data bytes in the chunk, ''not'' including any pad byte. Hence, the total space occupied by a chunk is given by its size field (rounded to the nearest even number) + 8 bytes for the chunk header}}

=== Composite Data Types ===

Standard IFF files generally contain a variable number of chunks within one of the standard IFF composite data types (which may be thought of as chunks which contain other chunks). The IFF specification defines three basic composite data types, ‘FORM’, ‘CAT ’, and ‘LIST’. A special composite data type, the ‘PROP’, is found only inside a LIST.

Usage of Composite IFF Types

{| class="wikitable"
| FORM || A grouping of chunks which describe one set of data
|-
| LIST || A grouping of the same type of FORMs with shared properties in a PROP
|-
| PROP || May appear in a LIST to define chunks shared by several FORMs
|-
| CAT || A concatenation of related FORMs or LISTs
|}

The special IFF composite data types, like simple chunks, start with a 4-character identifier (such as ‘FORM’), followed by a 32-bit length. But their data begins with a second 4-character identifier that tells you what type of data is in the composite. For example, a FORM ILBM contains chunks describing a bitmap image, and a FORM FTXT contains chunks describing formatted text.

It may help to think of each composite data type as a box containing chunks, the IFF building blocks. The following figure shows a diagram of a typical composite.

[[File:LibFig33-2.png|frame|center|The FORM – The Most Common IFF File Type]]

The example FORM in the previous figure is outlined below showing the size of chunks within the FORM. Notice that the size of a composite ''includes'' its second 4-character identifier (shown below as ‘NAME’).

. FORM 72 NAME (72 is the size of the FORM starting with the “N” of NAME)
. . CKID 22 (then 22 bytes of data, so chunk header + chunk size is 30)
. . CKID 10 (then 10 bytes of data, so chunk header + chunk size is 18)
. . CKID 12 (then 12 bytes of data, so chunk header + chunk size is 20)

{{Note|text=In the example above, indentation represents the nesting of the chunks within the FORM. Real FORMs and chunks would have different four-character identifiers rather than ‘NAME’ and ‘CKID’.}}

Any odd-length chunks must have a pad byte of zero at the end of the chunk. As shown below, this pad byte is not counted in the size of the chunk but ''is'' counted in the size of any composite types (such as FORM) that contain an odd-length chunk. '''Warning:''' some IFF readers and writers do not deal with this properly.

. FORM 72 NAME (72 is the size of the FORM starting with the “N” of NAME)
. . CKID 21 (then 21 bytes of data, so chunk header + chunk size is 29)
. . 0 (pad byte of zero, size 1)
. . CKID 10 (then 10 bytes of data, so chunk header + chunk size is 18)
. . CKID 12 (then 12 bytes of data, so chunk header + chunk size is 20)

Most IFF files are of the composite type FORM. Generally, a FORM is a simple grouping of chunks that provide information about some data, and the data itself. Although some standard chunks have common usage within different FORMS, the identity and format of most chunks within a FORM are relative to the definition and specification of the FORM. For example, a CRNG chunk in a FORM ILBM may have a totally different format and contents than a chunk named CRNG in a different type of FORM.

One of the most popular IFF FORMs that has been defined is the ILBM standard. This is how most Amiga bitmap imagery is stored. Since this is the most common IFF file, it is used frequently as an example.

Here is the output of a program called “Sift.c” that displays a text description of the contents of an IFF file ([[#IFF Scanner Example|Sift.c]] is listed at the end of this article). The file shown below is a fairly simple ILBM.

. FORM 11068 ILBM
. . BMHD 20
. . CAMG 4
. . CMAP 12
. . BODY 10995

{{Note|title=Computing the Size of a FORM|text=The size of the FORM (11,068 bytes) is equal to the sum of the sizes stated in each chunk contained within the FORM, plus 8 bytes for the overhead of each chunk header (4 bytes for the 4-character chunk ID, and 4 bytes for the 32-bit chunk size), plus 4 bytes for the FORM’s own 4-character ID (‘ILBM’), plus 1 byte more for each pad byte that follow any odd-length chunks.}}

== Parsing an IFF File ==

Chunk reading requires a parser to scan each chunk and dispatch the proper access/conversion procedure. For a simple IFF file, such parsing may be relatively easy, consisting mainly reading in the data of desired chunks, and seeking over unwanted chunks (and the pad byte after odd-length chunks). Interpreting nested chunks is more complex, and requires a method for keeping track of the current context, i.e., the data which is still relevant at any particular depth into the nest. The original IFF specifications compare an IFF file to a C program. Such a metaphor can be useful in understanding the scope of of the chunks in an IFF file.

The IFFParse library addresses general IFF parsing requirements by providing a run-time library which can extract the chunks you want from an IFF file, with the ability to pass control to you when it reaches a chunk that requires special processing such as decompression. IFFParse also understands complex nested IFF formats and will keep track of the context for you.

=== Basic Functions and Structures of IFFParse Library ===

The structures and flags of the IFFParse library are defined in the include files <libraries/iffparse.h> and <libraries/iffparse.i>. IFF files are manipulated through a structure called an IFFHandle. Only some of the fields in the IFFHandle are publicly documented. The rest are managed internally by IFFParse. This handle is passed to all IFFParse functions, and contains the current parse state and position in the file. An IFFHandle is obtained by calling AllocIFF(), and freed through FreeIFF(). This is the only legal way to obtain and dispose of an IFFHandle.

The public portion of if IFFHandle is defined as follows:

<syntaxhighlight>
/*
* Structure associated with an active IFF stream.
* "iff_Stream" is a value used by the client's read/write/seek functions -
* it will not be accessed by the library itself and can have any value
* (could even be a pointer or a BPTR).
*/
struct IFFHandle {
ULONG iff_Stream;
ULONG iff_Flags;
LONG iff_Depth; /* Depth of context stack. */
/* There are private fields hiding here. */
};
</syntaxhighlight>

== Stream Management ==

A stream is a linear array of bytes that may be accessed sequentially or randomly. DOS files are streams. IFFParse uses Hook structures (defined in <utility/hooks.h>) to implement a general stream management facility. This allows the IFFParse library to read, write, and seek any type of file handle or device by using an application-provided hook function to open, read, write, seek and close the stream.

Built on top of this facility, IFFParse has two internal stream managers: one for unbuffered DOS files (AmigaDOS filehandles), and one for the Clipboard.

=== Initialization ===

As shown above, the IFFHandle structure contains the public field iff_Stream. This is a longword that must be initialized to contain something meaningful to the stream manager. IFFParse never looks at this field itself (at least not directly). Your iff_Stream may be an AmigaDOS filehandle, or an IFFParse ClipboardHandle, or a custom stream of any type if you provide your own custom stream handler (see the section on [[#Custom Stream Handlers|Custom Stream Handlers]]). You must initialize your IFFHandle structure’s iff_Stream to your stream, and then initialize the IFFHandle’s flags and stream hook.

Three sample initializations are shown here. In the case of the internal DOS stream manager, iff_Stream is an AmigaDOS filehandle as returned by Open():

<syntaxhighlight>
iff->iff_Stream = (ULONG) IDOS->Open ("filename", MODE_OLDFILE);
if(iff->iff_Stream) IIFFParse->InitIFFasDOS (iff); /* use internal DOS stream manager */
</syntaxhighlight>

In the case of the internal Clipboard stream manager, iff_Stream is a pointer to an IFFParse ClipboardHandle structure (the OpenClipboard() call used here is a function of iffparse.library, not the clipboard.device):

<syntaxhighlight>
iff->iff_Stream = (ULONG) IIFFParse->OpenClipboard (PRIMARY_CLIP);
IIFFParse->InitIFFasClip (iff); /* use internal Clipboard stream manager */
</syntaxhighlight>

When using a custom handle such as an fopen() file handle, or a device other than the clipboard, you must provide your own flags and stream handler:

<syntaxhighlight>
iff->iff_Stream = (ULONG) OpenMyCustomStream("foo");
IIFFParse->InitIFF (iff, IFFF_FSEEK | IFFF_RSEEK, &mystreamhook);
</syntaxhighlight>

IFFParse “knows” the seek capabilities of DOS and ClipboardHandle streams, so InitIFFasDOS() and InitIFFasClip() set the flags for you.

{{Note|title=You May Change the Seek Bits in iff_Flags|text=IFFParse sets IFFF_FSEEK | IFFF_RSEEK for DOS files. This is not always true (e.g., pipes). If you know that a DOS file has different seek characteristics, your application may correct the seek bits in iff_Flags after calling InitIFFasDOS().}}

When using InitIFF() to provide a custom handler, you must also provide flags to tell IFFParse the capabilities of your stream. The flags are:

; IFFF_FSEEK
: This stream has forward-seek capability only.

; IFFF_RSEEK
: This stream has random-seek capability. IFFF_RSEEK tends to imply IFFF_FSEEK, but it’s best to specify both.

If neither flag is specified, you’re telling IFFParse that it can’t seek through the stream.

After your stream is initialized, call OpenIFF():

<syntaxhighlight>
error = IIFFParse->OpenIFF (iff, IFFF_READ);
</syntaxhighlight>

Once you establish a read/write mode (by passing IFFF_READ or IFFF_WRITE), you remain in that mode until you call CloseIFF().

=== Termination ===

Termination is simple. Just call CloseIFF(iff). This may be called at any time, and terminates IFFParse’s transaction with the stream. The stream itself is not closed. The IFFHandle may be reused; you may safely call OpenIFF() on it again. You are responsible for closing the streams you opened. A stream used in an IFFHandle must generally remain open until you CloseIFF().

=== Custom Streams ===

A custom stream handler can allow you (and iffparse.library) to use your compiler’s own file I/O functions such as fopen(), fread() and fwrite(), rather than the lower-level AmigaDOS equivalents Open(), Read(), and Write(). A custom stream handler could also be used to read or write IFF files from an Exec device or an unusual handler or file system.

If you install your own stream handler function, iffparse.library will call your function whenever it needs to read, write, or seek on your file. Your stream handler function will then perform these stream actions for iffparse.library. See the “Custom Stream Handlers” section for more information on custom stream handlers.

== Parsing and Writing IFF ==

For information on parsing IFF see [[Parsing_IFF|Parsing IFF]].

For information on writing IFF see [[Writing_IFF|Writing IFF]].

== Context Functions ==

Internally, IFFParse maintains IFF nesting and scoping context via a ''context stack''. The PushChunk() and PopChunk() functions get their names from this basic idea of the iffparse.library. Direct access to this stack is not allowed. However, many functions are provided to assist in examining and manipulating the context stack.

{{Note|title=About the Context Stack|text=It is probably easier to think of a stack of blocks on a table in front of you when reading this discussion.}}

As the nesting level increases (as would happen when parsing a nested LIST or FORM), the depth of the context stack increases; new elements are added to the top. When these contexts expire, the ContextNodes are deleted and the stack shrinks.

=== Context Nodes ===

The current context is said to be the top element on the stack. Contextual information is stored in a structure called a ContextNode:

<syntaxhighlight>
struct ContextNode {
struct MinNode cn_Node;
LONG cn_ID;
LONG cn_Type;
LONG cn_Size; /* Size of this chunk */
LONG cn_Scan; /* # of bytes read/written so far */
/* There are private fields hiding here. */
};
</syntaxhighlight>

==== CurrentChunk() ====

You can obtain a pointer to the current ContextNode through the function CurrentChunk():

<syntaxhighlight>
currentnode = IIFFParse->CurrentChunk (iff);
</syntaxhighlight>

The ContextNode tells you the type, ID, and size of the currently active chunk. If there is no currently active context, NULL is returned.

==== ParentChunk() ====

To find the parent of a context, you call ParentChunk() on the relevant ContextNode:

<syntaxhighlight>
parentnode = IIFFParse->ParentChunk(currentnode);
</syntaxhighlight>

If there is no parent context, NULL is returned.

=== The Default Context ===

When you first obtain an IFFHandle through AllocIFF(), a hidden default context node is created. You cannot get direct access to this node through CurrentChunk() or ParentChunk(). However, using StoreLocalItem(), you can store information in this context.

=== Context-Specific Data: LocalContextItems ===

ContextNodes can contain application data specific to that context. These data objects are called LocalContextItems. LocalContextItems (LCIs) are a grey-box structure which contain a type, ID and identification field. LCIs are used to store context-sensitive data. The format of this data is application-defined. A ContextNode can contain as many LCIs as you want.

[[File:LibFig33-3.png|frame|center|IFFParse Context Stack]]

The previous figure shows the relationship between the IFFHandle, the ContextNodes, and the LCIs. The IFFHandle is the root of the tree, so to speak. ContextNodes “grow” out of the IFFHandle. In turn, LCIs "grow" out of the ContextNodes. What grows out of an LCI is client-defined.

==== AllocLocalItem() ====

To create an LCI, you use the function AllocLocalItem():

<syntaxhighlight>
lci = IIFFParse->AllocLocalItem (type, id, ident, datasize);
</syntaxhighlight>

If successful, you will be returned a pointer to an LCI having the specified type, ID, and identification values; and with datasize bytes of buffer space for your application to use.

==== LocalItemData() ====

To get a pointer to an LCIs data buffer, you use LocalItemData():

<syntaxhighlight>
buf = IIFFParse->LocalItemData (lci);
</syntaxhighlight>

You may read and write the buffer to your heart’s content; it is yours. You should not, however, write beyond the end of the buffer. The size of the buffer is what you asked for when you called AllocLocalItem().

=== Storing LCIs ===

Once you’ve created and initialized an LCI, you’ll want to attach it to a ContextNode. Though a ContextNode can have many LCIs, a given LCI can be linked to only one ContextNode. Once linked, an LCI cannot be removed from a ContextNode (this may change in the future). Storing an LCI in a ContextNode is done with the functions StoreLocalItem() and StoreItemInContext().

==== StoreLocalItem() ====

The StoreLocalItem() function is called as follows:

<syntaxhighlight>
error = StoreLocalItem (iff, lci, position);
</syntaxhighlight>

The position argument determines where the LCI is stored. The possible values are IFFSLI_ROOT, IFFSLI_TOP, and IFFSLI_PROP.

; IFFSLI_ROOT
: causes StoreLocalItem() to store your LCI in the default ContextNode.

; IFFSLI_TOP
: gets your LCI stored in the top (current) ContextNode.

{{Note|title=The LCI Ends When the Current Context Ends|text=When the current context expires, your LCI will be deleted by the parser.}}

IFFSLI_PROP causes your LCI to be stored in the topmost context from which a property would apply. This is usually the topmost FORM or LIST chunk. For example, suppose you had a deeply nested ILBM FORM, and you wanted to store the BMHD property in its correct context such that, when the current FORM context expired, the BMHD property would be deleted. IFFSLI_PROP will cause StoreLocalItem() to locate the proper context for such scoping, and store the LCI there. See the section on "Finding the Prop Context" for additional information on the scope of properties.

==== StoreItemInContext() ====

StoreItemInContext() is used when you already have a pointer to the ContextNode to which you want to attach your LCI. It is called like so:

<syntaxhighlight>
IIFFParse->StoreItemInContext (iff, lci, contextnode);
</syntaxhighlight>

StoreItemInContext() links your LCI into the specified ContextNode. Then it searches the ContextNode to see if there is another LCI with the same type, ID, and identification values. If so, the old one is deleted.

==== FindLocalItem() ====

After you’ve stored your LCI in a ContextNode, you will no doubt want to be able to find it again later. You do this with the function FindLocalItem(), which is called as follows:

<syntaxhighlight>
lci = IIFFParse->FindLocalItem (iff, type, id, ident);
</syntaxhighlight>

FindLocalItem() attempts to locate an LCI having the specified type, ID, and identification values. The search proceeds as follows (refer to the previous figure to understand this better).

FindLocalItem() starts at the top (current) ContextNode and searches all LCIs in that context. If no matching LCIs are found, it proceeds down the context stack to the next ContextNode and searches all its LCIs. The process repeats until it finds the desired LCI (whereupon it returns a pointer to it), or reaches the end without finding anything (where it returns NULL).

{{Note|title=Context Stack Position|text=LCIs higher in the stack will "override" lower LCIs with the same type, ID, and identification field. This is how property scoping is handled. As ContextNodes are popped off the context stack, all its LCIs are deleted as well. See the section on “Freeing LCIs” below for additional information on deleting LCIs.}}

=== Some Interesting Internal Details ===

{{Note|title=Warning|text=This section details some internal implementation details of iffparse.library which may help you to understand it better. Use of the following information to do “clever” things in an application is forbidden and unsupportable. Don’t even think about it.}}

It turns out that StoredProperties, CollectionItems, and entry and exit handlers are all implemented using LCIs. For example, when you call FindProp(), you are actually calling a front-end to FindLocalItem(). The mysterious identification value (which has heretofore never been discussed) is a value which permits you to differentiate between LCIs having the same type and ID.

For instance, suppose you called PropChunk(), asking it to store an ILBM BMHD. PropChunk() will install an entry handler in the form of an LCI, having type equal to ‘ILBM’, ID equal to ‘BMHD’, and an identification value of IFFLCI_ENTRYHANDLER.

When an ILBM BMHD is encountered, the entry handler is called, and it creates and stores another LCI having type equal to ‘ILBM’, ID equal to ‘BMHD’ and an identification value of IFFLCI_PROP.

Thus, when you call FindProp(), it merely calls FindLocalItem() with your type and ID, and supplies IFFLCI_PROP for the identification value.

Therefore, handlers, StoredProperties, CollectionItems and your own custom LCIs can never be confused with each other, since they all have unique identification values. Since they are all handled (and searched for) in the same way, they all “override” each other in a consistent way. Just as StoredProperties higher in the context stack will be found and returned before identical ones in lower contexts, so will chunk handlers be found and invoked before ones lower on the context stack (recall FindLocalItem()’s search procedure).

This means you can temporarily override a chunk handler by installing an identical handler in a higher context. The handler will persist until the context in which it is stored expires, after which, the original one regains scope.

== Error Handling ==

If at any time during reading or writing you encounter an error, the IFFHandle is left in an undefined state. Upon detection of an error, you should perform an abort sequence and CloseIFF() the IFFHandle. Once CloseIFF() has been called, the IFFHandle is restored to normalcy and may be reused.

== Advanced Topics ==

This section discusses customizing of IFFParse data handling. For applications with special needs, IFFParse supports both custom stream handlers and custom chunk handlers.

=== Custom Stream Handlers ===

As discussed earlier, IFFParse contains built-in stream handlers for AmigaDOS file handles as returned by Open(), and for the clipboard.device. If you are using AmigaDOS filehandles or the clipboard.device, you need not supply a custom stream handler.

If you wish to use your compiler’s own file I/O functions (such as fread() ) or need to read or write to an unusual handler or Exec device, you must provide a custom stream handler for your IFFHandle. Your custom stream handler will be called to perform all reads, writes, and seeks on your custom stream. The allows you to use compiler file I/O functions, Exec device commands, or any other method to perform the requested stream operations.

If you are implementing your own custom stream handler, you will need to know the mechanics of hook call-backs, and how to interpret the parameters. An IFFParse custom stream handler is simply a function in your code that follows hook function conventions (Hook functions are also known as callback functions. See [[Utility_Library|Utility Library]] for more details).

==== Installing a Custom Stream Handler ====

To initialize your IFFHandle to point to your custom stream and stream handler, you must open your stream and place a pointer to the stream in your IFFHandle’s iff_Stream field. This pointer could be the return from fopen(), or an Exec device I/O request, or any other type of pointer which will provide your custom stream handler with a way to manage your stream. For example:

<syntaxhighlight>
iff->iff_Stream = (ULONG) fopen("foo");
</syntaxhighlight>

Next, you must install your custom handler for this stream, and also tell IFFParse the seek capabilities of your stream. To install your custom stream handler, you must first set up a Hook structure (<utility/hooks.h>) to point to your stream handling function. Then use InitIFF() to install your stream handler and also tell IFFParse the seek capabilities of your stream. There is “some assembly required”.

For an IFFParse custom stream hook the function prototype looks like this:

<syntaxhighlight>
int32 mystreamhandler(struct Hook *hook, struct IFFHandle *iff, struct IFFStreamCmd *actionpkt);
</syntaxhighlight>

A return of 0 indicates success. A non-zero return indicates an error.

For example,

<syntaxhighlight>
static int32 mystreamhandler
(
struct Hook *hook,
struct IFFHandle *iff,
struct IFFStreamCmd *actionpkt
)
{
/*
* Code to handle the stream commands - see end this section
* for a complete example custom stream handler function.
*
*/
}

/* Initialization of Hook structure for registerized handler function */
struct Hook mystreamhook
{
{ NULL },
(HOOKFUNC) mystreamhandler, /* h_Entry, registerized function entry */
NULL,
NULL
};

/* Open custom stream and InitIFF to custom stream handler */
if ( iff->iff_Stream = (ULONG) myopen("foo") )
{
IIFFParse->InitIFF (iff, IFFF_FSEEK | IFFF_RSEEK, &mystreamhook);
}
</syntaxhighlight>

==== Inside a Custom Stream Handler ====

When the library calls your stream handler, you’ll be passed a pointer to the Hook structure (hook in the example used here), a pointer to the IFFHandle (iff), and a pointer to an IFFStreamCmd structure (actionpkt). Your stream pointer may be found in iff->iff_Stream where you previously stored it. The IFFStreamCmd (actionpkt) will describe the action that IFFParse needs you to perform on your stream:

<syntaxhighlight>
/* Custom stream handler is passed struct IFFStreamCmd *actionpkt */
struct IFFStreamCmd {
LONG sc_Command; /* Operation to be performed (IFFCMD_) */
APTR sc_Buf; /* Pointer to data buffer */
LONG sc_NBytes; /* Number of bytes to be affected */
};

/* Possible call-back command values. (Using 0 as the value for IFFCMD_INIT
* was, in retrospect, probably a bad idea.)
*/
#define IFFCMD_INIT 0 /* Prepare the stream for a session */
#define IFFCMD_CLEANUP 1 /* Terminate stream session */
#define IFFCMD_READ 2 /* Read bytes from stream */
#define IFFCMD_WRITE 3 /* Write bytes to stream */
#define IFFCMD_SEEK 4 /* Seek on stream */
#define IFFCMD_ENTRY 5 /* You just entered a new context */
#define IFFCMD_EXIT 6 /* You're about to leave a context */
#define IFFCMD_PURGELCI 7 /* Purge a LocalContextItem */
</syntaxhighlight>

Your custom stream handler should perform the requested action on your custom stream, and then return 0 for success or an IFFParse error if an error occurred. The following code demonstrates a sample stream handler for a stream which was opened with a compiler’s fopen() buffered file I/O function:

<syntaxhighlight>
static int32 mystreamhandler ( struct Hook *hook,
struct IFFHandle *iff,
struct IFFStreamCmd *actionpkt )
{
FILE *stream;
int32 nbytes, error;
uint8 *buf;

stream = (FILE *) iff->iff_Stream; /* get your stream pointer */
nbytes = actionpkt->sc_NBytes; /* length for command */
buf = (uint8 *) actionpkt->sc_Buf; /* buffer for the command */

/* Now perform the action specified by the actionpkt->sc_Command */

switch (actionpkt->sc_Command) {
case IFFCMD_READ:
/*
* IFFCMD_READ means read sc_NBytes from the stream and place
* it in the memory pointed to by sc_Buf. Be aware that
* sc_NBytes may be larger than can be contained in an int.
* This is important if you plan on recompiling this for
* 16-bit ints, since fread() takes int arguments.
*
* Any error code returned will be remapped by IFFParse into
* IFFERR_READ.
*/
error = (fread (buf, 1, nbytes, stream) != nbytes);
break;

case IFFCMD_WRITE:
/*
* IFFCMD_WRITE is analogous to IFFCMD_READ.
*
* Any error code returned will be remapped by IFFParse into
* IFFERR_WRITE.
*/
error = (fwrite (buf, 1, nbytes, stream) != nbytes);
break;

case IFFCMD_SEEK:
/*
* IFFCMD_SEEK asks that you performs a seek relative to the
* current position. sc_NBytes is a signed number,
* indicating seek direction (positive for forward, negative
* for backward). sc_Buf has no meaning here.
*
* Any error code returned will be remapped by IFFParse into
* IFFERR_SEEK.
*/
error = (fseek (stream, nbytes, 1) == -1);
break;

case IFFCMD_INIT:
/*
* IFFCMD_INIT means to prepare your stream for reading.
* This is used for certain streams that can't be read
* immediately upon opening, and need further preparation.
* This operation is allowed to fail; the error code placed
* in D0 will be returned directly to the client.
*
* An example of such a stream is the clipboard. The
* clipboard.device requires you to set the io_ClipID and
* io_Offset to zero before starting a read. You would
* perform such a sequence here. (Stdio files need no such
* preparation, so we simply return zero for success.)
*/
case IFFCMD_CLEANUP:
/*
* IFFCMD_CLEANUP means to terminate the transaction with
* the associated stream. This is used for streams that
* can't simply be closed. This operation is not allowed to
* fail; any error returned will be ignored.
*
* An example of such a stream is (surprise!) the clipboard.
* It requires you to explicitly end reads by CMD_READing
* past the end of a clip, and end writes by sending a
* CMD_UPDATE. You would perform such a sequence here.
* (Again, stdio needs no such sequence.)
*/
error = 0;
break;
}
return (error);
}
</syntaxhighlight>

=== Custom Chunk Handlers ===

Like custom stream handlers, custom chunk handlers are implemented using Hook structures. See the previous section for details on how a handler function may be interfaced using a Hook structure.

There are two types of chunk handlers: entry handlers and exit handlers. Entry handlers are invoked just after the parser enters the chunk; the stream will be positioned to read the first byte in the chunk. (If the chunk is a FORM, LIST, CAT, or PROP, the longword type will be read by the parser; the stream will be positioned to read the byte immediately following the type.) Exit handlers are invoked just before the parser leaves the chunk; the stream is not positioned predictably within the chunk.

==== Installing a Custom Chunk Handler ====

To install an entry handler, you call EntryHandler() in the following manner:

<syntaxhighlight>
error = IIFFParse->EntryHandler (iff, type, id, position, hookptr, object);
</syntaxhighlight>

An exit handler is installed by saying:

<syntaxhighlight>
error = IIFFParse->ExitHandler (iff, type, id, position, hookptr, object);
</syntaxhighlight>

In both cases, a handler is installed for chunks having the specified type and id. The position argument specifies in what context to install the handler, and is identical to the position argument used by StoreLocalItem(). The hookptr argument given above is a pointer to your Hook structure.

==== Inside a Custom Chunk Handler ====

The mechanics of receiving parameters through the Hook are covered in the “Custom Stream Handlers” section, and are not duplicated here. Refer to the EntryHandler() and ExitHandler() Autodocs for the contents of the registers upon entry.

Once inside your handler, you can call nearly all functions in the iffparse.library, however, you should avoid calling ParseIFF() from within chunk handlers.

Your handler runs in the same environment as whoever called ParseIFF(). The propagation sequence is:

'''mainline''' --''calls''--> '''ParseIFF()''' --''calls''--> '''your_handler()'''

Thus, your handler runs on your mainline’s stack, and can call any OS functions the mainline code can. (Your handler will have to set the global base pointer if your code uses base-relative addressing.)

The return code will affect the parser in a number of ways:

* If you return zero (a normal, uneventful return), ParseIFF() will continue normally. If you return the value IFFERR_RETURN2CLIENT, ParseIFF() will stop and return the value zero to the mainline code.

* If you return any other value, ParseIFF() will stop and return that value to the mainline code. This is how you should return error conditions to the client code.

==== The Object Parameter ====

The object parameter supplied to EntryHandler() and ExitHandler() is a pointer which will be passed to your handler when invoked. This pointer can be anything; the parser doesn’t use it directly. As an example, you might pass the pointer to the IFFHandle. This way, when your handler is called, you’ll be able to easily perform operations on the IFFHandle within your handler. Such code might appear as follows:

<syntaxhighlight>
error = EntryHandler (iff, ID_ILBM, ID_BMHD, IFFSLI_ROOT, hook, iff);
</syntaxhighlight>

And your handler would be declared as follows:

<syntaxhighlight>
int32 MyHandler (struct Hook *hook,
int32 *cmd,
struct IFFHandle *iff)

</syntaxhighlight>

From within your handler, you could then call CurrentChunk(), ReadChunkBytes(), or nearly any other operation on the IFFHandle. Please refer to the EntryHandler() and ExitHandler() Autodocs for additional information on the use of chunk handlers.

=== Finding the Prop Context ===

Earlier it was mentioned that supplying a position value of IFFSLI_PROP to StoreLocalItem() would store it in the topmost property scope. FindPropContext() is the routine that finds that topmost context.

Property chunks (such as the BMHD, CMAP, and others) have dominion over the FORM that contains them; they are said to be “in scope” and their definition persists until the FORM’s context ends. Thus, a property chunk has a scoping level equal to the FORM that contains it; when the FORM ends, the property dies with it.

Consider a more complicated example. Suppose you have a LIST with a PROP in it. PROPs are the global variables of LISTs; thus a property chunk declared in a PROP will persist until the LIST’s context ends.

This is what FindPropContext() is looking for; a context level in which a property chunk may be installed.

FindPropContext() starts at the parent of the current context (second from the top of the context stack) and starts searching downward, looking for the first FORM or LIST context it finds. If it finds one, it returns a pointer to that ContextNode. If it can’t find a suitable context level, it returns NULL.

FindPropContext() is called as follows:

<syntaxhighlight>
struct ContextNode *cn = IFFParse->FindPropContext (iff);
</syntaxhighlight>

=== Freeing LCIs ===

Ordinarily, the parser will automatically delete LCIs you have allocated and installed. However, you may have a case where simply FreeVec()ing your LCI is not enough; you may need to free some ancillary memory, or decrement a counter, or send a signal, or something. This is where SetLocalItemPurge() comes in. It is called as follows:

<syntaxhighlight>
IFFParse->SetLocalItemPurge (lci, hookptr);
</syntaxhighlight>

When the parser is ready to delete your LCI, your purge handler code will be called through the Hook you supplied. You can then perform all your necessary operations. One of these operations should be to free the LCI itself. This is done with FreeLocalItem():

<syntaxhighlight>
IIFFParse->FreeLocalItem (lci);
</syntaxhighlight>

This deallocates the memory used to store the LCI and the client buffer allocated with it. FreeLocalItem() is only called as part of a custom purge handler.

As with custom chunk handlers, your purge handler executes in the same environment as the mainline code that called ParseIFF(). It is recommended that you keep purge handlers short and to the point; super clever stuff should be reserved for custom chunk handlers, or for the client’s mainline code. Custom purge handlers must ''always'' work; failures will be ignored.

== IFF FORM Specifications ==

The specifications for Amiga IFF formats are maintained by the AmigaOS Development Team. The latest specifications are published in the [[IFF_Standard|IFF Standard]]. Updates of the IFF Manual, selected new FORMs and changes to existing FORMs are documented on this wiki.

Some of the most commonly used IFF FORMs are the four that were originally specified in the EA IFF-85 standard:

{| class="wikitable"
| ILBM || Bitmap images and palettes
|-
| FTXT || Simple formatted text
|-
| SMUS || Simple musical scores
|-
| 8SVX || 8-bit sound samples
|}

Of these four, ILBM is the most commonly encountered FORM, and FTXT is becoming increasingly important since the ''conclip'' command passes clipped console text through the clipboard as FTXT. All data clipped to the clipboard must be in an IFF format.

This section will provide a brief summary of the ILBM and FTXT FORMs and their most used common chunks. Please consult the EA-IFF specifications for additional information.

=== FORM ILBM ===

The IFF file format for graphic images on the Amiga is called FORM ILBM (InterLeaved BitMap). It follows a standard parsable IFF format.

==== ILBM.BMHD BitMapHeader Chunk ====

The most important chunk in a FORM ILBM is the BMHD (BitMapHeader) chunk which describes the size and compression of the image:

<syntaxhighlight>
typedef UBYTE Masking; /* Choice of masking technique - Usually 0. */
#define mskNone 0
#define mskHasMask 1
#define mskHasTransparentColor 2
#define mskLasso 3

/* Compression algorithm applied to the rows of all source
* and mask planes. "cmpByteRun1" is byte run encoding.
* Do not compress across rows! Compression is usually 1.
*/
typedef UBYTE Compression;
#define cmpNone 0
#define cmpByteRun1 1

/* The BitMapHeader structure expressed as a C structure */
typedef struct {
UWORD w, h; /* raster width & height in pixels */
WORD x, y; /* pixel position for this image */
UBYTE nPlanes; /* # bitplanes (without mask, if any) */
Masking masking; /* One of the values above. Usually 0 */
Compression compression;/* One of the values above. Usually 1 */
UBYTE reserved1; /* reserved; ignore on read, write as 0 */
UWORD transparentColor; /* transparent color number. Usually 0 */
UBYTE xAspect, yAspect; /* pixel aspect, a ratio width : height */
WORD pageWidth, pageHeight; /* source "page" size in pixels */
} BitMapHeader;
</syntaxhighlight>

{{Note|title=Warning|text=This hex dump is shown only to help the reader understand how IFF chunks appear in a file. You cannot ever depend on any particular ILBM chunk being at any particular offset into the file. IFF files are composed, in their simplest form, of chunks within a FORM. Each chunk starts with a 4-letter chunkID, followed by a 32-bit length of the rest of the chunk. You must ''parse'' IFF files, skipping past unneeded or unknown chunks by seeking their length (+1 if odd length) to the next 4-letter chunk ID. In a real ILBM file, you are likely to encounter additional optional chunks. See the IFF Specification listed in [[IFF_Standard|IFF Standard]] for additional information on such chunks.}}

<pre>
0000: 464F524D 00016418 494C424D 424D4844 FORM..d.ILBMBMHD
0010: 00000014 01400190 00000000 06000100 .....@..........
0020: 00000A0B 01400190 43414D47 00000004 .....@..CAMG....
0030: 00000804 434D4150 00000030 001000E0 ....CMAP...0....
0040: E0E00000 20000050 30303050 50500030 .... ..P000PPP.0
0050: 90805040 70707010 60E02060 E06080D0 ..P@ppp.`. `.`..
0060: A0A0A0A0 90E0C0C0 C0D0A0E0 424F4459 ............BODY
0070: 000163AC F8000F80 148A5544 2ABDEFFF ..c.......UD*... etc.

Interpretation:

'F O R M' length 'I L B M''B M H D'<-start of BitMapHeader chunk
0000: 464F524D 00016418 494C424D 424D4844 FORM..d.ILBMBMHD

length WideHigh XorgYorg PlMkCoRe <- Planes Mask Compression Reserved
0010: 00000014 01400190 00000000 06000100 .....@..........

TranAspt PagwPagh 'C A M G' length <- start of C-AMiGa View modes chunk
0020: 00000A0B 01400190 43414D47 00000004 .....@..CAMG....

dir include:
ViewMode 'C M A P' length R g b R <- ViewMode 800=HAM | 4=LACE
0030: 00000804 434D4150 00000030 001000E0 ....CMAP...0....

g b R g b R g b R g b R g b R g <- Rgb's are for reg0 thru regN
0040: E0E00000 20000050 30303050 50500030 .... ..P000PPP.0

b R g b R g b R g b R g b R g b
0050: 90805040 70707010 60E02060 E06080D0 ..P@ppp.`. `.`..

R g b R g b R g b R g b 'B O D Y'
0060: A0A0A0A0 90E0C0C0 C0D0A000 424F4459 ............BODY

length start of body data <- Compacted (Compression=1 above)
0070: 000163AC F8000F80 148A5544 2ABDEFFF ..c.......UD*...
0080: FFBFF800 0F7FF7FC FF04F85A 77AD5DFE ...........Zw.]. etc.

Simple CAMG ViewModes: HIRES=0x8000 LACE=0x4 HAM=0x800 HALFBRITE=0x80

( ILBMs may contain a LONGWORD ViewPort ModeID in CAMG )
</pre>

==== Interpreting ILBMs ====

ILBM is a fairly simple IFF FORM. All you really need to deal with to extract the image are the following chunks:

Information about the size, depth, compaction method (see interpreted hex dump above).

Optional Amiga ViewModes chunk. Most HAM and HALFBRITE ILBMs should have this chunk. If no CAMG chunk is present, and image is 6 planes deep, assume HAM and you’ll probably be right. Some Amiga ViewModes flags are HIRES=0x8000, LACE=0x4, HAM=0x800, HALFBRITE=0x80. 2.0 ILBM writers should write a full 32-bit mode ID in the CAMG. See the IFF Manual for more information on writing and interpreting 32-bit CAMG values.

RGB values for color registers 0 to N. Previously, 4-bit RGB components each left justified in a byte. These should now be stored as a full 8-bit RGB values by duplicating 4-bit values in the high and low nibble of the byte.

The pixel data, stored in an interleaved fashion as follows (each line individually compacted if BMHD Compression = 1):

<pre>
plane 0 scan line 0
plane 1 scan line 0
plane 2 scan line 0
...
plane n scan line 0
plane 0 scan line 1
plane 1 scan line 1
etc.
</pre>

Also watch for AUTH Author chunks and (c) copyright chunks and preserve any copyright information if you rewrite the ILBM.

==== ILBM BODY Compression ====

The BODY contains pixel data for the image. Width, Height, and depth (Planes) is specified in the BMHD.

If the BMHD Compression byte is 0, then the scan line data is not compressed. If Compression=1, then each scan line is individually compressed as follows:

<pre>while (not produced the desired number of bytes)

/* get a byte, call it N */

if (N >= 0 && N <= 127)
/* copy the next N+1 bytes literally */

if (N >= -127 && N <= -1)
/* repeat the next byte N+1 times */

if (N == -128)
/* skip it, presumably it's padding */</pre>
==== Interpreting the Scan Line Data ====

If the ILBM is not HAM or HALFBRITE, then after parsing and uncompacting if necessary, you will have N planes of pixel data. Color register used for each pixel is specified by looking at each pixel thru the planes. For instance, if you have 5 planes, and the bit for a particular pixel is set in planes 0 and 3:

<pre>
PLANE 4 3 2 1 0
PIXEL 0 1 0 0 1
</pre>

then that pixel uses color register binary 01001 = 9.

The RGB value for each color register is stored in the CMAP chunk of the ILBM, starting with register 0, with each register’s RGB value stored as one byte of R, one byte G, and one byte of B, with each component left justified in the byte. (i.e. Amiga R, G, and B components are each stored in the high nibble of a byte)

But, if the picture is HAM or HALFBRITE, it is interpreted differently. Hopefully, if the picture is HAM or HALFBRITE, the package that saved it properly saved a CAMG chunk (look at a hex dump of your file with ASCII interpretation - you will see the chunks - they all start with a 4-ASCII-char chunk ID). If the picture is 6 planes deep and has no CAMG chunk, it is probably HAM. If you see a CAMG chunk, the ‘CAMG’ is followed by the 32-bit chunk length, and then the 32-bit Amiga view mode flags.

HAM pictures will have the 0x800 bit set in CAMG chunk ViewModes. HALFBRITE pictures will have the 0x80 bit set. See the graphics library articles for more information on HAM and HALFBRITE modes.

==== Other ILBM Notes ====

Amiga ILBMs images must be stored as an even number of bytes in width. However, the ILBM BMHD field w (width) should describe the actual image width, not the rounded up width as stored.

ILBMs created with Electronic Arts IBM or Amiga ''Deluxe Paint II'' packages are compatible (though you may have to use a ‘.lbm’ filename extension on an IBM). The ILBM graphic files may be transferred between the machines (or between the Amiga and IBM sides your Amiga if you have a CBM Bridgeboard card installed) and loaded into either package.

=== FORM FTXT ===

The FTXT (Formatted TeXT) form is the standard format for sharing text on the Amiga. The console device clip and paste functions, in conjunction with the startup-sequence ''conclip'' command, pass clipped console text through the clipboard as FTXT.

By supporting reading and writing of clipboard device FTXT, your application will allow users to cut and paste text between your application, other applications, and Amiga Shell windows.

The FTXT form is very simple. Generally, for clip and paste operations, you will only be concerned with the CHRS (character string) chunks of an FTXT. There may be one or more CHRS chunks, each of which contains a non-NULL-terminated string of ASCII characters whose length is equal to the length (StoredProperty.sp_Size) of the chunk.

Be aware that if you CollectionChunk() the CHRS chunks of an FTXT, the list accumulated by IFFParse will be in reverse order from the chunk order in the file. See the ClipFTXT.c example at the end of this article for a simple example of reading (and optionally writing) FTXT to and from the clipboard. See also the [[Clipboard_Device|Clipboard Device]] and [[Console_Device|Console Device]] for more information on console clip and paste.

== IFFParse Examples ==

Two examples follow: “ClipFTXT.c” and “Sift.c”. These are simple examples that demonstrate the use of the IFFParse library. More complex examples for displaying and saving ILBMs may be found in the [[IFF_Standard|IFF Standard]] section.

=== Clipboard FTXT Example ===

ClipFTXT.c demonstrates reading (and optional writing) of clipboard device FTXT. This example may be used as the basis for supporting console pastes.

<syntaxhighlight>
/*
*
* clipftxt.c: Writes ASCII text to clipboard unit as FTXT
* (All clipboard data must be IFF)
*
* Usage: clipftxt unitnumber
*
* To convert to an example of reading only, comment out #define WRITEREAD
*/

#include <exec/types.h>
#include <exec/memory.h>
#include <libraries/dos.h>
#include <libraries/iffparse.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/iffparse.h>

#include <stdlib.h>
#include <string.h>

/* Causes example to write FTXT first, then read it back
* Comment out to create a reader only
*/
#define WRITEREAD

#define MINARGS 2

CONST_STRPTR usage = "Usage: clipftxt unitnumber (use zero for primary unit)";

/*
* Text error messages for possible IFFERR_#? returns from various
* IFF routines. To get the index into this array, take your IFFERR code,
* negate it, and subtract one.
* idx = -error - 1;
*/
char *errormsgs[] = {
"End of file (not an error).",
"End of context (not an error).",
"No lexical scope.",
"Insufficient memory.",
"Stream read error.",
"Stream write error.",
"Stream seek error.",
"File is corrupt.",
"IFF syntax error.",
"Not an IFF file.",
"Required call-back hook missing.",
"Return to client. You should never see this."
};

#define RBUFSZ 512

#define ID_FTXT MAKE_ID('F','T','X','T')
#define ID_CHRS MAKE_ID('C','H','R','S')

struct IFFParseIFace *IIFFParse;

UBYTE mytext[]="This FTXT written to clipboard by clipftxt example.\n";

int main(int argc, char **argv)
{
struct IFFHandle *iff = NULL;
struct ContextNode *cn;
long error=0, unitnumber=0, rlen;
int textlen;
UBYTE readbuf[RBUFSZ];

/* if not enough args or '?', print usage */
if(((argc)&&(argc<MINARGS))||(argv[argc-1][0]=='?'))
{
IDOS->Printf("%s\n", usage);
return RETURN_WARN;
}

unitnumber = atoi(argv[1]);

struct Library *IFFParseBase = IExec->OpenLibrary("iffparse.library", 50);
IIFFParse = (struct IFFParseIFace*)IExec->GetInterface(IFFParseBase, "main", 1, NULL);

if (IIFFParse == NULL)
{
IDOS->Printf("Can't open iff parsing library.\n");
goto bye;
}

/*
* Allocate IFF_File structure.
*/
if (!(iff = IIFFParse->AllocIFF ()))
{
IDOS->Printf("AllocIFF() failed.\n");
goto bye;
}

/*
* Set up IFF_File for Clipboard I/O.
*/
if (!(iff->iff_Stream = (ULONG) IIFFParse->OpenClipboard (unitnumber)))
{
IDOS->Printf("Clipboard open failed.\n");
goto bye;
}
else IDOS->Printf("Opened clipboard unit %ld\n", unitnumber);

IIFFParse->InitIFFasClip (iff);

#ifdef WRITEREAD

/*
* Start the IFF transaction.
*/
if (error = IIFFParse->OpenIFF (iff, IFFF_WRITE))
{
IDOS->Printf("OpenIFF for write failed.\n");
goto bye;
}

/*
* Write our text to the clipboard as CHRS chunk in FORM FTXT
*
* First, write the FORM ID (FTXT)
*/
if(!(error = IIFFParse->PushChunk(iff, ID_FTXT, ID_FORM, IFFSIZE_UNKNOWN)))
{
/* Now the CHRS chunk ID followed by the chunk data
* We'll just write one CHRS chunk.
* You could write more chunks.
*/
if(!(error = IIFFParse->PushChunk(iff, 0, ID_CHRS, IFFSIZE_UNKNOWN)))
{
/* Now the actual data (the text) */
textlen = strlen(mytext);
if(IIFFParse->WriteChunkBytes(iff, mytext, textlen) != textlen)
{
IDOS->Printf("Error writing CHRS data.\n");
error = IFFERR_WRITE;
}
}
if(!error) error = IIFFParse->PopChunk(iff);
}
if(!error) error = IIFFParse->PopChunk(iff);

if(error)
{
IDOS->Printf("IFF write failed, error %ld: %s\n",
error, errormsgs[-error - 1]);
goto bye;
}
else IDOS->Printf("Wrote text to clipboard as FTXT\n");

/*
* Now let's close it, then read it back
* First close the write handle, then close the clipboard
*/
IIFFParse->CloseIFF(iff);
if (iff->iff_Stream) IIFFParse->CloseClipboard ((struct ClipboardHandle *)
iff->iff_Stream);

if (!(iff->iff_Stream = (ULONG) IIFFParse->OpenClipboard (unitnumber)))
{
IDOS->Printf("Reopen of Clipboard failed.\n");
goto bye;
}
else IDOS->Printf("Reopened clipboard unit %ld\n", unitnumber);

#endif /* WRITEREAD */

if (error = IIFFParse->OpenIFF (iff, IFFF_READ))
{
IDOS->Printf("OpenIFF for read failed.\n");
goto bye;
}

/* Tell iffparse we want to stop on FTXT CHRS chunks */
if (error = IFFParse->StopChunk(iff, ID_FTXT, ID_CHRS))
{
IDOS->Printf("StopChunk failed.\n");
goto bye;
}

/* Find all of the FTXT CHRS chunks */
while(1)
{
error = IIFFParse->ParseIFF(iff,IFFPARSE_SCAN);
if(error == IFFERR_EOC) continue; /* enter next context */
else if(error) break;

/* We only asked to stop at FTXT CHRS chunks
* If no error we've hit a stop chunk
* Read the CHRS chunk data
*/
cn = IIFFParse->CurrentChunk(iff);

if((cn)&&(cn->cn_Type == ID_FTXT)&&(cn->cn_ID == ID_CHRS))
{
IDOS->Printf("CHRS chunk contains:\n");
while((rlen = IIFFParse->ReadChunkBytes(iff,readbuf,RBUFSZ)) > 0)
{
IDOS->Write(Output(),readbuf,rlen);
}
if(rlen < 0) error = rlen;
}
}

if((error)&&(error != IFFERR_EOF))
{
IDOS->Printf ("IFF read failed, error %ld: %s\n",
error, errormsgs[-error - 1]);
}

bye:
if (iff) {
/*
* Terminate the IFF transaction with the stream. Free
* all associated structures.
*/
IIFFParse->CloseIFF (iff);

/*
* Close the clipboard stream
*/
if (iff->iff_Stream)
IIFFParse->CloseClipboard ((struct ClipboardHandle *)
iff->iff_Stream);
/*
* Free the IFF_File structure itself.
*/
IIFFParse->FreeIFF (iff);
}
IExec->DropInterface((struct Interface*)IIFFParse);
IExec->CloseLibrary (IFFParseBase);

return RETURN_OK;
}
</syntaxhighlight>

=== IFF Scanner Example ===

"Sift.c" lists the type and size of every chunk in an IFF file and, and checks the IFF file for correct syntax. You should use "Sift" to check IFF files created by your programs.

<syntaxhighlight>
/*
*
* sift.c: Takes any IFF file and tells you what's in it. Verifies syntax and all that cool stuff.
*
* Usage: sift -c ; For clipboard scanning
* or sift <file> ; For DOS file scanning
*
* Reads the specified stream and prints an IFFCheck-like listing of the contents of the IFF file, if any.
* Stream is a DOS file for <file> argument, or is the clipboard's primary clip for -c.
* This program must be run from a CLI.
*
*/

#include <exec/types.h>
#include <exec/memory.h>
#include <libraries/dos.h>
#include <libraries/iffparse.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/iffparse.h>

#include <stdlib.h>
#include <string.h>

#define MINARGS 2

CONST_STRPTR usage = "Usage: sift IFFfilename (or -c for clipboard)";

void PrintTopChunk(struct IFFHandle *); /* prototype for our function */

/*
* Text error messages for possible IFFERR_#? returns from various IFF routines. To get the index into
* this array, take your IFFERR code, negate it, and subtract one.
* idx = -error - 1;
*/
char *errormsgs[] = {
"End of file (not an error).", "End of context (not an error).", "No lexical scope.",
"Insufficient memory.", "Stream read error.", "Stream write error.",
"Stream seek error.", "File is corrupt.", "IFF syntax error.",
"Not an IFF file.", "Required call-back hook missing.", "Return to client. You should never see this."
};

struct IFFParseIFace *IIFFParse = NULL;

int main(int argc, char **argv)
{
struct IFFHandle *iff = NULL;
int32 error;
int16 cbio;

/* if not enough args or '?', print usage */
if(((argc)&&(argc<MINARGS))||(argv[argc-1][0]=='?'))
{
IDOS->Printf("%s\n", usage);
goto bye;
}

/* Check to see if we are doing I/O to the Clipboard. */
cbio = (argv[1][0] == '-' && argv[1][1] == 'c');

struct Library *IFFParseBase = IExec->OpenLibrary("iffparse.library", 50);
IIFFParse = (struct IFFParseIFace*)IExec->GetInterface(IFFParseBase, "main", 1, NULL);
if (IIFFParse == NULL)
{
IDOS->Printf("Can't open iff parsing library.\n");
goto bye;
}

/* Allocate IFF_File structure. */
if (!(iff = IIFFParse->AllocIFF()))
{
IDOS->Printf("AllocIFF() failed.\n");
goto bye;
}

/*
* Internal support is provided for both AmigaDOS files, and the clipboard.device. This bizarre
* 'if' statement performs the appropriate machinations for each case.
*/
if (cbio)
{
/*
* Set up IFF_File for Clipboard I/O.
*/
if (!(iff->iff_Stream = (ULONG) IIFFParse->OpenClipboard(PRIMARY_CLIP)))
{
IDOS->Printf("Clipboard open failed.\n");
goto bye;
}
IIFFParse->InitIFFasClip(iff);
}
else
{
/* Set up IFF_File for AmigaDOS I/O. */
if (!(iff->iff_Stream = IDOS->Open(argv[1], MODE_OLDFILE)))
{
IDOS->Printf("File open failed.\n");
goto bye;
}
IIFFParse->InitIFFasDOS(iff);
}

/* Start the IFF transaction. */
if (error = IIFFParse->OpenIFF(iff, IFFF_READ))
{
IDOS->Printf("OpenIFF failed.\n");
goto bye;
}

while (1)
{
/*
* The interesting bit. IFFPARSE_RAWSTEP permits us to have precision monitoring of the
* parsing process, which is necessary if we wish to print the structure of an IFF file.
* ParseIFF() with _RAWSTEP will return the following things for the following reasons:
*
* Return code: Reason:
* 0 Entered new context.
* IFFERR_EOC About to leave a context.
* IFFERR_EOF Encountered end-of-file.
* <anything else> A parsing error.
*/
error = IIFFParse->ParseIFF(iff, IFFPARSE_RAWSTEP);

/*
* Since we're only interested in when we enter a context, we "discard" end-of-context
* (_EOC) events.
*/
if (error == IFFERR_EOC)
continue;
else if (error)
/*
* Leave the loop if there is any other error.
*/
break;

/* If we get here, error was zero. Print out the current state of affairs. */
PrintTopChunk(iff);
}

/*
* If error was IFFERR_EOF, then the parser encountered the end of
* the file without problems. Otherwise, we print a diagnostic.
*/
if (error == IFFERR_EOF)
IDOS->Printf("File scan complete.\n");
else
IDOS->Printf("File scan aborted, error %ld: %s\n",
error, errormsgs[-error - 1]);

bye:
if (iff) {
/* Terminate the IFF transaction with the stream. Free all associated structures. */
IIFFParse->CloseIFF(iff);

/*
* Close the stream itself.
*/
if (iff->iff_Stream)
if (cbio)
IIFFParse->CloseClipboard((struct ClipboardHandle *)iff->iff_Stream);
else
IDOS->Close(iff->iff_Stream);

/* Free the IFF_File structure itself. */
IIFFParse->FreeIFF(iff);
}
IExec->DropInterface((struct Interface*)IIFFParse);
IExec->CloseLibrary(IFFParseBase);

return RETURN_OK;
}

void PrintTopChunk(struct IFFHandle *iff)
{
struct ContextNode *top;
int32 i;
char idbuf[5];

/* Get a pointer to the context node describing the current context. */
if (!(top = IIFFParse->CurrentChunk(iff)))
return;

/*
* Print a series of dots equivalent to the current nesting depth of chunks processed so far.
* This will cause nested chunks to be printed out indented.
*/
for (i = iff->iff_Depth; i--; )
IDOS->Printf(". ");

/* Print out the current chunk's ID and size. */
IDOS->Printf("%s %ld ", IIFFParse->IDtoStr(top->cn_ID, idbuf), top->cn_Size);

/* Print the current chunk's type, with a newline. */
IDOS->Printf(IIFFParse->IDtoStr(top->cn_Type, idbuf));
}
</syntaxhighlight>

== Function Reference ==

The following are brief descriptions of the IFFParse functions discussed in this article. Further information about these and other IFFParse functions can be found in the SDK.

{| class="wikitable"
! Function
! Description
|-
| AllocIFF()
| Creates an IFFHandle structure.
|-
| FreeIFF()
| Frees the IFFHandle structure created with AllocIFF().
|-
| OpenIFF()
| Initialize an IFFHandle structure to read or write an IFF stream.
|-
| CloseIFF()
| Closes an IFF context.
|-
| InitIFF()
| Initialize an IFFHandle as a user-defined stream.
|-
| InitIFFasDOS()
| Initialize an IFFHandle as an AmigaDOS stream.
|-
| InitIFFasClip()
| Initialize an IFFHandle as a clipboard stream.
|-
| OpenClipboard()
| Create a handle on a clipboard unit for InitIFFasClip().
|-
| ParseIFF()
| Parse an IFF file from an IFFHandle stream.
|-
| ReadChunkBytes()
| Read bytes from the current chunk into a buffer.
|-
| ReadChunkRecords()
| Read record elements from the current chunk into a buffer.
|-
| StopChunk()
| Declare a chunk that should cause ParseIFF() to return.
|-
| CurrentChunk()
| Get the context node for the current chunk.
|-
| PropChunk()
| Specify a property chunk to store.
|-
| FindProp()
| Search for a stored property in a given context.
|-
| CollectionChunk()
| Declare a chunk type for collection.
|-
| FindCollection()
| Get a pointer to the current list of collection items.
|-
| StopOnExit()
| Declare a stop condition for exiting a chunk.
|-
| EntryHandler()
| Add an entry handler to the IFFHandle context.
|-
| ExitHandler()
| Add an exit handler to the IFFHandle context.
|-
| PushChunk()
| Push a given context node onto the top of the context stack.
|-
| PopChunk()
| Pop the top context node off of the context stack.
|-
| CurrentChunk()
| Get the top context node for the current chunk.
|-
| ParentChunk()
| Get the nesting context node for a given chunk.
|-
| AllocLocalItem()
| Create a LocalContextItem (LCI) structure.
|-
| LocalItemData()
| Returns a pointer to the user data of a LocalContextItem (LCI).
|-
| StoreLocalItem()
| Insert a LocalContextItem (LCI).
|-
| StoreItemInContext()
| Store a LocalContextItem in a given context node.
|-
| FindPropContext()
| Find the property context for the current state.
|-
| FindLocalItem()
| Return a LocalContextItem from the context stack.
|-
| FreeLocalItem()
| Free a LocalContextItem (LCI) created with AllocLocalItem().
|-
| SetLocalItemPurge()
| Set purge vector for a local context item.
|}

Exec Lists and Queues

2017-09-21T17:29:55Z

Fredrik Wikstrom: /* Scanning a List */

== Exec Lists and Queues ==

The Amiga system software operates in a dynamic environment of data structures. An early design goal of Exec was to keep the system flexible and open-ended by eliminating artificial boundaries on the number of system structures used. Rather than using static system tables, Exec uses dynamically created structures that are added and removed as needed. These structures can be put in an unordered ''list'', or in an ordered ''list'' known as a ''queue''. A list can be empty, but never full. This concept is central to the design of Exec. Understanding lists and queues is important to understanding not only Exec itself, but also the mechanism behind the Amiga's message and port based inter-process communication.

Exec uses lists to maintain its internal database of system structures. Tasks, interrupts, libraries, devices, messages, I/O requests, and all other Exec data structures are supported and serviced through the consistent application of Exec's list mechanism. Lists have a common data structure, and a common set of functions is used for manipulating them. Because all of these structures are treated in a similar manner, only a small number of list handling functions need be supported by Exec.

== List Structure ==

A list is composed of a ''header'' and a doubly-linked chain of elements called ''nodes''. The header contains memory pointers to the first and last nodes of the linked chain. The address of the header is used as the handle to the entire list. To manipulate a list, you must provide the address of its header.

[[File:LibFig23-1.png|frame|center|Simplified Overview of an Exec List]]

Nodes may be scattered anywhere in memory. Each node contains two pointers; a successor and a predecessor. As illustrated above, a list header contains two placeholder nodes that contain no data. In an empty list, the head and tail nodes point to each other.

=== Node Structure Definition ===

A Node structure is divided into three parts: linkage, information, and content. The linkage part contains memory pointers to the node's successor and predecessor nodes. The information part contains the node type, the priority, and a name pointer. The content part stores the actual data structure of interest. For nodes that require linkage only, a small MinNode structure is used.

<syntaxhighlight>
struct MinNode
{
struct MinNode *mln_Succ;
struct MinNode *mln_Pred;
};
</syntaxhighlight>

; mln_Succ
: points to the next node in the list (successor).

; mln_Pred
: points to the previous node in the list (predecessor).

When a type, priority, or name is required, a full-featured Node structure is used.

<syntaxhighlight>
struct Node
{
struct Node *ln_Succ;
struct Node *ln_Pred;
uint8 ln_Type;
int8 ln_Pri;
STRPTR ln_Name;
};
</syntaxhighlight>

; ln_Type
: defines the type of the node (see <exec/nodes.h> for a complete list of types).

; ln_Pri
: specifies the priority of the node, ranging from +127 (highest) to -128 (lowest).

; ln_Name
: points to a printable name for the node (a NULL-terminated string).

The Node and MinNode structures are often incorporated into larger structures, so groups of the larger structures can easily be linked together. For example, the Exec Interrupt structure is defined as follows:

<syntaxhighlight>
struct Interrupt
{
struct Node is_Node;
APTR is_Data;
VOID (*is_Code)();
};
</syntaxhighlight>

Here the is_Data and is_Code fields represent the useful content of the node. Because the Interrupt structure begins with a Node structure, it may be passed to any of the Exec List manipulation functions.

=== Node Initialization ===

Before linking a node into a list, certain fields may need initialization. Initialization consists of setting the ln_Type, ln_Pri, and ln_Name fields to their appropriate values. (Note: this is only relevant to Node structures. The simpler MinNode structure does not have these fields.) The successor and predecessor fields do not require initialization.

The ln_Type field contains the data type of the node. This indicates to Exec (and other subsystems) the type, and hence the structure, of the content portion of the node (the extra data after the Node structure). The standard system types are defined in the <exec/nodes.h> include file. Some examples of standard system types are NT_TASK, NT_INTERRUPT, NT_DEVICE, and NT_MSGPORT. Custom node types are allowed, and should be defined ''downwards'' from NT_USER, for example like this:

<syntaxhighlight>
#define NT_MYTYPE1 NT_USER
#define NT_MYTYPE2 (NT_USER - 1)
#define NT_MYTYPE3 (NT_USER - 2)
/* etc., you get the idea */
</syntaxhighlight>

The ln_Pri field uses a signed numerical value ranging from +127 to -128 to indicate the priority of the node. Higher-priority nodes have greater values; for example, 127 is the highest priority, zero is nominal priority, and -128 is the lowest priority. Some Exec lists are kept sorted by priority order. In such lists, the highest-priority node is at the head of the list, and the lowest-priority node is at the tail of the list. Most Exec node types do not use a priority. In such cases, initialize the priority field to zero.

The ln_Name field is a pointer to a NULL-terminated string of characters. Node names are used to find and identify list-bound objects (like public message ports and libraries), and to bind symbolic names to actual nodes. Names are also useful for debugging purposes, so it is a good idea to provide every node with a name. Take care to provide a valid name pointer; Exec does not copy name strings.

This code fragment initializes a Node called ''sample.interrupt'', an instance of the Interrupt data structure introduced above:

<syntaxhighlight>
struct Interrupt interrupt;

interrupt.is_Node.ln_Type = NT_INTERRUPT;
interrupt.is_Node.ln_Pri = -10;
interrupt.is_Node.ln_Name = "sample.interrupt";
</syntaxhighlight>

=== List Header Structure Definition ===

As mentioned earlier, a list header maintains memory pointers to the first and last nodes of the linked chain of nodes. It also serves as a handle for referencing the entire list. The minimum list header ("mlh_") and the full-featured list header ("lh_") are generally interchangeable.

The structure MinList defines a minimum list header.

<syntaxhighlight>
struct MinList
{
struct MinNode *mlh_Head;
struct MinNode *mlh_Tail;
struct MinNode *mlh_TailPred;
};
</syntaxhighlight>

; mlh_Head
: points to the first node in the list.

; mlh_Tail
: is always NULL.

; mlh_TailPred
: points to the last node in the list.

In a few limited cases a full-featured List structure will be required:

<syntaxhighlight>
struct List
{
struct Node *lh_Head;
struct Node *lh_Tail;
struct Node *lh_TailPred;
uint8 lh_Type;
uint8 lh_Pad;
};
</syntaxhighlight>

; lh_Type
: defines the type of nodes within the list (see <exec/nodes.h>).

; lh_Pad
: is a structure alignment byte.

One subtlety here must be explained further. The list header is constructed in an efficient, but confusing manner. Think of the header as a structure containing the head and tail nodes for the list. The head and tail nodes are placeholders, and never carry data. The head and tail portions of the header actually overlap in memory. lh_Head and lh_Tail form the head node; lh_Tail and lh_TailPred form the tail node. This makes it easy to find the start or end of the list, and eliminates any special cases for insertion or removal.

[[File:LibFig23-2.png|frame|center|List Header Overlap]]

The lh_Head and lh_Tail fields of the list header act like the ln_Succ and lh_Pred fields of a node. The lh_Tail field is set permanently to NULL, indicating that the head node is indeed the first on the list - that is, it has no predecessors. See the figure below.

Likewise, the lh_Tail and lh_TailPred fields of the list header act like the ln_Succ and lh_Pred fields of a node. Here the NULL lh_Tail indicates that the tail node is indeed the last on the list-that is, it has no successors. See the figure below.

=== Header Initialization ===

List headers must be properly initialized before use. It is not adequate to initialize the entire header to zero. The head and tail entries must have specific values. The header must be initialized as follows:

# Set the lh_Head field to the address of lh_Tail.
# Clear the lh_Tail field.
# Set the lh_TailPred field to the address of lh_Head.
# Set lh_Type to the same data type as the nodes to be kept the list. (Unless you are using a MinList).

[[File:LibFig23-3.png|frame|center|Initializing a List Header Structure]]

The functions NewList() and NewMinList() are provided to properly initialize a List or a MinList, respectively, prior to use. This is not required if you create the List or MinList using AllocSysObject() because this function takes care of the initialization. The following call creates an empty Exec List of the NT_FONT type and initializes its header for you:

<syntaxhighlight>
struct List *newFontList;

newFontList = (struct List *) IExec->AllocSysObjectTags(ASOT_LIST,
ASOLIST_Type, NT_FONT,
TAG_END);

if ( newFontList == NULL )
IDOS->Printf("Out of memory\n");
</syntaxhighlight>

Lists or MinLists created via AllocSysObject() must be disposed of using a corresponding FreeSysObject() call. Please note that the list must always be empty before disposal – FreeSysObject() does not handle node removal, so failing to free your list nodes will cause a memory leak!

== List Functions ==

Exec provides a number of symmetric functions for handling lists. There are functions for inserting and removing nodes, for adding and removing head and tail nodes, for inserting nodes in a priority order, and for searching for nodes by name.

=== Node Insertion and Removal ===

The Insert() function is used for inserting a new node into any position in a list. It always inserts the node following a specified node that is already part of the list. For example, Insert(header, node, pred) inserts the node node after the node pred in the specified list. If the pred node points to the list header or is NULL, the new node will be inserted at the head of the list. Similarly, if the pred node points to the lh_Tail of the list, the new node will be inserted at the tail of the list. However, both of these actions can be better accomplished with the functions mentioned in the "Special Case Insertion" section below.

The Remove() function is used to remove a specified node from a list. For example, Remove(node) will remove the specified node from whatever list it is in. ''To be removed, a node must actually be in a list.'' If you attempt to remove a node that is not in a list, you will cause serious system problems.

=== Special Case Insertion ===

Although the Insert() function allows new nodes to be inserted at the head and the tail of a list, the AddHead() and AddTail() functions will do so with higher efficiency. Adding to the head or tail of a list is common practice in first-in-first-out (FIFO) or last-in-first-out (LIFO or stack) operations. For example, AddHead(header,node) would insert the node at the head of the specified list.

=== Special Case Removal ===

The two functions RemHead() and RemTail() are used in combination with AddHead() and AddTail() to create special list ordering. When you combine AddTail() and RemHead(), you produce a first-in-first-out (FIFO) list. When you combine AddHead() and RemHead() a last-in-first-out (LIFO or stack) list is produced. RemTail() exists for symmetry. Other combinations of these functions can also be used productively.

Both RemHead() and RemTail() remove a node from the list, and return a pointer to the removed node. If the list is empty, the function returns a NULL result.

=== MinList / MinNode Operations ===

All of the above functions and macros will work with long or short format node structures. A MinNode structure contains only linkage information. A full Node structure contains linkage information, as well as type, priority and name fields. The smaller MinNode is used where space and memory alignment issues are important. The larger Node is used for queues or lists that require a name tag for each node.

=== Prioritized Insertion ===

The list functions discussed so far do not make use of the priority field in a Node. The Enqueue() function is equivalent to Insert(), except it inserts nodes into a list sorting them according to their priority. It keeps the higher-priority nodes towards the head of the list. All nodes passed to this function must have their priority and name assigned prior to the call. Enqueue(header,mynode) inserts mynode behind the lowest priority node with a priority greater than or equal to mynode's. For Enqueue() to work properly, the list must already be sort according to priority. Because the highest priority node is at the head of the list, the RemHead() function will remove the highest-priority node. Likewise, RemTail() will remove the lowest-priority node.

{{Note|title=FIFO Is Used For The Same Priority|text=If you add a node that has the same priority as another node in the queue, Enqueue() will use FIFO ordering. The new node is inserted following the last node of equal priority.}}

=== Searching by Name ===

Because many lists contain nodes with symbolic names attached (via the ln_Name field), it is possible to find a node by its name. This naming technique is used throughout Exec for such nodes as tasks, libraries, devices, and resources.

The FindName() function searches a list for the first node with a given name. For example, FindName(header, "Furrbol") returns a pointer to the first node named "Furrbol." If no such node exists, a NULL is returned.

The case of the name characters is significant; "foo" is different from "Foo." If the case of a name should not be significant, use the FindIName() function.

Quite naturally, you cannot use FindName() or FindIName() with MinLists because these do not support named nodes.

[[File:LibFig23-4.png|frame|center|Complete Sample List Showing all Interconnections]]

=== More on the Use of Named Nodes ===

To find multiple occurrences of nodes with identical names, the FindName() or FindIName() function is called multiple times. For example, if you want to find all the nodes with the name pointed to by name:

<syntaxhighlight>
VOID DisplayName(struct List *list, CONST_STRPTR name)
{
struct Node *node;

if ( (node = IExec->FindName(list, name)) )
while ( node )
{
IDOS->Printf("Found %s at location %lx\n", node->ln_Name, node);
node = IExec->FindName((struct List *)node, name);
}
else IDOS->Printf("No node with name %s found.\n", name);
}
</syntaxhighlight>

Notice that the second search uses the node found by the first search. The FindName() function ''never'' compares the specified name with that of the starting node. It always begins the search with the successor of the starting point.

=== Empty Lists ===

It is often important to determine if a list is empty. This can be done in many ways, but only two are worth mentioning. If either the lh_TailPred field is pointing to the list header or the ln_Succ field of the lh_Head is NULL, then the list is empty.

These methods would be written as follows:

<syntaxhighlight>
/* You can use this method... */
if ( list->lh_TailPred == (struct Node *)list )
IDOS->Printf("list is empty\n");

/* Or you can use this method */
if ( NULL == list->lh_Head->ln_Succ )
IDOS->Printf("list is empty\n");
</syntaxhighlight>

Macros are available to make the code easier to read:

<syntaxhighlight>
struct List *list;
struct MinList *minlist;

if ( IsListEmpty(list) )
IDOS->Printf("list is empty\n");

if ( IsMinListEmpty(minlist) )
IDOS->Printf("minlist is empty\n");
</syntaxhighlight>

=== Scanning a List ===

Occasionally a program may need to scan a list to locate a particular node, find a node that has a field with a particular value, or just print the list. Because lists are linked in both the forward and backward directions, the list can be scanned from either the head or tail.

There are two methods to traverse lists in AmigaOS: 1) via direct manipulation of the pointers, and 2) using dedicated functions from Exec.

Here is a code fragment that uses pointers and a ''for'' loop to print the names of all nodes in a list:

<syntaxhighlight>
struct List *list;
struct Node *node;

for ( node = list->lh_Head ; node->ln_Succ != NULL ; node = node->ln_Succ )
IDOS->Printf("%p -> %s\n", node, node->ln_Name);
</syntaxhighlight>

A common mistake is to process the head or tail nodes. Valid data nodes have non-NULL successor and predecessor pointers. The above loop exits when node->ln_Succ is NULL.

Another common mistake is to free a node from within a loop, then reference the free memory to obtain the next node pointer. An extra temporary pointer solves this second problem. Here is an example:

<syntaxhighlight>
struct List *list;
struct Node *node, *next;

for ( node = list->lh_Head; (next = node->ln_Succ) != NULL ; node = next )
{
/* Do something with the node. */
/* This may include node removal from the list. */
if ( some_condition )
{
IExec->Remove(node);
}
}
</syntaxhighlight>

Here is a code fragment that uses functions and a ''for'' loop to print the names of all nodes in a list:

<syntaxhighlight>
struct List *list;
struct Node *node;

for ( node = IExec->GetHead(list) ; node != NULL ; node = IExec->GetSucc(node) )
IDOS->Printf("%p -> %s\n", node, node->ln_Name);
</syntaxhighlight>

Here is an example showing how to properly remove a node from a list while traversing:

<syntaxhighlight>
struct List *list;
struct Node *node, *next;

for ( node = IExec->GetHead(list); node != NULL; node = next )
{
next = IExec->GetSucc(node);
/* Do something with the node. */
/* This may include node removal from the list. */
if ( some_condition )
{
IExec->Remove(node);
}
}
</syntaxhighlight>

Programmers are free to choose the method they prefer. Performance is not likely a concern unless the code is used in a critical section of a program.

=== Finding the List of a Node ===

In an Exec List, the address of the header is used as the handle to the entire list so we can find the List given only a Node.

<syntaxhighlight>
struct List *findListOfNode(struct Node *node)
{
struct List *head = NULL;

if ( node != NULL )
{
while ( node->ln_Pred != NULL )
{
node = node->ln_Pred;
}

head = (struct List*)node;
}

return head;
}
</syntaxhighlight>

==== Exec List Example ====

The code below demonstrates the concepts and functions discussed in this section by building an application-defined Exec List.

<syntaxhighlight>
// buildlist.c - example which uses an application-specific Exec list

#include <exec/types.h>
#include <exec/lists.h>
#include <exec/nodes.h>
#include <exec/memory.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/utility.h>

/* Our function prototypes */
VOID AddName(struct List *, CONST_STRPTR);
VOID FreeNameNodes(struct List *);
VOID DisplayNameList(struct List *);
VOID DisplayName(struct List *, CONST_STRPTR);

struct NameNode {
struct Node nn_Node; /* System Node structure */
TEXT nn_Data[62]; /* Node-specific data */
};

#define NAMENODE_ID 100 /* The type of "NameNode" */

int main()
{
struct List *nameList;

nameList = (struct List *) IExec->AllocSysObjectTags(ASOT_LIST, TAG_END);

if ( nameList == NULL )
IDOS->Printf("Out of memory\n");
else {
AddName(nameList,"Name7"); AddName(nameList,"Name6");
AddName(nameList,"Name5"); AddName(nameList,"Name4");
AddName(nameList,"Name2"); AddName(nameList,"Name0");

AddName(nameList,"Name7"); AddName(nameList,"Name5");
AddName(nameList,"Name3"); AddName(nameList,"Name1");

DisplayName(nameList,"Name5");
DisplayNameList(nameList);

FreeNameNodes(nameList);
IExec->FreeSysObject(ASOT_LIST, nameList); /* Free list header */
}

return 0;
}

/* Allocate a NameNode structure, copy the given name into the structure,
* then add it the specified list. This example does not provide an
* error return for the out of memory condition.
*/
VOID AddName(struct List *list, CONST_STRPTR name)
{
struct NameNode *nameNode = IExec->AllocSysObjectTags(ASOT_NODE,
ASONODE_Size, sizeof(struct NameNode),
ASONODE_Type, NAMENODE_ID,
TAG_END);

if ( nameNode == NULL )
IDOS->Printf("Out of memory\n");
else {
IUtility->Strlcpy(nameNode->nn_Data, name, sizeof(nameNode->nn_Data));
nameNode->nn_Node.ln_Name = nameNode->nn_Data;
IExec->AddHead((struct List *)list, (struct Node *)nameNode);
}
}

/*
* Free the entire list, including the header. The header is not updated
* as the list is freed. This function demonstrates how to avoid
* referencing freed memory when deallocating nodes.
*/
VOID FreeNameNodes(struct List *list)
{
struct NameNode *workNode;
struct NameNode *nextNode;

workNode = (struct NameNode *) IExec->GetHead(list); /* First node */
while ( (nextNode = (struct NameNode *) IExec->GetSucc((struct Node *)workNode)) ) {
IExec->FreeSysObject(ASOT_NODE, workNode);
workNode = nextNode;
}
}

/*
* Print the names of each node in a list.
*/
VOID DisplayNameList(struct List *list)
{
struct Node *node;

if ( IsListEmpty(list) )
IDOS->Printf("List is empty.\n");
else {
for ( node = IExec->GetHead(list); node != NULL; node = IExec->GetSucc(node) )
IDOS->Printf("%lx -> %s\n", node, node->ln_Name);
}
}

/*
* Print the location of all nodes with a specified name.
*/
VOID DisplayName(struct List *list, CONST_STRPTR name)
{
struct Node *node;

if ( (node = IExec->FindName(list, name)) ) {
while ( node ) {
IDOS->Printf("Found a %s at location %lx\n", node->ln_Name, node);
node = IExec->FindName((struct List *)node, name);
}
} else IDOS->Printf("No node with name %s found.\n", name);
}
</syntaxhighlight>

=== Important Note About Shared Lists ===

It is possible to run into contention problems with other tasks when manipulating a list that is shared by more than one task. ''None'' of the standard Exec list functions arbitrates for access to the list. For example, if some other task happens to be modifying a list while your task scans it, an inconsistent view of the list may be formed. This can result in a corrupted system.

Generally it is not permissible to read or write a shared list without first locking out access from other tasks. ''All'' users of a list must use the same arbitration method. Several arbitration techniques are used on the Amiga. Some lists are protected by a semaphore. The ObtainSemaphore() call grants ownership of the list (see the [[Exec_Semaphores|Exec Semaphores]] for more information). Some lists require special arbitration. For example, you must use the Intuition LockIBase(0) call before accessing any Intuition lists. Other lists may be accessed only during Forbid() or Disable() (see [[Exec_Tasks|Exec Tasks]] for more information).

The preferred method for arbitrating use of a shared list is through semaphores because a semaphores only holds off other tasks that are trying to access the shared list. Rather than suspending all multitasking. Failure to lock a shared list before use ''will'' result in unreliable operation.

Note that I/O functions including printf() generally call Wait() to wait for I/O completion, and this allows other tasks to run. Therefore, it is not safe to print or Wait() while traversing a list unless the list is fully controlled by your application, or if the list is otherwise guaranteed not to change during multitasking.

== Function Reference ==

The following table gives a brief description of the Exec list and queue functions and macros. See the SDK for details about each call.

{| class="wikitable"
! Exec Function
! Description
|-
| AddHead()
| Insert a node at the head of a list.
|-
| AddTail()
| Append a node to the tail of a list.
|-
| AllocSysObject(ASOT_LIST)
| Allocate and initialize a new List or MinList.
|-
| AllocSysObject(ASOT_NODE)
| Allocate and initialize a new list node.
|-
| Enqueue()
| Insert or append a node to a system queue.
|-
| FindIName()
| Find a node with a given name in a system list ignoring case.
|-
| FindName()
| Find a node with a given name in a system list.
|-
| FreeSysObject(ASOT_LIST)
| Free an allocated List or MinList.
|-
| FreeSysObject(ASOT_NODE)
| Free an allocated list node.
|-
| GetHead()
| Gets the head node of a list.
|-
| GetPred()
| Gets the node predecessor.
|-
| GetSucc()
| Gets the node successor.
|-
| GetTail()
| Gets the tail node of a list.
|-
| Insert()
| Insert a node into a list.
|-
| IsMinListEmpty
| Test if minimal list is empty
|-
| IsListEmpty
| Test if list is empty
|-
| NewMinList()
| Initialize a minimal list structure for use.
|-
| NewList()
| Initialize a list structure for use.
|-
| MoveList()
| Moves all the nodes from one list to another efficiently.
|-
| RemHead()
| Remove the head node from a list.
|-
| Remove()
| Remove a node from a list.
|-
| RemTail()
| Remove the tail node from a list.
|}