Microsoft DirectX 8.0

IPin Interface

This interface is exposed by all input and output pins.

The filter graph manager uses this interface to connect pins and perform flushing operations. Applications can use this interface to query the pin for information. Applications should never call IPin methods that change a pin's state, such as Connect, Disconnect, BeginFlush, or EndFlush. To connect pins, an application must use the methods in IGraphBuilder.

Filter developers: The CBasePin, CBaseInputPin, and CBaseOutputPin classes implement this interface. Other base classes derive from these three classes.

Methods in Vtable Order

IUnknown methodsDescription
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.
IPin methodsDescription
ConnectConnects the pin to another pin.
ReceiveConnectionAccepts a connection from another pin.
DisconnectBreaks the current pin connection.
ConnectedToRetrieves the pin connected to this pin.
ConnectionMediaTypeRetrieves the media type for the current pin connection.
QueryPinInfoRetrieves information about the pin, such as the name, the owning filter, and the direction.
QueryIdRetrieves the pin identifier.
QueryAcceptDetermines whether the pin accepts a specified media type.
EnumMediaTypesEnumerates the pin's preferred media types.
QueryInternalConnectionsRetrieves the pins that are connected internally to this pin (within the filter).
EndOfStreamNotifies the pin that no additional data is expected.
BeginFlushBegins a flush operation.
EndFlushEnds a flush operation.
NewSegmentNotifies the pin that media samples received after this call are grouped as a segment.
QueryDirectionRetrieves the direction of the pin (input or output).

IPin::BeginFlush

IPin Interface

Begins a flush operation.

Syntax

HRESULT BeginFlush(void);

Return Value

Returns S_OK if successful, or an HRESULT value indicating the cause of the error.

Remarks

In a flush operation, a filter discards whatever data it was processing. It rejects new data until the flush is completed. The flush is completed when the upstream pin calls the IPin::EndFlush method. Flushing enables the filter graph to be more responsive when events alter the normal data flow. For example, flushing occurs during a seek.

When BeginFlush is called, the filter performs the following steps:

  1. Passes the IPin::BeginFlush call downstream.
  2. Sets an internal flag that causes all data-streaming methods to fail, such as IMemInputPin::Receive.
  3. Returns from any blocked calls to the Receive method.

When the BeginFlush notification reaches a renderer filter, the renderer frees any samples that it holds.

After BeginFlush is called, the pin rejects all samples from upstream, with a return value of S_FALSE, until the IPin::EndFlush method is called.

See Also

Data Flow In The Filter Graph

IPin::Connect

IPin Interface

Connects the pin to another pin.

Syntax

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

Parameters

pReceivePin
[in] Pointer to the receiving pin's IPin interface.
pmt
[in] Pointer to an AM_MEDIA_TYPE structure that specifies the media type for the connection. Can be NULL.

Return Value

Returns an HRESULT value. Possible values include the following.

S_OKSuccess.
VFW_E_ALREADY_CONNECTEDThe pin is already connected.
VFW_E_NO_ACCEPTABLE_TYPESCould not find an acceptable media type.
VFW_E_NOT_STOPPEDThe filter is active and the pin does not support dynamic reconnection.
VFW_E_TYPE_NOT_ACCEPTEDThe specified media type is not acceptable.

Remarks

The pmt parameter can be NULL. It can also specify a partial media type, with a value of GUID_NULL for the major type, subtype, or format.

This method verifies that the connection is possible. If the pin rejects the connection, the method fails. The connecting pin proposes media types by calling IPin::ReceiveConnection on the receiving pin.

IPin::ConnectedTo

IPin Interface

Retrieves a pointer to the connected pin, if any.

Syntax

HRESULT ConnectedTo(
    IPin **ppPin
);

Parameters

ppPin
[out] Address of a variable that receives a pointer to the IPin interface of the other pin. Cannot be NULL.

Return Value

Returns an HRESULT value. Possible values include the following.

S_OKSuccess.
E_POINTERNULL pointer argument.
VFW_E_NOT_CONNECTEDPin is not connected.

Remarks

If the method succeeds, the IPin interface that it returns has an outstanding reference count. Be sure to release it when you are done.

IPin::ConnectionMediaType

IPin Interface

Retrieves the media type for the current pin connection, if any.

Syntax

HRESULT ConnectionMediaType(
    AM_MEDIA_TYPE *pmt
);

Parameters

pmt
[out] Pointer to an AM_MEDIA_TYPE structure that receives the media type.

Return Value

Returns an HRESULT value. Possible values include the following.

S_OKSuccess.
E_POINTER Null pointer argument.
VFW_E_NOT_CONNECTEDPin is not connected.

Remarks

If the pin is connected, this method copies the media type into the AM_MEDIA_TYPE structure specified by pmt. The caller must free the media type's format block. You can use the Microsoft® Win32® CoTaskMemFree function, or the FreeMediaType helper function.

If the pin is not connected, this method clears the media type specified by pmt and returns an error code.

IPin::Disconnect

IPin Interface

Breaks the current pin connection.

Syntax

HRESULT Disconnect(void);

Return Value

Returns an HRESULT value. Possible values include the following.

S_FALSEThe pin was not connected.
S_OKSuccess.
VFW_E_NOT_STOPPEDThe filter is active.

Remarks

This method fails if the filter is paused or running. If the pin supports the IPinConnection interface, call IPinConnection::DynamicDisconnect to disconnect the pin when the filter is paused or running.

A pin should never use this method to disconnect from its peer.

IPin::EndFlush

IPin Interface

Ends a flush operation.

Syntax

HRESULT EndFlush(void);

Return Value

Returns S_OK if successful, or an HRESULT value indicating the cause of the error.

Remarks

When this method is called, the filter performs the following actions:

  1. Waits for all queued samples to be discarded.
  2. Frees any buffered data.
  3. Clears any pending EC_COMPLETE notifications.
  4. Calls EndFlush downstream.

When the method returns, the pin can accept new samples.

See Also

Data Flow In The Filter Graph

IPin::EndOfStream

IPin Interface

Notifies the pin that no additional data is expected, until a new run command is issued to the filter.

Syntax

HRESULT EndOfStream(void);

Return Value

Returns one of the following HRESULT values.

S_OK Success.
E_UNEXPECTEDPin does not support this method.

Remarks

Call this method only on input pins. Output pins return E_UNEXPECTED.

This method sends an end-of-stream notification to the pin. The pin delivers the notification downstream. It must serialize end-of-stream notifications with IMemInputPin::Receive calls. If the pin queues media samples for delivery, it should queue end-of-stream notifications as well. The IPin::BeginFlush method flushes any queued end-of-stream notifications.

IPin::EnumMediaTypes

IPin Interface

Enumerates the pin's preferred media types.

Syntax

HRESULT EnumMediaTypes(
    IEnumMediaTypes **ppEnum
);

Parameters

ppEnum
[out] Address of a variable that receives a pointer to the IEnumMediaTypes interface.

Return Value

Returns an HRESULT value. Possible values include the following.

S_OKSuccess.
E_OUTOFMEMORY Insufficient memory.
E_POINTER NULL pointer argument.

Remarks

The IEnumMediaTypes interface works like a standard COM enumerator. For more information, see Enumerating Objects in a Filter Graph. If the method succeeds, the IEnumMediaTypes interface has an outstanding reference count. Be sure to release it when you are done.

IPin::NewSegment

IPin Interface

Notifies the pin that media samples received after this call are grouped as a segment, with a common start time, stop time, and rate.

Syntax

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

Parameters

tStart
Start time of the segment, relative to the original source, in 100-nanosecond units.
tStop
End time of the segment, relative to the original source, in 100-nanosecond units.
dRate
Rate at which this segment should be processed, as a percentage of the original rate.

Return Value

Returns S_OK if successful, or an HRESULT value indicating the cause of the error.

Remarks

A source filter (or parser filter) calls this method at the start of each new stream and after each seek operation. It calls the method on the input pin of the downstream filter, after delivering the previous batch of data and before calling IMemInputPin::Receive with any new data. The downstream filter propagates the NewSegment call downstream.

Filters can use segment information to process samples. For example, with some formats it is impossible to reconstruct a delta frame without the next key frame. Therefore, if the stop time occurs on a delta frame, the source filter must send some additional frames. The decoder filter determines the final frame based on the segment information. The segment rate is used to render continuous data sources, such as audio data. For example, the audio renderer uses the sampling rate and the segment rate to render the audio data correctly.

IPin::QueryAccept

IPin Interface

Determines whether the pin accepts a specified media type.

Syntax

HRESULT QueryAccept(
    const AM_MEDIA_TYPE *pmt
);

Parameters

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

Return Value

Returns S_TRUE if the media type is acceptable. Otherwise, returns S_FALSE.

Remarks

A return value of S_OK does not guarantee that the pin can switch to the specified format while the filter is running. If you need to switch formats while the filter is running, and the pin supports the IPinConnection interface, call the IPinConnection::DynamicQueryAccept method.

IPin::QueryDirection

IPin Interface

Retrieves the direction of the pin (input or output).

Syntax

HRESULT QueryDirection(
    PIN_DIRECTION *pPinDir
);

Parameters

pPinDir
[out] Pointer to a variable that receives a member of the PIN_DIRECTION enumerated type.

Return Value

Returns an HRESULT value. Possible values include the following.

S_OKSuccess.
E_POINTERNull pointer argument.

IPin::QueryId

IPin Interface

Retrieves an identifier for the pin.

Syntax

HRESULT QueryId(
    LPWSTR *Id
);

Parameters

Id
[out] Address of a variable that receives a string containing the pin identifier.

Return Value

Returns an HRESULT value. Possible values include the following.

S_OKSuccess.
E_OUTOFMEMORYInsufficient memory.
E_POINTERNull pointer argument.

Remarks

This method supports graph persistence. Use this method to save a pin's state, and the IBaseFilter::FindPin method to restore the state. The pin's identifier string is defined by the filter implementation. The identifier must be unique within the filter.

Note  The pin identifier is not necessarily the same as the pin name that the QueryPinInfo method returns.

The filter allocates the returned string using the Microsoft® Win32® CoTaskMemAlloc function. The caller must free it using CoTaskMemFree.

IPin::QueryInternalConnections

IPin Interface

Retrieves the pins that are connected internally to this pin (within the filter).

Syntax

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

Parameters

apPin
[out] Address of an array of IPin pointers.
nPin
[in, out] On input, specifies the size of the array. When the method returns, the value is set to the number of pointers returned in the array.

Return Value

Returns one of the following HRESULT values.

S_FALSEInsufficient array size.
S_OKSuccess.
E_FAILFailure.
E_NOTIMPLNot implemented.

Remarks

On some filters, input pins correspond to particular output pins. For each pin, this method fills an array with pointers to the corresponding pins. If every input pin provides data for every output pin, the pin returns E_NOTIMPL.

If the method succeeds and returns a value of *nPin greater than zero, the array contains pointers to IPin interfaces. Be sure to release each interface pointer when you are done.

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 receives the pin information.

Return Value

Returns an HRESULT value. Possible values include the following.

S_OKSuccess.
E_POINTERNull pointer argument.

Remarks

When the method returns, if the pFilter member of the PIN_INFO structure is non-NULL, it has an outstanding reference count. Be sure to release the interface when you are done.

IPin::ReceiveConnection

IPin Interface

Accepts a connection from another pin.

Syntax

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

Parameters

pConnector
[in] Pointer to the connecting pin's IPin interface.
pmt
[in] Pointer to an AM_MEDIA_TYPE structure that specifies the media type for the connection.

Return Value

Returns an HRESULT value. Possible values include the following.

S_OKSuccess.
E_POINTER Null pointer argument.
VFW_E_ALREADY_CONNECTEDThe pin is already connected.
VFW_E_NOT_STOPPEDCannot connect while filter is active.
VFW_E_TYPE_NOT_ACCEPTEDThe specified media type is not acceptable.

Remarks

The pin that initiates the connection calls this method on the receiving pin. If the receiving pin returns an error code, the connection fails.