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.

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.

---

IPin::BeginFlush

IPin Interface

Informs the pin to begin a flush operation.

HRESULT BeginFlush(void);

Return Values

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

Value	Meaning
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.

1. Set a flushing flag to prevent any more IMemInputPin::Receive methods from succeeding.
2. Discard any queued data.
3. Free the pin if it was blocked by the Receive method, if possible.
4. 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.

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

Parameters

pReceivePin

[in] Other pin to connect to.

pmt

[in] Type to use for the connections (optional).

Return Values

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

Value	Meaning
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

If this pin is connected to another pin, the IPin::ConnectedTo method returns a pointer to that pin.

HRESULT ConnectedTo(
  IPin ** ppPin
  );

Parameters

ppPin

[out] Pointer to an IPin pointer to the IPin interface of the other pin (if any) to which this pin is connected. If there is no connection, the other pin interface pointer will be NULL.

Return Values

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

Value	Meaning
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 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.

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 elements are 0, with the exception of lSampleSize, which is set to 1, and bFixedSizeSamples, which is set to TRUE.

Return Values

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

Value	Meaning
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.

HRESULT Disconnect(void);

Return Values

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.

HRESULT EndFlush(void);

Return Values

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

Value	Meaning
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.

1. 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.)
2. Reenable the IMemInputPin::Receive method by clearing the internal flushing flag.
3. 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.

HRESULT EndOfStream(void);

Return Values

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.

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.

HRESULT EnumMediaTypes(
  IEnumMediaTypes ** ppEnum
  );

Parameters

ppEnum

[out] Pointer to an enumerator for the media types.

Return Values

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

Value	Meaning
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.

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 Values

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

Value	Meaning
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 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.

---

IPin::QueryAccept

IPin Interface

Determines if the pin could accept the format type.

HRESULT QueryAccept(
  const AM_MEDIA_TYPE * pmt
  );

Parameters

pmt

[in] Pointer to a proposed media type.

Return Values

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.

HRESULT QueryDirection(
  PIN_DIRECTION * pPinDir
  );

Parameters

pPinDir

[out] Pointer to a PIN_DIRECTION variable.

Return Values

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

Value	Meaning
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.

HRESULT QueryId(
  LPWSTR * Id
  );

Parameters

Id

[out] Pin identifier.

Return Values

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

Value	Meaning
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.

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

Parameters

apPin

[out] Array of IPin pointers.

nPin

[out] Upon input, indicates the number of array elements; upon output, indicates the number of pins.

Return Values

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.

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 allows 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.

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 Values

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

Value	Meaning
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.

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.

---

IPin::ReceiveConnection

IPin Interface

Makes a connection to the calling pin.

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

Parameters

pConnector

[in] Connecting pin.

pmt

[in] Media type of the samples to be streamed.

Return Values

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

Value	Meaning
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.

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Top of Page