ACreateSBucket(3X)

NAME

ACreateSBucket − create an empty sound bucket and return a pointer to it

SYNOPSIS

#include <Alib.h> SBucket ∗
ACreateSBucket (

Audio ∗ audio,

AudioAttrMask attr_mask,

AudioAttributes ∗ audio_attributes,

long ∗ status_return );

DESCRIPTION

ACreateSBucket() creates an empty sound bucket to receive recorded data, associates it with audio attributes, and returns the pointer to it.

This call will malloc the space for the sound bucket including the attributes structure.

The calling program may choose to specify some (or all) of the attributes. If no attributes are specified, set the attr_mask to 0 and send a NULL pointer for audio_attributes. A sound bucket will be created using best_audio_attr from the Audio structure.

Otherwise, the calling program may specify any combination of attributes that it wishes. In this case the attributes should be specified in audio_attributes and the corresponding mask bit should be set to 1. The Audio Library will fill in any remaining attributes based on best_audio_attr when it copies the attributes structure to the one that will be associated with the sound bucket.

audio specifies the Audio structure associated with this connection.

attr_mask specifies which of the audio attributes in the audio_attributes structure have been supplied by the user (mask bit set to 1). The mask is the bitwise inclusive OR of one or more of the mask values listed in the Structures section.

audio_attributes is the structure containing the audio type ( ATSampled ) and attributes. Audio type must be set.

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, ACreateSBucket() returns a pointer to a sound bucket.

STRUCTURES

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

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

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

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

EXAMPLE

The following example creates sound bucket sb and selects "bit per sample" and duration attributes.

SBucket ∗ sb; /∗ sound bucket ∗/

Audio ∗ audio; /∗ audio connection ∗/

AudioAttrMask amask; /∗ audio attributes mask ∗/

AudioAttributes ∗ attr; /∗ audio attributes ∗/

long status; /∗ error status ∗/
.
.
.

/∗ create sound bucket ∗/

amask = (ASAFBitPerSample | ASAFDuration);

sb = ACreateSBucket(audio, amask, attr, &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

ACreateSBucket() was developed by HP.

Museum

Related Articles