
 NAME
 ====
 rfile - RIFFIOFile routines

 SYNOPSIS
 ======== 

 - RIFFIOFileNew()
 - RIFFIOFileInit()
 - RIFFIOFileDelete()

 - RIFFIOFileGetFormType()

 - RIFFIORead()
 - RIFFIOWrite()
 - RIFFIOSeek()
 - RIFFIOTell()



 RIFFIOFileNew
 =============
 Return a pointer to a new RIFFIOFile,
 or null on failure

| RIFFIOFile *
| RIFFIOFileNew(void)

 OBLIGATIONS
 -----------
 The file cannot be operated on until RIFFIOFileInit() is called.


 RIFFIOFileInit
 ==============
 Provide a NIFFIOFile with a user-defined I/O callbacks.

| RIFFIOSuccess
| RIFFIOFileInit(RIFFIOFile *prf,
|                void *pvUserFile,
|                RIFFIOReader reader,
|                RIFFIOWriter writer,
|                RIFFIOSeeker seeker,
|                RIFFIOTeller teller)

 RIFFFIOFileInit() should be called immediately after NIFFIOFileNew()

 ENTRY
 -----
 
 <prf> :
   is the RIFFIOFile that is being initialized.

 <pvUserFile> :
   points to a user representation of a file that will be passed to
   user-defined reader, writer, seeker, and teller functions.
 
 <reader>,<writer>,<seeker>,<teller> :
   are user-defined functions that perform operations on <*pvUserFile>.


 RIFFIOFileDelete
 ================
 Free the memory allocated to a RIFFIOFile.

| void
| RIFFIOFileDelete(RIFFIOFile *prf)

 RIFFIOFileGetFormType
 =====================
 Return the form type (UNKNOWN, RIFF, or RIFX) 
 of a RIFFIOFile

| RIFFIOFormType 
| RIFFIOFileGetFormType(RIFFIOFile *prf)

 The form type is unknown until the first form chunk of a RIFFIOFile
 is descended into or created.


 RIFFIORead
 ==========
 Read bytes from a RIFF file.

| long 
| RIFFIORead(RIFFIOFile *prf, void *pvBuffer, long nBytes)

 ENTRY
 -----
 T <*pvBuffer> must be allocated to hold <nBytes>.

 EXIT
 ----
 - Up to <nBytes> have been read from <*prf> into <*pvBuffer>. 

 RETURN
 ------
     *   The number of bytes actually read,
     *   0 on end of file,
     *  -1 on error.


 RIFFIOWrite
 ===========
 Write bytes to a RIFF file.

| long 
| RIFFIOWrite(RIFFIOFile *prf, void *pvBuffer, long nBytes)

 Write <nBytes> from <*pvBuffer> to <*prf>.

 RETURN
 ------
 The number of bytes actually written.


 RIFFIOSeek
 ==========
 Seek to a location in a RIFF file.

| RIFFIOSuccess
| RIFFIOSeek(RIFFIOFile *prf, RIFFIOOffset offset, RIFFIOSeekOrigin origin)
 
 Seek <offset> bytes relative to <origin>.

 <origin> may be one of

     RIFFIO_SEEK_SET:
       beginning of file

     RIFFIO_SEEK_CUR:
       current file position
    
     RIFFIO_SEEK_END:
       end of file
 
 ERRORS
 ------ 
 On failure, the file position is undefined.


 RIFFIOTell
 ==========
 Return the current RIFF file position.

| long
| RIFFIOTell(RIFFIOFile *prf)

 A file's position is measured in bytes from the
 beginning of the file.

