Microsoft DirectX 8.0 |
Provides methods for controlling a filter. All Microsoft® DirectShow® filters expose this interface. This interface derives from the IMediaFilter interface, and inherits the IPersist interface through IMediaFilter.
The filter graph manager uses this interface to control filters. Applications and other filters can use this interface to enumerate pins and query for filter information. They should not use it to change the state of a filter. Instead, call IMediaControl interfaces on the filter graph manager.
Filter developers: Implement this interface on every DirectShow filter. The CBaseFilter base class implements this interface.
Methods in Vtable Order
IUnknown methods Description QueryInterface Retrieves pointers to supported interfaces. AddRef Increments the reference count. Release Decrements the reference count. IMediaFilter methods Description Stop Stops the filter. Pause Pauses the filter. Run Runs the filter. GetState Retrieves the filter's state (running, stopped, or paused). SetSyncSource Sets a reference clock for the filter. GetSyncSource Retrieves the reference clock that the filter is using. IBaseFilter methods Description EnumPins Enumerates the pins on this filter. FindPin Retrieves the pin with the specified identifier. QueryFilterInfo Retrieves information about the filter. JoinFilterGraph Notifies the filter that it has joined or left the filter graph. QueryVendorInfo Retrieves a string containing vendor information.
Enumerates the pins on this filter.
Syntax
HRESULT EnumPins( IEnumPins **ppEnum );
Parameters
- ppEnum
- [out] Address of a variable that receives a pointer to the IEnumPins interface.
Return Value
Returns an HRESULT value. Possible values include those shown in the following table.
S_OK Success E_OUTOFMEMORY Insufficient memory E_POINTER Null pointer argument
Remarks
This method returns an enumerator that supports the IEnumPins interface, which works like a standard COM enumerator. For more information, see Enumerating Pins.
If the method succeeds, the IEnumPins interface has an outstanding reference count. Be sure to release the interface when you are done.
Retrieves the pin with the specified identifier.
Syntax
HRESULT FindPin( LPCWSTR Id, IPin **ppPin );
Parameters
- Id
- [in] Pointer to a constant, null-terminated Unicode string that identifies the pin. Call the IPin::QueryId method to retrieve a pin's identifier.
- ppPin
- [out] Address of a variable that receives a pointer to the pin's IPin interface. If the method fails, *ppPin is set to NULL.
Return Value
Returns an HRESULT value. Possible values include those shown in the following table.
S_OK Success. E_POINTER Null pointer argument. VFW_E_NOT_FOUND Could not find a pin with this identifier.
Remarks
This method supports graph persistence. Use the IPin::QueryId method to save a pin's state, and use this method to restore the state. The pin's identifier string is defined by the filter implementation. The identifier must be unique within the filter.
If the method succeeds, the IPin interface that it returns has an outstanding reference count. Be sure to release the interface when you are done.
Notifies the filter that it has joined or left the filter graph.
Syntax
HRESULT JoinFilterGraph( IFilterGraph *pGraph, LPCWSTR pName );
Parameters
- pGraph
- [in] Pointer to the filter graph manager's IFilterGraph interface, or NULL if the filter is leaving the graph.
- pName
- [in, string] Pointer to a null-terminated Unicode string that specifies a name for the filter.
Return Value
Returns S_OK if successful, or an HRESULT value indicating the cause of the error.
Remarks
When the filter graph manager adds a filter to the filter graph, it calls this method with a pointer to itself. When it removes the filter from the graph, it calls this method with a NULL pointer.
Applications should never call this method. To add a filter to the graph, call the IFilterGraph::AddFilter method on the filter graph manager.
The filter should store the IFilterGraph interface pointer, so that it can post event notifications. However, it must not add a reference count to this interface. Doing so would create a circular reference count, because the filter graph manager keeps a reference count on the filter. A circular reference will prevent the interface from being released properly. The IFilterGraph interface is guaranteed to be valid until the filter graph manager notifies the filter that it has been removed from the graph.
The name passed in the pName parameter can be retrieved by calling the QueryFilterInfo method.
Retrieves information about the filter.
Syntax
HRESULT QueryFilterInfo( FILTER_INFO *pInfo );
Parameters
- pInfo
- [out] Pointer to a FILTER_INFO structure.
Return Value
Returns an HRESULT value. Possible values include those shown in the following table.
S_OK Success E_POINTER Null pointer argument
Remarks
This method fills the FILTER_INFO structure with the filter information. On return, if the pGraph member of the FILTER_INFO structure is non-NULL, the IFilterGraph interface has an outstanding reference count. Be sure to release the interface when you are done.
Retrieves a string containing vendor information.
Syntax
HRESULT QueryVendorInfo( LPWSTR *pVendorInfo );
Parameters
- pVendorInfo
- [out] Address of a variable that receives a pointer to a wide-character string containing the vendor information.
Return Value
Returns an HRESULT value. Possible values include those shown in the following table.
S_OK Success. E_NOTIMPL Method is not supported. E_POINTER Null pointer argument.
Remarks
This method is optional; filters are not required to support it.
If the method is supported, it uses the CoTaskMemAlloc function to allocate memory for the string. Call the CoTaskMemFree function to free the memory.