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.
When to Implement
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.
When to Use
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 | Returns 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 | Returns a pointer to the connecting pin. |
| ConnectionMediaType | Returns the media type of this pin's connection. |
| 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. |
Informs the pin to begin a flush operation.
HRESULT BeginFlush(void);
Returns an HRESULT value.
When this method is called, the pin is entering flush state. In this case, carry out the following steps.
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.
Initiates a connection from this pin to the other pin.
HRESULT Connect(
IPin * pReceivePin,
const AM_MEDIA_TYPE * pmt
);
Returns an HRESULT value.
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.
If this pin is connected to another pin, the IPin::ConnectedTo method returns a pointer to that pin.
HRESULT ConnectedTo(
IPin ** ppPin
);
Returns an HRESULT value.
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.
Determines the media type associated with the current connection of the pin. This method fails if the pin is unconnected.
HRESULT ConnectionMediaType(
AM_MEDIA_TYPE *pmt
);
Returns an HRESULT value.
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.
Breaks a connection.
HRESULT Disconnect(void);
Returns NOERROR if there is no connection.
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.
Informs the pin to end a flush operation.
HRESULT EndFlush(void);
Returns an HRESULT value.
When this method is called, the pin is beginning to end a flush operation. It should perform the following steps.
This method is implemented in the base classes by CBaseInputPin::EndFlush.
Informs the input pin that no additional data is expected until a new run command is issued.
HRESULT EndOfStream(void);
Returns one of the following HRESULT values.
| Value | Meaning |
| S_OK | No error occurred. |
| E_UNEXPECTED | Method was probably called on an output pin that does not support this. |
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.
Provides an enumerator for this pin's preferred media types.
HRESULT EnumMediaTypes(
IEnumMediaTypes ** ppEnum
);
Returns an HRESULT value.
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.
Specifies that samples following this method are grouped as a segment with a given start time, stop time, and rate.
HRESULT NewSegment(
REFERENCE_TIME tStart,
REFERENCE_TIME tStop,
double dRate
);
Returns an HRESULT value.
This method allows 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.
Determines if the pin could accept the format type.
HRESULT QueryAccept(
const AM_MEDIA_TYPE * pmt
);
Returns S_OK if the format is acceptable; otherwise, returns S_FALSE.
This method is implemented in the base classes by CBasePin::QueryAccept.
Retrieves the direction for this pin.
HRESULT QueryDirection(
PIN_DIRECTION * pPinDir
);
Returns an HRESULT value.
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.
Retrieves an identifier for the pin.
HRESULT QueryId(
LPWSTR * Id
);
Returns an HRESULT value.
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.
Provides an array of pointers to the IPin interface of the pins to which this pin internally connects.
HRESULT QueryInternalConnections(
IPin ** apPin,
ULONG * nPin
);
Returns one of the following HRESULT values.
| Value | Meaning |
| 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. |
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 allows the calling application to determine the number of required arrays.
This method is implemented in the base classes by CBasePin::QueryInternalConnections.
Retrieves information about the pin.
HRESULT QueryPinInfo(
PIN_INFO * pInfo
);
Returns an HRESULT value.
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.
Note that 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.
Makes a connection to the calling pin.
HRESULT ReceiveConnection(
IPin * pConnector,
AM_MEDIA_TYPE *pmt
);
Returns an HRESULT value.
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.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.