ASaveSBucket(3X)

NAME

ASaveSBucket − write sound bucket data into file with data conversion

SYNOPSIS

#include <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.

Because ARecordAData() does not block until the record operation is complete, calling ASaveSBucket() immediately after ARecordAData() usually results in an error. To avoid the error, the application program may set up its own wait loop, or wait on a transaction-stopped or transaction-completed event.

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.

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

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 from 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 one or more of the mask values listed in the Structures section.

The 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 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; there is no check against the file name extension. If sampling_rate is not specified, the file name is checked for an extension. Sampling rate attributes may 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. The value is returned 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. One of the following values:

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 this parameter is passed in as a NULL pointer. If status_return is set to NULL, Alib will do the error handling.

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;
/* Enumerated type and structure for time specification.
*/
typedef enum _ATimeType {
    ATTSamples,
    ATTMilliSeconds,
    ATTFullLength
} ATimeType;
typedef struct _ATime {
    ATimeType                   type;
    union {
        unsigned long           samples;
        unsigned long           milliseconds;
    } u;
} ATime;

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.

1 AESystemCall The system could not open the file for read or write. Check for a permissions problem or pathname problem.

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 data format specified in the target_attributes structure is either not appropriate for the file format or is not one of the supported data formats.

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

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 The Audio Library tried to allocate space but failed.

20 AEBadSoundBucket The sound bucket parameter does not point to a valid sound bucket.

EXAMPLE

The following example copies the data from sound bucket sb to a file that already exists, /myhome/a_dir/a_file, starting at offset 1668. The file format and audio attributes of the existing file will be used, so we set file_fmt to AFFUnknown, pass NULL for audio attributes, and set the attribute mask to 0.

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

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          */
static char a_name[] = {"/myhome/a_dir/a_file"};
.
.
.
/* save sound bucket data */
  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);"

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

ASaveSBucket() was developed by HP.

Museum

Related Articles