KSIDENTIFIER-Struktur (ks.h)
Die KSIDENTIFIER-Struktur gibt eine GUID an, die einen verwandten Satz von GUIDs eindeutig identifiziert, und einen Indexwert, der auf ein bestimmtes Element innerhalb dieses Satzes verweist.
Die KSDEGRADE, KSEVENT, KSMETHOD, KSPIN_INTERFACE, KSPIN_MEDIUMund KSPROPERTY Typedefs sind Aliase für die KSIDENTIFIER Struktur. Daher sind ihre Definitionen identisch. Einzelheiten zur Verwendung finden Sie in den einzelnen Typedef-Themen.
Syntax
typedef struct {
union {
struct {
GUID Set;
ULONG Id;
ULONG Flags;
} _IDENTIFIER;
struct {
GUID Set;
ULONG Id;
ULONG Flags;
};
LONGLONG Alignment;
};
} KSIDENTIFIER, *PKSIDENTIFIER;
Angehörige
_IDENTIFIER
Weitere Informationen finden Sie weiter unten.
_IDENTIFIER.Set
Weitere Informationen finden Sie weiter unten.
_IDENTIFIER.Id
Weitere Informationen finden Sie weiter unten.
_IDENTIFIER.Flags
Weitere Informationen finden Sie weiter unten.
Set
Weitere Informationen finden Sie weiter unten.
Id
Weitere Informationen finden Sie weiter unten.
Flags
Weitere Informationen finden Sie weiter unten.
Alignment
Weitere Informationen finden Sie weiter unten.
Bemerkungen
KSIDENTIFIER-Memberbeschreibungen
Set
Gibt eine GUID an, die eine Kernelstreamingeigenschaft, ein Ereignis, eine Methode, einen Kommunikationsbussatz identifiziert. Die KSPIN_INTERFACE Struktur beschreibt eine bestimmte Schnittstelle innerhalb eines Schnittstellensatzes. Die KSDEGRADE Struktur enthält Besonderheiten von Abbaustrategien. Weitere Informationen finden Sie im Abschnitt Anmerkungen weiter unten.
Id
Gibt das Element der Eigenschaft, des Ereignisses, des Methodensatzes an. Identifiziert für KSPIN_MEDIUMeine eindeutige Verbindung auf dem Bus. Gibt für KSPIN_INTERFACEdie 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 Streamklassen-Minidriver schreiben, finden Sie auch informationen zu klassenspezifischen Flags unter KSPROPERTY_ITEM. Flags sollten einen der werte sein, die in der folgenden Tabelle aufgeführt sind. Einige der Flags können mit einem bitweisen OR-Vorgang kombiniert werden.
Einzelheiten zur Verwendung finden Sie in den Themen KSDEGRADE, KSEVENT, KSMETHOD, KSPIN_INTERFACE, KSPIN_MEDIUMund KSPROPERTY Typedef.
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 Eigenschaftensatz unterstützt. |
| KSPROPERTY_TYPE_BASICSUPPORT | Fragt die Anforderungstypen ab, die der Treiber für dieses Eigenschaftselement behandelt. Gibt KSPROPERTY_TYPE_GET oder KSPROPERTY_TYPE_SET oder beides zurück. Alle Eigenschaftensätze müssen dieses Flag unterstützen. |
| KSPROPERTY_TYPE_DEFAULTVALUES | Fragt die Standardwerte für das angegebene Eigenschaftselement ab. Gibt eine Struktur vom Typ KSPROPERTY_VALUESzurück. |
| KSPROPERTY_TYPE_RELATIONS | Fragt alle Eigenschaften mit Abhängigkeiten von der aktuellen Einstellung dieser Eigenschaft ab. Gibt an, dass die Eigenschaftsbeziehungenliste 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 ist. Jedes Element befindet sich auf FILE_QUAD_ALIGNMENT, dem eine KSMULTIPLE_ITEM Struktur vorangestellt ist. Dies ist beim Abfragen der Unterstützung des Eigenschaftensatzes im Allgemeinen ungültig. Alle Eigenschaftensätze müssen dieses Flag unterstützen. |
| KSPROPERTY_TYPE_SERIALIZESET | Serialisieren Sie den Eigenschaftensatz mithilfe der standard-KSPROPERTY_SERIALHDR und KSPROPERTY_SERIAL Strukturen. |
| KSPROPERTY_TYPE_UNSERIALIZESET | Unserialisieren Sie den Eigenschaftensatz 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. Eine Größe von Null gibt an, dass eine Eigenschaft nicht serialisiert werden muss. |
| KSPROPERTY_TYPE_SERIALIZERAW | Gibt an, dass die Eigenschaften in diesem Satz vom Unterstützungshandler des Eigenschaftensatzes serialisiert werden sollen, sofern vorhanden. Wenn nicht, schlägt der Anruf fehl. Das Serialisierungsformat ist privat. Dieser Vorgang muss umkehrend 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 diese Kennzeichnung nicht selbst fest; Stattdessen OR it with other flags in this table. |
| 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, falls vorhanden. Wenn nicht, schlägt der Anruf fehl. Das Serialisierungsformat ist privat. Dieser Vorgang muss umkehren von KSPROPERTY_TYPE_SERIALIZERAW sein. |
Gibt den KSEVENT Anforderungstyp an. Dieses Kennzeichen sollte einer der Werte sein, die in der folgenden Tabelle aufgeführt sind.
| KSEVENT-Flagwert | Beschreibung |
|---|---|
| KSEVENT_TYPE_ENABLE | Aktiviert die Ereignisbenachrichtigung für diesen Ereignistyp. Der Treiber setzt die Ereignisbenachrichtigung fort, bis der Client sie explizit deaktiviert. |
| KSEVENT_TYPE_ONESHOT | Aktiviert die Ereignisbenachrichtigung nur für das nächste Vorkommen dieses Ereignisses. Der Client muss das Ereignis nach dem Auftreten nicht deaktivieren (und sollte es nicht). |
| KSEVENT_TYPE_SETSUPPORT | Fragt nach der Liste der Ereignissätze oder zur Unterstützung eines bestimmten Ereignissatzes ab. |
| KSEVENT_TYPE_BASICSUPPORT | Abfragen zur Unterstützung eines bestimmten Ereignistyps. |
| KSEVENT_TYPE_ENABLEBUFFERED | Statt den Client zu benachrichtigen, werden ereignisbenachrichtigungen vom Treiber in die Warteschlange gestellt. Der Client gibt dann eine zweite IOCTL_KS_ENABLE_EVENT Anforderung mit dem KSEVENT_TYPE_QUERYBUFFER aus, um die Benachrichtigungen über das In die Warteschlange gesendete Ereignis zu empfangen. |
| KSEVENT_TYPE_TOPOLOGY | Gibt an, dass das übergebene Ereignis vom Typ KSE_NODEist, wobei NodeId- die numerische ID des Topologieknotens angibt. Legen Sie diese Kennzeichnung nicht selbst fest; Stattdessen OR it with other flags from this list. |
| 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 werte enthalten, die in der folgenden Tabelle aufgeführt sind.
| KSMETHOD-Flagwert | Beschreibung |
|---|---|
| KSMETHOD_TYPE_BASICSUPPORT | Gibt an, den Minidriver abzufragen, um festzustellen, ob er die angegebene Methode des Methodensatzes unterstützt. |
| KSMETHOD_TYPE_SEND | Gibt an, dass der Minidriver die angegebene Methode ausführen soll. Die Auswirkung der Methode auf die angegebenen Parameter muss dem Client bekannt sein, d. h., ob die Parameter ausgelesen, in beides oder keines geschrieben werden. Der Minidriver verwendet die KSMETHOD_ITEM Struktur, um die Auswirkungen der Methode auf die Parameter anzugeben. |
| KSMETHOD_TYPE_SETSUPPORT | Gibt an, den Minidriver abzufragen, um festzustellen, ob er den angegebenen Methodensatz unterstützt. |
| KSMETHOD_TYPE_TOPOLOGY | Gibt an, dass die angegebene Methode vom Typ KSM_NODE ist, wobei das NodeId Member der Bezeichner des Topologieknotens ist. Legen Sie diese Kennzeichnung nicht selbst fest; Stattdessen OR it with other flags from this list. |
Gibt für KSDEGRADE entweder den aktuellen Prozentsatz der Beeinträchtigung an, ausgedrückt in Teilen pro Tausend (wobei ein Wert von 1000 keine Beeinträchtigung darstellt) oder gibt die Zeitmenge in systemeigenen Einheiten an, wie durch die Schnittstelle angegeben.
Alignment
Wird nicht verwendet. Ein Mitglied einer nicht benannten Union, die verwendet wird, um die richtige Ausrichtung auf die unbenannte Struktur zu erzwingen.
Notizen
Einzelheiten zur Verwendung finden Sie in den Themen KSDEGRADE, KSEVENT, KSMETHOD, KSPIN_INTERFACE, KSPIN_MEDIUMund KSPROPERTY Typedef.
Durch die Verwendung einer ID innerhalb des Satzes kann ein einzelner großer Vergleich für einen Satzbezeichner ausgeführt und dann kleinere schnelle Vergleiche durchgeführt werden (z. B. mithilfe einer Switch-Anweisung für Bezeichner innerhalb eines Satzes). Beispielsweise wird ein Eigenschaftensatz durch einen eindeutigen GUID-Bezeichner verwiesen, und Eigenschaften innerhalb dieses Satzes werden von der kurzen ID referenziert.
Methode, Event, Interfaceund mittleren Sätze können als "Klassen" von Sätzen betrachtet werden.
Die Größe des übergebenen Ausgabepuffers bestimmt, welche Daten aus einer KSPROPERTY_TYPE_BASICSUPPORT Anforderung zurückgegeben werden. Wenn der Ausgabepuffer die Größe einer ULONG-Datei hat, werden nur die Zugriffskennzeichnungen zurückgegeben. Wenn der Ausgabepuffer die Größe der KSPROPERTY_DESCRIPTION-Struktur ist, wird die Struktur mit den Zugriffskennzeichnungen, 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ängt die zurückgegebenen Daten auch von der Größe des Ausgabepuffers ab. Wenn die Größe des Ausgabepuffers null ist, wird die zum Zurückgeben der zugehörigen Eigenschaften erforderliche Größe in BytesReturned mit einem Warnstatus von STATUS_BUFFER_OVERFLOW zurückgegeben. Wenn der Puffer die Größe einer KSMULTIPLE_ITEM Struktur ist, wird 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 Eigenschaftsbezeichner zurückzugeben, die als Liste KSIDENTIFIER- Strukturen zurückgegeben wird.
KSPROPERTY_TYPE_SERIALIZESET- und KSPROPERTY_TYPE_UNSERIALIZESET Anforderungen ermöglichen die Interaktion mit mehreren Eigenschaften mit einem einzelnen Aufruf vom Client. Wenn der Kernelstreaminghandler zum Verarbeiten von Eigenschaftsanforderungen verwendet wird, werden diese durch die KsPropertyHandler-Funktion in mehrere Aufrufe unterteilt. Bei Verwendung dieses Handlers steuert der Eigenschaftensatz, welche Eigenschaften serialisiert werden sollen.
Bei Serialisierungsanforderungen wird die SerializedSize Member der relevanten KSPROPERTY_ITEM Struktur auf einen Wert ohne Null überprüft, der die Größe der Eigenschaft in Byte angibt. Wenn der Wert des SerializedSize-Elements 1 ist, ist es 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 einen Puffer der Länge Null im Aufruf von DeviceIoControl. BytesReturned gibt dann die Größe in Byte zurück, die der Puffer sein muss, um den Satz zu serialisieren, und einen Warnstatus von 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 eine Kopfzeile (KSPROPERTY_SERIAL), gefolgt von den Eigenschaftendaten, mit dem Anfang jeder Eigenschaft für FILE_LONG_ALIGNMENT. Beachten Sie, dass die serielle Kopfzeilenstruktur 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 Minidriver 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 sind, muss ein bestimmtes Element innerhalb des Eigenschaftensatzes im parameter Property angegeben werden. Dieser Handler kann mit mehreren Eigenschaften innerhalb des Satzes umgehen.
Microsoft stellt mehrere systemdefinierte Eigenschaftensatz-GUIDs bereit. Minidriver geben eine dieser GUIDs im Element " festlegen" an. Kernelstreaming-Eigenschaftssätze beginnen in der Regel entweder mit einer KSPROPSETID- oder einem PROPSETID Präfix. Kernel streaming property sets are defined in ks.h, ksmedia.h, bdamedia.h, und möglicherweise andere Headerdateien.
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. Kernelstreaming-Ereignissätze beginnen in der Regel mit einem KSEVENTSETID Präfix. Kernelstreaming-Ereignissätze werden in ks.h, ksmedia.h, bdamedia.hund 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 einer KSMETHODSETID Präfix. Kernelstreamingmethodensätze werden in ks.h, ksmedia.h, bdamedia.hund 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 der Minidriver behandelt. Weitere Informationen finden Sie unter KS-Methoden.
Die KSPIN_MEDIUM Struktur identifiziert ein Medium mit einer eindeutigen mittleren GUID und Instanz-ID, die 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 Instanzbezeichner immer nur als Komfort verwendet.
Ein Pin unterstützt möglicherweise mehrere Medien und Schnittstellen auf diesen Medien. Die Art und Weise, in der 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 zutrifft, kann ein anderer Pin verwendet werden, um jede Teilmenge der 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, Kreuzleisten und anderen Tunerkomponenten darstellt.
Das Flags Member kann unterschiedliche Werte enthalten, basierend auf dem Typ der Signalverschlechterung, die der Client verwendet. Siehe Qualitätsmanagement. weitere Details zu verschiedenen Strategien zur Lösung von Qualitätsmanagementproblemen durch Reduzierung 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 (enthalten Ks.h) |