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 VALUEafGetMiscIDs() 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:
Page 1
afGetMiscIDs(3dm)afGetMiscIDs(3dm)
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().
Page 2
afGetMiscIDs(3dm)afGetMiscIDs(3dm)
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 ALSOafOpenFile(3dm), afReadMisc(3dm), afInitMiscIDs(3dm), afSeekMisc(3dm).
Page 3
