afQuery(3dm) afQuery(3dm)
afQuery, afQueryLong, afQueryDouble, afQueryPointer - retrieve static
parameters associated with the Audio File Library formats
"#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)
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.
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
AF_NUM_UNLIMITED 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.
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:
AF_QUERYTYPE_INST [Toc] [Back]
Queries about the support and quantity of inst chunks by a given file
format. arg1 may be one of the following:
AF_QUERY_SUPPORTED Boolean value, 1 if the file format specified in
arg2 supports an inst chunk, 0 otherwise.
AF_QUERY_ID_COUNT 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.
AF_QUERYTYPE_INSTPARAM [Toc] [Back]
Instrument parameters associated with the INST chunk for formats which
support an INST. arg1 may be one of the following:
AF_QUERY_SUPPORTED Boolean value, 1 if the file format in arg2 supports
instrument parameters in its inst chunk, 0
otherwise.
AF_QUERY_ID_COUNT 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.
AF_QUERY_IDS Request an integer array of the available inst param
token values
AF_QUERY_TYPE 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 AU_PVTYPE_LONG,
AU_PVTYPE_DOUBLE, or AU_PVTYPE_PTR. See
afGetInstParams(3dm) for more information.
AF_QUERY_NAME 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)
AF_QUERY_DEFAULT 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
AF_QUERY_TYPE
AF_QUERYTYPE_LOOP [Toc] [Back]
Queries about the support and quantity of loops (in inst chunks) in a
given file format. arg1 may be one of the following:
AF_QUERY_SUPPORTED Boolean value, 1 if the file format specified in
arg2 supports inst chunks with loops in them, 0
otherwise.
AF_QUERY_ID_COUNT Request the total number of loops supported by the
insts in the format specified in arg2. This may be
any value.
AF_QUERYTYPE_FILEFMT [Toc] [Back]
Parameters associated with the various file formats supported by the
library. arg1 may be one of the following:
AF_QUERY_LABEL Request a 4-character label for the format,
e.g., "aiff"
AF_QUERY_NAME Request a short name for the format, e.g.,
"MS RIFF WAVE"
AF_QUERY_DESC Request a longer, more descriptive name for
the format, e.g., "Audio Interchange File
Format"
AF_QUERY_IMPLEMENTED Request a boolean value; 1 if format is
implemented for read/write in the Audio File
Library, otherwise 0.
AF_QUERY_ID_COUNT Request the total number of formats
currently implemented
AF_QUERY_IDS Request an integer array of the implemented
format id token values
AF_QUERY_COMPRESSION_TYPES Used with selector AF_QUERY_VALUE_COUNT in
arg2, it returns a long integer containing
the number of compression schemes supported
by the format in arg3. Used with selector
AF_QUERY_VALUES, 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)
AF_QUERY_SAMPLE_FORMATS Used with selector in AF_QUERY_DEFAULT in
arg2, it returns the default sample format
for the format specified in arg3.
AF_QUERY_SAMPLE_SIZES Used with selector AF_QUERY_DEFAULT in arg2,
it returns the default sample width for the
format specified in arg3.
AF_QUERYTYPE_COMPRESSION [Toc] [Back]
Parameters associated with the various compression schemes supported by
the library. arg1 may be one of the following:
AF_QUERY_LABEL Request a 4-character label for the
compression, e.g., "g722"
AF_QUERY_NAME Request a short name for the compression,
e.g., "Aware MultiRate"
AF_QUERY_DESC Request a longer, more descriptive name for
the compression, e.g., "SGI CCITT G.711 ulaw"
AF_QUERY_ID_COUNT Request the total number of compression
schemes currently implemented by the Audio
File Library.
AF_QUERY_IDS Request an integer array of the implemented
compression scheme id token values
AF_QUERY_NATIVE_SAMPFMT Request the native sample format, i.e., the
format of the data before compression and/or
after decompression, e.g.,
AF_SAMPFMT_TWOSCOMP
AF_QUERY_NATIVE_SAMPWIDTH Request the native format's sample width in
bits, e.g., '16' for short integer sample
data
AF_QUERYTYPE_COMPRESSIONPARAM [Toc] [Back]
Queries concerning the compression parameters supported by various
compression schemes. arg1 may be one of the following:
AF_QUERY_ID_COUNT [Toc] [Back]
Request the total number of compression parameters currently
supported by the compression scheme supplied in arg2.
AF_QUERY_IDS [Toc] [Back]
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)
AF_QUERYTYPE_MISC [Toc] [Back]
Parameters associated with the MISC chunks that can be stored by the
various file formats. arg1 may be one of the following:
AF_QUERY_LABEL Request the four-character label for the misc
chunk, e.g., "COPY".
AF_QUERY_NAME Request the name of the misc chunk, e.g.,
"copyright".
AF_QUERY_DESC Request a short description of the misc chunk,
e.g., "Copyright string".
AF_QUERY_TYPE_COUNT Request the number of misc chunk types
supported by a given file format.
AF_QUERY_TYPES 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.
AF_QUERY_MAX_NUMBER 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.
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);
afOpenFile(3dm), afGetFileFormat(3dm), afInitCompression(3dm)
PPPPaaaaggggeeee 6666 [ Back ]
|
