KSIDENTIFIER 結構 (ks.h)

發行項
02/26/2024

KSIDENTIFIER 結構會指定可唯一識別一組相關 GUID 的 GUID，以及參考該集合內特定成員的索引值。

KSDEGRADE、KSEVENT、KSMETHOD、KSPIN_INTERFACE、KSPIN_MEDIUM 和 KSPROPERTY typedefs 是 KSIDENTIFIER 結構的別名。因此，其定義完全相同。如需使用方式的詳細資訊，請參閱個別 typedef 主題。

語法

typedef struct {
  union {
    struct {
      GUID  Set;
      ULONG Id;
      ULONG Flags;
    } _IDENTIFIER;
    struct {
      GUID  Set;
      ULONG Id;
      ULONG Flags;
    };
    LONGLONG Alignment;
  };
} KSIDENTIFIER, *PKSIDENTIFIER;

成員

_IDENTIFIER

請參閱下面的＜備註＞。

_IDENTIFIER.Set

請參閱下面的＜備註＞。

_IDENTIFIER.Id

請參閱下面的＜備註＞。

_IDENTIFIER.Flags

請參閱下面的＜備註＞。

Set

請參閱下面的＜備註＞。

Id

請參閱下面的＜備註＞。

Flags

請參閱下面的＜備註＞。

Alignment

請參閱下面的＜備註＞。

備註

KSIDENTIFIER 成員描述

Set

指定 GUID，識別核心串流屬性、事件、方法、通訊總線集。 KSPIN_INTERFACE 結構描述介面集內的特定介面。 KSDEGRADE 結構包含降低策略的特定專案。如需詳細資訊，請參閱下面的＜備註＞一節。

Id

指定屬性、事件、方法集的成員。針對 KSPIN_MEDIUM，識別總線上的唯一連線。針對 KSPIN_INTERFACE，指定介面集內這個特定介面的標識碼。針對 KSDEGRADE，指定集合內專案的集合特定識別碼。

Flags

指定要求類型。如果您要撰寫數據流類別 minidriver，另請參閱類別特定旗標資訊的 KSPROPERTY_ITEM 。旗標應該是下表所列的其中一個值。某些旗標可能會使用位 OR 運算來結合。

如需使用方式的詳細資訊，請參閱 KSDEGRADE、 KSEVENT、 KSMETHOD、 KSPIN_INTERFACE、 KSPIN_MEDIUM和 KSPROPERTY typedef 主題。

指定 KSPROPERTY 要求類型。

KSPROPERTY 旗標值	Description
KSPROPERTY_TYPE_GET	擷取指定之屬性項的值。
KSPROPERTY_TYPE_SET	設定指定之屬性項的值。
KSPROPERTY_TYPE_SETSUPPORT	查詢驅動程式是否支援此屬性集。
KSPROPERTY_TYPE_BASICSUPPORT	查詢驅動程式處理這個屬性專案的要求類型。傳回KSPROPERTY_TYPE_GET或KSPROPERTY_TYPE_SET或兩者。所有屬性集都必須支援此旗標。
KSPROPERTY_TYPE_DEFAULTVALUES	查詢指定屬性項目的預設值。傳回類型 KSPROPERTY_VALUES的結構。
KSPROPERTY_TYPE_RELATIONS	查詢具有此屬性目前設定相依性的所有屬性。指定要傳回屬性關聯清單，如果傳回緩衝區是 ULONG 的大小，則為這類清單所需的緩衝區空間數量。每個元素都位於FILE_QUAD_ALIGNMENT上，前面加上KSMULTIPLE_ITEM結構。當查詢支援一般設定的屬性時，這無效。所有屬性集都必須支援此旗標。
KSPROPERTY_TYPE_SERIALIZESET	使用標準KSPROPERTY_SERIALHDR和KSPROPERTY_SERIAL結構串行化屬性集。
KSPROPERTY_TYPE_UNSERIALIZESET	使用標準 KSPROPERTY_SERIALHDR 和 KSPROPERTY_SERIAL 結構，取消串行化屬性集。
KSPROPERTY_TYPE_SERIALIZESIZE	當串行化為KSPROPERTY_TYPE_SERIALIZESET要求的一部分時，傳回指定屬性數據的ULONG大小。零的大小表示屬性不需要串行化。
KSPROPERTY_TYPE_SERIALIZERAW	指定這個集合中的屬性應該由屬性集支援處理程式串行化，如果有的話。如果沒有，呼叫就會失敗。串行化格式為私用。此作業必須是反向KSPROPERTY_TYPE_UNSERIALIZERAW。
KSPROPERTY_TYPE_TOPOLOGY	傳遞的屬性類型為 KSP_NODE，其中 NodeId 表示拓撲節點的數值識別碼。請勿自行設定此旗標;相反地，或與此表格中的其他旗標搭配使用。
KSPROPERTY_TYPE_UNSERIALIZERAW	指定提供的緩衝區包含屬於這個集合的屬性群組，如果屬性集支援處理程式存在，則應該取消串行化。如果沒有，呼叫就會失敗。串行化格式為私用。此作業必須是反向KSPROPERTY_TYPE_SERIALIZERAW。

指定 KSEVENT 要求類型。此旗標應該是下表所列的其中一個值。

KSEVENT 旗標值	Description
KSEVENT_TYPE_ENABLE	啟用此事件類型的事件通知。驅動程式會繼續事件通知，直到客戶端明確停用它為止。
KSEVENT_TYPE_ONESHOT	僅啟用此事件下一次出現的事件通知。用戶端不需要 (，而且不應該在事件發生后) 停用事件。
KSEVENT_TYPE_SETSUPPORT	查詢事件集清單，或支援特定事件集。
KSEVENT_TYPE_BASICSUPPORT	查詢以支援特定事件類型。
KSEVENT_TYPE_ENABLEBUFFERED	驅動程式會排入事件通知，而不是通知用戶端。然後，用戶端會發出第二個IOCTL_KS_ENABLE_EVENT要求，KSEVENT_TYPE_QUERYBUFFER以接收佇列的事件通知。
KSEVENT_TYPE_TOPOLOGY	表示傳遞的事件類型為 KSE_NODE，其中 NodeId 表示拓撲節點的數值識別碼。請勿自行設定此旗標;而是使用此清單中的其他旗標進行 OR。
KSEVENT_TYPE_QUERYBUFFER	擷取下一個緩衝事件通知。

指定 KSMETHOD 要求類型。另請參閱 KSMETHOD_ITEM的KSMETHOD_TYPE_Xxx旗標。要求可以包含下表所列值的組合。

KSMETHOD 旗標值	Description
KSMETHOD_TYPE_BASICSUPPORT	指示查詢迷你驅動程式，以判斷它是否支援方法集的指定方法。
KSMETHOD_TYPE_SEND	表示迷你驅動程式應該執行指定的方法。客戶端必須知道方法對指定參數的影響，亦即參數是讀取、寫入、寫入兩者或兩者皆非。迷你驅動程式會使用 KSMETHOD_ITEM 結構來指定方法對參數的影響。
KSMETHOD_TYPE_SETSUPPORT	指示查詢迷你驅動程式，以判斷它是否支援指定的方法集。
KSMETHOD_TYPE_TOPOLOGY	表示指定的方法的類型為 KSM_NODE，其中 NodeId 成員是拓撲節點的標識碼。請勿自行設定此旗標;相反地，或此清單中的其他旗標。

對於 KSDEGRADE，指定目前降低百分比、以每千個 (表示的值 1000 表示沒有降低) ，或指定介面所指定原生單位的時間量。

Alignment

未使用。未命名等位的成員，用來強制在未命名結構上正確對齊。

備註

如需使用方式的詳細資訊，請參閱 KSDEGRADE、KSEVENT、KSMETHOD、KSPIN_INTERFACE、KSPIN_MEDIUM 和 KSPROPERTY typedef 主題。

在集合內使用標識碼可讓一個標識符執行單一大型比較，例如，使用 switch 語句來比較集合) 內的識別碼，例如較小的快速比較 (。例如， 屬性集 是由唯一 GUID 識別碼所參考，而該集合內的屬性則由簡短標識碼所參考。

方法、事件、介面和 中型集合 可以視為集合的「類別」。

傳遞的輸出緩衝區大小會決定從KSPROPERTY_TYPE_BASICSUPPORT要求傳回的數據。如果輸出緩衝區是ULONG的大小，則只會傳回存取旗標。如果輸出緩衝區是 KSPROPERTY_DESCRIPTION 結構的大小，結構會填入存取旗標、整個值資訊的內含大小、屬性值類型資訊，以及對應至結構的成員清單數目。

對於KSPROPERTY_TYPE_RELATIONS要求，傳回的數據也取決於輸出緩衝區的大小。如果輸出緩衝區大小為零，傳回相關屬性所需的大小會以 BytesReturned 傳回，且警告狀態為 STATUS_BUFFER_OVERFLOW。如果緩衝區是 KSMULTIPLE_ITEM 結構的大小，則會傳回位元組大小和關聯計數。否則，緩衝區應該夠長，足以傳回KSMULTIPLE_ITEM結構和所有相關屬性標識碼，這會以 KSIDENTIFIER 結構清單的形式傳回。

KSPROPERTY_TYPE_SERIALIZESET和KSPROPERTY_TYPE_UNSERIALIZESET要求允許與多個屬性與來自用戶端的單一呼叫互動。如果使用核心串流處理程式來處理屬性要求，這些處理程式會由 KsPropertyHandler 函式分成多個呼叫。使用此處理程式時，屬性集定義會控制要串行化的屬性。

針對串行化要求，會檢查相關KSPROPERTY_ITEM結構的 SerializedSize 成員是否有非零值，指出屬性的大小，以位元組為單位。如果 SerializedSize 成員的值是 1，它就未知，而且必須查詢 (所有未知的屬性都是以可個別查詢) KSMULTIPLE_ITEM 結構開頭。若要查詢串行化需要的總大小，用戶端會在呼叫 DeviceIoControl 時傳遞零長度緩衝區。 BytesReturned 接著會傳回大小，以位元組為單位，緩衝區必須串行化集合，以及STATUS_BUFFER_OVERFLOW的警告狀態。接著，配置該大小的緩衝區可以填入串行化的數據。

串行化緩衝區的格式是 KSPROPERTY_SERIALHDR，後面接著串行化屬性。後面每個屬性都包含標頭 (KSPROPERTY_SERIAL) ，後面接著屬性數據，並在FILE_LONG_ALIGNMENT上包含每個屬性的開頭。請注意，串行標頭結構定義在 FILE_LONG_ALIGNMENT上。

如果屬性項目處理程式存在，則支援KSPROPERTY_TYPE_SERIALIZERAW和KSPROPERTY_TYPE_UNSERIALIZERAW。 KsPropertyHandler 函式會叫用 minidriver 所提供的處理程式。將長度為零的緩衝區傳遞至串行化原始要求，也可以查詢串行化所需的緩衝區大小。因為處理程式會附加至屬性專案，而不是屬性集，所以必須在 Property 參數中指定屬性集內的特定專案。此處理程式可能會處理集合內的多個屬性。

Microsoft 提供數個系統定義的屬性集 GUID。 Minidrivers 會在 Set 成員中指定其中一個 GUID。核心串流屬性集通常會以 KSPROPSETID 或 PROPSETID 前置詞開頭。核心串流屬性集定義於 ks.h、 ksmedia.h、 bdamedia.h，以及其他頭檔。

如需核心串流屬性的詳細資訊，請參閱 KS 屬性、事件和方法。

Microsoft 提供數個系統定義的事件集 GUID。 Minidrivers 會在 Set 成員中指定其中一個 GUID。核心串流事件集通常會以 KSEVENTSETID 前置詞開頭。核心串流事件集定義於 ks.h、 ksmedia.h、 bdamedia.h，以及其他頭檔。

如需核心串流事件的詳細資訊，請參閱 KS 屬性、事件和方法。

Microsoft 提供數個系統定義的方法集 GUID。 Minidrivers 會在 Set 成員中指定其中一個 GUID。核心串流方法集合通常會以 KSMETHODSETID 前置詞開頭。核心串流方法集定義於 ks.h、 ksmedia.h、 bdamedia.h，以及其他頭檔。

如需核心串流方法的詳細資訊，請參閱 KS 屬性、事件和方法。

用戶端可以使用IOCTL_KS_METHOD要求以及 KSMETHOD 結構，在迷你驅動程序處理的核心串流物件上執行方法。如需詳細資訊，請參閱 KS 方法。

KSPIN_MEDIUM結構會識別具有唯一媒體 GUID 和實例識別碼的媒體，這是以總線特定方式產生的。當總線實例不考慮時，會使用保留標識符值KSMEDIUM_TYPE_ANYINSTANCE。例如，KSMEDIUMSETID_Standard是指系統總線，其中應該只有一個。因此，這個實例標識符一律會作為方便使用。

針腳可支持這些媒體上的多個媒體和介面。描述針腳的方式表示針腳所列舉的所有媒體都支援介面清單。如果有情況不成立，可能會使用另一個針腳來描述特定媒體的每個介面子集。

媒體也會由核心串流快取，以加速搜尋可能的連線。

您可以在微調器範例中找到此結構的範例，其中 KSPIN_MEDIUM 代表微調器、交叉列和其他微調器元件之間的唯一連線。

Flags 成員可以根據用戶端採用的訊號降低類型，包含不同的值。請參閱品質管理。如需透過減少訊號質量來解決品質管理問題之不同策略的詳細資訊。

由於 Flags 包含 ULONG 值，因此可能需要多個 Skip 要求來補救品質管理問題。