IPin Interface

The IPin interface represents a single, unidirectional connection point on a filter. A pin connects to exactly one other pin on another filter. Other objects can use this interface on this pin. The interface between the filter and the pin is private to the implementation of a specific filter.

During the connection process, one pin takes the lead. The base classes assume that this is the output pin of the upstream connecting filter. The filter graph manager calls the IPin::Connect method on this pin's IPin interface, passing the IPin pointer for the connecting pin. This connecting pin then calls the IPin::ReceiveConnection method located on the other pin, in addition to its format-enumeration, IUnknown::QueryInterface, and possibly IPin::QueryAccept methods, to establish whether the connection is possible.

All filters must implement this interface on each of its pins. Which methods are implemented depends on whether the pin is an input pin or an output pin. Use the CBasePin, CBaseInputPin, or CBaseOutputPin class, or classes derived from these classes, to implement this interface.

This interface is used by other connecting pins and by the filter graph manager. Applications should not use this interface directly but should go through the filter graph manager. Connecting pins use the IPin interface on the opposite pin to negotiate a common media type and an agreed allocator to use for passing samples.

Methods in Vtable Order

IUnknown methods Description
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.

IPin methods Description
Connect Makes a connection to another pin.
ReceiveConnection Makes a connection to this pin and is called by a connecting pin.
Disconnect Breaks a connection.
ConnectedTo Retrieves a pointer to the pin that this pin is connected to, if any.
ConnectionMediaType Determines the media type associated with the current connection of the pin. This method fails if the pin is unconnected.
QueryPinInfo Retrieves information about this pin (for example, the name, owning filter, and direction).
QueryId Retrieves an identifier for the pin.
QueryAccept Queries whether a given media type is acceptable by the pin.
EnumMediaTypes Provides an enumerator for this pin's preferred media types.
QueryInternalConnections Provides an array of the pins to which this pin internally connects.
EndOfStream Informs the pin that no additional data is expected until a new run command is issued.
BeginFlush Informs the pin to begin a flush operation.
EndFlush Informs the pin to end a flush operation.
NewSegment Specifies that samples following this call are grouped as a segment with a given start time, stop time, and rate.
QueryDirection Retrieves the direction for this pin.

IUnknown methods	Description
QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IPin methods	Description
Connect	Makes a connection to another pin.
ReceiveConnection	Makes a connection to this pin and is called by a connecting pin.
Disconnect	Breaks a connection.
ConnectedTo	Retrieves a pointer to the pin that this pin is connected to, if any.
ConnectionMediaType	Determines the media type associated with the current connection of the pin. This method fails if the pin is unconnected.
QueryPinInfo	Retrieves information about this pin (for example, the name, owning filter, and direction).
QueryId	Retrieves an identifier for the pin.
QueryAccept	Queries whether a given media type is acceptable by the pin.
EnumMediaTypes	Provides an enumerator for this pin's preferred media types.
QueryInternalConnections	Provides an array of the pins to which this pin internally connects.
EndOfStream	Informs the pin that no additional data is expected until a new run command is issued.
BeginFlush	Informs the pin to begin a flush operation.
EndFlush	Informs the pin to end a flush operation.
NewSegment	Specifies that samples following this call are grouped as a segment with a given start time, stop time, and rate.
QueryDirection	Retrieves the direction for this pin.

IPin::BeginFlush

IPin Interface

Informs the pin to begin a flush operation.

Syntax

HRESULT BeginFlush(void);

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

Remarks

When this method is called, the pin is entering flush state. In this case, carry out the following steps.

Set a flushing flag to prevent any more IMemInputPin::Receive methods from succeeding.
Discard any queued data.
Free the pin if it was blocked by the Receive method, if possible.
Pass the IPin::BeginFlush method to any downstream pins.

The BeginFlush notification is passed downstream until it reaches the renderer, which must free any sample it holds. This unblocks other pins (usually in the IMemAllocator::GetBuffer or IMemInputPin::Receive methods).
After BeginFlush is called, all samples passed by the Receive method to the pin, or on another transport, are rejected with S_FALSE until the IPin::EndFlush method is called.
This method is implemented in the base classes by CBaseInputPin::BeginFlush.

IPin::Connect

IPin Interface

Initiates a connection from this pin to the other pin.

Syntax

HRESULT Connect(
    IPin *pReceivePin,
    const AM_MEDIA_TYPE *pmt
);

Parameters

pReceivePin
[in] Pointer to the other pin to connect to.
pmt
[in] Pointer to the type to use for the connections (optional).

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

Remarks

This method calls the IPin::ReceiveConnection method for the other pin. The IPin::Connect method verifies that the connection is possible and might reject it. This pin proposes a media type to the other pin.
This method is implemented in the base classes by CBasePin::Connect.
Applications should not use this method. Instead, use IFilterGraph::ConnectDirect, which will use this method. Changing connections underneath the filter graph manager can cause commands to be distributed incorrectly and can cause a deadlock.

IPin::ConnectedTo

IPin Interface

Retrieves a pointer to the pin that this pin is connected to, if any.

Syntax

HRESULT ConnectedTo(
    IPin **ppPin
);

Parameters

ppPin
[out] Pointer that will receive the address of the IPin interface of the other pin (if any) to which this pin is connected.

Return Value

Returns S_OK if this pin is connected to another pin; otherwise, returns VFW_E_NOT_CONNECTED.

Remarks

This method is implemented in the base classes by CBasePin::ConnectedTo. The interface returned by this method has had its reference count incremented. Be sure to use IUnknown::Release on the interface to decrement the reference count when you have finished using the interface.

IPin::ConnectionMediaType

IPin Interface

Determines the media type associated with the current connection of the pin. This method fails if the pin is unconnected.

Syntax

HRESULT ConnectionMediaType(
    AM_MEDIA_TYPE *pmt
);

Parameters

pmt
[out] Pointer to an AM_MEDIA_TYPE structure. If the pin is connected, the media type is returned. Otherwise, the structure is initialized to a default state in which all members are 0, with the exception of lSampleSize, which is set to 1, and bFixedSizeSamples, which is set to TRUE.

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

Remarks

The returned structure can contain an allocated format block and a reference-counted IUnknown interface pointer. These resources should be released by calling the FreeMediaType utility function.
This method is implemented in the base classes by CBasePin::ConnectionMediaType.

IPin::Disconnect

IPin Interface

Breaks a connection.

Syntax

HRESULT Disconnect(void);

Return Value

Returns NOERROR if there is no connection.

Remarks

There are no parameters because there is only one possible connection on this pin.
This method is implemented in the base classes by CBasePin::Disconnect.
A pin should never use this method to disconnect from its peer. An application should not use this method. Use IFilterGraph::Disconnect instead.

IPin::EndFlush

IPin Interface

Informs the pin to end a flush operation.

Syntax

HRESULT EndFlush(void);

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

Remarks

When this method is called, the pin is beginning to end a flush operation. It should perform the following steps.

Ensure that your filter will not push any additional data. (To do this, synchronize with a thread, stop it pushing, and discard any queued data.)
Reenable the IMemInputPin::Receive method by clearing the internal flushing flag.
Pass the EndFlush method downstream by calling the method on the connecting input pin.

This method is implemented in the base classes by CBaseInputPin::EndFlush.

IPin::EndOfStream

IPin Interface

Informs the input pin that no additional data is expected until a new run command is issued.

Syntax

HRESULT EndOfStream(void);

Return Value

Returns one of the following HRESULT values.

S_OK No error occurred.
E_UNEXPECTED Method was probably called on an output pin that does not support this.

Remarks

Calling this method notifies the pin that no additional data is expected until a new run command is issued. The end-of-stream notification should be queued and delivered after all queued data is delivered. It can be delivered immediately if there is no queued data.
The IPin::BeginFlush method flushes any queued end-of-stream notifications. This is intended for input pins only.
This method is implemented in the base classes by CBaseOutputPin::EndOfStream.

IPin::EnumMediaTypes

IPin Interface

Provides an enumerator for this pin's preferred media types.

Syntax

HRESULT EnumMediaTypes(
    IEnumMediaTypes **ppEnum
);

Parameters

ppEnum
[out] Address of a pointer to an enumerator for the media types.

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

Remarks

If an enumerator is received, it must be released when the operation is finished.
This method is implemented in the base classes by CBasePin::EnumMediaTypes.

IPin::NewSegment

IPin Interface

Specifies that samples following this method are grouped as a segment with a given start time, stop time, and rate.

Syntax

HRESULT NewSegment(
    REFERENCE_TIME tStart,
    REFERENCE_TIME tStop,
    double dRate
);

Parameters

tStart
[in] Start time of the segment.
tStop
[in] Stop time of the segment.
dRate
[in] Rate of the segment.

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

Remarks

This method enables filters that process buffers containing more than one sample to delineate the rendering of the samples between start and stop time, as indicated by the tStart and tStop parameters.
This method is intended to be implemented on an input pin. A connected output pin on the upstream filter calls this method after completing delivery of previous data and before calling IMemInputPin::Receive with any new data. It indicates that all data arriving after this call is part of a segment delineated by the parameters.

IPin::QueryAccept

IPin Interface

Determines if the pin could accept the format type.

Syntax

HRESULT QueryAccept(
    const AM_MEDIA_TYPE *pmt
);

Parameters

pmt
[in] Pointer to a proposed media type.

Return Value

Returns S_OK if the format is acceptable; otherwise, returns S_FALSE.

Remarks

This method is implemented in the base classes by CBasePin::QueryAccept.

IPin::QueryDirection

IPin Interface

Retrieves the direction for this pin.

Syntax

HRESULT QueryDirection(
    PIN_DIRECTION *pPinDir
);

Parameters

pPinDir
[out] Pointer to a PIN_DIRECTION variable.

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

Remarks

The returned pPinDir parameter will contain PINDIR_INPUT if the pin is an input pin or PINDIR_OUTPUT otherwise. The same information is available by using IPin::QueryPinInfo, but this method is more direct and more efficient.

IPin::QueryId

IPin Interface

Retrieves an identifier for the pin.

Syntax

HRESULT QueryId(
    LPWSTR *Id
);

Parameters

Id
[out] Pointer to the pin identifier.

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

Remarks

This method and the IBaseFilter::FindPin method allow connections in a filter graph to be saved and restored. Because pins are identified only by their IPin interface pointers at run time, and pointer information cannot be reliably saved, an identifier is necessary to specify which pins belong to each filter. The implementation of this method by the pin provides a unique name that the filter graph manager can use to turn into an IPin interface pointer, by calling IBaseFilter::FindPin when the filter graph is restored.
The storage is allocated by the filter using the Microsoft® Win32® CoTaskMemAlloc function. The caller should free it by using CoTaskMemFree.
This method is implemented in the base classes by CBasePin::QueryId.

IPin::QueryInternalConnections

IPin Interface

Provides an array of pointers to the IPin interface of the pins to which this pin internally connects.

Syntax

HRESULT QueryInternalConnections(
    IPin **apPin,
    ULONG *nPin
);

Parameters

apPin
[out] Address of a pointer to an array of IPin pointers.
nPin
[in, out] Pointer to a ULONG whose input value indicates the number of array elements and whose output value indicates the number of pins.

Return Value

Returns one of the following HRESULT values.

E_FAIL Undetermined.
S_FALSE Insufficient number of array elements to return all the results, in which case no pins are returned in the apPin array.
E_NOTIMPL Filter graph manager interprets E_NOTIMPL as meaning that any input pin connects to all visible output pins, and vice versa.

Remarks

All pins put in the array are added by the IUnknown::AddRef method. The apPin parameter can be NULL if the nPin parameter equals zero. This enables the calling application to determine the number of required arrays.
This method is implemented in the base classes by CBasePin::QueryInternalConnections.

IPin::QueryPinInfo

IPin Interface

Retrieves information about the pin.

Syntax

HRESULT QueryPinInfo(
    PIN_INFO *pInfo
);

Parameters

pInfo
[out] Pointer to a PIN_INFO structure that specifies the name of the pin, a pointer to an IBaseFilter interface on its owning filter, and the direction of the pin.

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

Remarks

Unlike the pin name in the IPin::QueryId method, which is used by the filter graph manager, the name in the PIN_INFO structure is intended to be read by users.
On return, the pFilter member of PIN_INFO has an outstanding reference count if it is non-NULL, and therefore should be released when the interface is no longer needed.

IPin::ReceiveConnection

IPin Interface

Makes a connection to the calling pin.

Syntax

HRESULT ReceiveConnection(
    IPin *pConnector,
    AM_MEDIA_TYPE *pmt
);

Parameters

pConnector
[in] Pointer to the connecting pin.
pmt
[in] Pointer to the media type of the samples to be streamed.

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

Remarks

This method is intended for input pins only. Output pins should implement this to return an error. The pin should verify that it accepts the media type passed to it and return S_OK if so.
This method is implemented in the base classes by CBasePin::ReceiveConnection.

E_FAIL	Failure.
E_POINTER	Null pointer argument.
E_INVALIDARG	Invalid argument.
E_NOTIMPL	Method isn't supported.
S_OK or NOERROR	Success.

S_OK	No error occurred.
E_UNEXPECTED	Method was probably called on an output pin that does not support this.

E_FAIL	Undetermined.
S_FALSE	Insufficient number of array elements to return all the results, in which case no pins are returned in the apPin array.
E_NOTIMPL	Filter graph manager interprets E_NOTIMPL as meaning that any input pin connects to all visible output pins, and vice versa.