ASaveSBucket(3X) — Series 700 Only

NAME

ASaveSBucket − write sound bucket data into file with data conversion

SYNOPSIS

#include <audio/Alib.h>

void ASaveSBucket(

Audio *audio,
SBucket *sb,
char *pathname,
AFileFormat file_format,
AudioAttrMask attr_mask,
AudioAttributes *target_attributes,
ATime *offset,
AWriteMode mode,
long *status_return

);

DESCRIPTION

ASaveSBucket() writes the data in sb into the file specified by pathname after making conversions according to the specified attributes.

ARecordAData() does not block until the record operation is complete, so calling ASaveSBucket() immediately after ARecordAData() usually results in an error. To avoid the error, the application program can set up its own wait loop, or wait on a transaction-stopped or transaction-completed event. See the program /usr/audio/examples/recorder.c for an example of waiting either for a transaction-stopped event or for the user to terminate the record operation by pressing [Return].

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

audio is the audio structure associated with this connection.

sb is the sound bucket that contains the audio data and associated attributes.

pathname specifies the file to receive the data. If the file does not exist, it is created.

file_format specifies the file format to use for the write. If this parameter is not set to a valid enumerated value, an error is returned.

If this parameter is set to AFFUnknown, the conversion utility checks for an extension on pathname. Extensions can be appended to the filename as follows:

name.sampling_rate.file_type.

Valid file type extensions are:

.u Mulaw

.al Alaw

.au Sun (NeXT)

.wav Riff

.snd NeXT

.l16 Linear16

.l8 Linear8

.lo8 Linear8Offset

If no recognizable extension exists and pathname is an existing file, the utility checks the header on the existing file. If there is no determinable file format, an error is returned; there is no default.

If this parameter specifies a different format than the one indicated by an existing file in pathname, (unless mode is AWMTruncateAppend and offset is 0), an error is returned.

attr_mask specifies the audio attributes to associate with the data written to the file; conversion occurs where necessary. The mask is a bitwise inclusive OR of the values defined in AudioAttrMask. This mask is cleared if target_attributes is set to NULL.

When a mask bit is set to 0 and pathname is an existing file, the conversion utility checks the existing file type in the file header and uses a value that is compatible with it.

When a mask bit is set to 0 and pathname is not an existing file, the conversion utility checks the file type indicated by the pathname extension, if any, and uses a value that is compatible with it. If no value can be determined, the sound bucket value for the attribute is used.

When a mask bit is set to 1 and pathname is not an existing file, the specified attribute is checked for compatibility with the existing file. An error is returned if there is a discrepancy.

When a mask bit is set to 1 and a file does not exist in pathname, the specified attribute is used.

NOTES: If ASDurationMask is set, the sound bucket data is truncated or padded with zeros to match the length specified in audio_attributes.sampled_attr.duration.

If ASSamplingRateMask is set, it is used without checking the file name extension. If sampling_rate is not specified, the file name is checked for an extension. Sampling rate attributes can be specified in a filename extension as follows:

name.sampling_rate.file_type

Valid sampling rate extensions are .n and .nk where .nk is typically 8k to 22k.

target_attributes specifies the attributes that are affected by the mask. If set to NULL, attr_mask is cleared and attributes are determined according to compatibility with pathname and sb (see attr_mask). Audio type must be set (separate from the mask).

offset specifies where to begin writing in the destination file, given in ATimeType units (ATTSamples, ATTMilliSeconds, or ATTFullLength) from the beginning of the audio data, excluding the header.

If pathname is not an existing file and offset is not 0, the new file is padded with zeros up to the offset.

If pathname is an existing file and offset is greater than the length of the audio data, zeros are appended to the audio data until its length is equal to offset.

mode specifies how the data should be written into the file:

AWMOverWrite specifies that data from the sound bucket sb overwrites the data in pathname starting at offset. Data that precedes or follows the overwritten region remains unchanged. If necessary, the length of the file is increased to accommodate the new data.

AWMTruncateAppend specifies that the data in pathname is truncated at offset and the write begins at that point. If necessary, the length of the file is increased or decreased to accommodate the new data.

AWMInsert specifies that data from the sound bucket sb is inserted in the file pathname starting at offset. The length of the file is increased to accommodate the new data.

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

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

13 AEBadAttribute

14 AEBadOffset

16 AECantDetermineFormat

20 AEBadSoundBucket

EXAMPLES

The following example copies the data from sound bucket sb to existing file /myhome/a_dir/a_file, starting at offset 1668. The file format and audio attributes of the existing file are to be used, so file_fmt is set to AFFUnknown, NULL is passed for audio attributes, and the attribute mask is set to 0.

The mode is set to AWMOverwrite so that data that precedes or follows the overwrite region will not be affected. If necessary, the length of the file will be increased to accommodate the new data.

Audio *audio; /* audio connection */
SBucket *sb; /* sound bucket */
AFileFormat file_fmt; /* file format */
AudioAttrMask a_mask; /* audio attributes mask */
ATime startoff; /* start offset */
AWriteMode mode; /* write mode */
long status; /* error status */
.
.
.
/* save sound bucket data */
staticchara_name[] = {"/myhome/a_dir/a_file"};
file_fmt = AFFUnknown;
a_mask = 0;
startoff.type = ATTSamples;
startoff.u.samples = 1668;
mode = AWMOverwrite; /* overwrite without truncate */
ASaveSBucket(audio, sb, a_name, file_fmt, a_mask, NULL, &startoff,
mode, &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

ASaveSBucket() was developed by HP.

Museum

Related Articles