KSIDENTIFIER-Struktur (ks.h)

  • Artikel

Die KSIDENTIFIER-Struktur gibt eine GUID an, die einen zugehörigen Satz von GUIDs eindeutig identifiziert, und einen Indexwert, der auf ein bestimmtes Element innerhalb dieser Gruppe verweist.

Die Typdefinitionen KSDEGRADE, KSEVENT, KSMETHOD, KSPIN_INTERFACE, KSPIN_MEDIUM und KSPROPERTY sind Aliase für die KSIDENTIFIER-Struktur . Daher sind ihre Definitionen identisch. Einzelheiten zur Verwendung finden Sie in den einzelnen Themen zur Typdefinition.

Syntax

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

Member

_IDENTIFIER

Weitere Informationen finden Sie weiter unten im Abschnitt "Hinweise".

_IDENTIFIER.Set

Weitere Informationen finden Sie weiter unten im Abschnitt "Hinweise".

_IDENTIFIER.Id

Weitere Informationen finden Sie weiter unten im Abschnitt "Hinweise".

_IDENTIFIER.Flags

Weitere Informationen finden Sie weiter unten im Abschnitt "Hinweise".

Set

Weitere Informationen finden Sie weiter unten im Abschnitt "Hinweise".

Id

Weitere Informationen finden Sie weiter unten im Abschnitt "Hinweise".

Flags

Weitere Informationen finden Sie weiter unten im Abschnitt "Hinweise".

Alignment

Weitere Informationen finden Sie weiter unten im Abschnitt "Hinweise".

Hinweise

KSIDENTIFIER-Memberbeschreibungen

Set

Gibt eine GUID an, die eine Kernelstreamingeigenschaft, ein Ereignis, eine Methode und einen Kommunikationsbussatz identifiziert. Die KSPIN_INTERFACE-Struktur beschreibt eine bestimmte Schnittstelle innerhalb eines Schnittstellensatzes. Die KSDEGRADE-Struktur enthält Besonderheiten von Degradationsstrategien. Weitere Informationen finden Sie weiter unten im Abschnitt Hinweise .

Id

Gibt das Element des Eigenschafts-, Ereignis- und Methodensatzes an. Identifiziert für KSPIN_MEDIUM eine eindeutige Verbindung auf dem Bus. Gibt für KSPIN_INTERFACE die ID-Nummer dieser bestimmten Schnittstelle innerhalb des Schnittstellensatzes an. Gibt für KSDEGRADE den setspezifischen Bezeichner für ein Element innerhalb der Gruppe an.

Flags

Gibt den Anforderungstyp an. Wenn Sie einen Streamklassenminidriver schreiben, finden Sie auch unter KSPROPERTY_ITEM klassenspezifische Flaginformationen. Flags sollten einer der Werte sein, die in der folgenden Tabelle aufgeführt sind. Einige der Flags können mithilfe eines bitweisen OR-Vorgangs kombiniert werden.

Weitere Informationen zur Verwendung finden Sie in den Themen KSDEGRADE, KSEVENT, KSMETHOD, KSPIN_INTERFACE, KSPIN_MEDIUM und KSPROPERTY .

Gibt den KSPROPERTY-Anforderungstyp an.

KSPROPERTY-Flagwert 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 müssen 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-Werts aufweist. Jedes Element befindet sich auf FILE_QUAD_ALIGNMENT, voran eine KSMULTIPLE_ITEM-Struktur. Dies ist beim Abfragen der Unterstützung der im Allgemeinen festgelegten Eigenschaft ungültig. Dieses Flag müssen von allen Eigenschaftensätzen unterstützt werden.
KSPROPERTY_TYPE_SERIALIZESET Serialisieren Sie den Eigenschaftensatz mithilfe der Standardstrukturen KSPROPERTY_SERIALHDR und KSPROPERTY_SERIAL.
KSPROPERTY_TYPE_UNSERIALIZESET Entialisieren Sie den Eigenschaftensatz mithilfe der Standardstrukturen KSPROPERTY_SERIALHDR und KSPROPERTY_SERIAL .
KSPROPERTY_TYPE_SERIALIZESIZE Gibt einen ULONG-Wert zurück, der die Größe der Eigenschaftsdaten 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 Eigenschaftensatzunterstützungshandler serialisiert werden sollen, sofern vorhanden. Andernfalls schlägt der Aufruf fehl. Das Serialisierungsformat ist privat. Dieser Vorgang muss die Inverse von 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 dieser Gruppe gehören, die vom Unterstützungshandler für den Eigenschaftensatz nichtialisiert werden soll, sofern vorhanden. Andernfalls schlägt der Aufruf fehl. Das Serialisierungsformat ist privat. Dieser Vorgang muss die Inverse von KSPROPERTY_TYPE_SERIALIZERAW sein.

Gibt den KSEVENT-Anforderungstyp an. Dieses Flag sollte einer der in der folgenden Tabelle aufgeführten Werte sein.

KSEVENT-Flagwert BESCHREIBUNG
KSEVENT_TYPE_ENABLE Aktiviert die Ereignisbenachrichtigung für diesen Ereignistyp. Der Treiber setzt die Ereignisbenachrichtigung fort, bis sie vom Client explizit deaktiviert wird.
KSEVENT_TYPE_ONESHOT Aktiviert die Ereignisbenachrichtigung nur für das nächste Auftreten dieses Ereignisses. Der Client muss (und sollte) das Ereignis nicht deaktivieren, sobald es aufgetreten ist.
KSEVENT_TYPE_SETSUPPORT Abfragen nach der Liste der Ereignissätze oder zur Unterstützung eines bestimmten Ereignissatzes.
KSEVENT_TYPE_BASICSUPPORT Abfragen zur Unterstützung eines bestimmten Ereignistyps.
KSEVENT_TYPE_ENABLEBUFFERED Anstatt den Client zu benachrichtigen, stellt der Treiber Ereignisbenachrichtigungen in die Warteschlange. Der Client stellt dann eine zweite IOCTL_KS_ENABLE_EVENT Anforderung mit dem KSEVENT_TYPE_QUERYBUFFER aus, um die Ereignisbenachrichtigungen in der Warteschlange zu empfangen.
KSEVENT_TYPE_TOPOLOGY Gibt an, dass das übergebene Ereignis vom Typ KSE_NODE ist, wobei NodeId die numerische ID des Topologieknotens angibt. Legen Sie dieses Flag nicht selbst fest. stattdessen ODER mit anderen Flags aus dieser Liste.
KSEVENT_TYPE_QUERYBUFFER Ruft die nächste gepufferte Ereignisbenachrichtigung ab.

Gibt den KSMETHOD-Anforderungstyp an. Siehe auch die KSMETHOD_TYPE_Xxx-Flags für KSMETHOD_ITEM. Eine Anforderung kann eine Kombination der in der folgenden Tabelle aufgeführten Werte enthalten.

KSMETHOD-Flagwert BESCHREIBUNG
KSMETHOD_TYPE_BASICSUPPORT Gibt an, dass der Minitreiber abfragt, um zu bestimmen, ob er die angegebene Methode des Methodensatzes unterstützt.
KSMETHOD_TYPE_SEND Gibt an, dass der Minitreiber die angegebene Methode ausführen soll. Die Auswirkung der -Methode auf die angegebenen Parameter muss dem Client bekannt sein, d. h. ob die Parameter aus gelesen, in beide oder nicht in beide geschrieben werden. Der Minitreiber verwendet die KSMETHOD_ITEM-Struktur, um die Auswirkung der Methode auf die Parameter anzugeben.
KSMETHOD_TYPE_SETSUPPORT Gibt an, dass der Minitreiber abfragt, um zu bestimmen, ob er den angegebenen Methodensatz unterstützt.
KSMETHOD_TYPE_TOPOLOGY Gibt an, dass die angegebene Methode vom Typ KSM_NODE ist, wobei der NodeId-Member der Bezeichner des Topologieknotens ist. Legen Sie dieses Flag nicht selbst fest. stattdessen ODER mit anderen Flags aus dieser Liste.

Für KSDEGRADE gibt entweder den aktuellen Prozentsatz der Beeinträchtigung an, ausgedrückt in Teilen pro Tausend (wobei ein Wert von 1000 keine Verschlechterung darstellt) oder gibt die Zeitdauer in systemeigenen Einheiten an, wie von der Schnittstelle angegeben.

Alignment

Wird nicht verwendet. Ein Member einer unbenannten Union, die verwendet wird, um die richtige Ausrichtung der unbenannten Struktur zu erzwingen.

Hinweise

Einzelheiten zur Verwendung finden Sie in den Themen KSDEGRADE, KSEVENT, KSMETHOD, KSPIN_INTERFACE, KSPIN_MEDIUM und KSPROPERTY .

Die Verwendung einer ID innerhalb des Satzes ermöglicht es, einen einzelnen großen Vergleich für einen Mengenbezeichner durchzuführen und dann kleinere schnelle Vergleiche durchzuführen (z. B. durch Verwendung einer switch-Anweisung für Bezeichner innerhalb einer Gruppe). Beispielsweise wird auf einen Eigenschaftensatz durch einen eindeutigen GUID-Bezeichner verwiesen, und eigenschaften innerhalb dieser Gruppe werden durch die kurz-ID verwiesen.

Methoden-, Ereignis-, Schnittstellen- und Mittelsätze können als "Klassen" von Sätzen betrachtet werden.

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 als 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 Kernelstreamingeigenschaften finden Sie unter KS-Eigenschaften, -Ereignisse und -Methoden.

Microsoft stellt mehrere systemdefinierte Ereignissatz-GUIDs bereit. Minidriver geben eine dieser GUIDs im Element Festlegen an. Kernel-Streamingereignissätze beginnen in der Regel mit einem KSEVENTSETID-Präfix . Kernel-Streamingereignissä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.

Microsoft stellt mehrere systemdefinierte Methodensatz-GUIDs bereit. Minidriver geben eine dieser GUIDs im Element Festlegen an. Kernelstreamingmethodensätze beginnen in der Regel mit einem KSMETHODSETID-Präfix . Kernel-Streamingmethodensätze werden in ks.h, ksmedia.h, bdamedia.h und möglicherweise anderen Headerdateien definiert.

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

Ein Client kann die IOCTL_KS_METHOD-Anforderung zusammen mit der KSMETHOD-Struktur verwenden, um Methoden für ein Kernelstreamingobjekt auszuführen, das vom Minidriver verarbeitet wird. Weitere Informationen finden Sie unter KS-Methoden.

Die KSPIN_MEDIUM-Struktur identifiziert ein Medium mit einer eindeutigen Medien-GUID und instance Bezeichner, der auf busspezifische Weise generiert wird. Es gibt einen reservierten Bezeichnerwert KSMEDIUM_TYPE_ANYINSTANCE, der verwendet wird, wenn Businstanzen nicht bedenklich sind. Beispielsweise bezieht sich die KSMEDIUMSETID_Standard auf den Systembus, von dem es nur einen geben sollte. Daher wird dieser instance Bezeichner immer nur als Benutzerfreundlichkeit verwendet.

Ein Pin unterstützt möglicherweise mehrere Medien und Schnittstellen auf diesen Medien. Die Art und Weise, wie ein Pin beschrieben wird, impliziert, dass die Liste der Schnittstellen auf allen Medien unterstützt wird, die für einen Pin aufgezählt werden. Wenn es einen Fall gibt, in dem dies nicht der Fall ist, kann ein anderer Pin verwendet werden, um jede Teilmenge von Schnittstellen für die spezifischen Medien zu beschreiben.

Das Medium wird auch vom Kernelstreaming zwischengespeichert, um die Suche nach einer möglichen Verbindung zu beschleunigen.

Ein Beispiel für die Verwendung dieser Struktur finden Sie in einem Tunerbeispiel, in dem KSPIN_MEDIUM eindeutige Verbindungen zwischen Tunern, Querleisten und anderen Tunerkomponenten darstellt.

Das Flags-Element kann unterschiedliche Werte enthalten, die auf der Art der Signalminderung basieren, die der Client verwendet. Weitere Informationen finden Sie unter Qualitätsmanagement. weitere Informationen zu verschiedenen Strategien zur Lösung von Qualitätsmanagementproblemen durch Verringerung der Signalqualität.

Da Flags einen ULONG-Wert enthält, sind möglicherweise mehrere Skip-Anforderungen erforderlich, um das Qualitätsverwaltungsproblem zu beheben.

Anforderungen

Anforderung Wert
Header ks.h (ks.h einschließen)

Weitere Informationen

KSDEGRADE

KSEVENT

KSMETHOD

KSPIN_INTERFACE

KSPIN_MEDIUM

KSPROPERTY