共用方式為


KSPROPERTY 結構

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

KSEVENTKSMETHODKSPROPERTY 結構是 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_GETKSPROPERTY_TYPE_SET 或兩者。 所有屬性集都必須支援此旗標。
KSPROPERTY_TYPE_DEFAULTVALUES 查詢指定屬性項目的預設值。 傳回類型 KSPROPERTY_VALUES的結構。
KSPROPERTY_TYPE_RELATIONS 查詢具有此屬性目前設定相依性的所有屬性。 指定要傳回屬性關聯清單,如果傳回緩衝區是 ULONG 的大小,則為這類清單所需的緩衝區空間數量。 每個元素都位於 FILE_QUAD_ALIGNMENT上,前面加上 KSMULTIPLE_ITEM 結構。 當查詢支援一般設定的屬性時,這無效。 所有屬性集都必須支援此旗標。
KSPROPERTY_TYPE_SERIALIZESET 使用標準 KSPROPERTY_SERIALHDRKSPROPERTY_SERIAL 結構串行化屬性集。
KSPROPERTY_TYPE_UNSERIALIZESET 使用標準 KSPROPERTY_SERIALHDRKSPROPERTY_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_SERIALIZESETKSPROPERTY_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。 核心串流屬性集通常以 KSPROPSETIDPROPSETID 前置詞開頭。 核心串流屬性集定義於 ks.hksmedia.hbdamedia.h,以及其他頭檔。

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

規格需求

標頭: ks.h (包含 Ks.h)

另請參閱

KSEVENT

KSMETHOD

KSIDENTIFIER

KSMETHOD_ITEM

KSE_NODE

KSPROPERTY_DESCRIPTION

KSPROPERTY_ITEM

KSMULTIPLE_ITEM

KsPropertyHandler

KSPROPERTY_SERIALHDR

KSPROPERTY_SERIAL