afOpenFile(3dm)afOpenFile(3dm)NAME
afOpenFile, afOpenFD, afOpenNamedFD - allocate an AFfilehandle structure
for an audio file identified by name / by a Unix file descriptor
SYNOPSIS
#include <dmedia/audiofile.h>
AFfilehandle afOpenFile(const char *name, const char *mode,
AFfilesetup setup)
AFfilehandle afOpenFD(int fd, const char *mode,
AFfilesetup setup)
AFfilehandle afOpenNamedFD(int fd, const char *mode,
AFfilesetup setup, const char* name)
PARAMETER
name A character string which names the audio file to be opened.
fd A Unix file descriptor corresponding to an audio data file which
has been previously returned by open(2) or its equivalent.
mode This parameter identifies whether the file is to be opened for
reading or writing audio sample data and header information.
Acceptable values:
"r" configures the file descriptor for read-only access
"w" configures the file descriptor for write-only access
The current library implementation causes existing files to be
truncated to zero length and rewritten when opened for write
access.
setup is an AFfilesetup structure previously returned by a call to
afNewFileSetup(3dm). setup contains initialization parameters
used by afOpenFile() when it configures a new AFfilehandle, and
initializes the corresponding file header. setup is generally
set to NULL when mode is "r".
If setup is non-NULL and mode is "r", it indicates a desire to
read an audio file as a raw (headerless) file. The setup
structure's file format parameter must be set to AF_FILE_RAWDATA,
and all its parameters must be initialized to acceptable values
prior to the call to the afOpen routine. This is done with
afInitFileFormat(3dm), afInitSampleFormat(3dm),
afInitChannels(3dm), afInitRate(3dm), etc. If this is not done,
afOpenFile(), etc. will return an error.
Page 1
afOpenFile(3dm)afOpenFile(3dm)RETURNED VALUE
If successful, each function returns an AFfilehandle structure for the
named file. A null (AF_NULL_FILEHANDLE) return value indicates an error.
afOpenFile(), afOpenFD(), and afOpenNamedFD() return null AFfilehandle
structures when a file opened with mode "r" does not parse according to
any of the implemented file format specifications.
DESCRIPTIONafOpenFile() allocates and initializes an AFfilehandle structure for an
audio file. This structure is then used as the basic argument for all
Audio File Library routines which access data in the audio file.
The audio track logical read/write pointer used by afReadFrames(3dm) and
afWriteFrames(3dm) is initialized to point to the location of the first
sample in the audio file.
afOpenFD() allows you to test whether a file can be opened for reading or
writing using regular Unix system calls before attempting to attach an
AFfilehandle structure to the file. This can help you eliminate error
messages from the Audio File Library in some cases. afOpenNamedFD() must
be used in place of afOpenFD(3dm) if any of the files to be identified
are Sound Designer II files. This is due to the multi-file nature of the
format (resource and data fork files at a minimum), and so the full path
to the file must be known to properly identify its format. See sd2(4)
for more information.
NOTE
The current Audio File Library does not support read-write (or "edit")
access for existing files. In order to edit an existing file through the
library, it is necessary to create a second version of the file.
Sample source code in /usr/share/src/dmedia/soundfile shows how to make a
copy of an audio file which contains all the logical components of the
original file.
CAVEATS
Many of the routines in the Audio File Library will not function
correctly if the user changes the file position on the file descriptor
for the AFfilehandle being manipulated. See the section CAVEATS FOR
USING THE HANDLE'S FILE DESCRIPTOR in afIntro(3dm) for some important
information about how to deal with this situation Be careful when using
afOpenFD(): Regardless of whether a file is opened with afOpenFD(),
afOpenNamedFD(), or afOpenFile(), its file descriptor will be closed when
the user issues afCloseFile(3dm). Do not expect the file descriptor to
remain open just because it was opened by an external function call.
This is unfortunately not consistent with the SGI Movie Library, but must
be maintained for backwards compatibility.
Page 2
afOpenFile(3dm)afOpenFile(3dm)SEE ALSOafCloseFile(3dm), afNewFileSetup(3dm), afReadFrames(3dm),
afWriteFrames(3dm)afInitFileFormat(3dm)
Page 3
