KSPROPERTY 結構

發行項
02/07/2024

KSPROPERTY 結構會指定屬性集中的單一核心串流屬性。

KSEVENT、KSMETHOD 和 KSPROPERTY 結構是 KSIDENTIFIER 結構的別名。因此，其定義完全相同。

語法

struct KSPROPERTY {
  GUID Set;
  ULONG Id;
  ULONG Flags;
};

成員

Set

指定識別核心串流屬性集的 GUID。如需屬性集 GUID 的詳細資訊，請參閱下面的一節。

Id

指定屬性集的成員。

Flags

指定要求類型。如果您要撰寫數據流類別 minidriver，另請參閱類別特定旗標資訊的 KSPROPERTY_ITEM 。

旗標應該是下表所列的其中一個值。某些旗標可能會使用位 OR 運算來結合。

值	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。

備註

傳遞的輸出緩衝區大小會決定從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 屬性、事件和方法。