afGetInstIDs(3dm)                                            afGetInstIDs(3dm)


NAME
     afGetInstIDs - get a list of instrument configurations from an
     AFfilehandle

SYNOPSIS
     #include <dmedia/audiofile.h>

     int afGetInstIDs(AFfilehandle file, int *instids)

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

     instids   an array of integer locations used to return a list of (unique)
               positive instrument ID's which can be used to reference the
               sampler configurations in a file.  For an AIFF/AIFF-C file,
               this array will return the ID AF_DEFAULT_INST if there is an
               instrument chunk.  If you pass a null instids array to
               afGetInstIDs(), it simply returns the number of sampler
               configurations stored in the audio file.

RETURN VALUE
     afGetInstIDs() returns a nonnegative integer count of the number of
     instrument configurations in the file, or -1 in case of error.

     For AIFF-C and AIFF files, this value is always either 0 or 1.  The value
     varies in other file formats, so it is important to use this routine to
     check the inst count prior to handing it a pointer to an array.

DESCRIPTION
     Typically, afGetInstIDs() is called twice.  The first time you pass it a
     null instids array, and just check the return value. The return value
     tells you how large an instids array to allocate, which you in turn pass
     back to afGetInstIDs() to obtain a list of unique positive instrument ID
     values.  You can then use these ID's to reference the various instrument
     configurations in the file.

     For example, you pass an instrument ID to afGetInstParamLong(3dm) to
     obtain the values of the individual instrument parameters such as gain,
     base note, and velocity range.

CAVEATS
     This function may return more than one inst, unlike the one fixed INST in
     AIFF/AIFF-C files.  Other currently supported file formats have different
     inst configurations than AIFF/AIFF-C.

     In the case of INST parameters it is important to be able to query at
     runtime the capabilities of a given file format.  An application can use
     afQuery(3dm) to determine whether a given file format supports INST
     chunks, and if so, the maximum number allowed.  Apps should also be
     written to expect and ignore instrument configurations or instrument
     parameters they do not understand.


SEE ALSO
     afOpenFile(3dm),  afInitInstIDs(3dm), afGetInstParamLong(3dm)


                                                                        Page 2