ALoadAFile(3X)

NAME

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

SYNOPSIS

SBucket ∗
ALoadAFile (

Audio ∗ audio,

char ∗ pathname,

AFileFormat file_format,

AudioAttrMask attr_mask,

AudioAttributes ∗ sb_attributes,

long ∗ status_return);

DESCRIPTION

ALoadAFile() copies the audio data in pathname into a new sound bucket and returns the pointer to the sound bucket. The data is converted according to the specified attributes.

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.

If this parameter is set to AFFUnknown, the conversion utility 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 Mulaw

.al Alaw

.au Sun

.wav Riff

.snd Mac

.l16 Linear16

.l8 Linear8

.lo8 Linear8Offset

If no recognizable extension exists, the utility checks the header on the pathname file. If file format is not valid or is not determinable, an error is returned.

attr_mask specifies the audio attributes to associate with the new sound bucket. The mask is a bitwise inclusive OR of values defined in AudioAttrMask.

If this value is set to 0 or if audio_attributes is set to NULL, the pathname attributes are used if the controller 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 controller 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.

status_return receives the returned status of the operation, unless it is set to NULL.

RETURN VALUE

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

ERRORS

If status_return is not set to NULL, one of the following is returned in status_return:

0 AENoError

2 AEBadAudio

6 AEBadFileFormat

7 AEBadDataFormat

8 AEFileNotFound

11 AEBadFileHdr

16 AECantDetermineFormat

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);

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 the hardware manual that accompanies your system.

AUTHOR

ALoadAFile() was developed by HP.

Museum

Related Articles