afIdentifyFD(3dm)afIdentifyFD(3dm)NAME
afIdentifyFD, afIdentifyNamedFD, afGetFileFormat, AFgetfilefmt - retrieve
the audio file format of a file descriptor / open AFfilehandle
SYNOPSIS
#include <dmedia/audiofile.h>
int afIdentifyFD(int fd)
int afIdentifyNamedFD(int fd, const char* filename,
int* implemented)
int afGetFileFormat(AFfilehandle file, int *vers)
PARAMETER
fd is a Unix file descriptor returned by a call to open(2) or
its equivalent.
filename is the full pathname of the file whose fd was passed as the
first argument.
implemented is a pointer to integer which will have its value set to 0
or 1 by afIdentifyNamedFD().
file is an AFfilehandle structure, previously created by a call
to afOpenFile(3dm).
vers is used to return a file format version number. The AIFF-C
format includes a file chunk which contains a version
number. AIFF does not contain a version number, so for
AIFF files, the value returned here is 0. If vers is a
null pointer, it is ignored.
RETURN VALUEafIdentifyFD() and afIdentifyNamedFD() return a positive value indicates
that fd's file format is supported by the Audio File Library. A negative
return value indicates an unsupported or unrecognized audio file format.
afGetFileFormat() returns the format of the file represented by the file
handle. It will return -1 only if the handle is bad.
DESCRIPTIONafIdentifyFD() and afIdentifyNamedFD() return a symbolic integer constant
which denotes the audio file format associated with fd.
afIdentifyNamedFD() sets the value of *implemented to 1 if the format was
both recognized and is supported (i.e., can be read and written) and 0 if
the file is either recognized but not supported or unrecognized. This
allows applications to distinguish filetypes regardless of their support
with the Audio File Library. If implemented is a null pointer, it will
be ignored.
Page 1
afIdentifyFD(3dm)afIdentifyFD(3dm)afIdentifyNamedFD() is provided for cases in which the desired audio
files may exist as two or more files separated into resource and data
files (plus possible ancillary data) as is the case with Sound Designer 2
files. For such cases, this routine must be used and supplied with the
original pathname to the file in order for the routine to properly
identify this filetype and other future types like it. This routine may
be used in place of afIdentityFD in all cases where a file pathname is
available. Note that it is possible to identify audio formats which are
not readable by the library.
afGetFileFormat() returns a symbolic integer constant which denotes the
audio file format in the file handle structure. The vers parameter can
be used to obtain additional information about the file format. For
example, for AIFF-C vers contains a long integer AIFF-C version number.
RETURN VALUE
All three routines return a symbolic integer constant which indicates the
format of the audio file. Current possible file format values (defined in
<dmedia/audiofile.h>):
AF_FILE_AIFFC extended Audio Interchange File Format (AIFF-C)
AF_FILE_AIFF Audio Interchange File Format (AIFF)
AF_FILE_NEXTSND NeXT .snd and Sun .au
AF_FILE_WAVE Waveform Audio File Format (RIFF)
AF_FILE_BICSF Berkeley/IRCAM/CARL Sound File format
AF_FILE_MPEG1BITSTREAM MPEG-1 Audio Bitstream encoded data
AF_FILE_SOUNDESIGNER1 Sound Designer File Format I (not supported)
AF_FILE_SOUNDESIGNER2 Sound Designer File Format II
AF_FILE_AVR Audio Visual Research File Format
AF_FILE_IFF_8SVX Amiga IFF/8SVX File Format
AF_FILE_VOC Creative Labs VOC File Format
AF_FILE_SAMPLEVISION Sample Vision File Format
AF_FILE_SOUNDFONT2 Creative Labs SoundFont2 (tm) File Format
AF_FILE_NIST_SPHERE NIST SPHERE File Format (not supported)
AF_FILE_UNKNOWN Unrecognized file format
Page 2
afIdentifyFD(3dm)afIdentifyFD(3dm)
Note that these are by no means all of the possible return values for
this function. The AF is a library which will continue to support new
file formats. As the Audio File Library is a Dynamic Shared Object
(DSO), it is possible for this function to return a token not found in
<audiofile.h>. In addition, other future file formats may contain a
version number which will be returned in vers.
CAVEATSafIdentifyNamedFD() represents a special case within the Audio File
Library routines in that it will attempt to open files other than the one
passed in via fd. Because the names of these other files vary with the
file system, this access is done by the library rather than by the
application to make the operation transparent to the user. In the event
that these files exist but are not readable, afIdentifyNamedFD() will
return AF_FILE_UNKNOWN (assuming the file did not match any other format)
and oserror(3C) will be set to the appropriate error value.
SEE ALSOafOpenFile(3dm), afGetFileFormat(3dm), afOpenNamedFD(3dm)
Page 3
