Microsoft DirectX 8.0 |
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 methods Description QueryInterface Retrieves pointers to supported interfaces. AddRef Increments the reference count. Release Decrements the reference count. IPin methods Description Connect Connects the pin to another pin. ReceiveConnection Accepts a connection from another pin. Disconnect Breaks the current pin connection. ConnectedTo Retrieves the pin connected to this pin. ConnectionMediaType Retrieves the media type for the current pin connection. QueryPinInfo Retrieves information about the pin, such as the name, the owning filter, and the direction. QueryId Retrieves the pin identifier. QueryAccept Determines whether the pin accepts a specified media type. EnumMediaTypes Enumerates the pin's preferred media types. QueryInternalConnections Retrieves the pins that are connected internally to this pin (within the filter). EndOfStream Notifies the pin that no additional data is expected. BeginFlush Begins a flush operation. EndFlush Ends a flush operation. NewSegment Notifies the pin that media samples received after this call are grouped as a segment. QueryDirection Retrieves the direction of the pin (input or output).
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:
- Passes the IPin::BeginFlush call downstream.
- Sets an internal flag that causes all data-streaming methods to fail, such as IMemInputPin::Receive.
- 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
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_OK Success. VFW_E_ALREADY_CONNECTED The pin is already connected. VFW_E_NO_ACCEPTABLE_TYPES Could not find an acceptable media type. VFW_E_NOT_STOPPED The filter is active and the pin does not support dynamic reconnection. VFW_E_TYPE_NOT_ACCEPTED The 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.
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_OK Success. E_POINTER NULL pointer argument. VFW_E_NOT_CONNECTED Pin 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.
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_OK Success. E_POINTER Null pointer argument. VFW_E_NOT_CONNECTED Pin 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.
Breaks the current pin connection.
Syntax
HRESULT Disconnect(void);
Return Value
Returns an HRESULT value. Possible values include the following.
S_FALSE The pin was not connected. S_OK Success. VFW_E_NOT_STOPPED The 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.
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:
- Waits for all queued samples to be discarded.
- Frees any buffered data.
- Clears any pending EC_COMPLETE notifications.
- Calls EndFlush downstream.
When the method returns, the pin can accept new samples.
See Also
Data Flow In The Filter Graph
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_UNEXPECTED Pin 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.
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_OK Success. 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.
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.
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.
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_OK Success. E_POINTER Null pointer argument.
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_OK Success. E_OUTOFMEMORY Insufficient memory. E_POINTER Null 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.
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_FALSE Insufficient array size. S_OK Success. E_FAIL Failure. E_NOTIMPL Not 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.
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_OK Success. E_POINTER Null 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.
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_OK Success. E_POINTER Null pointer argument. VFW_E_ALREADY_CONNECTED The pin is already connected. VFW_E_NOT_STOPPED Cannot connect while filter is active. VFW_E_TYPE_NOT_ACCEPTED The 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.