DirectShow Animated Header -- IDistributorNotify Interface DirectShow Animated Header -- IDistributorNotify Interface* Microsoft DirectShow SDK
*Index  *Topic Contents
*Previous Topic: IDirectDrawVideo Interface
*Next Topic: IDvdControl Interface

IDistributorNotify Interface


The IDistributorNotify interface is an optional interface for use by plug-in distributors to notify them of changes in the filter graph state.

When to Implement

Implement this interface when writing a plug-in distributor (PID) that is aggregated with the filter graph manager if you want the PID to receive notifications of control and changes in the composition of filter graphs.

PIDs may often use methods on the filter graph manager. During a call to an IDistributorNotify method, do not take any lock that may be held by another code path that calls the filter graph manager. To do so could result in a deadlock.

When to Use

The filter graph manager queries for this interface on any plug-in distributors that it aggregates. If found, it calls the appropriate Run, Pause, or SetSyncSource method before calling them on the IBaseFilter interface of each filter. It calls the NotifyGraphChange method whenever a filter is added or removed, or connections are changed.

Methods in Vtable Order
IUnknown methods Description
QueryInterface Returns pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.
IDistributorNotify methods Description
Stop Called when the filter graph is entering a stopped state.
Pause Called when the filter graph is entering a paused state.
Run Called when the filter graph is entering a running state.
SetSyncSource Called when a new clock is registered.
NotifyGraphChange Called when the set of filters in the filter graph change or their connections change.


IDistributorNotify::NotifyGraphChange

IDistributorNotify Interface

Called when the set of filters in the filter graph change or their connections change.

HRESULT NotifyGraphChange(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

This method is called whenever an IFilterGraph::AddFilter, IFilterGraph::RemoveFilter, or IFilterGraph::ConnectDirect method is called or a method is called that will lead to one of these being called (such as IGraphBuilder::RenderFile).

Make sure you use Release on any held filters that have been removed at this point. For performance reasons, PIDs might choose not to rescan the filters until the PIDs actually need the interfaces, because there might be several separate notifications sent. However, it is important to release any cached interfaces immediately.


IDistributorNotify::Pause

IDistributorNotify Interface

Called when the filter graph is entering a paused state.

HRESULT Pause(void);

Return Values

Returns S_OK if the transition is complete; otherwise, returns one of the following values.
Value Meaning
Error value Transition failed.
S_FALSE Transition is not complete, but no error has occurred.

Remarks

This method is called before the filters are notified.


IDistributorNotify::Run

IDistributorNotify Interface

Called when the filter graph is entering a running state.

HRESULT Run(
  REFERENCE_TIME tStart
  );

Parameters
tStart
Stream-time offset that will be passed to every filter's IBaseFilter::Run parameter.
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 called before the filters are notified.


IDistributorNotify::SetSyncSource

IDistributorNotify Interface

Called when a new clock is registered.

HRESULT SetSyncSource(
  IReferenceClock * pClock
  );

Parameters
pClock
[in] Pointer to the IReferenceClock interface.
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 called before the filters are notified. Make sure to use AddRef on the pClock parameter if the plug-in distributor intends to hold it beyond this method call.


IDistributorNotify::Stop

IDistributorNotify Interface

Called when the filter graph is entering a stopped state.

HRESULT Stop(void);

Return Values

Returns S_OK if the transition is complete; otherwise, returns one of the following values.
Value Meaning
Error value Transition failed.
S_FALSE Transition is not complete, but no error has occurred.

Remarks

This method is called before the filters are notified.

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

*Top of Page