KSPROPERTY-Struktur

Artikel
02/07/2024

Die KSPROPERTY-Struktur gibt eine einzelne Kernelstreamingeigenschaft innerhalb eines Eigenschaftensatzes an.

Die Strukturen KSEVENT, KSMETHOD und KSPROPERTY sind Aliase für die KSIDENTIFIER-Struktur . Daher sind ihre Definitionen identisch.

Syntax

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

Member

Set

Gibt eine GUID an, die einen Kernelstreamingeigenschaftensatz identifiziert. Weitere Informationen zu Eigenschaftensatz-GUIDs finden Sie weiter unten im Abschnitt Hinweise .

Id

Gibt den Member des Eigenschaftensatzes an.

Flags

Gibt den Anforderungstyp an. Wenn Sie einen Stream class minidriver schreiben, finden Sie auch unter KSPROPERTY_ITEM klassenspezifische Flaginformationen.

Flags sollten einer der in der folgenden Tabelle aufgeführten Werte sein. Einige der Flags können mithilfe einer bitweisen OR-Operation kombiniert werden.

Wert	BESCHREIBUNG
KSPROPERTY_TYPE_GET	Ruft den Wert des angegebenen Eigenschaftselements ab.
KSPROPERTY_TYPE_SET	Legt den Wert des angegebenen Eigenschaftselements fest.
KSPROPERTY_TYPE_SETSUPPORT	Fragt ab, ob der Treiber diesen Eigenschaftssatz unterstützt.
KSPROPERTY_TYPE_BASICSUPPORT	Fragt die Anforderungstypen ab, die der Treiber für dieses Eigenschaftselement verarbeitet. Gibt KSPROPERTY_TYPE_GET oder KSPROPERTY_TYPE_SET oder beides zurück. Dieses Flag muss von allen Eigenschaftensätzen unterstützt werden.
KSPROPERTY_TYPE_DEFAULTVALUES	Fragt die Standardwerte für das angegebene Eigenschaftselement ab. Gibt eine Struktur vom Typ KSPROPERTY_VALUES zurück.
KSPROPERTY_TYPE_RELATIONS	Fragt alle Eigenschaften mit Abhängigkeiten von der aktuellen Einstellung dieser Eigenschaft ab. Gibt an, dass die Eigenschaftsbeziehungsliste zurückgegeben werden soll, oder die Menge des Pufferraums, der für eine solche Liste erforderlich ist, wenn der Rückgabepuffer die Größe eines ULONG-Objekts aufweist. Jedes Element befindet sich auf FILE_QUAD_ALIGNMENT, dem eine KSMULTIPLE_ITEM-Struktur vorangestellt ist. Dies ist ungültig, wenn die Unterstützung des Eigenschaftssatzes im Allgemeinen abfragt. Dieses Flag muss von allen Eigenschaftensätzen unterstützt werden.
KSPROPERTY_TYPE_SERIALIZESET	Serialisieren Sie den Eigenschaftssatz mithilfe der Standard-KSPROPERTY_SERIALHDR - und KSPROPERTY_SERIAL strukturen.
KSPROPERTY_TYPE_UNSERIALIZESET	Wirialisieren Sie den Eigenschaftssatz mithilfe der Standardstrukturen KSPROPERTY_SERIALHDR und KSPROPERTY_SERIAL .
KSPROPERTY_TYPE_SERIALIZESIZE	Gibt eine ULONG zurück, die die Größe der Eigenschaftendaten angibt, wenn sie als Teil einer KSPROPERTY_TYPE_SERIALIZESET-Anforderung serialisiert werden. Die Größe 0 gibt an, dass eine Eigenschaft nicht serialisiert werden muss.
KSPROPERTY_TYPE_SERIALIZERAW	Gibt an, dass die Eigenschaften in diesem Satz vom Unterstützungshandler für den Eigenschaftensatz serialisiert werden sollen, sofern vorhanden. Andernfalls schlägt der Aufruf fehl. Das Serialisierungsformat ist privat. Dieser Vorgang muss umgekehrt KSPROPERTY_TYPE_UNSERIALIZERAW sein.
KSPROPERTY_TYPE_TOPOLOGY	Die übergebene Eigenschaft ist vom Typ KSP_NODE, wobei NodeId die numerische ID des Topologieknotens angibt. Legen Sie dieses Flag nicht selbst fest. stattdessen ODER mit anderen Flags in dieser Tabelle.
KSPROPERTY_TYPE_UNSERIALIZERAW	Gibt an, dass der bereitgestellte Puffer eine Gruppe von Eigenschaften enthält, die zu diesem Satz gehören, die vom Unterstützungshandler für den Eigenschaftensatz nichtialisiert werden sollen, sofern vorhanden. Andernfalls schlägt der Aufruf fehl. Das Serialisierungsformat ist privat. Dieser Vorgang muss umgekehrt KSPROPERTY_TYPE_SERIALIZERAW sein.

Hinweise

Die Größe des übergebenen Ausgabepuffers bestimmt, welche Daten von einer KSPROPERTY_TYPE_BASICSUPPORT-Anforderung zurückgegeben werden. Wenn der Ausgabepuffer die Größe einer ULONG hat, werden nur die Zugriffsflags zurückgegeben. Wenn der Ausgabepuffer die Größe der KSPROPERTY_DESCRIPTION-Struktur hat, wird die Struktur mit den Zugriffsflags, der inklusiven Größe der gesamten Werteinformationen, den Eigenschaftenwerttypinformationen und der Anzahl der Memberlisten gefüllt, die der Struktur entsprechen.

Bei einer KSPROPERTY_TYPE_RELATIONS Anforderung hängen die zurückgegebenen Daten auch von der Größe des Ausgabepuffers ab. Wenn die Ausgabepuffergröße null ist, wird die größe, die zum Zurückgeben der zugehörigen Eigenschaften erforderlich ist, in BytesReturned mit einer Warnung status STATUS_BUFFER_OVERFLOW zurückgegeben. Wenn der Puffer die Größe einer KSMULTIPLE_ITEM-Struktur hat, werden sowohl die Bytegröße als auch die Anzahl der Beziehungen zurückgegeben. Andernfalls wird erwartet, dass der Puffer lang genug ist, um die KSMULTIPLE_ITEM-Struktur und alle zugehörigen Eigenschaftenbezeichner zurückzugeben, die als Liste von KSIDENTIFIER-Strukturen zurückgegeben werden.

KSPROPERTY_TYPE_SERIALIZESET - und KSPROPERTY_TYPE_UNSERIALIZESET-Anforderungen ermöglichen die Interaktion mit mehreren Eigenschaften mit einem einzelnen Aufruf des Clients. Wenn der Kernelstreaminghandler zum Verarbeiten von Eigenschaftsanforderungen verwendet wird, werden diese von der KsPropertyHandler-Funktion in mehrere Aufrufe unterteilt. Bei Verwendung dieses Handlers steuert die Eigenschaftensatzdefinition, welche Eigenschaften serialisiert werden sollen.

Bei Serialisierungsanforderungen wird der SerializedSize-Member der relevanten KSPROPERTY_ITEM-Struktur auf einen Wert ungleich null überprüft, der die Größe der Eigenschaft in Bytes angibt. Wenn der Wert des SerializedSize-Elements 1 ist, ist er unbekannt und muss abgefragt werden (alle unbekannten Eigenschaften beginnen mit einer KSMULTIPLE_ITEM Struktur, die separat abgefragt werden kann). Um die Gesamtgröße einer Serialisierung abzufragen, übergibt der Client im Aufruf von DeviceIoControl einen Puffer der Länge Null. BytesReturned gibt dann die Größe in Bytes zurück, die der Puffer sein muss, um den Satz zu serialisieren, und eine Warnung status STATUS_BUFFER_OVERFLOW. Ein Puffer, der dieser Größe zugeordnet ist, kann dann mit den serialisierten Daten gefüllt werden.

Das Format des Serialisierungspuffers ist ein KSPROPERTY_SERIALHDR, gefolgt von serialisierten Eigenschaften. Jede folgende Eigenschaft enthält einen Header (KSPROPERTY_SERIAL), gefolgt von den Eigenschaftendaten, wobei der Anfang jeder Eigenschaft auf FILE_LONG_ALIGNMENT. Beachten Sie, dass die serielle Headerstruktur für FILE_LONG_ALIGNMENT definiert ist.

KSPROPERTY_TYPE_SERIALIZERAW und KSPROPERTY_TYPE_UNSERIALIZERAW werden unterstützt, wenn ein Eigenschaftenelementhandler vorhanden ist. Die KsPropertyHandler-Funktion ruft den vom Minitreiber bereitgestellten Handler auf. Die für die Serialisierung erforderliche Puffergröße kann auch abgefragt werden, indem ein Puffer der Länge null an eine Serialisierungsanforderung übergeben wird. Da Handler an Eigenschaftselemente und nicht an den Eigenschaftensatz angefügt werden, muss im Property-Parameter ein bestimmtes Element innerhalb des Eigenschaftensatzes angegeben werden. Dieser Handler kann mehrere Eigenschaften innerhalb des Satzes behandeln.

Microsoft stellt mehrere systemdefinierte Eigenschaftensatz-GUIDs bereit. Minidriver geben eine dieser GUIDs im Element Festlegen an. Kernel-Streamingeigenschaftensätze beginnen in der Regel mit einem KSPROPSETID - oder propSETID-Präfix . Kernel-Streaming-Eigenschaftssätze werden in ks.h, ksmedia.h, bdamedia.h und möglicherweise anderen Headerdateien definiert.

Weitere Informationen zu Kernelstreamingereignissen finden Sie unter KS-Eigenschaften, -Ereignisse und -Methoden.