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