Microsoft DirectX 8.0 |
This interface provides methods for manipulating a Microsoft® DirectX® Media Object (DMO).
IUnknown methods Description QueryInterface Retrieves pointers to supported interfaces. AddRef Increments the reference count. Release Decrements the reference count. IMediaObject methods Description GetStreamCount Retrieves the number of input and output streams. GetInputStreamInfo Retrieves information about a specified input stream. GetOutputStreamInfo Retrieves information about a specified output stream. GetInputType Retrieves a preferred media type for a specified input stream. GetOutputType Retrieves a preferred media type for a specified output stream. SetInputType Sets the media type on an input stream, or tests whether a particular media type is acceptable. SetOutputType Sets the media type on an output stream, or tests whether a particular media type is acceptable. GetInputCurrentType Retrieves the media type that was previously set for an input stream, if any. GetOutputCurrentType Retrieves the media type that was previously set for an output stream, if any. GetInputSizeInfo Retrieves the buffer requirements for a specified input stream. GetOutputSizeInfo Retrieves the buffer requirements for a specified output stream. GetInputMaxLatency Retrieves the maximum latency on a specified input stream. SetInputMaxLatency Sets the maximum latency on a specified input stream. Flush Flushes all internally buffered data. Discontinuity Signals a discontinuity on the specified input stream. AllocateStreamingResources Allocates any resources needed by the DMO. FreeStreamingResources Frees resources allocated by the DMO. GetInputStatus Queries whether a specified input stream can accept more input data. ProcessInput Delivers a buffer to the specified input stream. ProcessOutput Generates output from the current input data. Lock Acquires or releases a lock on the DMO.
Retrieves the number of input and output streams.
Syntax
HRESULT GetStreamCount( DWORD *pcInputStreams, DWORD *pcOutputStreams );
Parameters
- pcInputStreams
- [out] Pointer to a variable that receives the number of input streams. Cannot be NULL.
- pcOutputStreams
- [out] Pointer to a variable that receives the number of output streams. Cannot be NULL.
Return Value
Returns an HRESULT value. Possible values include the following:
S_OK Success E_POINTER NULL pointer argument
Remarks
The DMO might have zero input streams or zero output streams. The number of streams does not change; a DMO cannot dynamically add or remove streams.
Retrieves information about an input stream, such as any restrictions on the number of samples per buffer, and whether the stream performs lookahead on the input data. This information never changes.
Syntax
HRESULT GetInputStreamInfo( DWORD dwInputStreamIndex, DWORD *pdwFlags );
Parameters
- dwInputStreamIndex
- Zero-based index of an input stream on the DMO.
- pdwFlags
- [out] Pointer to a variable that receives a bitwise combination of zero or more DMO_INPUT_STREAM_INFO_FLAGS flags.
Return Value
Returns an HRESULT value. Possible values include the following:
S_OK Success DMO_E_INVALIDSTREAMINDEX Invalid stream index E_POINTER NULL pointer argument
Remarks
The DMO_INPUT_STREAMF_HOLDS_BUFFERS flag indicates that the DMO performs lookahead on the incoming data.
The application must be sure to allocate sufficient buffers for the DMO to process the input. Call the GetInputSizeInfo method to determine the buffer requirements.
Retrieves information about an output stream; for example, whether the stream is discardable, and whether it uses a fixed sample size. This information never changes.
Syntax
HRESULT GetOutputStreamInfo( DWORD dwOutputStreamIndex, DWORD *pdwFlags );
Parameters
- dwOutputStreamIndex
- Zero-based index of an output stream on the DMO.
- pdwFlags
- [out] Pointer to a variable that receives a bitwise combination of zero or more DMO_OUTPUT_STREAM_INFO_FLAGS flags.
Return Value
Returns an HRESULT value. Possible values include the following:
S_OK Success DMO_E_INVALIDSTREAMINDEX Invalid stream index E_POINTER NULL pointer argument
Retrieves a preferred media type for a specified input stream.
Syntax
HRESULT GetInputType( DWORD dwInputStreamIndex, DWORD dwTypeIndex, DMO_MEDIA_TYPE *pmt );
Parameters
- dwInputStreamIndex
- Zero-based index of an input stream on the DMO.
- dwTypeIndex
- Zero-based index on the set of acceptable media types.
- pmt
- [out] Pointer to a DMO_MEDIA_TYPE structure allocated by the caller. The method fills the structure with the media type. The format block might be NULL, in which case the format type GUID is GUID_NULL.
Return Value
Returns an HRESULT value. The following are possible return values.
S_OK Success. DMO_E_INVALIDSTREAMINDEX Invalid stream index. DMO_E_NO_MORE_ITEMS Type index is out of range. E_OUTOFMEMORY Insufficient memory. E_POINTER NULL pointer argument.
Remarks
Call this method to enumerate an input stream's preferred media types. The DMO assigns each media type an index value in order of preference. The most preferred type has an index of zero. To enumerate all the types, make successive calls while incrementing the type index until the method returns DMO_E_NO_MORE_ITEMS.
If the method succeeds, call MoFreeMediaType to free the format block.
To set the media type, call the SetInputType method. Setting the media type on one stream can change another stream's preferred types. In fact, a stream might not have a preferred type until the type is set on another stream. For example, a decoder might not have a preferred output type until the input type is set. However, the DMO is not required to update its preferred types dynamically in this fashion. Thus, the types returned by this method are not guaranteed to be valid; they might fail when used in the SetInputType method. Conversely, the DMO is not guaranteed to enumerate every media type that it supports. To test whether a particular media type is acceptable, call SetInputType with the DMO_SET_TYPEF_TEST_ONLY flag.
Retrieves a preferred media type for a specified output stream.
Syntax
HRESULT GetOutputType( DWORD dwOutputStreamIndex, DWORD dwTypeIndex, DMO_MEDIA_TYPE *pmt );
Parameters
- dwOutputStreamIndex
- Zero-based index of an output stream on the DMO.
- dwTypeIndex
- Zero-based index on the set of acceptable media types.
- pmt
- [out] Pointer to a DMO_MEDIA_TYPE structure allocated by the caller. The method fills the structure with the media type. The format block might be NULL, in which case the format type GUID is GUID_NULL.
Return Value
Returns an HRESULT value. The following are possible return values.
S_OK Success. DMO_E_INVALIDSTREAMINDEX Invalid stream index. DMO_E_NO_MORE_ITEMS Type index is out of range. E_OUTOFMEMORY Insufficient memory. E_POINTER NULL pointer argument.
Remarks
Call this method to enumerate an output stream's preferred media types. The DMO assigns each media type an index value, in order of preference. The most preferred type has an index of zero. To enumerate all the types, make successive calls while incrementing the type index, until the method returns DMO_E_NO_MORE_ITEMS.
If the method succeeds, call MoFreeMediaType to free the format block.
To set the media type, call the SetOutputType method. Setting the media type on one stream can change another stream's preferred types. In fact, a stream might not have a preferred type until the type is set on another stream. For example, a decoder might not have a preferred output type until the input type is set. However, the DMO is not required to update its preferred types dynamically in this fashion. Thus, the types returned by this method are not guaranteed to be valid; they might fail when used in the SetOutputType method. Conversely, the DMO is not guaranteed to enumerate every media type that it supports. To test whether a particular media type is acceptable, call SetOutputType with the DMO_SET_TYPEF_TEST_ONLY flag.
Sets the media type on an input stream, or tests whether a media type is acceptable.
Syntax
HRESULT SetInputType( DWORD dwInputStreamIndex, const DMO_MEDIA_TYPE *pmt, DWORD dwFlags );
Parameters
- dwInputStreamIndex
- Zero-based index of an input stream on the DMO.
- pmt
- [in] Pointer to a DMO_MEDIA_TYPE structure that specifies the media type.
- dwFlags
- Bitwise combination of zero or more flags from the DMO_SET_TYPE_FLAGS enumeration.
Return Value
Returns an HRESULT value. The following are possible return values.
S_OK Media type was set successfully, or is acceptable. S_FALSE Media type is not acceptable. DMO_E_INVALIDSTREAMINDEX Invalid stream index. DMO_E_TYPE_NOT_ACCEPTED Media type was not accepted.
Remarks
Call this method to test, set, or clear the media type on an input stream:
- To test the media type without setting it, use the DMO_SET_TYPEF_TEST_ONLY flag. If the media type is not acceptable, the method returns S_FALSE.
- To set the media type, set dwFlags to zero. If the media type is not acceptable, the method returns DMO_E_TYPE_NOT_ACCEPTED.
- To clear the current media type (if any), use the DMO_SET_TYPEF_CLEAR flag and set pmt to NULL. When the method returns, the stream no longer has a media type. The DMO cannot process samples until the application sets a new media type.
The media types that are currently set on other streams can affect whether the media type is acceptable.
Sets the media type on an output stream, or tests whether a media type is acceptable.
Syntax
HRESULT SetOutputType( DWORD dwOutputStreamIndex, const DMO_MEDIA_TYPE *pmt, DWORD dwFlags );
Parameters
- dwOutputStreamIndex
- Zero-based index of an output stream on the DMO.
- pmt
- [in] Pointer to a DMO_MEDIA_TYPE structure that specifies the media type.
- dwFlags
- Bitwise combination of zero or more flags from the DMO_SET_TYPE_FLAGS enumeration.
Return Value
Returns an HRESULT value. The following are possible return values.
S_OK Media type was set successfully, or is acceptable. S_FALSE Media type is not acceptable. DMO_E_INVALIDSTREAMINDEX Invalid stream index. DMO_E_TYPE_NOT_ACCEPTED Media type was not accepted.
Remarks
Call this method to test, set, or clear the media type on an output stream:
- To test the media type without setting it, use the DMO_SET_TYPEF_TEST_ONLY flag. If the media type is not acceptable, the method returns S_FALSE.
- To set the media type, set dwFlags to zero. If the media type is not acceptable, the method returns DMO_E_TYPE_NOT_ACCEPTED.
- To clear the current media type (if any), use the DMO_SET_TYPEF_CLEAR flag and set pmt to NULL. When the method returns, the stream no longer has a media type. The DMO cannot process samples until the application sets a new media type, unless the stream is optional.
The media types that are currently set on other streams can affect whether the media type is acceptable.
Retrieves the media type that was set for an input stream, if any.
Syntax
HRESULT GetInputCurrentType( DWORD dwInputStreamIndex, DMO_MEDIA_TYPE *pmt );
Parameters
- dwInputStreamIndex
- Zero-based index of an input stream on the DMO.
- pmt
- [out] Pointer to a DMO_MEDIA_TYPE structure allocated by the caller. The method fills the structure with the media type.
Return Value
Returns an HRESULT value. The following are possible return values.
S_OK Success. DMO_E_INVALIDSTREAMINDEX Invalid stream index. DMO_E_TYPE_NOT_SET Media type was not set. E_OUTOFMEMORY Insufficient memory.
Remarks
The caller must set the media type for the stream before calling this method. To set the media type, call the SetInputType method.
If the method succeeds, call MoFreeMediaType to free the format block.
Retrieves the media type that was set for an output stream, if any.
Syntax
HRESULT GetOutputCurrentType( DWORD dwOutputStreamIndex, DMO_MEDIA_TYPE *pmt );
Parameters
- dwOutputStreamIndex
- Zero-based index of an output stream on the DMO.
- pmt
- [out] Pointer to a DMO_MEDIA_TYPE structure allocated by the caller. The method fills the structure with the media type.
Return Value
Returns an HRESULT value. The following are possible return values.
S_OK Success. DMO_E_INVALIDSTREAMINDEX Invalid stream index. DMO_E_TYPE_NOT_SET Media type was not set. E_OUTOFMEMORY Insufficient memory.
Remarks
The caller must set the media type for the stream before calling this method. To set the media type, call the SetOutputType method.
If the method succeeds, call MoFreeMediaType to free the format block.
Retrieves the buffer requirements for a specified input stream.
Syntax
HRESULT GetInputSizeInfo( DWORD dwInputStreamIndex, DWORD *pcbSize, DWORD *pcbMaxLookahead, DWORD *pcbAlignment );
Parameters
- dwInputStreamIndex
- Zero-based index of an input stream on the DMO.
- pcbSize
- [out] Pointer to a variable that receives the minimum size of an input buffer for this stream, in bytes.
- pcbMaxLookahead
- [out] Pointer to a variable that receives the maximum amount of data that the DMO will hold for lookahead, in bytes. If the DMO does not perform lookahead on the stream, the value is zero.
- pcbAlignment
- [out] Pointer to a variable that receives the required buffer alignment, in bytes. If the input stream has no alignment requirement, the value is 1.
Return Value
Returns an HRESULT value. The following are possible return values.
S_OK Success. DMO_E_INVALIDSTREAMINDEX Invalid stream index. DMO_E_TYPE_NOT_SET Media type was not set.
Remarks
The buffer requirements may depend on the media types of the various streams. Before calling this method, set the media type of each stream by calling the SetInputType and SetOutputType methods. If the media types have not been set, this method might return an error.
If the DMO performs lookahead on the input stream, it returns the DMO_INPUT_STREAMF_HOLDS_BUFFERS flag in the GetInputStreamInfo method. During processing, the DMO holds up to the number of bytes indicated by the pcbMaxLookahead parameter. The application must allocate enough buffers for the DMO to hold this much data.
A buffer is aligned if the buffer's start address is a multiple of *pcbAlignment. The alignment must be a power of two. Depending on the microprocessor, reads and writes to an aligned buffer might be faster than to an unaligned buffer. Also, some microprocessors do not support unaligned reads and writes.
Retrieves the buffer requirements for a specified output stream.
Syntax
HRESULT GetOutputSizeInfo( DWORD dwOutputStreamIndex, DWORD *pcbSize, DWORD *pcbAlignment );
Parameters
- dwOutputStreamIndex
- Zero-based index of an output stream on the DMO.
- pcbSize
- [out] Pointer to a variable that receives the minimum size of an output buffer for this stream, in bytes.
- pcbAlignment
- [out] Pointer to a variable that receives the required buffer alignment, in bytes. If the output stream has no alignment requirement, the value is 1.
Return Value
Returns an HRESULT value. The following are possible return values.
S_OK Success. DMO_E_INVALIDSTREAMINDEX Invalid stream index. DMO_E_TYPE_NOT_SET Media type was not set.
Remarks
The buffer requirements may depend on the media types set for each of the streams.
Before calling this method, set the media type of each stream by calling the SetInputType and SetOutputType methods. If the media types have not been set, this method might return an error. However, if a stream is optional, and the application will not use the stream, you do not have to set the media type for the stream.
A buffer is aligned if the buffer's start address is a multiple of *pcbAlignment. Depending on the architecture of the microprocessor, it is faster to read and write to an aligned buffer than to an unaligned buffer. On some microprocessors, reading and writing to an unaligned buffer is not supported and can cause the program to crash. Zero is not a valid alignment.
Retrieves the maximum latency on a specified input stream.
Syntax
HRESULT GetInputMaxLatency( DWORD dwInputStreamIndex, REFERENCE_TIME *prtMaxLatency );
Parameters
- dwInputStreamIndex
- Zero-based index of an input stream on the DMO.
- prtMaxLatency
- [out] Pointer to a variable that receives the maximum latency.
Return Value
Returns an HRESULT value. The following are possible return values.
S_OK Success. DMO_E_INVALIDSTREAMINDEX Invalid stream index. E_FAIL Failure. E_NOTIMPL Not implemented. Assume zero latency.
The latency is the difference between a time stamp on the input stream and the corresponding time stamp on the output stream. The maximum latency is the largest possible difference in the time stamps. For a DMO, determine the maximum latency as follows:
Under this definition, latency does not include the time that it takes to process samples. Nor does it include any latency introduced by the size of the input buffer.
For the special case where a DMO processes exactly one sample at a time, the maximum latency is simply the difference in time stamps.
Latency is defined only when samples have time stamps, and the time stamps increase or decrease monotonically. Maximum latency might depend on the media types for the input and output streams.
Sets the maximum latency on a specified input stream. For the definition of maximum latency, see GetInputMaxLatency.
Syntax
HRESULT SetInputMaxLatency( DWORD dwInputStreamIndex, REFERENCE_TIME rtMaxLatency );
Parameters
- dwInputStreamIndex
- Zero-based index of an input stream on the DMO.
- rtMaxLatency
- Maximum latency.
Return Value
Returns an HRESULT value. The following are possible return values.
S_OK Success DMO_E_INVALIDSTREAMINDEX Invalid stream index E_FAIL Failure E_NOTIMPL Not implemented
Flushes all internally buffered data.
Syntax
HRESULT Flush(void);
Return Value
Returns S_OK if successful. Otherwise, returns an HRESULT value indicating the cause of the error.
Remarks
The DMO performs the following actions when this method is called:
- Releases any IMediaBuffer references it holds.
- Discards any values that specify the time stamp or sample length for a media buffer.
- Reinitializes any internal states that depend on the contents of a media sample.
Media types, maximum latency, and locked state do not change.
When the method returns, every input stream accepts data. Output streams cannot produce any data until the application calls the ProcessInput method on at least one input stream.
Signals a discontinuity on the specified input stream.
Syntax
HRESULT Discontinuity( DWORD dwInputStreamIndex );
Parameters
- dwInputStreamIndex
- Zero-based index of an input stream on the DMO.
Return Value
Returns an HRESULT value. The following are possible return values.
S_OK Success DMO_E_INVALIDSTREAMINDEX Invalid stream index
Remarks
A discontinuity represents a break in the input. A discontinuity might occur because no more data is expected, the format is changing, or there is a gap in the data. After a discontinuity, the DMO does not accept further input on that stream until all pending data has been processed. The application should call the ProcessOutput method until none of the streams returns the DMO_OUTPUT_DATA_BUFFERF_INCOMPLETE flag.
Allocates any resources needed by the DMO. Calling this method is always optional.
Syntax
HRESULT AllocateStreamingResources(void);
Return Value
Returns S_OK if successful. Otherwise, returns an HRESULT value indicating the cause of the error.
Remarks
An application can call this method as a streaming optimization. It gives the DMO an opportunity to perform any time-consuming initializations before streaming begins. If you call this method, do so after you set the media types on the DMO, but before you make the first calls to ProcessInput or ProcessOutput.
This method is optional in the following sense:
- If the DMO does not support this method, the method returns S_OK.
- If the application never calls this method, the DMO allocates resources within a call to ProcessInput or ProcessOutput.
If the DMO supports this method, it should also support the FreeStreamingResources method.
Frees resources allocated by the DMO. Calling this method is always optional.
Syntax
HRESULT FreeStreamingResources(void);
Return Value
Returns S_OK if successful. Otherwise, returns an HRESULT value indicating the cause of the error.
Remarks
This method releases any resources that the AllocateStreamingResources method initializes.
If the DMO does not support this method, the method returns S_OK. If you call this method during streaming, the method fails and the DMO does not release any resources.
Regardless of whether the method fails or succeeds, the application can continue to call other methods on the DMO. The DMO might need to re-initialize resources that were previously freed.
Queries whether an input stream can accept more input data.
Syntax
HRESULT GetInputStatus( DWORD dwInputStreamIndex, DWORD *dwFlags );
Parameters
- dwInputStreamIndex
- Zero-based index of an input stream on the DMO.
- dwFlags
- [out] Pointer to a variable that receives either zero or DMO_INPUT_STATUSF_ACCEPT_DATA.
Return Value
Returns an HRESULT value. The following are possible return values.
S_OK Success DMO_E_INVALIDSTREAMINDEX Invalid stream index
Remarks
If the input stream will accept more data, the method returns the DMO_INPUT_STATUSF_ACCEPT_DATA flag in the dwFlags parameter. Otherwise, it sets this parameter to zero. If the stream will accept more data, the application can call the ProcessInput method.
The status of an input stream can change only as the result of one of the following method calls:
Delivers a buffer to the specified input stream.
Syntax
HRESULT ProcessInput( DWORD dwInputStreamIndex, IMediaBuffer *pBuffer, DWORD dwFlags, REFERENCE_TIME rtTimestamp, REFERENCE_TIME rtTimelength );
Parameters
- dwInputStreamIndex
- Zero-based index of an input stream on the DMO.
- pBuffer
- Pointer to the buffer's IMediaBuffer interface.
- dwFlags
- Bitwise combination of zero or more flags from the DMO_INPUT_DATA_BUFFER_FLAGS enumeration.
- rtTimestamp
- Time stamp that specifies the start time of the data in the buffer. If the buffer has a valid time stamp, set the DMO_INPUT_DATA_BUFFERF_TIME flag in the dwFlags parameter. Otherwise, the DMO ignores this value.
- rtTimelength
- Reference time specifying the duration of the data in the buffer. If this value is valid, set the DMO_INPUT_DATA_BUFFERF_TIMELENGTH flag in the dwFlags parameter. Otherwise, the DMO ignores this value.
Return Value
Returns an HRESULT value. The following are possible return values.
S_FALSE No output to process. S_OK Success. DMO_E_INVALIDSTREAMINDEX Invalid stream index. DMO_E_NOTACCEPTING Data cannot be accepted.
Remarks
If the DMO does not process all the data in the buffer, it keeps a reference count on the buffer. It releases the buffer once it has generated all the output, unless it needs to perform lookahead on the data. (To determine whether a DMO performs lookahead, call the GetInputStreamInfo method.)
If this method returns DMO_E_NOTACCEPTING, call the ProcessOutput method until the input stream can accept more data. To determine whether the stream can accept more data, call the GetInputStatus method.
If the method returns S_FALSE, no output was generated from this input and the application does not need to call ProcessOutput. However, a DMO is not required to return S_FALSE in this situation; it might return S_OK.
Generates output from the current input data.
Syntax
HRESULT ProcessOutput( DWORD dwFlags, DWORD cOutputBufferCount, DMO_OUTPUT_DATA_BUFFER *pOutputBuffers, DWORD *pdwStatus );
Parameters
- dwFlags
- Bitwise combination of zero or more flags from the DMO_PROCESS_OUTPUT_FLAGS enumeration.
- cOutputBufferCount
- Number of output buffers.
- pOutputBuffers
- [in, out] Pointer to an array of DMO_OUTPUT_DATA_BUFFER structures containing the output buffers. Specify the size of the array in the cOutputBufferCount parameter.
- pdwStatus
- [out] Pointer to a variable that receives a reserved value (zero). The application should ignore this value.
Return Value
Returns an HRESULT value. The following are possible return values.
S_FALSE No output was generated. S_OK Success. E_FAIL Failure. E_INVALIDARG Invalid argument. E_POINTER NULL pointer argument.
Remarks
The pOutputBuffers parameter points to an array of DMO_OUTPUT_DATA_BUFFER structures. The application must allocate one structure for each output stream. To determine the number of output streams, call the GetStreamCount method. Set the cOutputBufferCount parameter to this number.
Each DMO_OUTPUT_DATA_BUFFER structure contains a pointer to a buffer's IMediaBuffer interface. The application allocates these buffers. The other members of the structure are status fields. The DMO sets these fields if the method succeeds. If the method fails, their values are undefined.
When the application calls ProcessOutput, the DMO processes as much input data as possible. It writes the output data to the output buffers, starting from the end of the data in each buffer. (To find the end of the data, call the IMediaBuffer::GetBufferAndLength method.) The DMO never holds a reference count on an output buffer.
If the DMO fills an entire output buffer and still has input data to process, the DMO returns the DMO_OUTPUT_DATA_BUFFERF_INCOMPLETE flag in the DMO_OUTPUT_DATA_BUFFER structure. The application should check for this flag by testing the dwStatus member of each structure.
If the method returns S_FALSE, no output was generated. However, a DMO is not required to return S_FALSE in this situation; it might return S_OK.
Discarding data:
You can discard data from a stream by setting the DMO_PROCESS_OUTPUT_DISCARD_WHEN_NO_BUFFER flag in the dwFlags parameter. For each stream that you want to discard, set the pBuffer member of the DMO_OUTPUT_DATA_BUFFER structure to NULL.
For each stream in which pBuffer is NULL:
- If the DMO_PROCESS_OUTPUT_DISCARD_WHEN_NO_BUFFER flag is set, and the stream is discardable or optional, the DMO discards the data.
- If the flag is set but the stream is neither discardable nor optional, the DMO discards the data if possible. It is not guaranteed to discard the data.
- If the flag is not set, the DMO does not produce output data for that stream, but does not discard the data.
To check whether a stream is discardable or optional, call the GetOutputStreamInfo method.
Acquires or releases a lock on the DMO. Call this method to keep the DMO serialized when performing multiple operations.
Syntax
HRESULT Lock( LONG bLock );
Parameters
- bLock
- Value that specifies whether to acquire or release the lock. If the value is non-zero, a lock is acquired. If the value is zero, the lock is released.
Return Value
Returns an HRESULT value. The following are possible return values.
S_OK Success E_FAIL Failure
Remarks
This method prevents other threads from calling methods on the DMO. If another thread calls a method on the DMO, the thread blocks until the lock is released.