afInitMiscIDs(3dm)                                          afInitMiscIDs(3dm)


NAME
     afInitMiscIDs, afInitMiscType, afInitMiscSize - initialize the list of
     miscellaneous data chunk ID's in an AFfilesetup file configuration
     structure, initialize the chunk type and number of data bytes for a given
     miscellaneous chunk.

SYNOPSIS
     #include <dmedia/audiofile.h>

     void afInitMiscIDs(AFfilesetup setup, int miscids[], int nmisc)

     void afInitMiscType(AFfilesetup setup, int chunkid, int type)

     void afInitMiscSize(AFfilesetup setup, int chunkid, int size)

PARAMETER
     setup  is an AFfilesetup structure, previously created by a call to
            afNewFileSetup().

     miscids
            is an array of (unique) positive integer ID's which are used to
            reference miscellaneous data chunks in a new audio file after it
            is created by passing setup to afOpenFile(3dm).

     nmisc  The total number of miscellaneous chunks in the file
            configuration.  See the audio file format man pages aifc(4),
            next(4), wave(4), bicsf(4), and sounddesigner2(4) for format-
            specific information.

     chunkid
            is one of the chunk ID's from the miscids list.

     type   is an integer constant which denotes a valid chunk type for the
            file format being configured with setup.

     size   is a nonnegative integer value indicating the number of bytes to
            be allocated in the file header for data in the chunk given by
            chunkid.

DESCRIPTION
     afInitMiscIDs() initializes a list of unique miscellaneous chunk ID's
     which are used to reference various file format dependent data chunks in
     an audio file created by passing setup to afOpenFile(3dm).

     After you specify the list of ID's, you have to specify a chunk type and
     a chunk data area size for each of the ID's by calling afInitMiscType()
     and afInitMiscSize().

     The current 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

     For AIFF-C (and AIFF) files, you do not need to worry about the "trailing
     zero pad byte" required at the end of chunks with odd numbers of data
     bytes.  The library hides this implementation detail from applications.

     When an application creates an audio file by passing setup to
     afOpenFile(3dm), the header for the file is written out with zero-filled
     areas reserved for each of the various requested miscellaneous data
     types.

     You use the routine afWriteMisc(3dm) to write data into the chunks after
     the file has be opened.  The application is responsible for managing the
     contents of the header space reserved for each chunk of miscellaneous
     data.

     For example, if the application reserves 1000 bytes of space for MIDI
     exclusive data, then the application needs make sure that any bytes which
     aren't used for meaningful data are filled with MIDI no-op messages
     instead.


CAVEATS
     The Audio File Library will continue to expand the number of supported
     file formats and misc types.  The ability of these file formats to store
     various kinds and numbers of miscellaneous chunks will vary.  See
     afGetMiscIDs(3dm) for some important notes about handling this situation.

SEE ALSO
     afNewFileSetup(3dm), afOpenFile(3dm), afWriteMisc(3dm)


                                                                        Page 3