 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 IDsDriverBuffer::Lockmethod is called to obtain a valid write 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 IDsDriverBuffer::Lockand IDsDriverBuffer::Unlockare unnecessary. In this case, the driver should specify the DSDCAPS_DONTNEEDLOCK flag in the DSDRIVERDESCstructure returned by IDsDriver::GetDriverDescmethod. If this flag is specified, then the IDsDriverBuffer::Lockmethod is never called by DirectSound. In that case, the IDsDriverBuffer::Lockmethod should simply return DSERR_UNSUPPORTED.
Last updated on Tuesday, July 13, 2004