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 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. 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 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 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 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. 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 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 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. 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 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 u- law" 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 Queries concerning the compression parameters supported by various compression schemes. arg1 may be one of the following: AF_QUERY_ID_COUNT Request the total number of compression parameters currently supported by the compression scheme supplied in arg2. AF_QUERY_IDS Request an integer array of the supported compression parameter id token values for the compression scheme supplied in arg2. AF_QUERYTYPE_MISC 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. 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; /* 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