UMSAudioDeviceMClass Class

Ultimedia Services Version 2 for AIX: Programmer's Guide and Reference

UMSAudioDeviceMClass Class

The UMSAudioDeviceMClass class is a metaclass that defines the class methods for children of the UMSAudioDevice base class. In particular, UMSAudioDeviceMClass specifies creation methods for UMSAudioDevice objects.

The metaclass provides a method to construct a specific audio device based on an application-specified audio alias and data in the configuration file. This allows an application to be ported to a new audio device merely by altering the data under the audio alias in the configuration file. This is the preferred construction technique for applications.

To learn more about the UMSAudioDeviceMClass class, see:

For introductory information, see MetaClass Objects.

Enumeration Lists

To avoid name collision on defines, integer values have been captured as enumeration 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 are listed as follows:

enum ReturnCode {
   Success, 
   Failure, 
   FatalUMSError, 
   NoConfigObject,
   AliasNotFound, 
   PropertyNotFound,
   InvalidClassName, 
   NotAChild, 
   DeviceNotAvail,
   MemoryError
   };

Method Descriptions

UMSAudioDevice make_by_alias(in string alias, in string mode, in long flags, inout ErrorCode error, out string error_string, out string audio_formats_alias, out string audio_inputs_alias, out string audio_outputs_alias)

Description

This method returns an instantiated child of the UMSAudioDevice class as determined by the alias parameter. The AudioDevice object is returned in the open state based upon the mode and flags parameters. The particular child returned depends upon interaction with a UMSConfig object.

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

Arguments

in string alias	Specifies the alias to seek using the UMSConfig object.
in string mode	Specifies the mode on the device being opened. Currently supported values are PLAY and RECORD.
in long flags	This parameter allows for flags to be set on the open. The only flag bit defined is: `UMSAudioDeviceMClass_BlockingIO 0x00000001` If this flag is not set, the underlying device is opened with the UNIX O_NDELAY flag set.
inout ErrorCode error	Provides success or reason for failure. If a failure occurred, a null pointer is returned instead of an instantiated object.
out string error_string	If an error occurred, this string contains more detailed information about the point of failure.
out string audio_formats_alias	The advertised formats_alias for the device.
out string audio_inputs_alias	The advertised inputs_alias for the device.
out string audio_outputs_alias	The advertised outputs_alias for the device.

Error Codes

For certain Error Codes, more specific information can be obtained from the error_string parameter.

Error Code	error_string
Failure	Name of the class that failed to be created.
AliasNotFound	Alias that could not be found by the UMSConfig object.
PropertyNotFound	Property that could not be found by the UMSConfig object.
InvalidClassName	Name of the class that could not be found by the SOM runtime.
NotAChild	Name of the class that is not a child of the UMSAudioDevice base class.

UMSAudioDeviceMClass Usage

AudioDeviceMClass make_by_alias methods use an audio device alias to choose the audio device object to instantiate. When audio device choices do not exist, this mechanism can seem overly complex. However, the device alias mechanism enables an application to migrate to different physical audio devices with no recompilation. It also enables programmers to categorize the applications and the way these applications use an audio device and to route certain usages to certain devices.

When an application requests an audio device, whether directly through the AudioDeviceMClass or indirectly through a media_handler object, it does so with an audio device alias of the following form:

Audio.<ApplicationClass>.<ApplicationName>.<Usage>

After the AudioDeviceMClass object has successfully used the seek_alias method of the Config object, it attempts to instantiate the device based upon the properties contained by that alias:

Audio:
        device_path              "/dev/acpa0"
        CLASS_UMSAudioDevice     "UMSACPADevice"
        audio_formats_alias      "UMSACPAFormats"
        audio_inputs_alias       "UMSACPAInputs"
        audio_outputs_alias      "UMSACPAOutputs"
*NEXT:
        device_path              "/dev/acpa1"
        CLASS_UMSAudioDevice     "UMSACPADevice"
        audio_formats_alias      "UMSACPAFormats"
        audio_inputs_alias       "UMSACPAInputs"
        audio_outputs_alias      "UMSACPAOutputs"

Note: Once it is determined that the value of the CLASS_UMSAudioDevice property is a valid class name and a child of the UMSAudioDevice class, an object of that class is instantiated. If the subsequent open call succeeds, the object is returned in the open state. Otherwise, the object is freed and the seek_next method is used to search for other devices. If no device can be successfully opened, DeviceNotAvail is returned as the ErrorCode.

For introductory information, see MetaClass Objects.