afReadMisc(3dm)                                                afReadMisc(3dm)


NAME
     afReadMisc, afWriteMisc, afSeekMisc - read from / write to / move logical
     read/write pointer for data in a miscellaneous chunk in an audio file

SYNOPSIS
     #include <dmedia/audiofile.h>

     int afReadMisc(const AFfilehandle file, int miscid,
                                  void *buf, int nbytes)

     int afWriteMisc(const AFfilehandle file, int miscid,
                                  void *buf, int nbytes)

     int afSeekMisc(const AFfilehandle file, int chunkid,
                                  int offbytes)

PARAMETER
     file     expects the AFfilehandle structure for the audio file from or to
              which you want to read or write data.  This structure is
              returned by afOpenFile(3dm) call.

     miscid   expects an integer which identifies the miscellaneous data chunk
              you want to read from or write to.

     buf      expects a pointer to a buffer which will receive a copy of the
              miscellaneous data from the file, or which contains the data you
              want to transfer into the file.

     nbytes   is the number of bytes of data you want to read from the file
              into buf or from buf into the file (beginning at the current
              position of file's logical read pointer for the data in miscid).

     offbytes specifies a nonnegative offset into the data area for chunkid
              (the offset should be less than total size of the data area).

RETURN VALUE
     afReadMisc() returns the number of bytes actually read from the
     miscellaneous chunk into buf.  afReadMisc() will not let you read beyond
     the end of the chunk's data area.  The return value is greater than or
     equal to 0 except in cases of error.  It is an error to call afReadMisc()
     on a miscellaneous chunk of size zero.

     afWriteMisc() returns the number of bytes actually written to the
     miscellaneous chunk.  afWriteMisc() will not let you write beyond the end
     of the chunk's data area.  The return value is always greater than or
     equal to 0 except in case of error, when -1 is returned.

     afSeekMisc() returns the new location of the logical read/write pointer
     for the miscellaneous chunk, measured as an offset in bytes from the
     beginning of the chunk's data area.  This value is always greater than or
     equal to 0, and less than or equal to the total number of data bytes, as
     reported by afGetMiscSize(3dm).


DESCRIPTION
     afReadMisc() copies data from the specified miscellaneous of an audio
     file to buf.  The file structure maintains internally a logical read
     pointer for each miscellaneous chunk in the file.  This allows you to
     read and write miscellaneous data (e.g., MIDI system exclusive data) from
     a file in small pieces in separate calls.

     You call afGetMiscIDs(3dm) to obtain the list of miscellaneous chunk ID's
     for file.  You call afGetMiscType(3dm) to figure out what types of
     miscellaneous chunks you have (see the afGetMiscType(3dm) man page for
     more information), and you call afGetMiscSize(3dm) to determine the total
     number of bytes in each chunk.

     When a file is opened by afOpenFile(3dm) or afOpenFD(3dm), the logical
     read pointer for each miscellaneous data chunk is initialized to the
     first data byte in the chunk.  On return from afReadMisc(), the chunk's
     read pointer is automatically updated so that it points to the data byte
     following the last one copied into buf.

     afWriteMisc() transfers data from buf the specified miscellaneous chunk
     of an audio file. The file structure maintains an internal logical write
     pointer for each miscellaneous chunk, so that you can write part of the
     data for a chunk with one call to afWriteMisc(), and write more data
     later with a second call.

     You call afInitMiscIDs(3dm) to set the list of miscellaneous chunk ID's
     for file when it is opened.  You call afInitMiscType(3dm) to initialize
     the types of miscellaneous chunks in the file (see the man page for
     afInitMiscType(3dm) for more details), and you call afInitMiscSize(3dm)
     to set the total number of data bytes allocated for each chunk.

     When an audio file is created by a call to afOpenFile(3dm), the write
     pointer for each miscellaneous chunk is initialized to the first data
     byte in the chunk.  The data area for each chunk is initially filled with
     0's. On return from afWriteMisc(), the logical write pointer for miscid
     is automatically updated so that it points to the data byte following the
     last one copied from buf to the file. It is up to the application to fill
     the data area of each chunk with consistent information (e.g., if you
     don't use all the bytes you allocated for a MIDI chunk, fill the
     remaining bytes with no-op messages).

     afSeekMisc allows you to reposition the logical read/write pointer for a
     specified miscellaneous chunk inside an audio file.  For example, you can
     move the read pointer for a MIDI data chunk in an AIFF/AIFF-C file to any
     location within the MIDI data before calling afReadMisc.  It is illegal
     to move the logical read/write pointer to a position before the first
     data byte of the specified chunk, or after the last data byte.

SEE ALSO
     afOpenFile(3dm), afInitMiscType(3dm), afInitMiscSize(3dm),
     afGetMiscIDs(3dm)


                                                                        Page 2