ALoadAFile(3X)

NAME

ALoadAFile − copy audio file into new sound bucket with data conversion

SYNOPSIS

#include <Alib.h> SBucket ∗
ALoadAFile (

Audio ∗ audio,

char ∗ pathname,

AFileFormat file_format,

AudioAttrMask attr_mask,

AudioAttributes ∗ sb_attributes,

long ∗ status_return );

DESCRIPTION

ALoadAFile() creates a sound bucket that contains the audio data from the file at pathname. A pointer to this new sound bucket structure is returned. If the audio data in the file is not in a format that is supported by the connected audio hardware, the audio data will be converted to a supported format before it is loaded into the sound bucket.

The HP-UX kernel configuration sets a data size restriction. If the audio data file exceeds this size, the function returns the "AEOutOfMemory" error in the status_return parameter.

When the sound bucket is no longer needed, call ADestroySBucket() to deallocate the space.

audio is the audio structure associated with this connection.

pathname specifies the file containing the audio data.

file_format must be set to a valid enumerated value, or else an error is returned.

Use one of the following values:

AFFUnknown − Have the Audio library determine the file type (see below).

AFFRiffWave − Microsoft RIFF waveform

AFFSun − Sun(NeXT) format

AFFRawMuLaw − MuLaw format

AFFRawALaw − ALaw format

AFFRawLin16 − Linear16 (16-bit signed) format

AFFRawLin8 − Linear8 (8-bit signed) format

AFFRawLin8Offset − Linear8Offset (8-bit unsigned)

If this parameter is set to AFFUnknown, the conversion utility checks for a valid header in the file. If it can’t find a valid header, it checks for an extension on pathname. Extensions may be appended to the filename as follows: name.sampling_rate.file_type. Valid sampling rate extensions are .n and .nk where .nk is typically 8k to 22k.

Valid file type extensions are:

.u raw Mulaw

.al raw Alaw

.au Sun (NeXT)

.wav Riff

.snd NeXT

.l16 raw Linear16

.l8 raw Linear8

.lo8 raw Linear8Offset

attr_mask specifies the audio attributes to associate with the new sound bucket. The mask is a bitwise inclusive OR of one or more of the mask values listed in the Structures section.

If this value is set to 0 or if sb_attributes is set to NULL, the a_name attributes are used if the connected audio hardware supports them. If there is an unsupported attribute, the attribute returned by ABestAudioAttributes() is used.

If the mask is set, the new attributes are used without checking for hardware support. This allows ALoadAFile() to be used purely for conversion purposes.

NOTE: If ASDurationMask is set, the pathname audio data is truncated or padded with zeros to match the length specified in audio_attributes.sampled_attr.duration.

sb_attributes specifies the attributes that are affected by the mask. Audio type must be set (i.e., ATSampled), separate from the mask. If the attribute is different from the one used by pathname, the data is converted.

status_return receives the returned status of the operation, unless this parameter is passed in as a NULL pointer. If status_return is set to NULL, Alib will do the error handling.

RETURN VALUE

Upon successful completion, ALoadAFile() returns a pointer to the new sound bucket.

STRUCTURES

The following are defined in /opt/audio/include/Alib.h.

typedef long                    AudioAttrMask;
#define ASDataFormatMask        ( 1 << ASAFDataFormat )
#define ASBitsPerSampleMask     ( 1 << ASAFBitsPerSample )
#define ASSamplingRateMask      ( 1 << ASAFSamplingRate )
#define ASChannelsMask          ( 1 << ASAFChannels )
#define ASInterleaveMask        ( 1 << ASAFInterleave )
#define ASDurationMask          ( 1 << ASAFDuration )
typedef struct _SBucket {
    AudioAttributes   audio_attr; /* Attributes of the audio data
                                     in the sound bucket.        */
    long              max_length; /* The maximum length, in bytes,
                                     of the audio_data buffer.   */
    char            * audio_data; /* A pointer to the buffer that
                                     contains the audio data
                                     for this sound bucket.      */
} SBucket;

ERRORS

If status_return is not set to NULL, it can return one of the following values:

0 AENoError No error - the call completed successfully.

2 AEBadAudio The audio structure is invalid. A pointer to a valid audio structure may be missing (use AOpenAudio() to get a valid pointer).

6 AEBadFileFormat The specified file format is currently unsupported.

7 AEBadDataFormat The data format specified in the sb_attributes structure is either not appropriate for the file format or is not one of the supported data formats.

8 AEFileNotFound The Audio Library could not find the specified file.

11 AEBadFileHdr The specified file type requires a header, but the file lacks a valid header for that file type.

13 AEBadAttribute The specified audio attributes structure contains an unsupported or inconsistent value.

16 AECantDetermineFormat AFFUnknown was specified for either the source or destination file format, but there is no valid header or filename extension.

17 AEOutOfMemory Alib attempted to malloc space but failed. A possible cause is the use of sound buckets with large audio files.

EXAMPLES

The following example copies the file /myhome/a_dir/a_file into the new sound bucket and specifies AFFRawALaw for the file format. Specifying zero for a_mask and NULL for myAttr means that the pathname attributes will be used if the controller supports them; if there is an unsupported attribute, the attribute returned by ABestAudioAttributes() will be used.

SBucket          *sb;    /* sound bucket */
Audio            *audio; /* audio connection */
char             a_name[30]; /* file name */
AFileFormat      file_fmt;   /* file format */
AudioAttrMask    a_mask;     /* audio attributes mask */
AudioAttributes *myAttr;    /* audio attributes */
long             status;     /* error status */
.
.
.
/* load file into new sound bucket */
a_name = "/myhome/a_dir/a_file";
file_fmt = AFFRawALaw;
a_mask = 0;
myAttr = " ";
sb = ALoadAFile(audio, a_name, file_fmt, a_mask, myAttr, &status);

NOTE

In order to ensure that the compiler finds the Audio Library (libAlib.sl) and the Alib.h header file, you must add the following switches:

-L /opt/audio/lib
-I/opt/audio/include

DEPENDENCIES

This function belongs to the Audio Library of functions that manage connections to an audio server. The audio server must run on a system that has audio hardware. To find out whether or not your system has audio hardware, refer to Using the Audio Developer’s Kit or the online help for the Audio control panel. For information about the audio capabilities of a particular system use the online example audioinfo.c.

AUTHOR

ALoadAFile() was developed by HP.

Museum

Related Articles