IPinFlowControl::Block method (strmif.h)
[The feature associated with this page, DirectShow, is a legacy feature. It has been superseded by MediaPlayer, IMFMediaEngine, and Audio/Video Capture in Media Foundation. Those features have been optimized for Windows 10 and Windows 11. Microsoft strongly recommends that new code use MediaPlayer, IMFMediaEngine and Audio/Video Capture in Media Foundation instead of DirectShow, when possible. Microsoft suggests that existing code that uses the legacy APIs be rewritten to use the new APIs if possible.]
The Block method blocks or unblocks the flow of data from the pin.
Syntax
HRESULT Block(
[in] DWORD dwBlockFlags,
[in] HANDLE hEvent
);
Parameters
[in] dwBlockFlags
Flag that indicates whether to block or unblock the pin. Must be one of the following values:
- Zero: Unblock data flow from the pin.
- AM_PIN_FLOW_CONTROL_BLOCK: Block data flow from the pin.
[in] hEvent
Handle to an event object, or NULL. If this parameter is non-NULL, the method is asynchronous and returns immediately. The event is signaled when the operation completes. If this parameter is NULL, the method is synchronous and does not complete until the pin is blocked. If dwBlockFlags is zero, this parameter must be NULL.
Return value
Returns an HRESULT value. Possible values include the following.
| Return code | Description |
|---|---|
|
Pin is already unblocked. |
|
Success. |
|
Pin is already blocked on another thread. |
|
Pin is already blocked on the calling thread. |
Remarks
This method can be synchronous or asynchronous:
- To call it asynchronously, use the CreateEvent function to create an event object. Pass the event handle in the hEvent parameter. The method returns immediately and signals the event when the operation has completed. Call a wait function such as WaitForSingleObject to wait for the event.
- To call this method synchronously, set the hEvent parameter to NULL. The method blocks until it completes. The method might not complete until the pin is ready to deliver a sample. If the filter is paused, the method might block indefinitely. Therefore, you should not call this method synchronously from your main application thread.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows XP [desktop apps only] |
| Minimum supported server | Windows Server 2003 [desktop apps only] |
| Target Platform | Windows |
| Header | strmif.h (include Dshow.h) |
| Library | Strmiids.lib |