Multimedia API Parameter Changes in the Win32 API

• Microsoft Win32 Software Development Kit (SDK)

SUMMARY

This article discusses the following topics concerning multimedia APIs in the Win32 SDK:

• Some Windows version 3.1 APIs that require a device ID will also accept a properly cast device handle in the Win32 API if the caller is a 32-bit application.
• An explanation of the difference between using a device ID and using a device handle in conjunction with the above functions is given.
• A list of related APIs that are now obsolete but are provided for backwards compatibility with Windows version 3.1 is given.

MORE INFORMATION

Functions That Accept A Device Handle or Device ID

Several MIDI and wave audio APIs have been revised in Win32 to provide greater flexibility to application developers. The following APIs require the calling application to provide a device ID for the target device under Windows 3.1, but under Win32 the APIs also accept a properly cast device handle if the caller is a 32-bit application:

   midiInGetDevCaps
   midiOutGetDevCaps
   waveInGetDevCaps
   waveOutGetDevCaps
   midiOutGetVolume
   midiOutSetVolume
   waveOutGetVolume
   waveOutSetVolume

Device ID vs. Device Handle

A device ID has a one-to-one correspondence with the physical device it references and is determined by querying for the number of devices of a given type in the system and selecting the desired device. A device handle refers to a specific instance of a device, of which there may be more than one, and is obtained by opening a device. A device instance may be thought of as a logical copy of a physical device.

If a 32-bit application is querying a device's capabilities using one of the xxxGetDevCaps APIs listed above, the distinction between whether a device ID or device handle is used in the function call is unimportant because all instances of a device have the same capabilities. The result of one of these function calls will be the same whether or not a device ID or device handle was used.

However, if a 32-bit application uses one of the xxxVolume APIs listed above to get or set the output volume of a device, the distinction between using a device ID or device handle becomes important. If a device ID is used in a call to these xxxVolume APIs, then the result of the call and/or information returned applies to all instances of the device. If a device handle is used in a call to the xxxVolume APIs, then the result of the call and/or information returned by the call applies only to the instance of the device referenced by the device handle.

The revised versions of the above APIs are available to 32-bit applications only. For backwards compatibility reasons, 16-bit applications are subject to the API design of Windows 3.1.

Obsolete APIs

In addition to the above changes, the following related APIs are now obsolete, but are included in Win32 for backwards compatibility purposes:

   midiInGetID
   midiOutGetID
   waveInGetID
   waveOutGetID