IMMDevice

The IMMDevice class is the base device class and provides behavior common to all devices. IMMDevice contains the device ID, alias, and similar information. There are numerous functions for querying the capabilities of the device. Also, there are functions for opening and closing the device, changing the speed and time formats, and for changing the audio.


IMMDevice - Member Functions and Data by Group

Constructors & Destructor

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


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

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
IMMDevice


Overload 1
protected:
IMMDevice(const IString& fileOrDevice)

A derived class can construct an IMMDevice from the following:

fileOrDevice
This is the name of the device. This name is operating-system-specific. For example the name of the amplifier-mixer device in the OS/2 operating system is AMPMIX.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


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

A derived class can construct an IMMDevice 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

Use these members to manipulate the audio for the device. You can turn the audio off and on, and you can change and query the volume.

Windows Considerations

Member functions exist to facilitate access to the Win32 mixer devices. These devices are somewhat similar to ampmixer devices in OS2 in that they support sound shaping. However, Win32 mixer devices are not treated as MCI devices, so require special functions specific to this environment.

[view class]
disableAudio
public:
virtual IMMDevice& disableAudio( AudioChannel channel = all, const IMMMillisecondTime& over = IMMMillisecondTime ( ), CallType call = wait )

Turns off the audio for the device. This audio change can be delayed based on the passed in vectored delay time (think of this the same as fade out on your car stereo). Based on this delay time, the audio is slowly turned off. The default is no delay.

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]
enableAudio
public:
virtual IMMDevice& enableAudio( bool enable = true, AudioChannel channel = all, const IMMMillisecondTime& over = IMMMillisecondTime ( ), CallType call = wait )

Turns on or turns off the audio for the device. This audio change can be delayed based on the passed in vectored delay (think of this the same as fade in on your car stereo). Based on this delay time, the audio is slowly turned on. The default is no delay.

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]
isAudioEnabled
public:
bool isAudioEnabled( AudioChannel channel = all, CallType call = wait )

Returns true if the audio for the passed in channel is turned on.

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]
setVolume
public:
virtual IMMDevice& 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.

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

OS/2 Considerations

This volume change can be delayed based on the passed-in vectored delay time (think of this the same as fade in or fade out on your car stereo). Based on this delay time, the volume is slowly changed to the new volume. The default is no delay.

In order to affect the volume of CD audio when using a cdStream, you must create an IMMAmpMixer to control the volume.

Windows Considerations

For Win32, the vectored delay time is not supported.


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

Returns the volume setting for the passed-in audio channel. This value is in the range of 0 to 100.

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]
mixerControlValues

Returns one or more values associated with a mixer control.


Overload 1
protected:
virtual bool mixerControlValues( unsigned long dwComponentType, unsigned long dwControlType, unsigned short* usDetails, bool uniform = true, unsigned long multipleItems = 0, unsigned long hmx = NULL )

This function returns details for a mixer control that has two states, on and off (such as a mute button).

Supported Platforms

Windows OS/2 AIX
Yes No No


Overload 2
protected:
virtual bool mixerControlValues( unsigned long dwComponentType, unsigned long dwControlType, unsigned long* ulDetails, bool uniform = true, unsigned long multipleItems = 0, unsigned long hmx = NULL )

This function returns details for a mixer control that has many states, such as a volume control. The values returned are a percentage of a maximum value, in the range from 0 to 100.

Supported Platforms

Windows OS/2 AIX
Yes No No


[view class]
setMixerControlValues

Sets one or more values associated with a mixer control.


Overload 1
protected:
virtual bool setMixerControlValues( unsigned long dwComponentType, unsigned long dwControlType, unsigned long* ulDetails, bool uniform = true, unsigned long multipleItems = 0, unsigned long hmx = NULL )

This function sets details for a mixer control that has many states, such as a volume control. The values should be a percentage of a maximum value, in the range from 0 to 100. Any value greater than 100 is treated as 100.

Supported Platforms

Windows OS/2 AIX
Yes No No


Overload 2
protected:
virtual bool setMixerControlValues( unsigned long dwComponentType, unsigned long dwControlType, unsigned short* usDetails, bool uniform = true, unsigned long multipleItems = 0, unsigned long hmx = NULL )

This function sets details for a mixer control that has two states, on and off (such as a mute button).

Supported Platforms

Windows OS/2 AIX
Yes No No


[view class]
setSystemMixerHandle
protected:
IMMDevice& setSystemMixerHandle(unsigned long hmx)

Sets the system mixer handle for this device.

Supported Platforms

Windows OS/2 AIX
Yes No No


[view class]
systemMixerHandle
protected:
unsigned long systemMixerHandle() const

Returns the currently set system mixer handle for this device. If one does not exist, this function will open a system mixer handle and set it for this device before returning.

Supported Platforms

Windows OS/2 AIX
Yes No No


Capabilities

Use these members to determine the capabilities of the device. All devices should respond to these inquiries.


[view class]
requiresFiles
public:
bool requiresFiles(CallType call = wait) const

Returns true if the device requires the use of files. An example of a device that requires files is the wave audio device, and an example of a device that does not require files is the amplifier-mixer device.

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]
supportsAudio
public:
bool supportsAudio(CallType call = wait) const

Returns true if the device has support for audio playback.

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]
supportsCommand
public:
bool supportsCommand( IMMNotifyEvent::Command command, CallType call = wait ) const

Returns true if the device supports the passed-in command.

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]
supportsDigitalTransfer
public:
bool supportsDigitalTransfer(CallType call = wait) const

Returns true if the device can internally process digital data, for example a digital-to-analog converter on a CD player.

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]
supportsDisableEject
public:
bool supportsDisableEject(CallType call = wait) const

Returns true if the device can disable the manual ejection of the media.

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]
supportsEject
public:
bool supportsEject(CallType call = wait) const

Returns true if the device can eject the media.

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]
supportsPlay
public:
bool supportsPlay(CallType call = wait) const

Returns true if the device can play.

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]
supportsRecord
public:
bool supportsRecord(CallType call = wait) const

Returns true if the device supports recording. This does not necessarily mean it also supports the ability to save the data you just recorded. See supportsSave 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]
supportsRecordInsertion
public:
bool supportsRecordInsertion(CallType call = wait) const

Returns true if the device supports insertion of data while recording. For example, you would use this function if you just recorded a sound file and then wanted to record your voice saying "Hello" in the middle of it without overlaying any of the recorded sound.

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]
supportsSave
public:
bool supportsSave(CallType call = wait) const

Returns true if the device can save data to some type of media (for example, a file). An example of a device that supports saving is the wave audio device, and an example of a device that does not support saving is the audio CD device.

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]
supportsStreaming
public:
bool supportsStreaming(CallType call = wait) const

Returns true if the device can continuously transfer digital data to or from another device. The source or destination of the data is determined by the device's connections.

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]
supportsVideo
public:
bool supportsVideo(CallType call = wait) const

Returns true if the device has support for video playback.

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]
supportsVolumeAdjustment
public:
bool supportsVolumeAdjustment(CallType call = wait) const

Returns true if the device supports software control of the volume. An example of a device that supports volume adjustment is the wave audio device, and an example of a device that does not support audio adjustment is the video disc device.

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


Connector Type

Use these members to query and manipulate the connectors for the device.

Connectors give devices the ability to connect to other devices. For those of you who have VCRs or stereos, you probably are familiar with those RCA connection cables that you use to connect different stereo and video components. You normally connect one end of the cable to a line in (such as video in on your TV) and connect the other end to the line out (such as video out on your VCR). Think of these software connections and connectors as those cables and connections.

For example, suppose you want to record your favorite song from a cassette as a sound file on your computer, but you do not have a microphone. You do, however, have a RCA cable connected to your stereo. You could connect one end of the cable to your cassette player and the other to the line in of your sound card. By default, the wave audio device would record from the microphone jack on the sound card because it is initially connected to the microphone connector. To record from the sound card's line in, you would have to make your wave audio device record from the line in connector on the sound card. To do this, you would enable the line in connector for your audio device by calling enableConnector(IMMDevice::lineIn); on your audio device. Because the audio device only supports one input connection to be enabled at a given time, it automatically disables the microphone connector. So, to create the sound file, all you would have to do is to press play on the cassette player and call the record function on the wave audio device.


[view class]
connectedDeviceId
public:
unsigned long connectedDeviceId( ConnectorType type, CallType call = wait ) const

Returns the ID of the device that is connected to the identified connector of this device.

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
Ignored Yes No


[view class]
disableConnector
public:
virtual IMMDevice& disableConnector( ConnectorType type, CallType call = wait )

Turns off the connector specified by type for this device.

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.
IInvalidRequest The connector type is not supported by this device.

Supported Platforms

Windows OS/2 AIX
Ignored Yes No


[view class]
enableConnector
public:
virtual IMMDevice& enableConnector( ConnectorType type, bool enable = true, CallType call = wait )

Turns on or turns off the connector specified by type for this device.

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.
IInvalidRequest The connector type is not supported by this device.

Supported Platforms

Windows OS/2 AIX
Ignored Yes No


[view class]
isConnectionSupported
public:
bool isConnectionSupported( ConnectorType type, CallType call = wait ) const

Returns true if the connector is valid for this device.

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
Ignored Yes No


[view class]
isConnectorEnabled
public:
bool isConnectorEnabled( ConnectorType type, CallType call = wait ) const

Returns true if the connector is enabled for this device.

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
Ignored Yes No


Device Information

Use these members to query information about the device and its state.


[view class]
aliasName
public:
IString aliasName() const

Returns the alias associated with the device during the open procedure. This function is can return an empty string because a device can be constructed solely from a device ID.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
deviceId
public:
unsigned long deviceId() const

Returns the ID of the current device. This value is used by the system to identify the device. In the construction of this object, a device identifier is passed in.

Exception

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]
deviceName
public:
IString deviceName() const

Returns the name of the device depending on the class of the object. For example, some devices can be opened with a file name (song.mid), but other devices, such as IMMAudioCD, are opened with a specific device name (such as CDAUDIO01).

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Device Type and Description

Use these members to query the type and description of the device.


[view class]
description
public:
IString description(CallType call = wait) const

Returns the description of the hardware associated with this device.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


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

Returns the type of the device.

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]
allDevices
public:
static const unsigned long allDevices

A device type for representing all devices.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
ampMixer
public:
static const unsigned long ampMixer

A device type for representing a combination amplifier-mixer that is used to control the characteristics of an audio signal from one or more audio sources.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
animation
public:
static const unsigned long animation

A device type for representing a device that uses a sequence of images to produce the effect of movement.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
audioCD
public:
static const unsigned long audioCD

A device type for representing an audio CD device.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
audioTape
public:
static const unsigned long audioTape

A device type for representing an audio tape recorder device.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
cdxa
public:
static const unsigned long cdxa

A device type for representing a compact disc-extended architecture (CD-XA) device.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
dat
public:
static const unsigned long dat

A device type for representing a digital audio tape device.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
digitalVideo
public:
static const unsigned long digitalVideo

A device type for representing a digital video device.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
headphone
public:
static const unsigned long headphone

A device type for representing a headphone.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
microphone
public:
static const unsigned long microphone

A device type for representing a microphone.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
monitor
public:
static const unsigned long monitor

A device type for representing a device that can listen to (monitor) an audio and video source.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
other
public:
static const unsigned long other

A device type for representing devices other than the system-provided device types.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
overlay
public:
static const unsigned long overlay

A device type for representing a device that can overlay an image on top of the screen that does not disrupt what is displayed there.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
sequencer
public:
static const unsigned long sequencer

A device type for representing a MIDI synthesizer device.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
speaker
public:
static const unsigned long speaker

A device type for representing output to the speakers.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
videoDisc
public:
static const unsigned long videoDisc

A device type for representing a video disc player device.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
videoTape
public:
static const unsigned long videoTape

A device type for representing a video tape device.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
waveAudio
public:
static const unsigned long waveAudio

A device type for representing a device that uses digital audio data in the wave format.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Error Information

Use these members to set and query an error value.


[view class]
lastError
protected:
unsigned long lastError() const

Returns the return code from the last call. This return code could be 0 because the value is reset with each call. If an error code needs to be captured, this function should be called directly after the error-causing function because each function overwrites this value.

Supported Platforms

Windows OS/2 AIX
Yes Yes No

OS/2 Considerations

Because the system multimedia architecture does not keep track of the return value of the last function call, this function does that. It allows all of the functions to throw exceptions where they are meaningful.


[view class]
setLastError
protected:
IMMDevice& setLastError(unsigned long errorId)

Sets the return code of the last low-level function call.

Supported Platforms

Windows OS/2 AIX
Yes Yes No

OS/2 Considerations

Because the system multimedia architecture does not keep track of the return value of the last function call, this function does that. It allows all of the functions to throw exceptions where they are meaningful.


Event Dispatching

Event-dispatching members interact with the notification handlers for this device.


[view class]
enableNotification
public:
virtual IMMDevice& enableNotification(bool enabled = true)

Flags this object as being ready to accept notifications. A Notifier, like IMMDevice, does not send notifications to observer objects until it is enabled.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
notificationHandler
protected:
IMMDeviceNotifyHandler* notificationHandler() const

Returns a pointer to the notification handler

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
setNotificationHandler
protected:
IMMDevice& setNotificationHandler( IMMDeviceNotifyHandler* notifyHandler )

Sets the notification handler to the passed value.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Event Type and DeletePendingEvents

Use these members to specify the type of pending events that are to be deleted.


[view class]
deletePendingEvents
public:
virtual IMMDevice& deletePendingEvents( EventType event = allEvents )

Removes all of the passed-in event types from the queue.

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


Implementation

Use these members to access the low-level functions and to set and query a user parameter that can be passed on function calls.


[view class]
deviceWindow
protected:
IMMMessageWindow& deviceWindow() const

Returns the window object that the device uses to communicate to the operating system.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
isOpenStringValid
protected:
virtual bool isOpenStringValid( const IString& deviceName ) const

Returns true if the passed-in open string is valid for this device.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
itemCapability
protected:
unsigned long itemCapability( unsigned long item, CallType call ) const

Gets the device capabilities for the item. This is similar to using the devQueryCaps system call on the OS/2 operating system.

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]
itemStatus
protected:
unsigned long itemStatus( unsigned long item, unsigned long value = 0, CallType call = wait ) const

Checks the status of the item.

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]
restoreDeviceSettings
protected:
virtual IMMDevice& 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 IMMDevice& 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]
sendCommand

Sends a command string to the device. This returns the resulting string from the call.


Overload 1
protected:
IString sendCommand( const IString& command, unsigned short userParm )

The passed in userParameter is in the notification message and does not replace the value set with setUserParameter.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Overload 2
protected:
IString sendCommand(const IString& command)

The currently set userParameter is in the notification message.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Overload 3
protected:
IMMDevice& sendCommand( unsigned short message, unsigned long param1, void* param2, unsigned short userParm )

The passed in userParameter is in the notification message and does not replace the value set with the setUserParameter.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Overload 4
protected:
IMMDevice& sendCommand( unsigned short message, unsigned long param1, void* param2 )

The currently set userParameter is in the notification message.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
setPassDeviceRequested
protected:
IMMDevice& setPassDeviceRequested(bool sawPassDevice)

Sets the pass device flag. Use this to notify the device object that the device object has received use of the actual hardware device. Until the device receives the first pass device event, the device is not initialized.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
setUserParameter
protected:
IMMDevice& setUserParameter(unsigned short userParm = 0)

Sets the user parameter. This parameter is automatically passed in the notification messages for all but two of the device functions. The exceptions are the two sendCommand functions that take their own user parameter.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
userParameter
protected:
unsigned short userParameter() const

Returns the user parameter that is in all of the notification messages except for the two sendCommand functions that take their own user parameter.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
wasPassDeviceRequested
protected:
bool wasPassDeviceRequested() const

Returns true if it has already processed a passDevice event. Use this to notify the device object that the device object has received use of the actual hardware device. Until the device receives the first pass device event, the device is not initialized.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Mode

Use these members to query the current mode of the device.


[view class]
mode
public:
virtual Mode mode(CallType call = wait) const

Returns the current mode of the device.

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


Notification Event Descriptions

These INotificationId strings are used for all notifications that IMMDevice provides to its observers.


[view class]
commandNotifyId
public:
static INotificationId const commandNotifyId

Provides a notification identifier to observers when one of the IMMDevice functions has been called with the notify flag. IMMDevice provides a pointer to an IMMNotifyEvent for the command in the INotificationEvent::eventData field of the INotificationEvent.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
cuePointId
public:
static INotificationId const cuePointId

Provides a notification identifier to observers when the device receives a cue point message. IMMDevice provides a pointer to an IMMCuePointEvent for the message in the INotificationEvent::eventData field of the INotificationEvent.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
deviceEventId
public:
static INotificationId const deviceEventId

Provides a notification identifier to observers when the device receives a device message. IMMDevice provides a pointer to an IMMDeviceEvent for the message in the INotificationEvent::eventData field of the INotificationEvent.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
passDeviceId
public:
static INotificationId const passDeviceId

Provides a notification identifier to observers when the device receives a pass device message. IMMDevice provides a pointer to an IMMPassDeviceEvent for the message in the INotificationEvent::eventData field of the INotificationEvent.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
positionChangeId
public:
static INotificationId const positionChangeId

Provides a notification identifier to observers when the device receives a position change message. IMMDevice provides a pointer to an IMMPositionChangeEvent for the message in the INotificationEvent::eventData field of the INotificationEvent.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Opening and Closing

Use these members to query if the device is opened, to open or close the device, and to direct the device to close itself when the device object is destructed.


[view class]
close
public:
virtual IMMDevice& close(CallType call = wait)

Closes a device.

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]
isCloseOnDestroy
public:
bool isCloseOnDestroy() const

Returns true if the device closes itself when the device object is deleted.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
isOpen
public:
bool isOpen() const

Returns true if the device is opened. In general, open a device before calling multimedia functions.

Exception

IAccessError The device identifier is not valid.
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
open

Opens the device or file based on the passed-in string. The default string uses the deviceName. Note, if call is wait, then the windowing system will be tied up until the file or device is opened. If you do not want to tie up the windowing system and you do not want the open function to return until the file or device is opened, then use the openOnThread function. Otherwise, you could set call to nowait, causing open to return immediately. When the open finishes, an INotificationEvent is sent to any observers that are attached to this device, notifying them that the open is finished.

You must have opened the device before you try to acquire access to it. When a device is open, it notifies the operating system that you want to have the use of the hardware at sometime in the future, and notifies the operating system that it can share the device. When you acquire access, you are requesting that the system provide you access to the hardware now. Then, based on the type of ShareMode that you requested, it gives you access to the hardware.


Overload 1
public:
virtual IMMDevice& open( const IString& fileOrDevice = IString ( ), bool shareable = true, CallType call = wait )

Exception

IAccessError The device identifier is not valid;
IAccessError An internal driver error occurred.
IAccessError The device is locked.
IAccessError A hardware error occurred.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Overload 2
protected:
virtual IMMDevice& open( unsigned long instanceNumber, bool shareable = true, CallType call = nowait )

Exception

IAccessError The device identifier is not valid;
IAccessError An internal driver error occurred.
IAccessError The device is locked.
IAccessError A hardware error occurred.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
openOnThread

Opens the file or device by creating a thread to do the actual opening. The default string uses the deviceName. By doing the opening this way, it does not tie up the windowing system. This function does not return until the file or device is opened.


Overload 1
public:
virtual IMMDevice& openOnThread( const IString& fileOrDevice = IString ( ), bool shareable = true, CallType call = wait )

Exception

IAccessError The device identifier is not valid;
IAccessError An internal driver error occurred.
IAccessError The device is locked.
IAccessError A hardware error occurred.

Supported Platforms

Windows OS/2 AIX
Yes Yes No

Windows Considerations

The Win32 MCI does not support threads, so this function behaves like open() in this environment.


Overload 2
protected:
virtual IMMDevice& openOnThread( unsigned long instanceNumber, bool shareable = true )

Exception

IAccessError The device identifier is not valid;
IAccessError An internal driver error occurred.
IAccessError The device is locked.
IAccessError A hardware error occurred.

Supported Platforms

Windows OS/2 AIX
Yes Yes No

Windows Considerations

The Win32 MCI does not support threads, so this function behaves like open() in this environment.


[view class]
setCloseOnDestroy
public:
IMMDevice& setCloseOnDestroy(bool close = true)

Closes the device when this object is destroyed. The default is to close the device.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


OpenStatus

Use these members to set and query the open state of the device.


[view class]
openStatus
protected:
OpenStatus openStatus() const

Returns the result of the open attempt. This is used by the device to determine if the opening of the device has occurred yet and if it was successful. This is important because basically all of the multimedia function calls require the device to be opened first before you can make any calls.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
setOpenStatus
protected:
IMMDevice& setOpenStatus(OpenStatus status)

Sets the open flag. This is used by the device to determine if the opening of the device has occurred yet and if it was successful. This is important because basically all of the multimedia function calls require the device to be opened first before you can make any calls.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Preroll Type

Use these members to prepare a device to begin a playback or recording function with minimal delay. These members set and query the amount of preroll time.


[view class]
prerollTime
public:
IMMTime prerollTime(CallType call = wait) const

Returns the amount of preroll time in IMMTime. If the returned time object is invalid, then the preroll time is not bounded.

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
No Yes No


[view class]
prerollType
public:
PrerollType prerollType(CallType call = wait) const

Returns the preroll characteristics of the device.

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
No Yes No


Share Mode and Acquiring

Use these members to specify the three ways that the operating system can share access to the device and to query, acquire, and release access to the device.


[view class]
acquire
public:
virtual IMMDevice& acquire( ShareMode acquire = shareable, bool queuedForResources = false, CallType call = wait )

Requests assignment of (access to) the device. If queued is true, the request is queued and executed as soon as the device resources are available. If the request can be satisfied immediately, then it is not queued.

You must have opened the device before you try to acquire access to it. When a device is open, it notifies the operating system that you want to have the use of the hardware at some time in the future and notifies the operating system that it can share the device. When you acquire access, you are requesting that the system provide you access to the hardware now. Then, based on the type of ShareMode that you requested, it gives you access 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]
isAcquired
public:
bool isAcquired(CallType call = wait) const

Returns true if the device is ready. If a device is not ready, then access to it needs to be acquired using acquire.

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]
release
public:
virtual IMMDevice& release(CallType call = wait)

Releases exclusive use of the device resources.

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


Speed and Time

Use these members to set and query the current formats for speed and time for the device.


[view class]
setSpeedFormat
public:
virtual IMMDevice& setSpeedFormat( IMMSpeed::Format format, CallType call = wait )

Sets the speed format for the device. See IMMSpeed for more information on the different speed formats.

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

Windows Considerations
For Win32, the only supported format is framesPerSecond.

[view class]
setTimeFormat
public:
virtual IMMDevice& setTimeFormat( IMMTime::Format format, CallType call = wait )

Sets the time format for the device. See IMMTime::Format enumeration for more information on the different time formats.

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]
speedFormat
public:
IMMSpeed::Format speedFormat(CallType call = wait) const

Returns the currently set speed format for the device. See IMMSpeed for more information on the different speed formats.

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]
timeFormat
public:
IMMTime::Format timeFormat(CallType call = wait) const

Returns the currently set time format for the device. See the Format enumeration for more information on the different time formats.

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


IMMDevice - Enumerations


[view class]
AudioChannel
enum AudioChannel { all, 
                    left, 
                    right }

Use this enumeration to specify audio channel identifiers.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
CallType
enum CallType { nowait=0X00000001, 
                wait=0x00000002 }

This enumeration determines how the multimedia functions call the low level operating system functions. In both call types, a notification event is sent to all attached IObservers when the command finishes processing. Most functions that result in a call to the operating system take this type as their last parameter. The following are valid values:

nowait
The method is asynchronous and returns immediately (before the requested processing is complete). If you want to know when the command finishes processing, attach an observer to the device because it gets notified when the command finishes.
wait
The method is synchronous and all processing occurs before the function returns. Wait is not recommended for threads having a message queue that is processing messages for user interface windows. A long wait could tie up the message queue.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
ConnectorType
enum ConnectorType { midiStream=0x00000001, 
                     cdStream=0x00000002, 
                     waveStream=0x00000003, 
                     ampStream=0x00000004, 
                     xaStream=0x00000005, 
                     headphones=0x00000006, 
                     speakers=0x00000007, 
                     microphones=0x00000008, 
                     lineIn=0x00000009, 
                     lineOut=0x0000000a, 
                     videoIn=0x0000000b, 
                     videoOut=0x0000000c, 
                     phoneSet=0x0000000d, 
                     phoneLine=0x0000000e, 
                     audioIn=0x0000000f, 
                     audioOut=0x00000010, 
                     universal=0x00000011 }

Use the preceding enumerations to specify connection types. These are all of the types of connections that a device can support. Each device only supports a subsection of this list. For example, an audio CD device would not support xaStream or microphones.
Note: "Stream in" these enumerations means the digital transfer of the data for these devices.

Supported Platforms

Windows OS/2 AIX
Ignored Yes No


[view class]
EventType
enum EventType { allEvents, 
                 notifyEvent=0x0500, 
                 passDeviceEvent, 
                 positionChangeEvent, 
                 cuePointEvent, 
                 deviceEvent, 
                 synchEvent }

Use the preceding enumerations to specify the type of events that are to be removed.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
Mode
enum Mode { notReady=1, 
            paused, 
            playing, 
            stopped, 
            recording, 
            seeking }

An enumeration that denotes the current state of the device. The following are valid values:

notReady
A device is in this state when the device is not acquired.
paused
The device is paused.
playing
The device is playing.
stopped
The device is stopped.
recording
The device is recording.
seeking
The device is moving the current position to a new location.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
OpenStatus
enum OpenStatus { openNotAttempted, 
                  openSuccessful, 
                  openFailed }

An enumeration that denotes the different states for opening a device. The following are valid values:

openNotAttempted
You have not tried to open the device yet.
openSuccessful
The open succeeded.
openFailed
The open failed.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
PrerollType
enum PrerollType { variable=1, 
                   fixed, 
                   none }

Use these enumerators to specify preroll characteristic identifiers. Preroll means preparing a device to begin a playback or recording function with minimal delay. The following are valid values:

variable
The preroll time for the device is variable, meaning that you can change the preroll time value.
fixed
The preroll time for the device is fixed, meaning that you cannot change the preroll time value; it is fixed by the operating system.
none
The preroll time is not supported by the device.

Supported Platforms

Windows OS/2 AIX
No Yes No


[view class]
ShareMode
enum ShareMode { shareable, 
                 isolatedExclusive=0x00000100, 
                 exclusive=0x00000200 }

Use these enumerators to specify share mode identifiers:

shareable
Allows the device to be shared by other applications.
isolatedExclusive
Inhibits other applications from acquiring use of the physical (or hardware) device until released by the owning application.
exclusive
Acquires the device for exclusive use without acquiring the entire device resource for exclusive use. This basically means that the operating system cannot make this device inactive.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


IMMDevice - Inherited Member Functions and Data

Inherited Public Functions

INotifier
IStandardNotifier

Inherited Public Data

INotifier

Inherited Protected Functions

IStandardNotifier
INotifier

Inherited Protected Data