afQuery(3dm) afQuery(3dm)
NAME
afQuery, afQueryLong, afQueryDouble, afQueryPointer - retrieve static
parameters associated with the Audio File Library formats
SYNOPSIS
"#include <dmedia/audiofile.h>"
AUpvlist afQuery(int querytype, int arg1, int arg2,
int arg3, int arg4)
long afQueryLong(int querytype, int arg1, int arg2,
int arg3, int arg4)
double afQueryDouble(int querytype, int arg1, int arg2,
int arg3, int arg4)
void* afQueryPointer(int querytype, int arg1, int arg2,
int arg3, int arg4)
PARAMETER
querytype is an integer value token representing the type of query
being made.
arg1,...arg4 are integer value tokens representing the query selectors
and/or subtypes. The number of meaningful arguments to
the afQuery routines varies with the querytype.
RETURN VALUE
Each of the four afQuery() variants returns the requested information via
the return value, which may be of type AUpvlist, long, double, or void *,
depending on the variant. afQueryPointer()'s return value will usually
be cast by the application to the appropriate pointer type (i.e., char*
for strings, int* for id arrays). If the query represents a character
string (AF_QUERY_LABEL, AF_QUERY_NAME, AF_QUERY_DESC), the pointer should
not and must not be free()'d by the application; in all other cases it
must be free()'d to avoid memory leakage.
If the return value represents a quantity such as the number of loops
supported by a file format's inst chunks, the special return value
AFNUMUNLIMITED indicates that there is no hard limit on the quantity.
If an error occurs, afQueryLong() and afQueryDouble() will return -1, and
afQueryPointer() will return NULL.
DESCRIPTION
afQuery() and its associated routines are designed to allow an
application to query the audio file library for information about its
supported features. These features include such things as the names,
descriptions, labels, default values, ID counts, and implementation
status of the instrument parameters, file formats, compression algorithms
and parameters, and miscellaneous chunks read from and stored into
headers. Which routine should be used depends on the data type of the
Page 1
afQuery(3dm) afQuery(3dm)
parameter to be queried. For example, to retrieve a character string,
use afQueryPointer and cast the return value to (char *).
The rule for placement of arguments is as follows: querytype is always
the AF_QUERYTYPE desired. arg1 is always the first sub-selector, such as
AF_QUERY_TYPE or AF_QUERY_NAME. arg2 will sometimes be an additional
sub-selector, such as AF_QUERY_DEFAULT, and will sometimes be the target
of the query, such as the file format or the compression type. The
target of the query will always be the final non-zero argument to
afQuery(). All subsequent arguments must be set to 0.
Possible querytype values (defined in <dmedia/audiofile.h>), and their
appropriate selectors and subtypes:
AFQUERYTYPEINST
Queries about the support and quantity of inst chunks by a given file
format. arg1 may be one of the following:
AFQUERYSUPPORTED Boolean value, 1 if the file format specified in
arg2 supports an inst chunk, 0 otherwise.
AFQUERYIDCOUNT Request the total number of inst chunks supported by
the format specified in arg2. This is usually 1 or
0, but may be any value.
AFQUERYTYPEINSTPARAM
Instrument parameters associated with the INST chunk for formats which
support an INST. arg1 may be one of the following:
AFQUERYSUPPORTED Boolean value, 1 if the file format in arg2 supports
instrument parameters in its inst chunk, 0
otherwise.
AFQUERYIDCOUNT Request the total number of inst params supported by
this format's inst. This can be any value -- not
just the number supported by AIFF/AIFF-C files.
AFQUERYIDS Request an integer array of the available inst param
token values
AFQUERYTYPE With the file format as arg2 and a particular inst
param id as arg3, this will return the param type of
the param. This will be one of AUPVTYPELONG,
AUPVTYPEDOUBLE, or AUPVTYPEPTR. See
afGetInstParams(3dm) for more information.
AFQUERYNAME With the file format as arg2 and a particular inst
param id as arg3, this will return the param type of
the param as a character string.
Page 2
afQuery(3dm) afQuery(3dm)
AFQUERYDEFAULT With the file format as arg2 and a particular inst
param id as arg3, this will return default value of
the param based on the type as returned via
AFQUERYTYPE
AFQUERYTYPELOOP
Queries about the support and quantity of loops (in inst chunks) in a
given file format. arg1 may be one of the following:
AFQUERYSUPPORTED Boolean value, 1 if the file format specified in
arg2 supports inst chunks with loops in them, 0
otherwise.
AFQUERYIDCOUNT Request the total number of loops supported by the
insts in the format specified in arg2. This may be
any value.
AFQUERYTYPEFILEFMT
Parameters associated with the various file formats supported by the
library. arg1 may be one of the following:
AFQUERYLABEL Request a 4-character label for the format,
e.g., "aiff"
AFQUERYNAME Request a short name for the format, e.g.,
"MS RIFF WAVE"
AFQUERYDESC Request a longer, more descriptive name for
the format, e.g., "Audio Interchange File
Format"
AFQUERYIMPLEMENTED Request a boolean value; 1 if format is
implemented for read/write in the Audio File
Library, otherwise 0.
AFQUERYIDCOUNT Request the total number of formats
currently implemented
AFQUERYIDS Request an integer array of the implemented
format id token values
AFQUERYCOMPRESSIONTYPES Used with selector AFQUERYVALUECOUNT in
arg2, it returns a long integer containing
the number of compression schemes supported
by the format in arg3. Used with selector
AFQUERYVALUES, it returns a pointer to an
integer array containing the compression ids
of the compression types supported by format
specified in arg3.
Page 3
afQuery(3dm) afQuery(3dm)
AFQUERYSAMPLEFORMATS Used with selector in AFQUERYDEFAULT in
arg2, it returns the default sample format
for the format specified in arg3.
AFQUERYSAMPLESIZES Used with selector AFQUERYDEFAULT in arg2,
it returns the default sample width for the
format specified in arg3.
AFQUERYTYPECOMPRESSION
Parameters associated with the various compression schemes supported by
the library. arg1 may be one of the following:
AFQUERYLABEL Request a 4-character label for the
compression, e.g., "g722"
AFQUERYNAME Request a short name for the compression,
e.g., "Aware MultiRate"
AFQUERYDESC Request a longer, more descriptive name for
the compression, e.g., "SGI CCITT G.711 u-
law"
AFQUERYIDCOUNT Request the total number of compression
schemes currently implemented by the Audio
File Library.
AFQUERYIDS Request an integer array of the implemented
compression scheme id token values
AFQUERYNATIVESAMPFMT Request the native sample format, i.e., the
format of the data before compression and/or
after decompression, e.g.,
AFSAMPFMTTWOSCOMP
AFQUERYNATIVESAMPWIDTH Request the native format's sample width in
bits, e.g., '16' for short integer sample
data
AFQUERYTYPECOMPRESSIONPARAM
Queries concerning the compression parameters supported by various
compression schemes. arg1 may be one of the following:
AFQUERYIDCOUNT
Request the total number of compression parameters currently
supported by the compression scheme supplied in arg2.
AFQUERYIDS
Request an integer array of the supported compression parameter id
token values for the compression scheme supplied in arg2.
Page 4
afQuery(3dm) afQuery(3dm)
AFQUERYTYPEMISC
Parameters associated with the MISC chunks that can be stored by the
various file formats. arg1 may be one of the following:
AFQUERYLABEL Request the four-character label for the misc
chunk, e.g., "COPY".
AFQUERYNAME Request the name of the misc chunk, e.g.,
"copyright".
AFQUERYDESC Request a short description of the misc chunk,
e.g., "Copyright string".
AFQUERYTYPECOUNT Request the number of misc chunk types
supported by a given file format.
AFQUERYTYPES Request an integer array of the misc chunk
types supported by a given file format, as
supplied via arg2. The array is returned as a
pointer, and will be null if no misc types are
supported by the given file format.
AFQUERYMAXNUMBER Request the maximum number of allowed misc
chunks of a given type for a given file
format, as supplied via arg2 If the number is
unlimited, 0 is returned for backwards
compatibility rather than AF_NUM_UNLIMITED.
If the misc type is not supported, -1 is
returned but no error is generated.
EXAMPLE
To query and print the name of a given audio file format:
AFfilehandle handle = afOpenFile("somefile.aiff", "r", NULL);
char* formatstring;
int fileformat = afGetFileFormat(handle, NULL);
formatstring = afQueryPointer(AF_QUERYTYPE_FILEFMT,
AF_QUERY_NAME,
fileformat,
0,
0);
printf("The file format name is %s0, formatstring);
To query a list of supported compression type ids:
AFfilehandle handle = afOpenFile("somefile.aifc", "r", NULL);
int fileformat = afGetFileFormat(handle, NULL);
long numCompressionTypes;
int *compressionIDs = NULL;
Page 5
afQuery(3dm) afQuery(3dm)
/* first get the total number */
numCompressionTypes = afQueryLong(AF_QUERYTYPE_FILEFMT,
AF_QUERY_COMPRESSION_TYPES,
AF_QUERY_VALUE_COUNT,
fileformat,
0);
/* if number is not zero, retrieve the array of IDs */
if(numCompressionTypes > 0) {
compressionIDs = (int *) afQueryPointer(AF_QUERYTYPE_FILEFMT,
AF_QUERY_COMPRESSION_TYPES,
AF_QUERY_VALUES,
fileformat,
0);
/* here you would do whatever you wished with these IDs */
}
/* free the array memory */
if(compressionIDs != NULL)
free(compressionIDs);
SEE ALSO
afOpenFile(3dm), afGetFileFormat(3dm), afInitCompression(3dm)
Page 6