home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Programming / Assembler / TFF-AOC.DMS / in.adf / Release3.1 / AutoDocs3.1.lha / doc / iffparse.doc < prev    next >
Encoding:
Text File  |  1993-08-12  |  43.7 KB  |  1,405 lines
  1. TABLE OF CONTENTS
  2.  
  3. iffparse.library/AllocIFF
  4. iffparse.library/AllocLocalItem
  5. iffparse.library/CloseClipboard
  6. iffparse.library/CloseIFF
  7. iffparse.library/CollectionChunk
  8. iffparse.library/CollectionChunks
  9. iffparse.library/CurrentChunk
  10. iffparse.library/EntryHandler
  11. iffparse.library/ExitHandler
  12. iffparse.library/FindCollection
  13. iffparse.library/FindLocalItem
  14. iffparse.library/FindProp
  15. iffparse.library/FindPropContext
  16. iffparse.library/FreeIFF
  17. iffparse.library/FreeLocalItem
  18. iffparse.library/GoodID
  19. iffparse.library/GoodType
  20. iffparse.library/IDtoStr
  21. iffparse.library/InitIFF
  22. iffparse.library/InitIFFasClip
  23. iffparse.library/InitIFFasDOS
  24. iffparse.library/LocalItemData
  25. iffparse.library/OpenClipboard
  26. iffparse.library/OpenIFF
  27. iffparse.library/ParentChunk
  28. iffparse.library/ParseIFF
  29. iffparse.library/PopChunk
  30. iffparse.library/PropChunk
  31. iffparse.library/PropChunks
  32. iffparse.library/PushChunk
  33. iffparse.library/ReadChunkBytes
  34. iffparse.library/ReadChunkRecords
  35. iffparse.library/SetLocalItemPurge
  36. iffparse.library/StopChunk
  37. iffparse.library/StopChunks
  38. iffparse.library/StopOnExit
  39. iffparse.library/StoreItemInContext
  40. iffparse.library/StoreLocalItem
  41. iffparse.library/WriteChunkBytes
  42. iffparse.library/WriteChunkRecords
  43. iffparse.library/AllocIFF                           iffparse.library/AllocIFF
  44.  
  45.    NAME
  46.     AllocIFF -- create a new IFFHandle structure. (V36)
  47.  
  48.    SYNOPSIS
  49.     iff = AllocIFF()
  50.     D0
  51.  
  52.     struct IFFHandle *AllocIFF(VOID);
  53.  
  54.    FUNCTION
  55.     Allocates and initializes a new IFFHandle structure.
  56.     This function is the only supported way to create an IFFHandle
  57.     structure since there are private fields that need to be initialized.
  58.  
  59.    RESULT
  60.     iff - pointer to IFFHandle structure or NULL if the allocation failed.
  61.  
  62.    SEE ALSO
  63.     FreeIFF(), <libraries/iffparse.h>
  64.  
  65. iffparse.library/AllocLocalItem               iffparse.library/AllocLocalItem
  66.  
  67.    NAME
  68.     AllocLocalItem -- create a local context item structure. (V36)
  69.  
  70.    SYNOPSIS
  71.     item = AllocLocalItem(type, id, ident, dataSize);
  72.     D0                    D0    D1  D2     D3
  73.  
  74.     struct LocalContextItem *AllocLocalItem(LONG, LONG, LONG, LONG);
  75.  
  76.    FUNCTION
  77.     Allocates and initializes a LocalContextItem structure with "dataSize"
  78.     bytes of associated user data. This is the only supported way to
  79.     create such an item. The user data can be accessed with the
  80.     LocalItemData() function. An item created with this function
  81.     automatically has its purge vectors set up correctly to dispose of
  82.     itself and its associated user data area. Any additional cleanup
  83.     should be done with a user-supplied purge vector.
  84.  
  85.    INPUTS
  86.     type,id - additional longword identification values
  87.     ident - longword identifier for class of context item
  88.     dataSize - number of bytes of user data to allocate for this item
  89.  
  90.    RESULT
  91.     item - pointer to initialized LocalContextItem or NULL if the
  92.            allocation failed.
  93.  
  94.    SEE ALSO
  95.     FreeLocalItem(), LocalItemData(), StoreLocalItem(),
  96.     StoreItemInContext(), SetLocalItemPurge(), <libraries/iffparse.h>
  97.  
  98. iffparse.library/CloseClipboard               iffparse.library/CloseClipboard
  99.  
  100.    NAME
  101.     CloseClipboard -- close and free an open ClipboardHandle. (V36)
  102.  
  103.    SYNOPSIS
  104.     CloseClipboard(clipHandle);
  105.                    A0
  106.  
  107.     VOID CloseClipboard(struct ClipboardHandle *);
  108.  
  109.    FUNCTION
  110.     Closes the clipboard.device and frees the ClipboardHandle structure.
  111.  
  112.    INPUTS
  113.     clipHandle - pointer to ClipboardHandle struct created with
  114.                  OpenClipboard(). Starting with V39, this may be NULL.
  115.  
  116.    SEE ALSO
  117.     OpenClipboard(), InitIFFasClip(), <libraries/iffparse.h>
  118.  
  119. iffparse.library/CloseIFF                           iffparse.library/CloseIFF
  120.  
  121.    NAME
  122.     CloseIFF -- close an IFF context. (V36)
  123.  
  124.    SYNOPSIS
  125.     CloseIFF(iff);
  126.              A0
  127.  
  128.     VOID CloseIFF(struct IFFHandle *);
  129.  
  130.    FUNCTION
  131.     Completes an IFF read or write operation by closing the IFF context
  132.     established for this IFFHandle structure. The IFFHandle structure
  133.     itself is left ready for re-use and a new context can be opened with
  134.     OpenIFF(). This function can be used for cleanup if a read or write
  135.     fails partway through.
  136.  
  137.     As part of its cleanup operation, CloseIFF() calls the client-
  138.     supplied stream hook vector. The IFFStreamCmd packet will be set
  139.     as follows:
  140.  
  141.         sc_Command:    IFFCMD_CLEANUP
  142.         sc_Buf:        (Not applicable)
  143.         sc_NBytes:    (Not applicable)
  144.  
  145.     This operation is NOT permitted to fail;  any error code returned
  146.     will be ignored (best to return 0, though). DO NOT write to this
  147.     structure.
  148.  
  149.    INPUTS
  150.     iff - pointer to IFFHandle structure previously opened with
  151.           OpenIFF(). Starting with V39, this may be NULL.
  152.  
  153.    SEE ALSO
  154.     OpenIFF(), InitIFF(), <libraries/iffparse.h>
  155.  
  156. iffparse.library/CollectionChunk             iffparse.library/CollectionChunk
  157.  
  158.    NAME
  159.     CollectionChunk -- declare a chunk type for collection. (V36)
  160.  
  161.    SYNOPSIS
  162.     error = CollectionChunk(iff, type, id);
  163.     D0                      A0   D0    D1
  164.  
  165.     LONG CollectionChunk(struct IFFHandle *, LONG, LONG);
  166.  
  167.    FUNCTION
  168.     Installs an entry handler for chunks with the given type and id so
  169.     that the contents of those chunks will be stored as they are
  170.     encountered. This is like PropChunk() except that more than one
  171.     chunk of this type can be stored in lists which can be returned by
  172.     FindCollection(). The storage of these chunks still follows the
  173.     property chunk scoping rules for IFF files so that at any given
  174.     point, stored collection chunks will be valid in the current context.
  175.  
  176.    INPUTS
  177.     iff - pointer to IFFHandle structure (does not need to be open)
  178.     type - type code for the chunk to declare (ex. "ILBM")
  179.     id - identifier for the chunk to declare (ex. "CRNG")
  180.  
  181.    RESULT
  182.     error - 0 if successful or an IFFERR_#? error code if unsuccessful.
  183.  
  184.    SEE ALSO
  185.     CollectionChunks(), FindCollection(), PropChunk(),
  186.     <libraries/iffparse.h>
  187.  
  188. iffparse.library/CollectionChunks           iffparse.library/CollectionChunks
  189.  
  190.    NAME
  191.     CollectionChunks -- declare many collection chunks at once. (V36)
  192.  
  193.    SYNOPSIS
  194.     error = CollectionChunks(iff, propArray, numPairs);
  195.     D0                       A0   A1         D0
  196.  
  197.     LONG CollectionChunks(struct IFFHandle *, LONG *, LONG);
  198.  
  199.    FUNCTION
  200.     Declares multiple collection chunks from a list. The propArray argument
  201.     is a pointer to an array of longwords arranged in pairs. The format
  202.     for the list is as follows:
  203.  
  204.         TYPE1, ID1, TYPE2, ID2, ..., TYPEn, IDn
  205.  
  206.     The argument numPairs is the number of pairs. CollectionChunks() just calls
  207.     CollectionChunk() numPairs times.
  208.  
  209.    INPUTS
  210.     iff - pointer to IFFHandle structure (does not need to be open)
  211.     propArray - pointer to array of longword chunk types and identifiers
  212.     numPairs - number of pairs in array.
  213.  
  214.    RESULT
  215.     error - 0 if successful or an IFFERR_#? error code if unsuccessful
  216.  
  217.    SEE ALSO
  218.     CollectionChunk(), <libraries/iffparse.h>
  219.  
  220. iffparse.library/CurrentChunk                   iffparse.library/CurrentChunk
  221.  
  222.    NAME
  223.     CurrentChunk -- get context node for current chunk. (V36)
  224.  
  225.    SYNOPSIS
  226.     top = CurrentChunk(iff);
  227.     D0                 A0
  228.  
  229.     struct ContextNode *CurrentChunk(struct IFFHandle *);
  230.  
  231.    FUNCTION
  232.     Returns the top context node for the given IFFHandle structure. The top
  233.     context node corresponds to the chunk most recently pushed on the
  234.     stack, which is the chunk where the stream is currently positioned.
  235.     The ContextNode structure contains information on the type of chunk
  236.     currently being parsed (or written), its size and the current
  237.     position within the chunk.
  238.  
  239.    INPUTS
  240.     iff - pointer to IFFHandle structure
  241.  
  242.    RESULT
  243.     top - pointer to top context node or NULL if none
  244.  
  245.    SEE ALSO
  246.     PushChunk(), PopChunk(), ParseIFF(), ParentChunk(),
  247.     <libraries/iffparse.h>
  248.  
  249. iffparse.library/EntryHandler                   iffparse.library/EntryHandler
  250.  
  251.    NAME
  252.     EntryHandler -- add an entry handler to the IFFHandle context. (V36)
  253.  
  254.    SYNOPSIS
  255.     error = EntryHandler(iff, type, id, position, handler, object);
  256.     D0                   A0   D0    D1  D2        A1       A2
  257.  
  258.     LONG EntryHandler(struct IFFHandle *, LONG, LONG, LONG,
  259.                       struct Hook *, APTR);
  260.  
  261.    FUNCTION
  262.     Installs an entry handler vector for a specific type of chunk into
  263.     the context for the given IFFHandle structure. Type and id are the
  264.     longword identifiers for the chunk to handle. The handler is a client-
  265.     supplied standard Hook structure, properly initialized. position
  266.     tells where to put the handler in the context. The handler will be
  267.     called whenever the parser enters a chunk of the given type, so the
  268.     IFF stream will be positioned to read the first data byte in the
  269.     chunk. The handler will execute in the same context as whoever
  270.     called ParseIFF(). The handler will be called (through the hook)
  271.     with the following arguments:
  272.  
  273.         A0:    the Hook pointer you passed.
  274.         A2:    the 'object' pointer you passed.
  275.         A1:    pointer to a LONG containing the value
  276.             IFFCMD_ENTRY.
  277.  
  278.     The error code your call-back routine returns will affect the parser
  279.     in three different ways:
  280.  
  281.     Return value        Result
  282.     ------------        ------
  283.     0:            Normal success;  ParseIFF() will continue
  284.                 through the file.
  285.     IFF_RETURN2CLIENT:    ParseIFF() will stop and return the value 0.
  286.                 (StopChunk() is internally implemented using
  287.                 this return value.)
  288.     Any other value:    ParseIFF() will stop and return the value
  289.                 you supplied. This is how errors should be
  290.                 returned.
  291.  
  292.    INPUTS
  293.     iff - pointer to IFFHandle structure.
  294.     type - type code for chunk to handle (ex. "ILBM").
  295.     id - ID code for chunk to handle (ex. "CMAP").
  296.     position- local context item position. One of the IFFSLI_#? codes.
  297.     handler - pointer to Hook structure.
  298.     object - a client-defined pointer which is passed in A2 during call-
  299.          back.
  300.  
  301.    RESULT
  302.     error - 0 if successful or an IFFERR_#? error code if unsuccessful.
  303.  
  304.    BUGS
  305.     Returning the values IFFERR_EOF or IFFERR_EOC from the call-back
  306.     routine *may* confuse the parser.
  307.  
  308.     There is no way to explicitly remove a handler once installed.
  309.     However, by installing a do-nothing handler using IFFSLI_TOP,
  310.     previous handlers will be overridden until the context expires.
  311.  
  312.    SEE ALSO
  313.     ExitHandler(), StoreLocalItem(), StoreItemInContext(),
  314.     <utility/hooks.h>, <libraries/iffparse.h>
  315.  
  316. iffparse.library/ExitHandler                     iffparse.library/ExitHandler
  317.  
  318.    NAME
  319.     ExitHandler -- add an exit handler to the IFFHandle context. (V36)
  320.  
  321.    SYNOPSIS
  322.     error = ExitHandler(iff, type, id, position, handler, object);
  323.     D0                  A0   D0    D1  D2        A1       A2
  324.  
  325.     LONG ExitHandler(struct IFFHandle *, LONG, LONG, LONG,
  326.                      struct Hook *, APTR object(;
  327.  
  328.    FUNCTION
  329.     Installs an exit handler vector for a specific type of chunk into the
  330.     context for the given IFFHandle structure. Type and id are the longword
  331.     identifiers for the chunk to handle. The handler is a client-supplied
  332.     standard Hook structure, properly initialized. Position tells
  333.     where to put the handler in the context. The handler will be called
  334.     just before the parser exits the given chunk in the "pause" parse
  335.     state. The IFF stream may not be positioned predictably within the
  336.     chunk. The handler will execute in the same context as whoever
  337.     called ParseIFF(). The handler will be called (through the hook)
  338.     with the following arguments:
  339.  
  340.         A0:    the Hook pointer you passed.
  341.         A2:    the 'object' pointer you passed.
  342.         A1:    pointer to a LONG containing the value
  343.             IFFCMD_EXIT.
  344.  
  345.     The error code your call-back routine returns will affect the parser
  346.     in three different ways:
  347.  
  348.     Return value        Result
  349.     ------------        ------
  350.     0:            Normal success;  ParseIFF() will continue
  351.                 through the file.
  352.     IFF_RETURN2CLIENT:    ParseIFF() will stop and return the value 0.
  353.                 (StopChunk() is internally implemented using
  354.                 this return value.)
  355.     Any other value:    ParseIFF() will stop and return the value
  356.                 you supplied. This is how errors should be
  357.                 returned.
  358.  
  359.    INPUTS
  360.     iff - pointer to IFFHandle structure.
  361.     type - type code for chunk to handle (ex. "ILBM").
  362.     id - identifier code for chunk to handle (ex. "CMAP").
  363.     position - local context item position. One of the IFFSLI_#? codes.
  364.     handler - pointer to Hook structure.
  365.     object - a client-defined pointer which is passed in A2 during call-
  366.          back.
  367.  
  368.    RESULT
  369.     error - 0 if successful or an IFFERR_#? error code if unsuccessful.
  370.  
  371.    BUGS
  372.     Returning the values IFFERR_EOF or IFFERR_EOC from the call-back
  373.     routine *may* confuse the parser.
  374.  
  375.     There is no way to explicitly remove a handler once installed.
  376.     However, by installing a do-nothing handler using IFFSLI_TOP,
  377.     previous handlers will be overridden until the context expires.
  378.  
  379.    SEE ALSO
  380.     EntryHandler(), StoreLocalItem(), StoreItemInContext(),
  381.     <utility/hooks.h>, <libraries/iffparse.h>
  382.  
  383. iffparse.library/FindCollection               iffparse.library/FindCollection
  384.  
  385.    NAME
  386.     FindCollection -- get a pointer to the current list of collection
  387.               items. (V36)
  388.  
  389.    SYNOPSIS
  390.     ci = FindCollection(iff, type, id);
  391.     D0                  A0   D0    D1
  392.  
  393.     struct CollectionItem *FindCollection(struct IFFHandle *, LONG, LONG);
  394.  
  395.    FUNCTION
  396.     Returns a pointer to a list of CollectionItem structures for each of
  397.     the collection chunks of the given type encountered so far in the
  398.     course of parsing this IFF file. The items appearing first in the
  399.     list will be the ones encountered most recently.
  400.  
  401.    INPUTS
  402.     iff - pointer to IFFHandle structure.
  403.     type - type code to search for.
  404.     id - identifier code to search for.
  405.  
  406.    RESULT
  407.     ci - pointer to last collection chunk encountered with
  408.          links to previous ones.
  409.  
  410.    SEE ALSO
  411.     CollectionChunk(), CollectionChunks(), <libraries/iffparse.h>
  412.  
  413. iffparse.library/FindLocalItem                 iffparse.library/FindLocalItem
  414.  
  415.    NAME
  416.     FindLocalItem -- return a local context item from the context stack.
  417.                      (V36)
  418.  
  419.    SYNOPSIS
  420.     lci = FindLocalItem(iff, type, id, ident);
  421.     D0                  A0   D0    D1  D2
  422.  
  423.     struct LocalContextItem    *FindLocalItem(struct IFFHandle    *,
  424.                                            LONG, LONG, LONG);
  425.  
  426.    FUNCTION
  427.     Searches the context stack of the given IFFHandle structure for a
  428.     local context item which matches the given ident, type and id. This
  429.     function searches the context stack from the most current context
  430.     backwards, so that the item found (if any) will be the one with
  431.     greatest precedence in the context stack.
  432.  
  433.    INPUTS
  434.     iff - pointer to IFFHandle structure.
  435.     type - type code to search for.
  436.     id - ID code to search for.
  437.     ident - ident code for the class of context item to search for
  438.         (ex. "exhd" -- exit handler).
  439.  
  440.    RESULT
  441.     lci - pointer to local context item, or NULL if nothing matched.
  442.  
  443.    SEE ALSO
  444.     StoreLocalItem(), <libraries/iffparse.h>
  445.  
  446. iffparse.library/FindProp                           iffparse.library/FindProp
  447.  
  448.    NAME
  449.     FindProp -- search for a stored property chunk. (V36)
  450.  
  451.    SYNOPSIS
  452.     sp = FindProp(iff, type, id);
  453.     D0            A0   D0    D1
  454.  
  455.     struct StoredProperty *FindProp(struct IFFHandle *, LONG, LONG);
  456.  
  457.    FUNCTION
  458.     Searches for the stored property which is valid in the given context.
  459.     Property chunks are automatically stored by ParseIFF() when
  460.     pre-declared by PropChunk() or PropChunks(). The StoredProperty
  461.     struct, if found, contains a pointer to a data buffer containing the
  462.     contents of the stored property.
  463.  
  464.    INPUTS
  465.     iff - pointer to IFFHandle structure.
  466.     type - type code for chunk to search for (ex. "ILBM").
  467.     id - identifier code for chunk to search for (ex. "CMAP").
  468.  
  469.    RESULT
  470.     sp - pointer to stored property, or NULL if none found.
  471.  
  472.    SEE ALSO
  473.     PropChunk(), PropChunks(), <libraries/iffparse.h>
  474.  
  475. iffparse.library/FindPropContext             iffparse.library/FindPropContext
  476.  
  477.    NAME
  478.     FindPropContext -- get the property context for the current state.
  479.                        (V36)
  480.  
  481.    SYNOPSIS
  482.     cn = FindPropContext(iff);
  483.     D0                   A0
  484.  
  485.     struct ContextNode *FindPropContext(struct IFFHandle *);
  486.  
  487.    FUNCTION
  488.     Locates the context node which would be the scoping chunk for
  489.     properties in the current parsing state. (Huh?)  This is used for
  490.     locating the proper scoping context for property chunks i.e. the
  491.     scope from which a property would apply. This is usually the FORM
  492.     or LIST with the highest precedence in the context stack.
  493.  
  494.     If you don't understand this, read the IFF spec a couple more times.
  495.  
  496.    INPUTS
  497.     iff - pointer to IFFHandle structure.
  498.  
  499.    RESULT
  500.     cn - ContextNode of property scoping chunk.
  501.  
  502.    SEE ALSO
  503.     CurrentChunk(), ParentChunk(), StoreItemInContext(),
  504.     <libraries/iffparse.h>
  505.  
  506. iffparse.library/FreeIFF                             iffparse.library/FreeIFF
  507.  
  508.    NAME
  509.     FreeIFF -- deallocate an IFFHandle structure. (V36)
  510.  
  511.    SYNOPSIS
  512.     FreeIFF(iff);
  513.             A0
  514.  
  515.     VOID FreeIFF(struct IFFHandle *);
  516.  
  517.    FUNCTION
  518.     Deallocates all resources associated with this IFFHandle structure.
  519.     The structure MUST have already been closed with CloseIFF().
  520.  
  521.    INPUTS
  522.     iff - pointer to IFFHandle structure to free. Starting with V39,
  523.           this may be NULL.
  524.  
  525.    SEE ALSO
  526.     AllocIFF(), CloseIFF(), <libraries/iffparse.h>
  527.  
  528. iffparse.library/FreeLocalItem                 iffparse.library/FreeLocalItem
  529.  
  530.    NAME
  531.     FreeLocalItem -- deallocate a local context item structure. (V36)
  532.  
  533.    SYNOPSIS
  534.     FreeLocalItem(localItem);
  535.                   A0
  536.  
  537.     VOID FreeLocalItem(struct LocalContextItem *);
  538.  
  539.    FUNCTION
  540.     Frees the memory for the local context item and any associated user
  541.     memory as allocated with AllocLocalItem(). User purge vectors should
  542.     call this function after they have freed any other resources
  543.     associated with this item.
  544.  
  545.     Note that FreeLocalItem() does NOT call the custom purge vector set
  546.     up through SetLocalItemPurge(); all it does is free the local context
  547.     item. (This implies that your custom purge vector would want to call
  548.     this to ultimately free the LocalContextItem.)
  549.  
  550.    INPUTS
  551.     localItem - pointer to LocalContextItem created with AllocLocalItem.
  552.                 Starting with V39, this may be NULL.
  553.  
  554.    SEE ALSO
  555.     AllocLocalItem(), <libraries/iffparse.h>
  556.  
  557. iffparse.library/GoodID                               iffparse.library/GoodID
  558.  
  559.    NAME
  560.     GoodID -- test if an identifier follows the IFF 85 specification. (V36)
  561.  
  562.    SYNOPSIS
  563.     isok = GoodID(id);
  564.     D0            D0
  565.  
  566.     LONG GoodID(LONG);
  567.  
  568.    FUNCTION
  569.     Tests the given longword identifier to see if it meets all the EA IFF
  570.     85 specifications for a chunk ID. If so, it returns non-zero,
  571.     otherwise 0.
  572.  
  573.    INPUTS
  574.     id - potential 32 bit identifier.
  575.  
  576.    RESULT
  577.     isok - non-zero if this is a valid ID, 0 otherwise.
  578.  
  579.    SEE ALSO
  580.     GoodType()
  581.  
  582. iffparse.library/GoodType                           iffparse.library/GoodType
  583.  
  584.    NAME
  585.     GoodType -- test if a type follows the IFF 85 specification. (V36)
  586.  
  587.    SYNOPSIS
  588.     isok = GoodType(type)
  589.     D0              D0
  590.  
  591.     LONG GoodType(LONG);
  592.  
  593.    FUNCTION
  594.     Tests the given longword type identifier to see if it meets all the
  595.     EA IFF 85 specifications for a FORM type (requirements for a FORM
  596.     type are more stringent than those for a simple chunk ID). If it
  597.     complies, GoodType() returns non-zero, otherwise 0.
  598.  
  599.    INPUTS
  600.     type - potential 32 bit format type identifier.
  601.  
  602.    RESULT
  603.     isok - non-zero if this is a valid type id, 0 otherwise.
  604.  
  605.    SEE ALSO
  606.     GoodID()
  607.  
  608. iffparse.library/IDtoStr                             iffparse.library/IDtoStr
  609.  
  610.    NAME
  611.     IDtoStr -- convert a longword identifier to a null-terminated string.
  612.                (V36)
  613.  
  614.    SYNOPSIS
  615.     str = IDtoStr(id, buf);
  616.     D0            D0  A0
  617.  
  618.     STRPTR IDtoStr(LONG, STRPTR);
  619.  
  620.    FUNCTION
  621.     Writes the ASCII equivalent of the given longword ID into buf as a
  622.     null-terminated string.
  623.  
  624.    INPUTS
  625.     id - longword ID.
  626.     buf - character buffer to accept string (at least 5 chars).
  627.  
  628.    RESULT
  629.     str - the value of 'buf'.
  630.  
  631. iffparse.library/InitIFF                             iffparse.library/InitIFF
  632.  
  633.    NAME
  634.     InitIFF -- initialize an IFFHandle structure as a user stream. (V36)
  635.  
  636.    SYNOPSIS
  637.     InitIFF(iff, flags, streamHook);
  638.             A0   D0     A1
  639.  
  640.     VOID InitIFF(struct IFFHandle *, LONG, struct Hook *);
  641.  
  642.    FUNCTION
  643.     Initializes an IFFHandle as a general user-defined stream by
  644.     allowing the user to declare a hook that the library will call to
  645.     accomplish the low-level reading, writing, and seeking of the stream.
  646.     Flags are the stream I/O flags for the specified stream; typically a
  647.     combination of the IFFF_?SEEK flags.
  648.  
  649.     The stream vector is called with the following arguments:
  650.  
  651.         A0:    pointer to streamhook.
  652.         A2:    pointer to IFFHandle structure.
  653.         A1:    pointer to IFFStreamCmd structure.
  654.  
  655.     The IFFStreamCmd packet appears as follows:
  656.  
  657.         sc_Command:    Contains an IFFCMD_#? value
  658.         sc_Buf:        Pointer to memory buffer
  659.         sc_NBytes:    Number of bytes involved in operation
  660.  
  661.     The values taken on by sc_Command, and their meaning, are as follows:
  662.  
  663.     IFFCMD_INIT:
  664.         Prepare your stream for reading. This is used for certain
  665.         streams that can't be read immediately upon opening, and need
  666.         further preparation. (The clipboard.device is an example of
  667.         such a stream.)  This operation is allowed to fail;  any
  668.         error code will be returned directly to the client. sc_Buf
  669.         and sc_NBytes have no meaning here.
  670.     IFFCMD_CLEANUP:
  671.         Terminate the transaction with the associated stream. This
  672.         is used with streams that can't simply be closed. (Again,
  673.         the clipboard is an example of such a stream.)  This
  674.         operation is not permitted to fail;  any error returned will
  675.         be ignored (best to return 0, though). sc_Buf and sc_NBytes
  676.         have no meaning here.
  677.     IFFCMD_READ:
  678.         Read from the stream. You are to read sc_NBytes from the
  679.         stream and place them in the buffer pointed to by sc_Buf.
  680.         Any (non-zero) error returned will be remapped by the parser
  681.         into IFFERR_READ.
  682.     IFFCMD_WRITE:
  683.         Write to the stream. You are to write sc_NBytes to the
  684.         stream from the buffer pointed to by sc_Buf. Any (non-zero)
  685.         error returned will be remapped by the parser into
  686.         IFFERR_WRITE.
  687.     IFFCMD_SEEK:
  688.         Seek on the stream. You are to perform a seek on the stream
  689.         relative to the current position. sc_NBytes is signed;
  690.         negative values mean seek backward, positive values mean seek
  691.         forward. sc_Buf has no meaning here. Any (non-zero) error
  692.         returned will be remapped by the parser into IFFERR_SEEK.
  693.  
  694.     All errors are returned in D0. A return of 0 indicates success.
  695.     UNDER NO CIRCUMSTANCES are you permitted to write to the IFFStreamCmd
  696.     structure.
  697.  
  698.    INPUTS
  699.     iff - pointer to IFFHandle structure to initialize.
  700.     flags - stream I/O flags for the IFFHandle.
  701.     streamHook - pointer to Hook structure.
  702.  
  703.    SEE ALSO
  704.     <utility/hooks.h>, <libraries/iffparse.h>
  705.  
  706. iffparse.library/InitIFFasClip                 iffparse.library/InitIFFasClip
  707.  
  708.    NAME
  709.     InitIFFasClip -- initialize an IFFHandle as a clipboard stream. (V36)
  710.  
  711.    SYNOPSIS
  712.     InitIFFasClip(iff);
  713.                   A0
  714.  
  715.     VOID InitIFFasClip(struct IFFHandle *);
  716.  
  717.    FUNCTION
  718.     Initializes the given IFFHandle to be a clipboard stream. The
  719.     function initializes the stream processing vectors to operate on
  720.     streams of the ClipboardHandle type. The iff_Stream field will still
  721.     need to be initialized to point to a ClipboardHandle as returned from
  722.     OpenClipboard().
  723.  
  724.    INPUTS
  725.     iff - pointer to IFFHandle structure.
  726.  
  727.    SEE ALSO
  728.     InitIFF(), OpenClipboard(), <libraries/iffparse.h>
  729.  
  730. iffparse.library/InitIFFasDOS                   iffparse.library/InitIFFasDOS
  731.  
  732.    NAME
  733.     InitIFFasDOS -- initialize an IFFHandle as a DOS stream. (V36)
  734.  
  735.    SYNOPSIS
  736.     InitIFFasDOS(iff)
  737.                  A0
  738.  
  739.     InitIFFasDOS(struct IFFHandle *);
  740.  
  741.    FUNCTION
  742.     The function initializes the given IFFHandle to operate on DOS
  743.     streams. The iff_Stream field will need to be initialized as a BPTR
  744.     returned from the DOS function Open().
  745.  
  746.    INPUTS
  747.     iff - pointer to IFFHandle structure.
  748.  
  749.    SEE ALSO
  750.     InitIFF()
  751.  
  752. iffparse.library/LocalItemData                 iffparse.library/LocalItemData
  753.  
  754.    NAME
  755.     LocalItemData -- get pointer to user data for local context item. (V36)
  756.  
  757.    SYNOPSIS
  758.     data = LocalItemData(localItem);
  759.     D0                   A0
  760.  
  761.     APTR LocalItemData(struct LocalContextItem *);
  762.  
  763.    FUNCTION
  764.     Returns pointer to the user data associated with the given local
  765.     context item. The size of the data area depends on the "dataSize"
  766.     argument used when allocating this item. If the pointer to the item
  767.     given (localItem) is NULL, this function returns NULL.
  768.  
  769.    INPUTS
  770.     localItem - pointer to local context item or NULL.
  771.  
  772.    RESULT
  773.     data - pointer to user data area or NULL if localItem is NULL.
  774.  
  775.    BUGS
  776.     Currently, there is no way to determine the size of the user data
  777.     area; you have to 'know'.
  778.  
  779.    SEE ALSO
  780.     AllocLocalItem(), FreeLocalItem(), <libraries/iffparse.h>
  781.  
  782. iffparse.library/OpenClipboard                 iffparse.library/OpenClipboard
  783.  
  784.    NAME
  785.     OpenClipboard -- create a handle on a clipboard unit. (V36)
  786.  
  787.    SYNOPSIS
  788.     ch = OpenClipboard(unitNumber)
  789.     D0                 D0
  790.  
  791.     struct ClipboardHandle *OpenClipboard(LONG);
  792.  
  793.    FUNCTION
  794.     Opens the clipboard.device and opens a stream for the specified unit
  795.     (usually PRIMARY_CLIP). This handle structure will be used as the
  796.     clipboard stream for IFFHandles initialized as clipboard streams by
  797.     InitIFFasClip().
  798.  
  799.    INPUTS
  800.     unitNumber - clipboard unit number (usually PRIMARY_CLIP).
  801.  
  802.    RESULT
  803.     ch - pointer to ClipboardHandle structure or NULL if unsuccessful.
  804.  
  805.    BUGS
  806.     This function had several bugs prior to V39.
  807.  
  808.        First bug was that if the clipboard.device couldn't open, two calls
  809.     to FreeSignal() were made with uninitialized values as parameters.
  810.     The result of this was a corrupt signal mask in the Task field.
  811.  
  812.     Second bug was that OpenDevice() was called with an IO request that
  813.     didn't have a valid MsgPort pointer in it.
  814.  
  815.     Third bug was that the two message ports allocated by the function
  816.     (ClipboardHandle->cbh_CBport and ClipboardHandle->cbh_SatisfyPort)
  817.     were not being initialized correctly and would cause a system crash
  818.     if a message ever got to either of them.
  819.  
  820.    SEE ALSO
  821.     InitIFFasClip(), CloseClipboard(), <libraries/iffparse.h>
  822.  
  823. iffparse.library/OpenIFF                             iffparse.library/OpenIFF
  824.  
  825.    NAME
  826.     OpenIFF -- prepare an IFFHandle to read or write a new IFF stream.
  827.                (V36)
  828.  
  829.    SYNOPSIS
  830.     error = OpenIFF(iff, rwMode);
  831.     D0              A0   D0
  832.  
  833.     LONG OpenIFF(struct IFFHandle *, LONG);
  834.  
  835.    FUNCTION
  836.     Initializes an IFFHandle structure for a new read or write. The
  837.     direction of the I/O is given by the value of rwMode, which can be
  838.     either IFFF_READ or IFFF_WRITE.
  839.  
  840.     As part of its initialization procedure, OpenIFF() calls the client-
  841.     supplied stream hook vector. The IFFStreamCmd packet will contain
  842.     the following:
  843.  
  844.         sc_Command:    IFFCMD_INIT
  845.         sc_Buf:        (Not applicable)
  846.         sc_NBytes:    (Not applicable)
  847.  
  848.     This operation is permitted to fail. DO NOT write to this structure.
  849.  
  850.    INPUTS
  851.     iff - pointer to IFFHandle structure. Starting with V39, this may be
  852.           NULL, in which case IFFERR_NOMEM is returned.
  853.     rwMode - IFFF_READ or IFFF_WRITE
  854.  
  855.    RESULT
  856.     error - contains an error code or 0 if successful
  857.  
  858.    SEE ALSO
  859.     CloseIFF(), InitIFF(), <libraries/iffparse.h>
  860.  
  861. iffparse.library/ParentChunk                     iffparse.library/ParentChunk
  862.  
  863.    NAME
  864.     ParentChunk -- get the nesting context node for the given chunk. (V36)
  865.  
  866.    SYNOPSIS
  867.     parent = ParentChunk(contextNode);
  868.     D0                   A0
  869.  
  870.     struct ContextNode *ParentChunk(struct ContextNode *);
  871.  
  872.    FUNCTION
  873.     Returns a context node for the chunk containing the chunk for the
  874.     given context node. This function effectively moves down the context
  875.     stack into previously pushed contexts. For example, to get a
  876.     ContextNode pointer for the enclosing FORM chunk while reading a data
  877.     chunk, use: ParentChunk(CurrentChunk(iff)) to find this pointer.
  878.     The ContextNode structure contains information on the type of chunk
  879.     and its size.
  880.  
  881.    INPUTS
  882.     contextNode - pointer to a context node.
  883.  
  884.    RESULT
  885.     parent - pointer to the enclosing context node or NULL if none.
  886.  
  887.    SEE ALSO
  888.     CurrentChunk(), <libraries/iffparse.h>
  889.  
  890. iffparse.library/ParseIFF                           iffparse.library/ParseIFF
  891.  
  892.    NAME
  893.     ParseIFF -- parse an IFF file from an IFFHandle structure stream. (V36)
  894.  
  895.    SYNOPSIS
  896.     error = ParseIFF(iff, control);
  897.     D0               A0   D0
  898.  
  899.     LONG ParseIFF(struct IFFHandle *, LONG);
  900.  
  901.    FUNCTION
  902.     This is the biggie.
  903.  
  904.     Traverses a file opened for read by pushing chunks onto the context
  905.     stack and popping them off directed by the generic syntax of IFF
  906.     files. As it pushes each new chunk, it searches the context stack
  907.     for handlers to apply to chunks of that type. If it finds an entry
  908.     handler it will invoke it just after entering the chunk. If it finds
  909.     an exit handler it will invoke it just before leaving the chunk.
  910.     Standard handlers include entry handlers for pre-declared
  911.     property chunks and collection chunks and entry and exit handlers for
  912.     for stop chunks - that is, chunks which will cause the ParseIFF()
  913.     function to return control to the client. Client programs can also
  914.     provide their own custom handlers.
  915.  
  916.     The control flag can have three values:
  917.  
  918.     IFFPARSE_SCAN:
  919.         In this normal mode, ParseIFF() will only return control to
  920.         the caller when either:
  921.             1) an error is encountered,
  922.             2) a stop chunk is encountered, or a user handler
  923.                returns the special IFF_RETURN2CLIENT code, or
  924.             3) the end of the logical file is reached, in which
  925.                case IFFERR_EOF is returned.
  926.  
  927.         ParseIFF() will continue pushing and popping chunks until one
  928.         of these conditions occurs. If ParseIFF() is called again
  929.         after returning, it will continue to parse the file where it
  930.         left off.
  931.  
  932.     IFFPARSE_STEP and _RAWSTEP:
  933.         In these two modes, ParseIFF() will return control to the
  934.         caller after every step in the parse, specifically, after
  935.         each push of a context node and just before each pop. If
  936.         returning just before a pop, ParseIFF() will return
  937.         IFFERR_EOC, which is not an error, per se, but is just an
  938.         indication that the most recent context is ending. In STEP
  939.         mode, ParseIFF() will invoke the handlers for chunks, if
  940.         any, before returning. In RAWSTEP mode, ParseIFF() will not
  941.         invoke any handlers and will return right away. In both
  942.         cases the function can be called multiple times to step
  943.         through the parsing of the IFF file.
  944.  
  945.    INPUTS
  946.     iff - pointer to IFFHandle structure.
  947.     control    - control code (IFFPARSE_SCAN, _STEP or _RAWSTEP).
  948.  
  949.    RESULT
  950.     error - 0 or IFFERR_#? value or return value from user handler.
  951.  
  952.    SEE ALSO
  953.     PushChunk(), PopChunk(), EntryHandler(), ExitHandler(),
  954.     PropChunk(), CollectionChunk(), StopChunk(), StopOnExit(),
  955.     <libraries/iffparse.h>
  956.  
  957. iffparse.library/PopChunk                           iffparse.library/PopChunk
  958.  
  959.    NAME
  960.     PopChunk -- pop top context node off context stack. (V36)
  961.  
  962.    SYNOPSIS
  963.     error = PopChunk(iff);
  964.     D0               A0
  965.  
  966.     LONG PopChunk(struct IFFHandle *);
  967.  
  968.    FUNCTION
  969.     Pops top context chunk and frees all associated local context items.
  970.     The function is normally called only for writing files and signals
  971.     the end of a chunk.
  972.  
  973.    INPUTS
  974.     iff - pointer to IFFHandle structure.
  975.  
  976.    RESULT
  977.     error - 0 if successful or an IFFERR_#? error code if unsuccessful.
  978.  
  979.    SEE ALSO
  980.     PushChunk(), <libraries/iffparse.h>
  981.  
  982. iffparse.library/PropChunk                         iffparse.library/PropChunk
  983.  
  984.    NAME
  985.     PropChunk -- specify a property chunk to store. (V36)
  986.  
  987.    SYNOPSIS
  988.     error = PropChunk(iff, type, id);
  989.     D0                A0   D0    D1
  990.  
  991.     LONG PropChunk(struct IFFHandle *, LONG, LONG);
  992.  
  993.    FUNCTION
  994.     Installs an entry handler for chunks with the given type and ID so
  995.     that the contents of those chunks will be stored as they are
  996.     encountered. The storage of these chunks follows the property chunk
  997.     scoping rules for IFF files so that at any given point, a stored
  998.     property chunk returned by FindProp() will be the valid property for
  999.     the current context.
  1000.  
  1001.    INPUTS
  1002.     iff - pointer to IFFHandle structure (does not need to be open).
  1003.     type - type code for the chunk to declare (ex. "ILBM").
  1004.     id - identifier for the chunk to declare (ex. "CMAP").
  1005.  
  1006.    RESULT
  1007.     error - 0 if successful or an IFFERR_#? error code if unsuccessful.
  1008.  
  1009.    SEE ALSO
  1010.     PropChunks(), FindProp(), CollectionChunk(), <libraries/iffparse.h>
  1011.  
  1012. iffparse.library/PropChunks                       iffparse.library/PropChunks
  1013.  
  1014.    NAME
  1015.     PropChunks -- declare many property chunks at once. (V36)
  1016.  
  1017.    SYNOPSIS
  1018.     error = PropChunks(iff, propArray, numPairs);
  1019.     D0                 A0   A1         D0
  1020.  
  1021.     LONG PropChunks(struct IFFHandle *, LONG *, LONG);
  1022.  
  1023.    FUNCTION
  1024.     Declares multiple property chunks from a list. The propArray argument
  1025.     if a pointer to an array of longwords arranged in pairs, and has the
  1026.     following format:
  1027.  
  1028.         TYPE1, ID1, TYPE2, ID2, ..., TYPEn, IDn
  1029.  
  1030.     The argument numPairs is the number of pairs. PropChunks() just calls
  1031.     PropChunk() numPairs times.
  1032.  
  1033.    INPUTS
  1034.     iff - pointer to IFFHandle structure.
  1035.     propArray - pointer to array of longword chunk types and identifiers.
  1036.     numPairs - number of pairs in the array.
  1037.  
  1038.    RESULT
  1039.     error - 0 if successful or an IFFERR_#? error code if unsuccessful.
  1040.  
  1041.    SEE ALSO
  1042.     PropChunk(), <libraries/iffparse.h>
  1043.  
  1044. iffparse.library/PushChunk                         iffparse.library/PushChunk
  1045.  
  1046.    NAME
  1047.     PushChunk -- push a new context node on the context stack. (V36)
  1048.  
  1049.    SYNOPSIS
  1050.     error = PushChunk(iff, type, id, size);
  1051.     D0                A0   D0    D1  D2
  1052.  
  1053.     LONG PushChunk(struct IFFHandle *, LONG, LONG, LONG);
  1054.  
  1055.    FUNCTION
  1056.     Pushes a new context node on the context stack by reading it from the
  1057.     stream if this is a read file, or by creating it from the passed
  1058.     parameters if this is a write file. Normally this function is only
  1059.     called in write mode, where the type and id codes specify the new
  1060.     chunk to create. If this is a leaf chunk, i.e. a local chunk inside
  1061.     a FORM or PROP chunk, then the type argument is ignored. If the size
  1062.     is specified then the chunk writing functions will enforce this size.
  1063.     If the size is given as IFFSIZE_UNKNOWN, the chunk will expand to
  1064.     accommodate whatever is written into it.
  1065.  
  1066.    INPUTS
  1067.     iff - pointer to IFFHandle structure.
  1068.     type - chunk type specifier (ex. ILBM) (ignored for read mode or
  1069.            leaf chunks).
  1070.     id - chunk id specifier (ex. CMAP) (ignored for read mode).
  1071.     size - size of the chunk to create or IFFSIZE_UNKNOWN (ignored for
  1072.            read mode).
  1073.  
  1074.    RESULT
  1075.     error - 0 if successful or an IFFERR_#? error code if not unsuccessful.
  1076.  
  1077.    SEE ALSO
  1078.     PopChunk(), WriteChunkRecords(), WriteChunkBytes(),
  1079.     <libraries/iffparse.h>
  1080.  
  1081. iffparse.library/ReadChunkBytes               iffparse.library/ReadChunkBytes
  1082.  
  1083.    NAME
  1084.     ReadChunkBytes -- read bytes from the current chunk into a buffer.
  1085.                       (V36)
  1086.  
  1087.    SYNOPSIS
  1088.     actual = ReadChunkBytes(iff, buf, numBytes);
  1089.     D0                      A0   A1   D0
  1090.  
  1091.     LONG ReadChunkBytes(struct IFFHandle *, APTR buf, LONG);
  1092.  
  1093.    FUNCTION
  1094.     Reads the IFFHandle stream into the buffer for the specified number
  1095.     of bytes. Reads are limited to the size of the current chunk and
  1096.     attempts to read past the end of the chunk will truncate. This
  1097.     function returns positive number of bytes read or a negative error
  1098.     code.
  1099.  
  1100.    INPUTS
  1101.     iff - pointer to IFFHandle structure.
  1102.     buf - pointer to buffer area to receive data.
  1103.     numBytes - number of bytes to read.
  1104.  
  1105.    RESULT
  1106.     actual - (positive) number of bytes read if successful or a
  1107.          (negative) IFFERR_#? error code if unsuccessful.
  1108.  
  1109.    SEE ALSO
  1110.     ReadChunkRecords(), ParseIFF(), WriteChunkBytes(),
  1111.     <libraries/iffparse.h>
  1112.  
  1113. iffparse.library/ReadChunkRecords           iffparse.library/ReadChunkRecords
  1114.  
  1115.    NAME
  1116.     ReadChunkRecords -- read record elements from the current chunk into
  1117.                 a buffer. (V36)
  1118.  
  1119.    SYNOPSIS
  1120.     actual = ReadChunkRecords(iff, buf, bytesPerRecord, numRecords);
  1121.     D0                        A0   A1   D0              D1
  1122.  
  1123.     LONG ReadChunkRecords(struct IFFHandle *, APTR, LONG, LONG);
  1124.  
  1125.    FUNCTION
  1126.     Reads records from the current chunk into buffer. Truncates attempts
  1127.     to read past end of chunk (only whole records are read; remaining
  1128.     bytes that are not of a whole record size are left unread and
  1129.     available for ReadChunkBytes()).
  1130.  
  1131.    INPUTS
  1132.     iff - pointer to IFFHandle structure.
  1133.     buf - pointer to buffer area to receive data.
  1134.     bytesPerRecord    - size of data records to read.
  1135.     numRecords - number of data records to read.
  1136.  
  1137.    RESULT
  1138.     actual - (positive) number of whole records read if successful or a
  1139.          (negative) IFFERR_#? error code if unsuccessful.
  1140.  
  1141.    SEE ALSO
  1142.     ReadChunkBytes(), ParseIFF(), WriteChunkRecords(),
  1143.     <libraries/iffparse.h>
  1144.  
  1145. iffparse.library/SetLocalItemPurge         iffparse.library/SetLocalItemPurge
  1146.  
  1147.    NAME
  1148.     SetLocalItemPurge -- set purge vector for a local context item. (V36)
  1149.  
  1150.    SYNOPSIS
  1151.     SetLocalItemPurge(localItem, purgeHook);
  1152.                       A0         A1
  1153.  
  1154.     VOID SetLocalItemPurge(struct LocalContextItem *, struct Hook *);
  1155.  
  1156.    FUNCTION
  1157.     Sets a local context item to use a client-supplied cleanup (purge)
  1158.     vector for disposal when its context is popped. The purge vector
  1159.     will be called when the ContextNode containing this local item is
  1160.     popped off the context stack and is about to be deleted itself. If
  1161.     the purge vector has not been set, the parser will use FreeLocalItem()
  1162.     to delete the item, but if this function is used to set the purge
  1163.     vector, the supplied vector will be called with the following
  1164.     arguments:
  1165.  
  1166.         A0:    pointer to purgeHook.
  1167.         A2:    pointer to LocalContextItem to be freed.
  1168.         A1:    pointer to a LONG containing the value
  1169.             IFFCMD_PURGELCI.
  1170.  
  1171.     The user purge vector is then responsible for calling FreeLocalItem()
  1172.     as part of its own cleanup. Although the purge vector can return a
  1173.     value, it will be ignored -- purge vectors must always work (best to
  1174.     return 0, though).
  1175.  
  1176.    INPUTS
  1177.     localItem - pointer to a local context item.
  1178.     purgeHook - pointer to a Hook structure.
  1179.  
  1180.    SEE ALSO
  1181.     AllocLocalItem(), FreeLocalItem(), <utility/hooks.h>
  1182.     <libraries/iffparse.h>
  1183.  
  1184. iffparse.library/StopChunk                         iffparse.library/StopChunk
  1185.  
  1186.    NAME
  1187.     StopChunk -- declare a chunk which should cause ParseIFF to return.
  1188.                  (V36)
  1189.  
  1190.    SYNOPSIS
  1191.     error = StopChunk(iff, type, id);
  1192.     D0                A0   D0    D1
  1193.  
  1194.     LONG StopChunk(struct IFFHandle *, LONG, LONG);         type;
  1195.  
  1196.    FUNCTION
  1197.     Installs an entry handler for the specified chunk which will cause
  1198.     the ParseIFF() function to return control to the caller when this
  1199.     chunk is encountered. This is only of value when ParseIFF() is
  1200.     called with the IFFPARSE_SCAN control code.
  1201.  
  1202.    INPUTS
  1203.     iff - pointer to IFFHandle structure (need not be open).
  1204.     type - type code for chunk to declare (ex. "ILBM").
  1205.     id - identifier for chunk to declare (ex. "BODY").
  1206.  
  1207.    RESULT
  1208.     error - 0 if successful or an IFFERR_#? error code if unsuccessful.
  1209.  
  1210.    SEE ALSO
  1211.     StopChunks(), ParseIFF(), <libraries/iffparse.h>
  1212.  
  1213. iffparse.library/StopChunks                       iffparse.library/StopChunks
  1214.  
  1215.    NAME
  1216.     StopChunks -- declare many stop chunks at once. (V36)
  1217.  
  1218.    SYNOPSIS
  1219.     error = StopChunks(iff, propArray, numPairs);
  1220.     D0                 A0   A1         D0
  1221.  
  1222.     LONG StopChunks(struct IFFHandle *, LONG *, LONG);
  1223.  
  1224.    FUNCTION
  1225.     (is to StopChunk() as PropChunks() is to PropChunk().)
  1226.  
  1227.    INPUTS
  1228.     iff - pointer to IFFHandle structure.
  1229.     propArray - pointer to array of longword chunk types and identifiers.
  1230.     numPairs - number of pairs in the array.
  1231.  
  1232.    RESULT
  1233.     error - 0 if successful or an IFFERR_#? error code if unsuccessful.
  1234.  
  1235.    SEE ALSO
  1236.     StopChunk(), <libraries/iffparse.h>
  1237.  
  1238. iffparse.library/StopOnExit                       iffparse.library/StopOnExit
  1239.  
  1240.    NAME
  1241.     StopOnExit -- declare a stop condition for exiting a chunk. (V36)
  1242.  
  1243.    SYNOPSIS
  1244.     error = StopOnExit(iff, type, id);
  1245.     D0                 A0   D0    D1
  1246.  
  1247.     LONG StopOnExit(struct IFFHandle *, LONG, LONG);
  1248.  
  1249.    FUNCTION
  1250.     Installs an exit handler for the specified chunk which will cause the
  1251.     ParseIFF() function to return control to the caller when this chunk
  1252.     is exhausted. ParseIFF() will return IFFERR_EOC when the declared
  1253.     chunk is about to be popped. This is only of value when ParseIFF()
  1254.     is called with the IFFPARSE_SCAN control code.
  1255.  
  1256.    INPUTS
  1257.     iff - pointer to IFFHandle structure (need not be open).
  1258.     type - type code for chunk to declare (ex. "ILBM").
  1259.     id - identifier for chunk to declare (ex. "BODY").
  1260.  
  1261.    RESULT
  1262.     error - 0 if successful or an IFFERR_#? error code if unsuccessful.
  1263.  
  1264.    SEE ALSO
  1265.     ParseIFF(), <libraries/iffparse.h>
  1266.  
  1267. iffparse.library/StoreItemInContext       iffparse.library/StoreItemInContext
  1268.  
  1269.    NAME
  1270.     StoreItemInContext -- store local context item in given context node.
  1271.                           (V36)
  1272.  
  1273.    SYNOPSIS
  1274.     StoreItemInContext(iff, localItem, contextNode);
  1275.                        A0   A1         A2
  1276.  
  1277.     VOID StoreItemInContext(struct IFFHandle *, struct LocalContextItem *,
  1278.                                struct ContextNode *);
  1279.  
  1280.    FUNCTION
  1281.     Adds the LocalContextItem to the list of items for the given context
  1282.     node. If an LCI with the same Type, ID, and Ident is already
  1283.     present in the ContextNode, it will be purged and replaced with the
  1284.     new one. This is a raw form of StoreLocalItem().
  1285.  
  1286.    INPUTS
  1287.     iff - pointer to IFFHandle structure for this context.
  1288.     localItem - pointer to a LocalContextItem to be stored.
  1289.     contextNode - pointer to context node in which to store item.
  1290.  
  1291.    SEE ALSO
  1292.     StoreLocalItem(), <libraries/iffparse.h>
  1293.  
  1294. iffparse.library/StoreLocalItem               iffparse.library/StoreLocalItem
  1295.  
  1296.    NAME
  1297.     StoreLocalItem -- insert a local context item into the context stack.
  1298.                       (V36)
  1299.  
  1300.    SYNOPSIS
  1301.     error = StoreLocalItem(iff, localItem, position);
  1302.     D0                     A0   A1         D0
  1303.  
  1304.     LONG StoreLocalItem(struct IFFHandle *, struct LocalContextItem    *,
  1305.                         LONG);
  1306.  
  1307.    FUNCTION
  1308.     Adds the local context item to the list of items for one of the
  1309.     context nodes on the context stack and purges any other item in the
  1310.     same context with the same ident, type and id. The position argument
  1311.     determines where in the stack to add the item:
  1312.  
  1313.     IFFSLI_ROOT:
  1314.         Add item to list at root (default) stack position.
  1315.     IFFSLI_TOP:
  1316.         Add item to the top (current) context node.
  1317.     IFFSLI_PROP:
  1318.         Add element in top property context. Top property context is
  1319.         either the top FORM chunk, or the top LIST chunk, whichever
  1320.         is closer to the top of the stack.
  1321.  
  1322.     Items added to the root context, or added to the top context before
  1323.     the IFFHandle has been opened or after it has been closed, are put in
  1324.     the default context. That is, they will be the local items found
  1325.     only after all other context nodes have been searched. Items in the
  1326.     default context are also immune to being purged until the IFFHandle
  1327.     structure itself is deleted with FreeIFF(). This means that handlers
  1328.     installed in the root context will still be there after an IFFHandle
  1329.     structure has been opened and closed. (Note that this implies that
  1330.     items stored in a higher context will be deleted when that context
  1331.     ends.)
  1332.  
  1333.    INPUTS
  1334.     iff - pointer to IFFHandle structure.
  1335.     localItem - pointer to LocalContextItem struct to insert.
  1336.     position - where to store the item (IFFSLI_ROOT, _TOP or _PROP).
  1337.  
  1338.    RESULT
  1339.     error - 0 if successful or an IFFERR_#? error code if unsuccessful.
  1340.  
  1341.    SEE ALSO
  1342.     FindLocalItem(), StoreItemInContext(), EntryHandler(), ExitHandler(),
  1343.     <libraries/iffparse.h>
  1344.  
  1345. iffparse.library/WriteChunkBytes             iffparse.library/WriteChunkBytes
  1346.  
  1347.    NAME
  1348.     WriteChunkBytes -- write data from a buffer into the current chunk.
  1349.                        (V36)
  1350.  
  1351.    SYNOPSIS
  1352.     error = WriteChunkBytes(iff, buf, numBytes);
  1353.     D0                      A0   A1   D0
  1354.  
  1355.     LONG WriteChunkBytes(struct IFFHandle *, APTR, LONG);
  1356.  
  1357.    FUNCTION
  1358.     Writes "numBytes" bytes from the specified buffer into the current
  1359.     chunk. If the current chunk was pushed with IFFSIZE_UNKNOWN, the size
  1360.     of the chunk gets increased by the size of the buffer written. If
  1361.     the size was specified for this chunk, attempts to write past the end
  1362.     of the chunk will be truncated.
  1363.  
  1364.    INPUTS
  1365.     iff - pointer to IFFHandle structure.
  1366.     buf - pointer to buffer area with bytes to be written.
  1367.     numBytes - number of bytes to write.
  1368.  
  1369.    RESULT
  1370.     error - (positive) number of bytes written if successful or a
  1371.         (negative) IFFERR_#? error code if unsuccessful.
  1372.  
  1373.    SEE ALSO
  1374.     PushChunk(), PopChunk(), WriteChunkRecords(), <libraries/iffparse.h>
  1375.  
  1376. iffparse.library/WriteChunkRecords         iffparse.library/WriteChunkRecords
  1377.  
  1378.    NAME
  1379.     WriteChunkRecords -- write records from a buffer to the current
  1380.                  chunk. (V36)
  1381.  
  1382.    SYNOPSIS
  1383.     error = WriteChunkRecords(iff, buf, recsize, numrec);
  1384.     D0                        A0   A1   D0       D1
  1385.  
  1386.     LONG WriteChunkRecords(struct IFFHandle *, APTR, LONG, LONG);
  1387.  
  1388.    FUNCTION
  1389.     Writes record elements from the buffer into the top chunk. This
  1390.     function operates much like ReadChunkBytes().
  1391.  
  1392.    INPUTS
  1393.     iff - pointer to IFFHandle structure.
  1394.     buf - pointer to buffer area containing data.
  1395.     recsize    - size of data records to write.
  1396.     numrec - number of data records to write.
  1397.  
  1398.    RESULT
  1399.     error - (positive) number of whole records written if successful
  1400.         or a (negative) IFFERR_#? error code if unsuccessful.
  1401.  
  1402.    SEE ALSO
  1403.     WriteChunkBytes(), <libraries/iffparse.h>
  1404.  
  1405.