KSFILTER_DESCRIPTOR 結構 (ks.h)

發行項
02/26/2024

KSFILTER_DESCRIPTOR 結構描述指定篩選處理站所建立之篩選的特性。

語法

typedef struct _KSFILTER_DESCRIPTOR {
  const KSFILTER_DISPATCH     *Dispatch;
  const KSAUTOMATION_TABLE    *AutomationTable;
  ULONG                       Version;
  ULONG                       Flags;
  const GUID                  *ReferenceGuid;
  ULONG                       PinDescriptorsCount;
  ULONG                       PinDescriptorSize;
  const KSPIN_DESCRIPTOR_EX   *PinDescriptors;
  ULONG                       CategoriesCount;
  const GUID                  *Categories;
  ULONG                       NodeDescriptorsCount;
  ULONG                       NodeDescriptorSize;
  const KSNODE_DESCRIPTOR     *NodeDescriptors;
  ULONG                       ConnectionsCount;
  const KSTOPOLOGY_CONNECTION *Connections;
  const KSCOMPONENTID         *ComponentId;
} KSFILTER_DESCRIPTOR, *PKSFILTER_DESCRIPTOR;

成員

Dispatch

此類型篩選條件 之KSFILTER_DISPATCH 結構的指標。此成員是選擇性的，而且只有想要接收篩選建立、刪除等通知的用戶端才能提供。有興趣處理數據 (轉換的驅動程式，) 通常會提供這個分派數據表和處理函式。提供篩選處理函式，而不是個別的針腳處理函式，是讓驅動程式以篩選為主而不是以針腳為中心的功能。

AutomationTable

此類型篩選條件 之KSAUTOMATION_TABLE 結構的指標。自動化數據表說明此篩選所支援的屬性、方法和事件。此自動化數據表會與AVStream針對所有篩選所提供的自動化數據表合併。如果用戶端提供已由 AVStream 實作的屬性、方法或事件處理程式，用戶端的實作會取代 AVStream 的。

Version

這個成員會指定篩選描述元的版本。此成員應設定為 KSFILTER_DESCRIPTOR_VERSION。

Flags

描述篩選行為的旗標。使用位 OR 指定旗標，但KSFILTER_FLAG_CRITICAL_PROCESSING和KSFILTER_FLAG_HYPERCRITICAL_PROCESSING除外，互斥：

旗標	描述
KSFILTER_FLAG_DISPATCH_LEVEL_PROCESSING	表示 IRQL DISPATCH_LEVEL的篩選進程，而不是PASSIVE_LEVEL。這適用於篩選進程回呼，如 KSFILTER_DISPATCH中所述。
KSFILTER_FLAG_CRITICAL_PROCESSING	如果已指定異步處理，或系統在PASSIVE_LEVEL執行，且進程呼叫會在DISPATCH_LEVEL中執行，則會在佇列的工作專案中完成處理。此旗標表示工作項目應該放在重要工作佇列上，而不是延遲的工作佇列。
KSFILTER_FLAG_RECEIVE_ZERO_LENGTH_SAMPLES	如果篩選中心篩選條件需要接收長度為零的樣本， (具有旗標但沒有數據) 數據流標頭，請設定此旗標。如果未設定此旗標，則會將零長度樣本傳遞至下游針腳，並自動傳播必要的旗標。請注意，這與 DX8 和先前的預設行為相同。如果發生這種情況，這些範例會略過minidriver。將 KSPROCESSPIN 中的 Terminate 旗標設定為「關閉」此旗標。另請參閱以篩選為中心的處理。
KSFILTER_FLAG_DENY_USERMODE_ACCESS	此旗標可防止使用者模式存取特定篩選，以及在此篩選上具現化的所有針腳。
KSFILTER_FLAG_HYPERCRITICAL_PROCESSING	如果已指定異步處理，或系統在PASSIVE_LEVEL執行，且進程呼叫位於DISPATCH_LEVEL，AVStream 會處理已排入佇列的工作專案。此旗標表示工作項目應該放在超關鍵工作佇列上，而不是延遲的工作佇列或重大工作佇列。

ReferenceGuid

GUID 的指標，這是識別此篩選類型之 Unicode 參考字串的二進位表示法。如果有多個篩選處理站存在，每個篩選站都必須有唯一的 GUID。另請注意，提供參考字串的其他方法需要使用 KsCreateFilterFactory 註冊篩選描述元。 ReferenceGuid 中指定的值必須符合驅動程式 INF 檔案中的篩選特定參考 GUID。請參閱初始化 AVStream Minidriver。

PinDescriptorsCount

此成員會指定 PinDescriptors 成員中為此篩選類型提供的針腳描述元數目。在 Windows XP 和更新版本上，如果驅動程式動態建立針腳， PinDescriptorsCount 可能是零。

PinDescriptorSize

此成員會指定描述元數據表中每個個別描述項的大小。這個值必須是八個的倍數，而且必須至少 大小為 (KSPIN_DESCRIPTOR_EX) 。較大的值可讓用戶端特定的描述元資訊附加至釘選描述元。請參閱中的其他資訊。

PinDescriptors

描述此篩選類型所支持針腳之 KSPIN_DESCRIPTOR_EX 結構的陣列指標。如果 PinDescriptorsCount 為零，請將此成員設定為 NULL。

CategoriesCount

此成員會指定此篩選類型之 Categories 成員中提供的類別 GUID 數目。零是這個成員的合法值。

Categories

此篩選類型類別 GUID 陣列的指標。如有需要，系統會為每個類別註冊裝置介面。只有當 CategoriesCount 為零時，這個成員才會是 Null。

NodeDescriptorsCount

此成員會指定 NodeDescriptors 中提供的拓撲節點描述項數目。零是這個成員的合法值。

NodeDescriptorSize

此成員會指定描述元數據表中每個個別描述元位元組的大小。這個值必須是八個以上的倍數，且大小至少為 (KSNODE_DESCRIPTOR) 。較大的值可讓用戶端特定的描述元資訊附加至節點描述元。請參閱中的其他資訊。

NodeDescriptors

描述此篩選類型拓撲節點之 KSNODE_DESCRIPTOR 結構的陣列指標。只有當 NodeDescriptorsCount 為零時，這個成員才會是 Null。

ConnectionsCount

此成員會指定 Connections 中存在的拓撲連線數目。這個成員可能是零，表示使用預設連接集。使用預設連線表示篩選條件的拓撲會以單一拓撲節點描述，其中篩選上的每個針腳都會連線到拓撲節點上的對應標識符。每個連線的方向都是由釘選數據流所決定。

Connections

此篩選類型中存在 KSTOPOLOGY_CONNECTION 結構的陣列指標。此成員是選擇性的;只有在 ConnectionsCount 為零時， (在此情況下，才會使用預設拓撲) 為 NULL。

ComponentId

這個篩選類型的 KSCOMPONENTID 結構的指標。這用於提供識別資訊的元件標識碼屬性。這個成員是選擇性的。

備註

在配置篩選描述元時，呼叫端可能會發現一些宏很有用。除了指定針腳描述元、類別、節點描述元和聯機的計數、大小和數據表，還有一些有用的宏：

巨集	描述
DEFINE_KSFILTER_PIN_DESCRIPTORS (數據表)	自動將數據表中的項目數目、數據表中的每個專案大小，以及釘選描述項本身的數據表插入篩選描述元中。
DEFINE_KSFILTER_CATEGORIES (數據表)	自動將數據表中的類別數目和數據表本身插入篩選描述元中。
DEFINE_KSFILTER_CATEGORIES_NULL	自動填入類別成員，以取得未定義任何類別的篩選。
DEFINE_KSFILTER_NODE_DESCRIPTORS (數據表)	自動將數據表中的項目數目、數據表中的每個專案大小，以及節點描述項本身的數據表插入篩選描述元中。
DEFINE_KSFILTER_NODE_DESCRIPTORS_NULL	針對未定義拓撲節點的篩選，自動填入節點描述項成員。
DEFINE_KSFILTER_CONNECTIONS (數據表)	自動將數據表中的連接數目和數據表本身插入篩選描述元。
DEFINE_KSFILTER_DEFAULT_CONNECTIONS	自動填入連接數據表，以取得未定義明確連線的篩選。