[DirectShow] 026 - Plug-in Distributors

Plug-in distributors (PIDs) are a way to extend the functionality of the filter graph manager. A plug-in distributor is a COM object that the filter graph manager aggregates at run time. Applications obtain access to the PID through the filter graph manager.

PIDs 是一种扩展 filter graph manager 功能的方法。一个 PIDs 是一个 filter graph manager 在运行时聚合的 COM 对象。应用程序通过 filter graph manager 获得访问 PID 的权限。

When the filter graph manager is queried for an interface that it does not support, it searches the registry for a key with the following form:

当 filter graph manager 被询问一个它不支持的接口的时候，它就到注册表的 HKEY_CLASSES_ROOT/Interface/IID/Distributor KEY 中搜索。

IID is a string containing the interface identifier. If the registry entry exists, the value of the entry defines the class identifier (CLSID) of a PID that supports the interface. The filter graph manager aggregates the PID and returns an interface pointer, thereby acting as the outer IUnknown for the PID. When the application calls methods on the interface, it is actually calling them on the PID. However, the existence of the PID is transparent to the application 。

IID 是一个包含接口标识的字符串。如果注册表条目存在，那个条目的值就是支持这个接口的 PID 的类标识（ CLSID ）。 filter graph manager 聚合 PID 并返回接口指针，当应用程序在接口上调用方法，实际上是在 PID 上调用方法。对于应用程序来说， PID 是透明的。

The term distributor stems from the fact that a PID can query its outer IUnknown pointer for interfaces on the filter graph manager. By calling the IFilterGraph::EnumFilters method, the PID can enumerate the filters in the graph and distribute method calls to those filters. In this way, a PID can serve as a single control point for the application to call methods on filters.

术语 distributor 源自 PID 能在 filter graph manager 上为接口询问它外部的 IUnknown 指针。通过调用 IFilterGraph::EnumFilter 方法， PID 可以枚举 graph 中的 filter 并分配 filter 调用的方法。用这种方法， PID 可以为应用程序在 filter 上调用方法充当一个控制点。

When the filter graph manager aggregates a PID, it queries the PID for the IDistributorNotify interface. If the PID supports this interface, the filter graph manager uses it to notify the PID about changes in the graph:

当 filter graph manager 聚合一个 PID ，它就询问 PID 的 IDistributorNotify 接口。如果 PID 支持这个接口， filter graph manager 就使用这个接口通知 PID 一下 graph 的变化：

·         When the filter graph switches between run, paused, and stopped states, it calls IDistributorNotify::Run , IDistributorNotify::Pause , or IDistributorNotify::Stop .

·         当 filter graph 在运行，暂停和停止之间切换状态时，它调用 IDistributorNotify::Run ， IDistributorNotify::Pasuse ，或者 IDistributorNotify::Stop 。

·         When a reference clock is set, the filter graph manager calls IDistributorNotify::SetSyncSource .

·         当参考时钟被设置， filter graph manager 调用 IDistributorNotify::SetSyncSource 。

·         When filters are added or removed, or pin connections are changed, the filter graph manager calls IDistributorNotify::NotifyGraphChange .

·         当 filter 被添加或移除，或者 pin 连接被改变， filter graph manager 调用 IDistributorNotify::NotifyGraphChange 。

To implement a custom PID, create a COM object that supports aggregation. It must support an interface that the filter graph manager does not already support. Optionally, it can support the IDistributorNotify interface.

要执行通用的 PID ，就要创建一个支持聚合的 COM 对象。必须支持一个 filter graph manager 不支持的接口。它能支持 IDistributorNotify 接口。

If the PID obtains any interface pointers from the filter graph manager, it should release them immediately. Otherwise, it might create a circular reference count, which could prevent the filter graph manager from being destroyed. Holding a reference count on the filter graph manager is unnecessary in any case, because the filter graph manager controls the PID's lifetime.

如果 PID 从 filter graph manager 获得一些接口指针，它应该立即释放掉。否则，它可能创建循环引用计数。在 filter Graph Manager 上握着引用计数没有必要，因为 filter graph manager 控制 PID 的生命周期。

Because a PID is designed specifically for aggregation by the filter graph manager, you might want to enforce this in the PID's constructor method. Check whether the outer IUnknown pointer is NULL, and if so, return the error code VFW_E_NEED_OWNER. (See Error and Success Codes .) Also, to prevent other objects from aggregating the PID, you can query the outer IUnknown pointer for the IGraphBuilder interface. Return an error code if the object does not expose IGraphBuilder .

因为 PID 被 filter graph manager 设计特殊的聚合，你可能想在 PID 的构造函数中强制这一点。检测 IUnknown 指针释放为 NULL ，如果为，返回错误码 VFW_E_NEED_OWNER 。为了防止其他对象聚合 PD ，你可以询问 IGrpahBuilder 接口的 IUnknown 指针。如果对象没有暴露 IGraphBuilder 则返回错误码。