Play Buffer Notification

[The feature associated with this page, DirectSound, is a legacy feature. It has been superseded by WASAPI and Audio Graphs. Media Casting have been optimized for Windows 10 and Windows 11. Microsoft strongly recommends that new code use Media Casting instead of DirectSound, when possible. Microsoft suggests that existing code that uses the legacy APIs be rewritten to use the new APIs if possible.]

DirectSound can notify your application when the play cursor reaches certain points in a buffer, or when the buffer stops. This can be useful in two common situations:

• The application must take some action, such as playing another buffer, when a sound has finished playing.

• The application is streaming data to the buffer, and needs to know when the play cursor reaches predefined points so that data that has been played can be replaced by new data.

If you are taking advantage of voice management, it's possible that a buffer could be terminated before a notification position is reached. See the Remarks for DSBPOSITIONNOTIFY.

Using the IDirectSoundNotify8::SetNotificationPositions method, you can set any number of points within the buffer where events are to be signaled. You cannot do this while the buffer is playing.

First you obtain a pointer to the IDirectSoundNotify8 interface. You can do this by using the buffer object's QueryInterface method. A separate interface must be obtained from each buffer on which you want to set notifications.

For each notification position, create an event object with the Win32 CreateEvent function. Put the handle to this event in the hEventNotify member of a DSBPOSITIONNOTIFY structure. In the dwOffset member of that structure, specify the offset within the buffer where you want the event to be signaled. Then pass the address of the structure-or of an array of structures, if you want to set more than one notification position-to SetNotificationPositions.

The following example function sets a single notification position. The event will be signaled when playback stops, either because the end of a nonlooping buffer has been reached, or because the application called the IDirectSoundBuffer8::Stop method. Assume that hMyEvent is a handle returned by CreateEvent and that lpDsbSecondary is a secondary buffer created with the DSBCAPS_CTRLPOSITIONNOTIFY flag.

HRESULT SetStopNotification(HANDLE hMyEvent, 
        LPDIRECTSOUNDBUFFER8 lpDsbSecondary)
{
  LPDIRECTSOUNDNOTIFY8 lpDsNotify; 
  DSBPOSITIONNOTIFY PositionNotify;
  HRESULT hr;

  if (SUCCEEDED(
      hr = lpDsbSecondary->QueryInterface(IID_IDirectSoundNotify8,
             (LPVOID*)&lpDsNotify))) 
  { 
    PositionNotify.dwOffset = DSBPN_OFFSETSTOP;
    PositionNotify.hEventNotify = hMyEvent;
    hr = lpDsNotify->SetNotificationPositions(1, &PositionNotify);
    lpDsNotify->Release();
  }
  return hr;
}

Notifications for hardware-controlled buffers are not provided reliably by all drivers; some may generate false notifications. To work around this problem, you can call IDirectSoundBuffer8::GetCurrentPosition whenever your application receives a notification, to be sure that the notification position has actually been reached. Another solution is to create the buffer in software.