home *** CD-ROM | disk | FTP | other *** search
/ DOpus Plus / DOpus Plus.iso / SDK / docs / iff.doc < prev    next >
Encoding:
Text File  |  1998-10-26  |  10.2 KB  |  377 lines
  1. dopus5.library/IFFChunkID                           dopus5.library/IFFChunkID
  2.  
  3.     NAME
  4.         IFFChunkID - get current chunk ID
  5.  
  6.     SYNOPSIS
  7.         IFFChunkID(handle)
  8.                      A0
  9.  
  10.         ULONG IFFChunkID(APTR);
  11.  
  12.     FUNCTION
  13.         Returns the four-byte ID of the current chunk.
  14.  
  15.     INPUTS
  16.         handle - IFF handle
  17.  
  18.     RESULT
  19.         Returns chunk ID.
  20.  
  21.     SEE ALSO
  22.         IFFOpen(), IFFGetFORM(), IFFNextChunk()
  23.  
  24. dopus5.library/IFFChunkRemain                   dopus5.library/IFFChunkRemain
  25.  
  26.     NAME
  27.         IFFChunkRemain - return size of remaining data
  28.  
  29.     SYNOPSIS
  30.         IFFChunkRemain(handle)
  31.                          A0
  32.  
  33.         long IFFChunkRemain(APTR);
  34.  
  35.     FUNCTION
  36.         Returns the amout of data left to be read in the current chunk.
  37.  
  38.     INPUTS
  39.         handle - IFF handle
  40.  
  41.     RESULT
  42.         Returns size of data or 0 if no data left.
  43.  
  44.     SEE ALSO
  45.         IFFOpen(), IFFNextChunk(), IFFChunkSize(), IFFReadChunkBytes()
  46.  
  47. dopus5.library/IFFChunkSize                       dopus5.library/IFFChunkSize
  48.  
  49.     NAME
  50.         IFFChunkSize - size of current chunk
  51.  
  52.     SYNOPSIS
  53.         IFFChunkSize(handle)
  54.                        A0
  55.  
  56.         long IFFChunkSize(APTR);
  57.  
  58.     FUNCTION
  59.         Obtain the amount of data in the current chunk.
  60.  
  61.     INPUTS
  62.         handle - IFF handle
  63.  
  64.     RESULT
  65.         Returns the total number of bytes of data in the current chunk
  66.         (excluding the chunk header). If there is no valid current chunk,
  67.         returns -1.
  68.  
  69.     SEE ALSO
  70.         IFFOpen(), IFFNextChunk(), IFFChunkRemain(), IFFReadChunkBytes()
  71.  
  72. dopus5.library/IFFClose                               dopus5.library/IFFClose
  73.  
  74.     NAME
  75.         IFFClose - close an IFF file
  76.  
  77.     SYNOPSIS
  78.         IFFClose(handle)
  79.                    A0
  80.  
  81.         void IFFClose(APTR);
  82.  
  83.     FUNCTION
  84.         Closes an IFF file.
  85.  
  86.     INPUTS
  87.         handle - file to close
  88.  
  89.     RESULT
  90.         The file is closed.
  91.  
  92.     SEE ALSO
  93.         IFFOpen()
  94.  
  95. dopus5.library/IFFFailure                           dopus5.library/IFFFailure
  96.  
  97.     NAME
  98.         IFFFailure - indicate failure to "safe" file routine
  99.  
  100.     SYNOPSIS
  101.         IFFFailure(handle)
  102.                      A0
  103.  
  104.         void IFFFailure(APTR)
  105.  
  106.     FUNCTION
  107.         The IFFOpen() routine has a "safe" mode, where an existing IFF file
  108.         is renamed rather than being over-written. If you create a file in
  109.         this safe mode, and then subsequent IFF operations fail (with the
  110.         result that the whole operation fails), you should call this routine.
  111.         Then, when you call IFFClose(), the pre-existing file will be
  112.         renamed back to what it was instead of being deleted.
  113.  
  114.     INPUTS
  115.         handle - IFF handle
  116.  
  117.     RESULT
  118.         The 'failure' flag is set, and the "safe" file will be restored.
  119.  
  120.     SEE ALSO
  121.         IFFOpen(), IFFClose()
  122.  
  123. dopus5.library/IFFGetForm                           dopus5.library/IFFGetForm
  124.  
  125.     NAME
  126.         IFFGetForm - get current FORM ID
  127.  
  128.     SYNOPSIS
  129.         IFFGetForm(handle)
  130.                      A0
  131.  
  132.         ULONG IFFGetForm(APTR);
  133.  
  134.     FUNCTION
  135.         This routine returns the four-byte FORM ID of the file.
  136.  
  137.     INPUTS
  138.         handle - IFF handle
  139.  
  140.     RESULT
  141.         Returns the FORM ID, or 0 if no valid FORM.
  142.  
  143.     SEE ALSO
  144.         IFFOpen(), IFFChunkID()
  145.  
  146. dopus5.library/IFFNextChunk                       dopus5.library/IFFNextChunk
  147.  
  148.     NAME
  149.         IFFNextChunk - skip to the next chunk
  150.  
  151.     SYNOPSIS
  152.         IFFNextChunk(handle, chunkid)
  153.                        A0       D0
  154.  
  155.         ULONG IFFNextChunk(APTR, ULONG);
  156.  
  157.     FUNCTION
  158.         This is the main work-horse of the IFF routines. This function will
  159.         scan through the IFF file from the current position looking for the
  160.         next chunk. You can optionally specify a chunk to look for.
  161.  
  162.     INPUTS
  163.         handle - IFF handle
  164.         chunkid - ID of chunk to look for, or 0 for next chunk
  165.  
  166.     RESULT
  167.         Returns ID of the new chunk, or 0 for error or end-of-file.
  168.  
  169.     NOTES
  170.         The IFF routines do not handle LISTs, CATs or other complicated IFF
  171.         structures. This routine will handle multiple FORMs within the one
  172.         file, which allows it to read ANIMs.
  173.  
  174.     SEE ALSO
  175.         IFFOpen(), IFFReadChunkBytes()
  176.  
  177. dopus5.library/IFFOpen                                 dopus5.library/IFFOpen
  178.  
  179.     NAME
  180.         IFFOpen - open an IFF file
  181.  
  182.     SYNOPSIS
  183.         IFFOpen(name, mode, form)
  184.                  A0    D0    D1
  185.  
  186.         APTR IFFOpen(char *, USHORT, ULONG);
  187.  
  188.     FUNCTION
  189.         This routine opens either a disk-based file or the clipboard for
  190.         IFF reading/writing. This and the other IFF routines in the
  191.         dopus5.library are far simpler (and seem to be less buggy) than the
  192.         iffparse.library functions. These routines were specifically designed
  193.         to make the reading and writing of "normal" IFF files as easy as
  194.         possible. They use the buffered IO routines for high performance.
  195.         They do not support LISTs, CATs or other complicated IFF structures.
  196.  
  197.     INPUTS
  198.         name - Filename or clipboard unit to open.
  199.         mode - Mode to open in :
  200.  
  201.                    IFF_READ       - open for reading
  202.                    IFF_WRITE      - open for writing
  203.                    IFF_CLIP_READ  - open clipboard for reading
  204.                    IFF_CLIP_WRITE - open clipboard for writing
  205.  
  206.                This flag can be set in conjunction with IFF_WRITE :
  207.  
  208.                    IFF_SAFE       - backup existing file
  209.  
  210.         form - If this is not 0, it specifies an IFF FORM. If you open
  211.                the file for reading, it will be tested against this FORM and
  212.                the open will fail if the FORM does not match. If you open
  213.                for writing, this specifies the FORM of the file to be
  214.                created.
  215.  
  216.     RESULT
  217.         If successful, returns an IFF handle which you use in all subsequent
  218.         calls to the IFF routines. Returns 0 on failure, and IoErr() is set
  219.         to the reason for the failure.
  220.  
  221.     NOTES
  222.         To use the clipboard, you must specify either IFF_CLIP_READ or
  223.         IFF_CLIP_WRITE. The clipboard unit you want is passed as the name
  224.         parameter. For example, to open clipboard unit 3 to write an ILBM,
  225.  
  226.             handle = IFFOpen( (char *)3, IFF_CLIP_WRITE, ID_ILBM );
  227.  
  228.         If you specify IFF_WRITE|IFF_SAFE, and the file you are creating
  229.         already exists, it will be renamed to a temporary filename. When
  230.         IFFClose() is called, the temporary file will be deleted. If you
  231.         call IFFFailure() because of a failure at some stage, it sets a flag
  232.         which causes the old file to be restored. If you specify IFF_SAFE
  233.         and the file already exists, and is read-only, this call will fail.
  234.  
  235.     SEE ALSO
  236.         IFFClose(), IFFFailure()
  237.  
  238. dopus5.library/IFFPopChunk                         dopus5.library/IFFPopChunk
  239.  
  240.     NAME
  241.         IFFPopChunk - flush the chunk cache
  242.  
  243.     SYNOPSIS
  244.         IFFPopChunk(handle)
  245.                       A0
  246.  
  247.         long IFFPopChunk(APTR);
  248.  
  249.     FUNCTION
  250.         This function flushes the current chunk write cache and writes the
  251.         chunk to disk.
  252.  
  253.     INPUTS
  254.         handle - IFF handle
  255.  
  256.     RESULT
  257.         The current chunk is written to disk. Returns TRUE if successful.
  258.  
  259.     SEE ALSO
  260.         IFFOpen(), IFFPushChunk(), IFFWriteChunkBytes()
  261.  
  262. dopus5.library/IFFPushChunk                       dopus5.library/IFFPushChunk
  263.  
  264.     NAME
  265.         IFFPushChunk - start writing a chunk
  266.  
  267.     SYNOPSIS
  268.         IFFPushChunk(handle, id)
  269.                        A0    D0
  270.  
  271.         long IFFPushChunk(APTR, ULONG);
  272.  
  273.     FUNCTION
  274.         This routine initialises a new chunk to be written to the file.
  275.         It is similar in concept to the PushChunk() routine in
  276.         iffparse.library, but does not support nesting of chunks. Therefore,
  277.         you should always call IFFPopChunk() before you call IFFPushChunk()
  278.         again.
  279.  
  280.     INPUTS
  281.         handle - IFF handle
  282.         id - ID of chunk to write
  283.  
  284.     RESULT
  285.         The chunk is initialised for writing. The usual procedure is :
  286.  
  287.             1. IFFPushChunk()
  288.             2. One or more calls to IFFWriteChunkBytes()
  289.             3. IFFPopChunk()
  290.  
  291.     SEE ALSO
  292.         IFFOpen(), IFFWriteChunkBytes(), IFFPopChunk()
  293.  
  294. dopus5.library/IFFReadChunkBytes             dopus5.library/IFFReadChunkBytes
  295.  
  296.     NAME
  297.         IFFReadChunkBytes - read data from a chunk
  298.  
  299.     SYNOPSIS
  300.         IFFReadChunkBytes(handle, buffer, size)
  301.                             A0      A1     D0
  302.  
  303.         long IFFReadChunkBytes(APTR, APTR, long);
  304.  
  305.     FUNCTION
  306.         This routine reads data from the current position in the current
  307.         chunk.
  308.  
  309.     INPUTS
  310.         handle - IFF handle
  311.         buffer - buffer to store data
  312.         size - amount of data to read
  313.  
  314.     RESULT
  315.         Returns the amount of data read or -1 for failure. Will not read
  316.         past the end of a chunk.
  317.  
  318.     SEE ALSO
  319.         IFFOpen(), IFFNextChunk(), IFFChunkSize()
  320.  
  321. dopus5.library/IFFWriteChunkBytes           dopus5.library/IFFWriteChunkBytes
  322.  
  323.     NAME
  324.         IFFWriteChunkBytes - write data in a chunk
  325.  
  326.     SYNOPSIS
  327.         IFFWriteChunkBytes(handle, data, size)
  328.                              A0     A1    D0
  329.  
  330.         long IFFWriteChunkBytes(APTR, APTR, long);
  331.  
  332.     FUNCTION
  333.         This routine writes data to a chunk that was initialised with
  334.         PushChunk(). The data is generally cached and not written to the disk
  335.         until PopChunk() is called, resulting in higher performance.
  336.  
  337.     INPUTS
  338.         handle - IFF handle
  339.         data - data to write
  340.         size - amount of data
  341.  
  342.     RESULT
  343.         Returns TRUE if successful.
  344.  
  345.     SEE ALSO
  346.         IFFOpen(), IFFPushChunk(), IFFPopChunk()
  347.  
  348. dopus5.library/IFFWriteChunk                     dopus5.library/IFFWriteChunk
  349.  
  350.     NAME
  351.         IFFWriteChunk - write a chunk straight out
  352.  
  353.     SYNOPSIS
  354.         IFFWriteChunk(handle, data, id, size)
  355.                         A0     A1   D0   D1
  356.  
  357.         long IFFWriteChunk(APTR, APTR, ULONG, ULONG);
  358.  
  359.     FUNCTION
  360.         If you have a single structure or piece of data you wish to write
  361.         as a chunk, this routine is simpler than the PushChunk()/PopChunk()
  362.         method.
  363.  
  364.     INPUTS
  365.         handle - IFF handle
  366.         data - data to write
  367.         id - ID of chunk
  368.         size - size of data
  369.  
  370.     RESULT
  371.         If successful, the chunk is written straight to the file. Returns
  372.         FALSE on failure.
  373.  
  374.     SEE ALSO
  375.         IFFOpen(), IFFPushChunk(), IFFPopChunk(), IFFWriteChunkBytes()
  376.  
  377.