Sharing the Audio Capture Device

The most recent versions of Microsoft® Windows®, Windows Millennium Edition (Windows Me), and Windows XP allow the audio capture device to be shared between different processes. However, in Windows 95, Windows 98, and Windows 2000 operating systems, the audio capture device is a shared resource and can be opened by only one process at a time. To use audio capture on these operating systems, your application must be designed to effectively handle resource ownership and coordination issues. This document discusses how multiple Microsoft DirectPlay® Voice applications can share the same audio capture device on any Windows operating system.

Coordinating Shared Resources

Resource ownership becomes a problem when a physical resource such the audio capture device is a shared resource. If one application owns the shared audio capture device, other applications cannot open it. In the past, this limitation rarely posed problems because few applications used audio capture. However, the increasing popularity of technologies such as voice recognition means that applications can no longer assume that they can have exclusive ownership of the audio capture device. For instance, a lobby operator might want to implement a voice chat feature to help clients set up game sessions. However, if the lobby client application owns the audio capture device, the game application will not be able to use audio capture and its voice features will be effectively disabled.

Resource coordination is the process by which two or more applications manage ownership of a shared resource. For example, if two voice communication applications are running, the foreground application is typically the only application that needs the audio capture device. When focus changes, ownership of the audio capture device needs to shift to the new foreground application. For instance, after a group of players have finished using a lobby's voice chat feature to set up their session, they will launch their game applications. At that point, the game application moves to the foreground and acquires ownership of the audio capture device for game-related voice features.

DirectPlay Voice handles the problem of sharing the audio capture device through a feature called capture focus. Capture focus operates on a per-device basis, and allows multiple DirectPlay Voice applications to share a single audio capture device regardless of which version of Windows is installed on the system. As long as capture focus is enabled, any number of DirectPlay Voice application instances can have the same audio capture device open. Capture focus also provides a way for DirectPlay Voice applications to coordinate their use of the audio capture device. Capture focus is not available to applications that are not using DirectPlay Voice.

Using Capture Focus

DirectPlay Voice automatically coordinates the use of the audio capture device for all DirectPlay Voice applications that have enabled capture focus. If multiple DirectPlay Voice applications are running with capture focus enabled, focus is normally coordinated in the following way.

• The application whose window is in the foreground has capture focus and can capture audio.
• An application retains capture focus until another DirectPlay Voice application that has enabled capture focus gains the foreground.
• None of the other applications can capture audio until they acquire capture focus.

The shift in capture focus normally occurs after the shift in window focus. Typically, your application will acquire capture focus one to two seconds after your window gains the foreground.

Capture focus is enabled by default. To disable capture focus, you must set the DVSOUNDCONFIG_NOFOCUS flag in the dwFlags member of the DVSOUNDDEVICECONFIG structure when you call IDirectPlayVoiceClient::Connect to connect to a voice session.

To specify which window you want DirectPlay Voice to use for focus determination, assign its window handle to the hwndApp member of the DVSOUNDDEVICECONFIG structure when you connect to the voice session. You should use the window handle of your application's top-level window for focus determination. Do not use the desktop window. Doing so may lead to inconsistent determination of focus.

When capture focus shifts, DirectPlay sends a DVMSGID_LOSTFOCUS message to the application that has lost focus. When an application receives this message, audio capture stops until the application regains focus. DirectPlay sends a DVMSGID_GAINFOCUS message to the application that has gained focus. This message indicates that the application has started capturing audio. It will continue to do so until it loses focus to another application.

Strict Mode

By default, your application loses capture focus only if another capture focus-enabled DirectPlay Voice application gains the foreground. Your application can retain capture focus even if it is no longer the foreground application. It must only be higher in the z-order than any other capture focus-enabled application. If you want your application to have capture focus only when it is the foreground application, specify strict mode. In strict mode, a DirectPlay Voice application must be active and at the top of the z-order in order to have capture focus. If it loses that status to any other application, audio capture will cease. To specify strict mode, set the DVSOUNDCONFIG_STRICTFOCUS flag in the dwFlags member of the DVSOUNDDEVICECONFIG when you connect to the voice session.

Muting Capture Focus

You can give up capture focus programmatically by muting audio capture. To mute audio capture, call IDirectPlayVoiceClient::SetClientConfig, and set the DVCLIENTCONFIG_RECORDMUTE flag in the dwFlags member of the DVCLIENTCONFIG structure. When you mute audio capture, your application loses capture focus and the last application that had capture focus gains it again. If no other application has capture focus enabled, DirectPlay stops audio capture. You can unmute audio capture and attempt to regain capture focus by calling IDirectPlayVoiceClient::SetClientConfig without the DVCLIENTCONFIG_RECORDMUTE flag. However, this action does not necessarily return capture focus to your application.

• If yours is the only capture focus-enabled application, you will immediately regain capture focus.
• If your application is higher in the z-order than any other capture focus-enabled application, you will immediately regain capture focus even if you are not the foreground application. In particular, when you mute audio capture, capture focus often passes an application application below yours in the z-order. If that order does not change, you will regain capture focus when you unmute audio capture.
• If capture focus has passed to another capture focus-enabled application that is higher than yours in the z-order, you do not immediately regain capture focus. Your application must become the foreground application in order to regain capture focus.
• If you are in strict mode, you will regain capture focus only if your application is at the top of the z-order. Your application must become the foreground application in order to regain capture focus.