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 VALUEafReadMisc() 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).
Page 1
afReadMisc(3dm)afReadMisc(3dm)DESCRIPTIONafReadMisc() 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 ALSOafOpenFile(3dm), afInitMiscType(3dm), afInitMiscSize(3dm),
afGetMiscIDs(3dm)
Page 2
