Microsoft DirectX 8.0

IPinConnection Interface

This interface provides methods for reconnecting an input pin while the filter is still running. The filter graph calls methods on this interface when it performs dynamic reconnections (see the IGraphConfig interface). For more information, see Dynamic Graph Building.

Filter developers: Implement this interface on any input pin that allows dynamic reconnection or dynamic changes in format.

Methods in Vtable Order

IUnknown methodsDescription
QueryInterfaceRetrieves pointers to supported interfaces.
AddRefIncrements the reference count.
ReleaseDecrements the reference count.
IPinConnection methodsDescription
DynamicQueryAcceptQueries whether the pin can accept the specified media type while the graph is running with the current connection to this pin.
NotifyEndOfStreamRequests notification from the pin when the next end-of-stream condition occurs.
IsEndPinIndicates whether a reconnection search should end at this pin.
DynamicDisconnectDisconnects the pin when the filter is running.

IPinConnection::DynamicDisconnect

IPinConnection Interface

Disconnects the pin when the filter is active (paused or running). Call this method instead of IPin::Disconnect to disconnect a pin on an active filter.

Syntax

HRESULT DynamicDisconnect(void)

Return Value

If the pin was connected and the method succeeds, the return value is S_OK. If the pin was not connected, the return value is S_FALSE.

If the method fails, it returns an HRESULT value indicating the cause of the error.

IPinConnection::DynamicQueryAccept

IPinConnection Interface

Queries whether the pin can accept the specified media type while the graph is running with the current connection to this pin.

Syntax

HRESULT DynamicQueryAccept(
    const AM_MEDIA_TYPE *pmt
);

Parameters

pmt
[in] Pointer to an AM_MEDIA_TYPE structure that specifies the media type.

Return Value

Returns one of the following HRESULT values.

S_OKMedia type is acceptable.
VFW_E_TYPE_NOT_ACCEPTEDMedia type is not acceptable.

Remarks

If this method succeeds, the pin can accept the media type on the next sample or in a call to IPin::ReceiveConnection.

An application or filter can call this method to determine whether the filter graph must be reconfigured. If the pin can accept the specified media type, there is no need to reconfigure the graph.

Although the IPin::QueryAccept method also determines whether a pin can accept a format type, it does not guarantee that the pin can switch to that format while the filter is running. If you need to switch formats while the filter is running, call DynamicQueryAccept instead.

IPinConnection::IsEndPin

IPinConnection Interface

Indicates whether a reconnection search should end at this pin.

Syntax

HRESULT IsEndPin(void);

Return Value

If successful, returns one of the following HRESULT values.

S_FALSEMedia type is not acceptable.
S_OKMedia type is acceptable.

Otherwise, returns an error code indicating the error that occurred.

Remarks

A filter or application can call this method to determine whether the pin is a candidate for dynamic reconnection.

Generally, a sink filter or a filter that splits or merges data should return S_OK. Other filters (for example, simple transform filters) should return S_FALSE.

IPinConnection::NotifyEndOfStream

IPinConnection Interface

Requests notification from the pin when the next end-of-stream condition occurs.

Syntax

HRESULT NotifyEndOfStream(
    HANDLE hNotifyEvent
);

Parameters

hNotifyEvent
[in] Handle to an event object that the pin will signal.

Return Value

Returns one of the following HRESULT values if successful.

S_FALSEEvent handle was NULL, but there was no existing event handle to reset.
S_OKEvent handle was set. (If event handle was NULL, event notification was canceled.)

Otherwise, returns an error code indicating the error that occurred.

Remarks

This method enables the caller to push data through a portion of the filter graph ending with this pin.

For example, suppose the caller is pushing data from an output pin called "A" on one filter, to an input pin called "B" on another filter, possibly with intermediate filters connecting them. The following sequence of events would take place.

  1. The caller blocks the data flow at pin A.
  2. It calls IPinConnection::NotifyEndOfStream on pin B.
  3. It calls IPin::EndOfStream on the input pin connected to pin A.
  4. As the remaining data travels downstream through any intermediate filters, those filters propagate the end-of-stream notification.
  5. When pin B receives the end-of-stream notification, it signals the event given in the hNotifyEvent parameter. At that point, the caller can safely reconfigure the graph between pin A and pin B.

Because the purpose of this method is to enable the caller to rebuild the graph dynamically and then restart the connection, the end-of-stream notification does not represent the actual end of the stream. Therefore, pin B does not propagate the end-of-stream condition or signal EC_COMPLETE. This is an exception to the usual rules for data flow in the filter graph.

It is the caller's responsibility to cancel notification by calling this method again with a NULL event handle.

The filter graph calls this method inside the IGraphConfig::Reconnect method. If an application or filter does any specialized dynamic reconfiguration to the graph (using the IGraphConfig::Reconfigure method), it might call this method first in order to push data through the portion of the graph that is being reconfigured.