CDynamicOutputPin Class

Microsoft DirectShow 9.0

CDynamicOutputPin Class

The CDynamicOutputPin class implements an output pin that supports dynamic reconnections and format changes.

This class derives from the CBaseOutputPin class and implements the IPinFlowControl interface. It supports several operations that are important for dynamic graph building:

• Dynamic reconnection: The pin can disconnect and reconnect while the filter is still active (paused or running).
• Dynamic format change: The pin can negotiate a new media type while the filter is still active, without reconnecting.
• Flow control: The owning filter (or an application) can block data flow from the pin without stopping the filter.

For more information, see Dynamic Graph Building.

The pin has three possible states: blocked, unblocked, and pending. In the pending state, the pin is waiting for some operation to complete on another thread, before the pin switches to the blocked state. While the pin is blocked, the filter cannot deliver data through the pin, or change the pin's connection.

To coordinate among multiple threads, the owning filter must follow certain rules. (For more information about threads in the filter graph, see Threads and Critical Sections.) First, the streaming thread must always call the CDynamicOutputPin::StartUsingOutputPin method before it calls any of the following methods:

• CDynamicOutputPin::ChangeOutputFormat
• CDynamicOutputPin::ChangeMediaType
• CDynamicOutputPin::DynamicReconnect
• CBaseOutputPin::Deliver
• CBaseOutputPin::DeliverEndOfStream
• CBaseOutputPin::DeliverNewSegment
• IMemInputPin::Receive
• IMemInputPin::ReceiveMultiple
• IPin::EndOfStream
• IPin::NewSegment

Afterward, it must call the CDynamicOutputPin::StopUsingOutputPin method.

Second, the application thread must not call any of the methods in the previous list. Third, the streaming thread must not call the class methods that block or unblock the pin. These methods are: CDynamicOutputPin::Block, CDynamicOutputPin::SynchronousBlockOutputPin, CDynamicOutputPin::AsynchronousBlockOutputPin, and CDynamicOutputPin::UnblockOutputPin.

These rules ensure that the application thread cannot block the pin while the streaming thread is using it, and vice versa. After the streaming thread has called StartUsingOutputPin, the pin will not block until the streaming thread calls StopUsingOutputPin. Conversely, if the pin is blocked, StartUsingOutputPin waits until the pin is unblocked.

To avoid forgetting to call StopUsingOutputPin, you can use the CAutoUsingOutputPin class. It calls StopUsingOutputPin automatically when it goes out of scope.

When the owning filter joins or leaveds the filter graph (in its IBaseFilter::JoinFilterGraph method), it must call the pin's CDynamicOutputPin::SetConfigInfo method.

Requirements

**  Header:** Declared in Amfilter.h; include Streams.h.

**  Library:** Use Strmbase.lib (retail builds) or Strmbasd.lib (debug builds).

Protected Member Variables	Description
m_BlockStateLock	Critical section that protects the blocking state.
m_hUnblockOutputPinEvent	Event that is signaled when the pin is not blocked.
m_hNotifyCallerPinBlockedEvent	Event that is signaled when the pin successfully blocks, or the user cancels a pending block.
m_BlockState	Blocking state.
m_dwBlockCallerThreadID	The identifier of the thread that last called the IPinFlowControl::Block method on this pin.
m_dwNumOutstandingOutputPinUsers	Number of streaming threads using this pin.
m_hStopEvent	Event that is signaled when the filter stops or the pin flushes data.
m_pGraphConfig	Pointer to the IGraphConfig interface for performing dynamic reconnections.
m_bPinUsesReadOnlyAllocator	Flag that specifies whether samples from the pin's allocator are read-only.
Protected Methods
SynchronousBlockOutputPin	Blocks the pin; does not return until the pin is blocked.
AsynchronousBlockOutputPin	Blocks the pin; might return before the pin is blocked.
UnblockOutputPin	Unblocks the pin.
BlockOutputPin	Blocks the pin.
WaitEvent	Waits until the specified event is signaled.
Public Methods
CDynamicOutputPin	Constructor method.
~CDynamicOutputPin	Destructor method.
SetConfigInfo	Specifies the IGraphConfig pointer and the stop event.
DeliverBeginFlush	Requests the connected input pin to begin a flush operation.
DeliverEndFlush	Requests the connected input pin to end a flush operation.
Inactive	Notifies the pin that the filter has stopped.
Active	Notifies the pin that the filter is now active.
CompleteConnect	Completes a connection to an input pin. Virtual.
StartUsingOutputPin	Obtains access to the pin for a streaming operation. Virtual.
StopUsingOutputPin	Releases access to the pin after a streaming operation. Virtual.
StreamingThreadUsingOutputPin	Determines whether any thread is performing a streaming operation on the pin. Virtual.
ChangeOutputFormat	Dynamically changes the media type for the connection, and delivers new segment information.
ChangeMediaType	Dynamically changes the media type for the connection.
DynamicReconnect	Performs a dynamic reconnection with a new media type.
IPin Methods
Disconnect	Breaks the current pin connection.
IPinFlowControl Methods
Block	Blocks or unblocks the flow of data from the pin.