IDirectSoundCaptureBuffer::Lock

  • Article

This method locks the buffer. Locking the buffer returns pointers into the buffer, allowing the application to read or write audio data into that memory.

HRESULT Lock( 
  DWORD dwReadCursor, 
  DWORD dwReadBytes, 
  LPVOID* lplpvAudioPtr1, 
  LPDWORD lpdwAudioBytes1, 
  LPVOID* lplpvAudioPtr2, 
  LPDWORD lpdwAudioBytes2, 
  DWORD dwFlags 
);

Parameters

  • dwReadCursor
    Offset, in bytes, from the start of the buffer to where the lock begins.
  • dwReadBytes
    Size, in bytes, of the portion of the buffer to lock. Note that the capture buffer is conceptually circular.
  • lplpvAudioPtr1
    Address of a pointer to contain the first block of the capture buffer to be locked.
  • lpdwAudioBytes1
    Address of a variable to contain the number of bytes pointed to by the lplpvAudioPtr1 parameter. If this value is less than the dwReadBytes parameter, lplpvAudioPtr2 will point to a second block of data.
  • lplpvAudioPtr2
    Address of a pointer to contain the second block of the capture buffer to be locked. If the value of this parameter is NULL, the lplpvAudioPtr1 parameter points to the entire locked portion of the capture buffer.
  • lpdwAudioBytes2
    Address of a variable to contain the number of bytes pointed to by the lplpvAudioPtr2 parameter. If lplpvAudioPtr2 is NULL, this value will be 0.
  • dwFlags
    Flags modifying the lock event. This value can be zero or the following flag:
    Flag Description
    DSCBLOCK_ENTIREBUFFER The dwReadBytes parameter is to be ignored and the entire capture buffer is to be locked.

Return Values

If the method succeeds, the return value is DS_OK.

If the method fails, the return value may be one of the following values:

DSERR_INVALIDPARAM
DSERR_INVALIDCALL

Remarks

This method accepts an offset and a byte count, and returns two read pointers and their associated sizes. Two pointers are required because capture buffers are circular. If the locked bytes do not wrap around the end of the buffer, the second pointer, lplpvAudioBytes2, will be NULL. However, if the bytes do wrap around, then the second pointer will point to the beginning of the buffer.

If the application passes NULL for the lplpvAudioPtr2 and lpdwAudioBytes2 parameters, DirectSoundCapture will not lock the wraparound portion of the buffer.

The application should read data from the pointers returned by the IDirectSoundCaptureBuffer::Lock method and then call the IDirectSoundCaptureBuffer::Unlock method to release the buffer back to DirectSoundCapture. The sound buffer should not be locked for long periods of time; if it is, the capture cursor will reach the locked bytes and configuration-dependent audio problems may result.

Requirements

OS Versions: Windows CE 2.12 and later. Version 2.12 requires DXPAK 1.0 or later.
Header: Dsound.h.
Link Library: Dsound.lib.

See Also

IDirectSoundCaptureBuffer::Unlock

 Last updated on Thursday, April 08, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.