Microsoft Windows CE 3.0  

IDsCaptureDriverBuffer::Lock

Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

The IDsCaptureDriverBuffer::Lockmethod is called to obtain a valid read pointer to the sound buffer's audio data.

HRESULT Lock(
LPLPVOID
ppvAudio1
,
LPDWORD
pdwLen1
,
LPLPVOID
ppvAudio2
,
LPDWORD
pdwLen2
,
DWORD
dwWritePosition
,
DWORD
dwWriteLen
,
DWORD
dwFlags
);

Parameters

ppvAudio1
Pointer to a value that the driver must fill in with a pointer to the first block of sound data.
pdwLen1
Pointer to a doubleword that the driver must fill in with the number of bytes pointed to by *ppvAudio1.
ppvAudio2
Pointer to a value that the driver must fill in with a pointer to the second block of sound data. If the first block (pointed to by *ppvAudio1) points to the entire block of requested data, this value should be set to NULL.
pdwLen2
Pointer to a doubleword that the driver must fill in with the number of bytes pointed to by *ppvAudio2. If *ppvAudio2is NULL, this value must be set to zero.
dwWritePosition
The position relative to the start of the buffer that should be locked, and therefore subject to change by the locking application.
dwWriteLen
The number of bytes relative to the write position that will be locked, and therefore subject to change by the locking application.
dwFlags
No flags are currently defined. This value will always be 0.

Return Values

Returns DS_OK if successful, or one of the following error values otherwise:

  • DSERR_INVALIDCALL
  • DSERR_INVALIDPARAM
  • DSERR_BUFFERLOST

    Remarks

    This method accepts an offset and a count of bytes, and the driver returns two write pointers and their associated sizes. Two pointers are required because sound buffers are circular. If the locked bytes do not wrap around the end of the buffer, the second pointer ( *ppvAudio2) should be NULL. However, if the bytes do wrap around, the second pointer should point to the beginning of the buffer.

    For some devices (such as DMA-based cards that do not support hardware secondary buffers), repeated calls to IDsCaptureDriverBuffer::Lockand IDsCaptureDriverBuffer::Unlockare unnecessary. In this case, the driver should specify the DSDCAPS_DONTNEEDLOCK flag in the DSDRIVERDESCstructure returned by IDsCaptureDriver::GetDriverDescmethod. If this flag is specified, then the IDsCaptureDriverBuffer::Lockmethod is never called by DirectSound. In that case, the IDsCaptureDriverBuffer::Lockmethod should simply return DSERR_UNSUPPORTED.



     Last updated on Tuesday, July 13, 2004

    © 2004 Microsoft Corporation. All rights reserved.