afGetMiscIDs(3dm)                                            afGetMiscIDs(3dm)


NAME
     afGetMiscIDs,  afGetMiscType, afGetMiscSize - get number and list of
     miscellaneous chunk ID's for a file, get the data type and size for a
     miscellaneous data chunk.

SYNOPSIS
     #include <dmedia/audiofile.h>

     int afGetMiscIDs(AFfilehandle file, int miscids[])

     int afGetMiscType(AFfilehandle file, int chunkid)

     int afGetMiscSize(AFfilehandle file, int chunkid)

PARAMETER
     file      is an AFfilehandle structure, created when an audio file was
               opened by a call to afOpenFile(3dm).

     miscids[] is an array of integer locations used to return a list of
               unique positive miscellaneous chunk ID's which can be used to
               reference the miscellaneous chunks in a file.

     chunkid   is a miscellaneous chunk id from the miscids[] list returned by
               afGetMiscIDs().

RETURN VALUE
     afGetMiscIDs() returns a nonnegative integer count of the number of
     miscellaneous chunks in the file, or -1 on error.

     afGetMiscType() returns a positive symbolic constant denoting the chunk
     type for a given miscellaneous chunk ID. If there is an error or the
     chunk ID is invalid for the file, the return value is -1.

     afGetMiscSize() returns a nonnegative integer count of the number of data
     bytes contained in the specified chunk, or -1 on error.

DESCRIPTION
     The Audio File Library allows you to access file format-specific non-
     audio data chunks in audio files through miscellaneous chunk ID's.  Each
     ID corresponds to a chunk type and a chunk data size in bytes.

     afGetMiscIDs() returns the number of miscellaneous chunks contained in
     file.  You can call afGetMiscIDs() with a null miscids pointer, and
     allocate a miscids[] buffer according to the return value.

     You can then pass the miscids[] buffer back to afGetMiscIDs() to obtain a
     list of ID's for the various chunks of miscellaneous data in file.

     afGetMiscType() gives you the chunk type for a given chunk ID.  Valid
     miscellaneous data types are:


     AF_MISC_COPY      Copyright string

     AF_MISC_AUTH      Author/artist string

     AF_MISC_NAME      Name string

     AF_MISC_ANNO      AIFF/AIFF-C annotation string

     AF_MISC_MIDI      AIFF/AIFF-C MIDI system exclusive data

     AF_MISC_APPL      AIFF/AIFF-C application-specific data

     AF_MISC_PCMMAP    PCM mapping information (for future use)

     AF_MISC_NeXT      NeXT file info chunk

     AF_MISC_IRCAM_PEAKAMP
                       BICSF peak amplitude sfcode

     AF_MISC_COMMENT   Text comment string.  The tags AF_MISC_IRCAM_COMMENT
                       and AF_MISC_ICMT are also allowed for this type, though
                       this chunk is supported by several file types.

     AF_MISC_ICRD      Creation date string.  This is usually of the form
                       "YYYY-MM-DD".

     AF_MISC_ISFT      Software name string.  Usually set to the name of the
                       software package which created the sound.

     AF_MISC_UNRECOGNIZED
                       unrecognized data chunk

     See the AIFF-C spec for descriptions of the first six chunks, and the
     various audio format man pages (next(4), bicsf(3dm)) for the remainder.
     Since the AIFF-C format is extensible, and new audio file formats are
     likely to be added to the AF in future versions, the AF_MISC_UNRECOGNIZED
     data type is included to handle any data chunks encountered in a file
     which are neither part of the AIFF-C standard nor recognized by the other
     currently supported file formats.

     afGetMiscSize() returns the number of data bytes in the chunk.

     Note: for AIFF-C (AIFF) files, you don't have to worry about the possible
     trailing zero pad byte at the end of a miscellaneous chunk data area.
     The library hides this file format implementation detail.

EXAMPLE
     The routine afReadMisc(3dm) allows you to read miscellaneous data from an
     audio file.  In order to read a copyright string from an AIFF-C file, for
     example, you first obtain a list of miscellaneous chunk ID's for the file
     by querying afGetMiscIDs().


     You determine the type of each miscellaneous chunk by calling
     afGetMiscType() for each of the ID's.  The ID which has chunk type
     AF_MISC_COPY corresponds to the copyright string in the file.

     You can determine the length of the string by passing the ID to
     afGetMiscSize(), and allocate a buffer with the appropriate length
     (allocate one extra location for the null-terminator).

     Finally, you obtain a copy of the string by passing the chunk ID, buffer,
     and buffer length to afReadMisc(3dm).  Put a null character in the last
     buffer location to null-terminate the string.

CAVEATS
     These functions may return ANY type of misc chunk, even one not included
     in <dmedia/audiofile.h>.  As indicated above, the possible types of misc
     chunk are no longer limited to those found in an AIFF/AIFF-C file.  Apps
     should be written to expect and ignore miscellaneous chunks they do not
     understand.

     Apps should be especially careful not to copy misc chunks from one file
     to another unless they understand the content of those misc chunks;  the
     chunk may contain references to other parts of the file which the
     application has modified.  In this case the chunk in the new file becomes
     corrupt.  This is to be avoided.  The chunk should not be copied and the
     user should probably be warned.

SEE ALSO
     afOpenFile(3dm), afReadMisc(3dm), afInitMiscIDs(3dm), afSeekMisc(3dm).


                                                                        Page 3