[ Previous | Next | Contents | Glossary | Home | Search ]
Ultimedia Services Version 2 for AIX: Programmer's Guide and Reference

UMSAudioPlayer Object

The UMSAudioPlayer object provides methods to play and record audio files using the generic base classes of UMSAudioFile and UMSAudioDevice. This enables the UMSAudioPlayer object to support new file formats and new audio devices simply by the availability of new implementations of the UMSAudioFile and UMSAudioDevice base classes.

UMSAudioFile object implementations are provided for WAV, SND, and RAW file formats. UMSAudioDevice implementations support the various audio devices used across supported systems.

To learn more about the UMSAudioPlayer object, see:

For introductory information, see Media Handler Objects.

Enumeration Lists

To avoid name collision on defines, integer values have been captured as enumerated lists. The set of valid values from an enumerated list can vary with the application. The detailed method descriptions describe the valid or possible values for the specific use. The enumerated lists that are defined for this object include:

enum ReturnCode {
   Success,
   InternalError,
   InvalidState,
   NoPlayer,
   NoAlias,
   NoDevice,
   DeviceNotAvail,
   NoDeviceObj,
   DeviceError,
   NoFile,
   NoFileObj,
   NoFileName,
   FileError,
   NoRecord,
   OutOfRange,
   InvalidCuepoint,
   Duplicate,
   CueLimit,
   MemoryError,
   InvalidParam,
   InvalidAudioParams,
   FileDifferent,
   NoEventPending
   NotSupported
   SettingsChanged
   Failure
   }
enum Connector {
   LineIn,
   HighGainMic,
   LowGainMic
   OtherConnector
   };
enum Mode {
   Mono,
   Stereo
   OtherMode
   };
enum RecordFlag {
   Insert,
   Overwrite,
   Append,
   New
   };
enum State {
   NotReady,
   Ready,
   Playing,
   Recording, 
   PausePlay, 
   PauseRecord 
   Closing
   };
enum OnOff {
   Off, 
   On
   };
enum SetClear {
   Clear, 
   Set
   };
enum CueType {
   PlayCue, 
   RecordCue 
   };
enum AudioFormat {
   PCM, 
   MU_LAW, 
   A_LAW 
   OtherAudioFormat
   };
enum BitsPerSample {
   Eight, 
   Sixteen 
   OtherBitsPerSample
   };
enum TimeFormat {
   Msecs, 
   Bytes, 
   Samples 
   };
enum SourceType {
   LocalFile 
   };
enum NumberFormat {
   Unsigned, 
   Signed, 
   TwosComplement 
   };
enum ByteOrder {
   MSBFirst, 
   LSBFirst 
   };
enum EventType {
   Error, 
   PlayComplete, 
   CuePoint, 
   PositionAdvise 
   };

Defined Constants

The audio player defines the following constants: 

const unsigned long PLAY_COMPLETE = 0x00000001;
const unsigned long CUE_POINT = 0x00000002;
const unsigned long POSITION_ADVISE = 0x00000004;
const unsigned long PLAYER_ERROR = 0x80000000;

Defined Structures

The following structures are defined for the UMSAudioPlayer object: 

struct EventData {
        enum EventType type;     /* also directly returned */
        ulong current_position;  /* uses current time format */
       ulong specific;    /* error number or cuepoint tag */
        };

State Diagram

The player has five possible states:

NotReady Player is not ready because it either does not have a defined audio device (as provided by the open method) or it does not have a file name (as provided by the load method).
Ready Player has both a device and file name but has not been cued for either play or record.
Play Player is actively playing.
Record Player is actively recording.
Pause Player is cued for play or record.

The following table illustrates the UMSAudioPlayer state diagram.

Audio Player States
Not Ready Ready Play Record Pause Play/ Pause Record
load Ready1 Ready Ready Ready Ready
open Ready1 Ready Ready Ready Pause Play/Record
close Not Ready Not Ready Not Ready Not Ready Not Ready
cue- Play Error Pause Play Pause Play Pause Play Pause Play
cue- Record Error Pause Record Pause Record Pause Record Pause Record
play Error Play Play Play Play
record Error Record2 Record Record Record Record
seek Not Ready Ready Ready Ready Ready
pause Error Error Pause Play Pause Record Pause Play/Record
resume Error Error Play Record Play/Record
stop Not Ready Ready Ready Ready Ready
1 open and load are methods that may fulfill the last requirement to become Ready. 2 record can occur if the audio device has been opened. It is not necessary to have a file loaded. If the audio device has not been opened, an error condition exists.

For introductory information, see Media Handler Objects.

Method Descriptions

ReturnCode close()

Description

Closes the previously specified audio device. The UMSAudioPlayer becomes NotReady. This method does not affect the state or location of the media file specified with the load method. Any temporary file that was being used for record is closed and removed.

Return Values

Success

Failure

NoPlayer A process or thread of the player object has terminated.

ReturnCode cue(in CueType type)

Description

This method cues the media for play or record as specified by the type argument. The player enters a Pause state.

Arguments
in CueType type Specifies PlayCue or RecordCue.
Return Values

Success

InvalidState Player cannot accept cue from current state.
DeviceError A device error occurred.
MemoryError Error allocating memory.
NoFile Unable to create a temporary file or file object.
InvalidAudioParams The audio parameter combination is invalid.
InvalidParam An invalid parameter was passed to the method.
FileError Error reading from a file.
NoPlayer A process or thread of the player object has terminated.

boolean event_pending()

Description

This method checks the event queue to determine if any events are ready for processing. If an event is ready, True is returned; otherwise, False is returned.

Return Values
True Returns True if an event is available.
False Returns False if no events are in the event queue.

long get_balance()

Description

This method returns the audio balance.

Return Values

The balance as an integer from -100 to 100.

ByteOrder get_byte_order()

Description

This method returns the byte-order setting that is currently in effect.

Return Values
MSBFirst Most-significant byte first.
LSBFirst Least-significant byte first.

unsigned long get_current_position()

Description

This method queries the current position of the media; it returns the current position in the current time format setting.

Return Values

The current position in the time format is returned. If there is no current position (a file is not loaded), 0 is returned.

EventType get_event(out EventData *event_data)

Description

Returns the next event in the space provided by event_data. It blocks if no event is available. The event type is available in the event data structure and is also returned.

If an event is not available and a play is not in progress, an event type error is returned. This prevents the possibility of indefinitely blocking.

Error event types return a ReturnCode in the specific field of the EventData indicating what the error is. These have possible values of:

InternalError An error occurred in the player. The player stops all processing.
DeviceError An error occurred relating the physical audio device. The device is closed and the player enters the NotReady state.
FileError An error occurred relating to the file system. The files are closed and the player enters the NotReady state.
NoEventPending Returned as response to get_event when no events exist in the event queue and future events are not expected.
Arguments
out EventData *event_data Address of an EventData structure to hold the specific event information.

struct EventData { 
        EventType type;          /* also directly returned */
        ulong current_position;  /* uses current time format */
        ulong specific;          /* error number or cuepoint tag */
        };
Return Values
A value from Event Type enumeration list.

long get_event_handle()

Description

This method returns an event handle. The application can use this handle as a file descriptor on which to select and thereby query or block on events. If the file descriptor is readable, an event is queued.

Return Values

The return value is a nonzero handle number for success and zero (0) for failure.

unsigned long get_event_mask()

Description

This method returns the current event mask.

Return Values

Current event mask.

unsigned long get_length()

Description

This method returns the length of the currently loaded audio data.

Return Values

Returns the length of the audio data in the current time format.

OnOff get_monitoring()

Description

This method returns the current setting for monitoring.

Return Values
On Monitoring is turned on.
Off Monitoring is turned off.

NumberFormat get_number_format()

Description

This method returns the number format setting that is currently in effect.

Return Values
TwosComplement
Signed
Unsigned

OnOff get_repeat()

Description

This method returns the current setting for the repeat flag.

Return Values
On The repeat flag is currently turned on.
Off The repeat flag is currently turned off.

long get_samples_second()

Description

This method returns the samples per second that are in effect on the next play, record, or cue commands.

State get_state()

Description

This method returns the the current state of the player.

Return Values
Ready
NotReady
Playing
Recording
PausePlay
PauseRecord

TimeFormat get_time_format()

Description

This method returns the current setting for the time format, which defines the interpretation of time arguments.

Return Values
Msecs Time format in milliseconds.

Bytes

Samples

long get_volume()

Description

This method returns the audio volume setting.

Return Values
Channel volume as an integer from 0 to 100.

ReturnCode info(inout string fname, inout string device)

Description

This method returns the current loaded file name and opened device alias name as NULL terminated strings. The pointers are passed by the caller and must have space to hold the name strings. If the device or file name has not been defined, a NULL is returned at the pointer location.

Arguments
inout string fname The path name of the currently loaded file is returned as a string.
inout string device The resultant audio device alias is returned as a string. This is the resultant alias which achieved a match in the configuration file at device-creation time.
Return Values

Success

Failure

NoPlayer A process or thread of the player object has terminated.

ReturnCode load(in string path, in SourceType source, in string obj_name)

Description

This method specifies the pathname of the file to be opened in the path parameter. The UMSAudioPlayer uses an instance of the UMSAudioFile base class to access audio files. The specific implementation of the UMSAudioFile used is transparent to the UMSAudioPlayer. The methods of the UMSAudioFileMClass object are used to instantiate the specific object. If the string parameter file_alias is NULL, the make_by_pathname method of UMSAudioFileMClass is used to construct the specific object based on detection of the appropriate file type. If the string parameter is not NULL, the make_by_alias method of UMSAudioFileMClass is used to construct the specific object. This allows the application to specify the file types of new files, override file type detection and request instantiation of a specific object via a UMSAudioFile file_type_alias. A successful load clears the existing cuepoints and displaces a previously opened file.

Arguments
in string path Specifies the path name of the file to open.
in SourceType source Specifies the file type. Only local file system is supported.
in string obj_name If not NULL, specifies a file type alias for construction of the UMSAudioFile object used by the player.
Return Values

Success

Failure

NoAlias The alias does not exist in the config object.
NoFile File does not exist. The file name is saved and used with the save method.
NoFileObj The object specified by file_alias cannot be created.
FileError File could not be accessed.
NoPlayer A process or thread of the player object has terminated.

ReturnCode open(in string device)

Description

This method uses an alias to specify which audio device should be used by the UMSAudioPlayer. The configuration file is accessed to relate the alias and device name. If an open is issued when a device is already open, the open device is closed and the new device is opened.

Arguments
in string device The audio device alias specifying the desired audio device. Device aliases are mapped in the configuration file to real devices. This allows you to map applications to devices and establish device characteristics independently for each application if desired. Applications should use a device alias of the form: 
Audio.<application_class>.<application_name>.<usage_of_device>

In the alias search, this name is successively truncated until a match in the configuration file is found. If you have not specifically identified any of the intermediate aliases the search resolves to the base Audio alias.

Return Values

Success

Failure

NoAlias The alias name does not exist in the configuration file.
NoDevice The device specified in the configuration file does not exist.
DeviceError The device is not available.
NoDeviceObj Unable to create an Audio Device object.
NoPlayer A process or thread of the player object has terminated.

ReturnCode pause()

Description

This method suspends playback or record. The device and file remain in an open state at the current location and cued for play or record. Play or record can be resumed with the resume, play, or record method.

Return Values

Success

InvalidState Player cannot be paused from this state.
DeviceError Unable to complete the command.
NoPlayer A process or thread of the player object has terminated.

ReturnCode play()

Description

This method is used to start playback from the current position to the end of the file. When the end of file is reached a PlayComplete event is issued. If repeat is not set on, the Ready state is entered at completion.

If repeat is set on, play continues with successive playing of the file (from beginning to end) with a PlayComplete event each time the end of the file is reached until play is explicitly stopped by a command (such as pause or stop).

An error is returned if the audio settings of the audio device do not match the currently opened files audio settings.

Return Values

Success

InvalidState Invalid state to accept play.
DeviceNotAvail The audio device has become unavailable.
DeviceError Audio device not responding or failed command.
MemoryError Error allocating or freeing memory.
InvalidAudioParams The combination of audio parameters is invalid.
NoPlayer A process or thread of the player object has terminated.

ReturnCode play_to(in unsigned long to)

Description

This method plays from the current position and continues until the to position is reached, at which time a PlayComplete event is returned. If repeat is not set on, the Ready state is entered at completion.

If repeat is set on, play continues with successive playing of the segment (from the location at which play_to was issued to the to location) generating a PlayComplete event each time the to location is reached until play is explicitly stopped by a command (such as pause or stop).

If the to position is beyond the end of the file, the command is rejected with an OutOfRange return code.

Arguments
in unsigned long to Specifies the file location in units of the current time format to play to.
Return Values

Success

OutOfRange The to position specified is out of range.
InvalidState Invalid state to accept play.
DeviceNotAvail The audio device has become unavailable.
DeviceError Audio device not responding or failed command.
MemoryError Error allocating or freeing memory.
InvalidAudioParam The combination of audio parameters is invalid.
NoPlayer A process or thread of the player object has terminated.

ReturnCode record(in unsigned long from, in unsigned long to, in RecordFlag flags)

Description

This method starts recording from the audio device. How the player performs the record depends on the RecordFlag parameter and whether a file is currently loaded as follows:

No File loaded The RecordFlags are ignored and a new file containing the audio data is created.
File is loaded and RecordFlag is Insert The player records the audio data and, upon completion of the record operation, combines the loaded file's audio data with the recorded data, by inserting the new audio data into the existing data at the from parameters position.
File loaded and RecordFlag is Overwrite The player records the audio data and, upon completion of the record operation, combines the current audio data with the recorded data by inserting the new data into the existing data at the from parameter position, discarding the existing audio data between the from and to position, and appending the remainder of the existing audio data.
File loaded and RecordFlag is Append The player records the audio data and appends it to the existing data.
File loaded and RecordFlag is New The existing audio data is discarded and the new data is recorded.
Arguments
in unsigned long from Specifies the location in current file to begin recording.
in unsigned long to Used only with the Overwrite flag. The data between from and to is replaced by the new recording.
in RecordFlag flags Specifies the record mode. Valid values are Insert, Overwrite, Append, New
Return Values
Success Recording has started.
InvalidState Player is in an invalid state for record (No device).
DeviceNotAvail Audio device has not been opened or the player no longer owns the resource.
DeviceError Commands to the audio device failed.
MemoryError Unable to allocate or free memory.
FileError Error creating the temporary files or file objects.
InvalidAudioParam The currently set audio parameter combination is invalid.
NoPlayer A process or thread of the player object has terminated.

ReturnCode resume()

Description

This method resumes playing or recording from a paused state. If already playing or recording, Success is returned and the command is ignored.

Return Values

Success

InvalidState Player is not in the Pause state.
DeviceError Unable to complete the command.
NoPlayer A process or thread of the player object has terminated.

ReturnCode save(in string filename, in SourceType source, in string obj_name)

Description

This method is valid only after a record operation and is used to create the newly requested file. This can be a new file containing only the newly recorded data or it can be the existing file with the new data inserted, appended, or overwritten in the currently loaded file.

Arguments
in string filename This is the path name of the file to write.
in SourceType source Indicates what the source device is. Currently the only setting is LocalFile.
in string obj_name If not NULL, this is the alias name of an AudioFile object to be used to write the file.
Return Values
Success Save completed.
MemoryError Error allocating or freeing memory.
FileError An error occurred in saving the file.
NoFileObj Unable to create the file object.
NoFileName A filename has not been specified.
NoRecord Nothing has been recorded.
NoAlias Unable to resolve the file alias.
NoPlayer A process or thread of the player object has terminated.

ReturnCode seek(in unsigned long location)

Description

This method changes the current media position, within the audio data, to the position that is indicated by the location argument. The player is returned to the Ready state.

Arguments
in unsigned long location Target of the seek location in the current time format.
Return Values

Success

OutOfRange Time location is out of range.
DeviceError Device failed a command.
FileError Error seeking into the file.
MemoryError Unable to allocate memory.
NoPlayer A process or thread of the player object has terminated.

ReturnCode set_balance(in long level, in unsigned long time)

Description

This method changes the level of audio in each channel as a percentage of the maximum audio. If the integer in level field is greater than 100, 100 is used as the value. The time argument permits fade left and fade right capability but is currently not supported.

Arguments
in long level An integer from -100 to 100. Zero is the balance center point.
in unsigned long time This field sets the delay time over which the balance is changed. The time is interpreted based on the current setting for the time format.
Return Values

Success

OutOfRange A parameter was out of range.
DeviceError A device error occurred.
NoPlayer A process or thread of the player object has terminated.

ReturnCode set_byte_order(in ByteOrder order)

Description

This method sets the byte-order interpretation of the audio data. If the currently loaded audio data and the new byte-order setting are different, the warning FileDifferent is returned.

Arguments
in ByteOrder order Specifies the byte-order of the data as:
MSBFirst
LSBFirst
Return Values

Success

InvalidParam Unknown byte-order passed to method.
FileDifferent File and device settings are different.
NoPlayer A process or thread of the player object has terminated.

ReturnCode set_cuepoint(in SetClear flag, in unsigned long cue)

Description

This method sets a cuepoint for playback. This is specified as a time offset from the beginning of the file. When the cuepoint is reached, a Cuepoint event is generated if the event mask has been set to enable cuepoint events. The maximum number of cuepoints allowed is 20.

Arguments
in SetClear flag Indicates whether a cuepoint is being set or removed. The Set value sets a cuepoint; the Clear value removes a cuepoint.
in unsigned long cue Specifies the cuepoint location.
Return Values

Success

InvalidParam A parameter is not valid.
CueLimit Maximum number of cuepoints is exceeded.
OutOfRange Position is out of range.
Duplicate Cuepoint has been set before.
InvalidCuepoint Tried to remove a cuepoint that was not set.
InvalidState No audio data currently loaded.
NoPlayer A process or thread of the player object has terminated.

ReturnCode set_event_mask(in unsigned long event_mask)

Description

This allows the setting of a mask used to enable and disable the issuing of maskable events. The default is for these bits to be 0 and masked. The PlayComplete and Error events are not maskable and are always sent.

Arguments
in unsigned long event_mask An ORed set of these bits. Valid values are CUE_POINT and POSITION_ADVISE.
Return Values

Success

NoPlayer A process or thread of the player object has terminated.

ReturnCode set_monitoring(in OnOff monitor)

Description

This method turns monitoring of a recording on or off. If a device error occurs, the device is closed and the player enters the NotReady state.

Arguments
in OnOff monitor Specifies whether output of recorded sound is requested during recording.
Return Values

Success

InvalidParam Invalid parameter passed to method.
DeviceError A device error occurred.
NoPlayer A process or thread of the player object has terminated.

ReturnCode set_number_format(in NumberFormat numb_fmt)

Description

This method sets the audio player's interpretation of what type of numbers make up the audio data. If the currently loaded audio data's number format and the audio players new setting are different, the warning FileDifferent is returned.

Arguments
in NumberFormat numb_fmt Specifies whether the audio data is to be interpreted as Signed, Unsigned, or TwosComplement data.
Return Values

Success

InvalidParam Unknown number format.
FileDifferent The currently loaded audio data and the new setting are different.
NoPlayer A process or thread of the player object has terminated.

ReturnCode set_position_advise(in unsigned long interval)

Description

This method sets the position-change notification frequency. Only one frequency can be set. If the value of interval is 0 (zero) or less, it turns off position advise. The player uses the most current definition of interval. PositionAdvise events are sent at the given interval if that event type is enabled.

Arguments
in unsigned long interval Position-advise notification interval in the current time format.
Return Values

Success

OutOfRange Time interval is too small or too large.
DeviceError Unable to get the audio device current position.
NoPlayer A process or thread of the player object has terminated.

ReturnCode set_repeat(in OnOff repeat)

Description

This method turns on and off the repeat flag. If the flag is on then the play method causes it to repeat from the beginning of the file when encountering the end of file. The play_to method repeats from the current position when play_to is called to the end position passed into the play_to method. Repeat can take effect on the next or current play.

During play, if repeat is set a PlayComplete event is generated as each repetition is completed.

Arguments
in OnOff repeat Specifies that repeat should be turned ON or OFF.
Return Values

Success

InvalidParam

NoPlayer A process or thread of the player object has terminated.

long set_samples_second(in long samples)

Description

This method sets the sample rate for recording. If you are recording into a currently loaded file, then you should not set the sample rate. Only set the sample rate when recording to a new file. A subsequent play or record returns an error if the setting is not valid with other audio settings.

Arguments
in long samples The number of samples expected per second.
Return Values

The actual number of samples per second that is used. This is typically the same as that passed in, but could instead be the closest match, as constrained by the implementation. You should compare this to the desired rate and notice any significant difference. If an error occurs, the method returns -1.

ReturnCode set_time_format(in TimeFormat fmt)

Description

This method sets how Time values are interpreted. Time is a long that can be interpreted in any of the defined units to describe an offset within the audio data. For stereo data, a sample includes the data for both the left and right channel.

Arguments
in TimeFormat fmt Defines how the Time arguments are to be be interpreted. Valid values are Msecs, Bytes, or Samples
Return Values
Success The time format has successfully been set.
InvalidParam The time format specified is invalid.
NoPlayer A process or thread of the player object has terminated.

ReturnCode set_volume(in long level, in unsigned long time)

Description

This method changes the level of audio as a percentage of the maximum audio. If the integer in level field is greater than 100, then 100 is used as the volume. The time argument is provided to permit fade in and fade out capability but is not currently supported.

Arguments
in long level Specifies the requested volume level as a value from 0 to 100
in unsigned long time Specifies the time delay over which the volume adjustment is made. (Only a value of 0 is supported at this time.)
Return Values

Success

OutOfRange A parameter was out of range.
DeviceError A device error occurred.
NoPlayer A process or thread of the player object has terminated.

ReturnCode stop()

Description

This method exits the play, record, or pause state and returns the audio player to the ready state.

Return Values

Success

DeviceError Unable to complete the command.
InvalidState The player is in an invalid state to accept stop.
MemoryError Unable to allocate memory.
FileError Error reading, writing, or creating a file.
NoPlayer A process or thread of the player object has terminated.

ReturnCode set_bits_per_sample(in long bits)

Description

This method sets the number of bits-per-sample.

Arguments
in long bits The number of bits in a sample.
Return Values

Success

InvalidParam

FileDifferent

NoPlayer A process or thread of the player object has terminated.

long get_bits_per_sample()

Description

The current setting of bits_per_sample is returned.

Return Values

The current setting of bits_per_sample.

ReturnCode set_number_of_channels(in long channels)

Description

This method sets the number of audio channels for play or record. Mono is specified with a value of 1 and stereo is specified with a value of 2. This value should not be modified when a play or record is in progress.

Arguments
in long channels The number of channels for play or record. A value of 1 specifies mono and a value of 2 specifies stereo.
Return Values

Success

Failure

InvalidParam

long get_number_of_channels()

Description

The current setting of number_of_channels is returned.

Return Values

The value of the current setting for number of channels.

ReturnCode set_audio_format_type(in string fmt)

Description

This method sets the audio format that is to be used for play or record. Each specific audio device implementation advertises the formats that it supports as properties under its formats_alias in the configuration file. All devices are required to minimally support PCM, A-law, and mu-law. The setting should not be modified when a play or record is active.

Arguments
in string fmt A string specifying the desired audio format.
Return Values

Success

Failure

InvalidParam

NoPlayer A process or thread of the player object has terminated.

ReturnCode get_audio_format_type(out string fmt)

Description

The current format setting is returned as a string. The value should not be modified when a play or record is active.

Arguments
out string fmt The string value representing the current audio setting.
Return Values

Success

Failure

NoPlayer A process or thread of the player object has terminated.

ReturnCode enable_input(in string input, inout long left_gain, inout long right_gain)

Description

This method enables a given input connector and sets the left and right gain on the input if the device supports individual gain. This method can be called multiple times to enable several inputs. If the device does not support multiple inputs then the last valid input specified takes effect on the next initialization. The actual gain value used for each channel is returned in the associated parameter. The settings should not be modified during an active play or record. Specific devices advertise their input and output connection capability in the configuration file.

Arguments
in string input The string specifying the desired input.
inout long left_gain The desired gain value is passed in and the resulting gain is passed out.
inout long right_gain The desired gain value is passed in and the resulting gain is passed out.
Return Values

Success

Failure

InvalidParam

SettingsChanged

NoPlayer A process or thread of the player object has terminated.

ReturnCode disable_input(in string input)

Description

This method disables a previously enabled input. The input settings should not be modified during an active play or record.

Arguments
in string input The input connection to be disabled.
Return Values

Success

Failure

InvalidParam

SettingsChanged

NoPlayer A process or thread of the player object has terminated.

ReturnCode input_enabled(in string input, inout boolean enabled)

Description

This method returns a Boolean into the enabled parameter which states whether the input is currently enabled or not.

Arguments
in string input The input connection being queried.
inout boolean enabled Returned as True if the input is enabled.
Return Values

Success

Failure

InvalidParam

NoPlayer A process or thread of the player object has terminated.

ReturnCode enable_output(in string output, inout long left_gain, inout long right_gain)

Description

This method enables a given output connector and sets the left and right gain on the output if the device supports individual gain. This method can be called multiple times to enable several outputs. If the device does not support multiple inputs then the last valid output specified takes effect on the next initialization. The actual gain value used for each channel is returned in the associated parameter. The settings should not be modified during an active play or record. Specific devices advertise their input and output connection capability in the configuration file.

Arguments
in string output The string specifying the desired output.
inout long left_gain The desired gain value is passed in and the resulting gain is passed out.
inout long right_gain The desired gain value is passed in and the resulting gain is passed out.
Return Values

Success

Failure

InvalidParam

SettingsChanged

NoPlayer A process or thread of the player object has terminated.

ReturnCode disable_output(in string output)

Description

This method disables a previously enabled output. The settings should not be modified during an active play or record.

Arguments
in string output The output connection to be disabled.
Return Values

Success

Failure

InvalidParam

SettingsChanged

NoPlayer A process or thread of the player object has terminated.

ReturnCode output_enabled(in string output, inout boolean enabled)

Description

This method returns a Boolean into the enabled parameter which states whether the output is currently enabled or not.

Arguments
in string output The output connection being queried.
inout boolean enabled Returned as True if the output is enabled.
Return Values

Success

Failure

InvalidParam

NoPlayer A process or thread of the player object has terminated.

ReturnCode enable_audio_master_settings()

Description

This method is used in the presentation of device specific capabilities that are shared for all invocations of the device. An example of this is configuring the pass through of CD-ROM audio data. If you enable master setting mode, you share in this configuration of the device. If you choose not to participate in the master settings, the you must try to disable master_settings mode. Each device can enforce rules based on current state and as to when the master_settings mode can be entered or exited. Some devices cannot support master setting at all, in which case a NotSupported ReturnCode is returned. Some methods on a device cannot be available on a device if they conflict with the master_settings mode. An example is selection of input and output connections which can have been established via the master setting mode.

Return Values

Success

Failure

NotSupported

NoPlayer A process or thread of the player object has terminated.

ReturnCode disable_audio_master_settings()

Description

This method is used to disable the master setting mode on the audio device in use. If the method is not supported by the audio device in use a NotSupported value is returned. If the device cannot be acquired with master setting disabled, a value of Failure is returned.

Return Values

Success

Failure

NotSupported

NoPlayer A process or thread of the player object has terminated.

ReturnCode get_audio_master_settings(inout boolean enabled)

Description

Returns a Boolean value indicating whether master settings state is enabled.

Arguments
inout boolean enabled A Boolean is returned indicating whether master settings are enabled or disabled for the audio device.
Return Values

Success

Failure

NotSupported

NoPlayer A process or thread of the player object has terminated.

ReturnCode get_audio_device_class(out string device_class)

Description

This method returns a string representing the device class for the currently opened device. If you constructed the object using the metaclass, the specific device class can be unknown.

Arguments
out string device_class A string is returned containing the specific AudioDevice class.
Return Values

Success

Failure

NoPlayer A process or thread of the player object has terminated.

ReturnCode get_audio_device_pathname(out string device_pathname)

Description

This method returns a string which contains the full path of the device that this object is currently using, such as /dev/acpa0.

Arguments
out string device_pathname A string is returned containing the device path name.
Return Values

Success

Failure

NoPlayer A process or thread of the player object has terminated.

ReturnCode get_audio_device_master_exec(out string exec_pathname)

Description

This method returns the path to an executable that, when executed, provides an interface that the you can use to adjust the audio device's master settings. This is most likely a graphical user interface to the device specific master settings available for the device. This executable is advertised in the configuration file and, therefore, can be replaced by any executable desired.

Arguments
out string exec_pathname The path name to the executable registered in the configuration file for the specific device is returned.
Return Values

Success

Failure

NotSupported

NoPlayer A process or thread of the player object has terminated.

ReturnCode get_audio_device_inout_alias(out string inputs_alias, out string outputs_alias)

Description

This method returns two strings that contain the aliases for the devices inputs and outputs. These strings can be used to query the configuration file and determine the set of input and output connections that are supported for the device.

Arguments
out string inputs_alias The advertised inputs_alias for the device.
out string outputs_alias The advertised outputs_alias for the device.
Return Values

Success

Failure

MemoryError

NoPlayer A process or thread of the player object has terminated.

For introductory information, see Media Handler Objects.

[ Previous | Next | Contents | Glossary | Home | Search ]