IDirectSoundBuffer::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 IDirectSoundBuffer::Lockmethod obtains a valid write pointer to the sound buffer's audio data.

HRESULT Lock(
DWORD
dwWriteCursor
,
DWORD
dwWriteBytes
,
LPVOID
lplpvAudioPtr1
,
LPDWORD
lpdwAudioBytes1
,
LPVOID
lplpvAudioPtr2
,
LPDWORD
lpdwAudioBytes2
,
DWORD
dwFlags
);

Parameters

dwWriteCursor

Offset, in bytes, from the start of the buffer to where the lock begins. This parameter is ignored if DSBLOCK_FROMWRITECURSOR is specified in the dwFlagsparameter.

dwWriteBytes

Size, in bytes, of the portion of the buffer to lock. Note that the sound buffer is conceptually circular.

lplpvAudioPtr1

Address of a pointer to contain the first block of the sound buffer to be locked.

lpdwAudioBytes1

Address of a variable to contain the number of bytes pointed to by the lplpvAudioPtr1parameter. If this value is less than the dwWriteBytesparameter, lplpvAudioPtr2will point to a second block of sound data.

lplpvAudioPtr2

Address of a pointer to contain the second block of the sound buffer to be locked. If the value of this parameter is NULL, the lplpvAudioPtr1parameter points to the entire locked portion of the sound buffer.

lpdwAudioBytes2

Address of a variable to contain the number of bytes pointed to by the lplpvAudioPtr2parameter. If lplpvAudioPtr2is NULL, this value will be 0.

dwFlags

Flags modifying the lock event. The following flags are defined:

Flag	Description
DSBLOCK_FROMWRITECURSOR	Locks from the current write position, making a call to IDirectSoundBuffer::GetCurrentPositionunnecessary. If this flag is specified, the dwWriteCursorparameter is ignored.
DSBLOCK_ENTIREBUFFER	Locks the entire buffer. The dwWriteBytesparameter is ignored.

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 error values:

DSERR_BUFFERLOST

DSERR_INVALIDCALL

DSERR_INVALIDPARAM

DSERR_PRIOLEVELNEEDED

Remarks

This method accepts an offset and a byte count, and 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, 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 lplpvAudioPtr2and lpdwAudioBytes2parameters, DirectSound will not lock the wraparound portion of the buffer.

The application should write data to the pointers returned by the IDirectSoundBuffer::Lockmethod, and then call the IDirectSoundBuffer::Unlockmethod to release the buffer back to DirectSound. The sound buffer should not be locked for long periods of time; if it is, the play cursor will reach the locked bytes and configuration-dependent audio problems, possibly random noise, will result.

Warning This method returns a write pointer only. The application should not try to read sound data from this pointer; the data might not be valid even though the DirectSoundBuffer object contains valid sound data. For example, if the buffer is located in on-board memory, the pointer might be an address to a temporary buffer in main system memory. When IDirectSoundBuffer::Unlockis called, this temporary buffer will be transferred to the on-board memory.

Requirements

Runs On	Versions	Defined in	Include	Link to
Windows CE OS	2.12 or later. Version 2.12 requires DXPAK 1.0 or later.	dsound.h		dsound.lib

Note This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.