IDirectSound::SetCooperativeLevel
HRESULT SetCooperativeLevel(HWND hwnd, DWORD dwLevel);
Sets the cooperative level of the application for this sound device.
·Returns DS_OK if successful, or one of the following error values otherwise:
DSERR_ALLOCATED DSERR_INVALIDPARAM
DSERR_UNINITIALIZED DSERR_UNSUPPORTED
hwnd
Window handle for the application.
dwLevel
Requested priority level. Specify one of the following values:
Sets the application to the exclusive level. When it has the input focus, the application will be the only one audible. With this level, it also has all the privileges of the DSSCL_PRIORITY level. DirectSound will restore the hardware format, as specified by the most recent call to the IDirectSoundBuffer::SetFormat method, once the application gains the input focus.
Sets the application to a fully cooperative status. Most applications should use this level, since it has the smoothest multi-tasking and resource-sharing behavior.
Sets the application to the priority level. Applications with this cooperative level can call the IDirectSoundBuffer::SetFormat and IDirectSound::Compact methods.
This is the highest priority level. The application has write access to the primary buffers. No secondary buffers in any application can be played.
The application must set the cooperative level by calling this method before its buffers can be played. The recommended cooperative level is DSSCL_NORMAL; use other priority levels when necessary.
Four cooperative levels are defined: normal, priority, exclusive, and write-primary.
The normal cooperative level is the lowest level. At the normal level, the IDirectSoundBuffer::SetFormat and IDirectSound::Compact methods cannot be called. In addition, the application cannot obtain write access to primary buffers. All applications using this cooperative level use a primary buffer format of 22 kHz, monaural sound, and 8-bit samples to make task switching as smooth as possible.
When using a DirectSound object with the priority cooperative level, the application has first priority to hardware resources, such as hardware mixing, and can call IDirectSoundBuffer::SetFormat and IDirectSound::Compact.
When using a DirectSound object with the exclusive cooperative level, the application has all the privileges of the priority level; in addition, when it has the input focus, only this application's buffers are audible. Once the input focus is gained, DirectSound restores the application's preferred wave format, which was defined in the most recent call to IDirectSoundBuffer::SetFormat.
The highest cooperative level is write-primary. When using a DirectSound object with this cooperative level, your application has direct access to the primary sound buffer. In this mode, the application must lock the buffer using the IDirectSoundBuffer::Lock method and write directly into the primary buffer. While this occurs, secondary buffers cannot be played.
When the application is set to the write-primary cooperative level and gains the input focus, all secondary buffers for other applications are stopped and marked as lost. These buffers must be restored using the IDirectSoundBuffer::Restore method before they can be played again. When the application then loses the input focus, its primary buffer is marked as lost and can be restored after the application regains the input focus.
The write-primary level is not required in order to create a primary buffer. However, to obtain access to the audio samples in the primary buffer, the application must have the write-primary level. If the application does not have this level, then all calls to IDirectSoundBuffer::Lock and IDirectSoundBuffer::Play will fail, although some methods, such as IDirectSoundBuffer::GetFormat, IDirectSoundBuffer::SetFormat, and IDirectSoundBuffer::GetVolume, can still be called successfully.