IMMConfigurableAudio

The IMMConfigurableAudio class is the base class for all devices that support audio. It provides functions for setting and querying the audio formats, speed, and audio channels.


IMMConfigurableAudio - Member Functions and Data by Group

Constructors & Destructor

Derived classes can use these members to create objects of this class.


[view class]
~IMMConfigurableAudio
public:
virtual ~IMMConfigurableAudio()

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
IMMConfigurableAudio


Overload 1
protected:
IMMConfigurableAudio( const IString& deviceName, bool openNow = true, unsigned long instance = 0, bool openShareable = true )

A derived class can construct an IMMConfigurableAudio from the following:

deviceName
You must specify what device you want to construct.
openNow
If true, it causes the device to automatically open the device before returning from the constructor; otherwise, you would have to call one of the open functions to open the device yourself.
instance
You can provide your own instance number instead of letting IMMConfigurableAudio generate one.
openShareable
If true, it allows the hardware device to be shared by different programs; otherwise, the hardware cannot be shared.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Overload 2
protected:
IMMConfigurableAudio( unsigned long deviceIdentifier, const IString& newAlias = IString ( ) )

A derived class can construct an IMMConfigurableAudio from the following:

deviceIdentifier
The value the system uses to identify the device.
newAlias
The name you can use to associate a string to the device. Optional.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Audio Attributes

Use these members to query and set the audio attributes for the current device.


[view class]
bitsPerSample
public:
unsigned long bitsPerSample(CallType call = wait) const

Returns the number of bits-per-sample. This is the number of bits of data used to represent each sample of each channel. The standard values are 4, 8, and 16.

Exception

IAccessError The device identifier is not valid; possibly the device is closed.
IAccessError The device cannot acquire access to the hardware device; possibly another device of this same type was acquired for exclusive use in this or another process.
IAccessError An internal driver error occurred.
IInvalidRequest The device must be in the open state before calling this function.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
blockAlignment
public:
unsigned long blockAlignment(CallType call = wait) const

Returns the block alignment of data in bytes. The system processes a multiple of block-aligned bytes of data at a time. For example, if you have a 24-byte buffer, then you can only set a block alignment of 2, 3, 4, 6, 8, or 12.

Exception

IAccessError The device identifier is not valid; possibly the device is closed.
IAccessError The device cannot acquire access to the hardware device; possibly another device of this same type was acquired for exclusive use in this or another process.
IAccessError An internal driver error occurred.
IInvalidRequest The device must be in the open state before calling this function.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
bytesPerSecond
public:
unsigned long bytesPerSecond(CallType call = wait) const

Returns the average number of bytes-per-second played or recorded. This is the rate the data is transferred to the hardware.

Exception

IAccessError The device identifier is not valid; possibly the device is closed.
IAccessError The device cannot acquire access to the hardware device; possibly another device of this same type was acquired for exclusive use in this or another process.
IAccessError An internal driver error occurred.
IInvalidRequest The device must be in the open state before calling this function.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
channels
public:
unsigned long channels(CallType call = wait) const

Returns the number of audio channels set. For example, mono is 1; stereo is 2.

Exception

IAccessError The device identifier is not valid; possibly the device is closed.
IAccessError The device cannot acquire access to the hardware device; possibly another device of this same type was acquired for exclusive use in this or another process.
IAccessError An internal driver error occurred.
IInvalidRequest The device must be in the open state before calling this function.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
format
public:
IMMAudioBuffer::Format format(CallType call = wait) const

Returns the interpretation of the audio format. See IMMAudioBuffer::Format for more information.

Exception

IAccessError The device identifier is not valid; possibly the device is closed.
IAccessError The device cannot acquire access to the hardware device; possibly another device of this same type was acquired for exclusive use in this or another process.
IAccessError An internal driver error occurred.
IInvalidRequest The device must be in the open state before calling this function.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
samplesPerSecond
public:
unsigned long samplesPerSecond(CallType call = wait) const

Returns the number of samples-per-second played or recorded. This is the sampling rate, in kilohertz, that each channel should use. Standard values are 11025, 22050, and 44100.

Exception

IAccessError The device identifier is not valid; possibly the device is closed.
IAccessError The device cannot acquire access to the hardware device; possibly another device of this same type was acquired for exclusive use in this or another process.
IAccessError An internal driver error occurred.
IInvalidRequest The device must be in the open state before calling this function.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
setBitsPerSample
public:
virtual IMMConfigurableAudio& setBitsPerSample( unsigned long bitsPerSample, CallType call = wait )

Sets the bits-per-sample to be played or recorded. This is the number of bits of data used to represent each sample of each channel. The standard values are 4, 8, and 16. You must set an audio format using setFormat before calling this function. The file is saved in this format.

Exception

IAccessError The device identifier is not valid; possibly the device is closed.
IAccessError The device cannot acquire access to the hardware device; possibly another device of this same type was acquired for exclusive use in this or another process.
IAccessError An internal driver error occurred.
IInvalidRequest The device must be in the open state before calling this function.
IAccessError The value is out of range.
IAccessError A audio format has not been set before calling this function.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
setBlockAlignment
public:
virtual IMMConfigurableAudio& setBlockAlignment( unsigned long alignment, CallType call = wait )

Sets the block alignment of the data. The system processes a multiple of block-aligned bytes of data at a time. For example, if you have a 24-byte buffer, then you can only set a block alignment of 2, 3, 4, 6, 8, or 12. You must set an audio format using setFormat before calling this function. The file is saved in this format.

Exception

IAccessError The device identifier is not valid; possibly the device is closed.
IAccessError The device cannot acquire access to the hardware device; possibly another device of this same type was acquired for exclusive use in this or another process.
IAccessError An internal driver error occurred.
IInvalidRequest The device must be in the open state before calling this function.
IAccessError The value is out of range.
IAccessError An audio format has not been set before calling this function.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
setBytesPerSecond
public:
virtual IMMConfigurableAudio& setBytesPerSecond( unsigned long averageBytes, CallType call = wait )

Sets the average bytes-per-second to be played or recorded. This is the rate the data is transferred to the hardware. You must set an audio format using setFormat before calling this function. The file is saved in this format.

Exception

IAccessError The device identifier is not valid; possibly the device is closed.
IAccessError The device cannot acquire access to the hardware device; possibly another device of this same type was acquired for exclusive use in this or another process.
IAccessError An internal driver error occurred.
IInvalidRequest The device must be in the open state before calling this function.
IAccessError The value is out of range.
IAccessError An audio format has not been set before calling this function.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
setChannels
public:
virtual IMMConfigurableAudio& setChannels( unsigned long channels, CallType call = wait )

Sets the number of audio channels for playing and recording. Monaural is 1; stereo is 2. You must set an audio format using setFormat before calling this function. The file is saved in this format.

Exception

IAccessError The device identifier is not valid; possibly the device is closed.
IAccessError The device cannot acquire access to the hardware device; possibly another device of this same type was acquired for exclusive use in this or another process.
IAccessError An internal driver error occurred.
IInvalidRequest The device must be in the open state before calling this function.
IAccessError The value is out of range.
IAccessError An audio format has not been set before calling this function.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
setFormat
public:
virtual IMMConfigurableAudio& setFormat( IMMAudioBuffer::Format tag = IMMAudioBuffer::pcm, CallType call = wait )

Sets the audio format for playing and recording. See IMMAudioBuffer::Format for more information. The file is saved in this format.

Exception

IAccessError The device identifier is not valid; possibly the device is closed.
IAccessError The device cannot acquire access to the hardware device; possibly another device of this same type was acquired for exclusive use in this or another process.
IAccessError An internal driver error occurred.
IInvalidRequest The device must be in the open state before calling this function.
IAccessError The value is out of range.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
setSamplesPerSecond
public:
virtual IMMConfigurableAudio& setSamplesPerSecond( unsigned long samplesPerSecond, CallType call = wait )

Sets the sampling rate for playing and recording. This is the sampling rate, in kilohertz, which each channel should use. Standard values are 11025, 22050, and 44100. You must set an audio format using setFormat before calling this function. The file is saved in this format.

Exception

IAccessError The device identifier is not valid; possibly the device is closed.
IAccessError The device cannot acquire access to the hardware device; possibly another device of this same type was acquired for exclusive use in this or another process.
IAccessError An internal driver error occurred.
IInvalidRequest The device must be in the open state before calling this function.
IAccessError The value is out of range.
IAccessError An audio format has not been set before calling this function.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
setVolume
public:
virtual IMMConfigurableAudio& setVolume( unsigned long volume, AudioChannel channel = all, const IMMMillisecondTime& over = IMMMillisecondTime ( ), CallType call = wait )

Sets the volume of the audio channel for the device, where 0 is the least amount of volume and 100 is the most amount of volume.

Supported Platforms

Windows OS/2 AIX
Yes Yes No

Portability Considerations

This member is overridden in this derived class for specific operating system behavior.


[view class]
volume
public:
virtual unsigned long volume( AudioChannel channel = left, CallType call = wait ) const

Returns the volume of the audio channel for the device, where 0 is the least amount of volume and 100 is the most amount of volume.

Supported Platforms

Windows OS/2 AIX
Yes Yes No

Portability Considerations

This member is overridden in this derived class for specific operating system behavior.


Implementation

These members translate the audio command to device-specific values.


[view class]
restoreDeviceSettings
protected:
virtual IMMConfigurableAudio& restoreDeviceSettings( bool newRecordMode = false )

Restores settings for the current device. Derived classes should override this function, handle class-specific settings, and call the corresponding inherited function.

Supported Platforms

Windows OS/2 AIX
Yes No No


[view class]
saveDeviceSettings
protected:
virtual IMMConfigurableAudio& saveDeviceSettings()

Saves settings for the current device. Derived classes should override this function, handle class-specific settings, and call the corresponding inherited function.

Supported Platforms

Windows OS/2 AIX
Yes No No


[view class]
translateAudioFlag
protected:
virtual unsigned long translateAudioFlag( unsigned long ) const

Allows derived classes to map the general audio commands to the device-specific values. For example, the digital video and the wave audio device both support setting the bytes-per-second, but the actual system values are different. By allowing the mapping of the wave audio values to the digital video values, the digital video player does not have to override all of the audio functions because they call this function.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


IMMConfigurableAudio - Inherited Member Functions and Data

Inherited Public Functions

IMMDevice
IMMFileMedia
IMMPlayableDevice
IMMRecordable
INotifier
IStandardNotifier

Inherited Public Data

INotifier
IMMDevice

Inherited Protected Functions

IStandardNotifier
INotifier
IMMDevice
IMMFileMedia
IMMPlayableDevice
IMMRecordable

Inherited Protected Data