Freigeben über

DXGK_SPB_INTERFACE Struktur (dispmprt.h)

  • Artikel

Die DXGK_SPB_INTERFACE Struktur enthält Zeiger auf Funktionen in der SPB-Schnittstelle (Simple Peripheral Bus), die ein Windows Display Driver Model (WDDM) 1.2 und höher den Miniporttreiber aufrufen kann, um SPB-Ressourcen zu prüfen und zu ändern.

Syntax

typedef struct _DXGK_SPB_INTERFACE {
  USHORT                 Size;
  USHORT                 Version;
  PVOID                  Context;
  PINTERFACE_REFERENCE   InterfaceReference;
  PINTERFACE_DEREFERENCE InterfaceDereference;
  NTSTATUS(HANDLE DeviceHandle,LARGE_INTEGER SpbReourceId,UNICODE_STRING *SpbResourceSubName,ACCESS_MASK DesiredAccess,ULONG ShareAccess,ULONG OpenOptions,VOID **SpbResource)              * )(OpenSpbResource;
  NTSTATUS()(HANDLE DeviceHandle,VOID *SpbResource)              * CloseSpbResource;
  NTSTATUS(ANDLE DeviceHandle,VOID *SpbResource,ULONG Length,VOID *Buffer,LARGE_INTEGER *ByteOffset,HANDLE EventHandle,IO_STATUS_BLOCK *IoStatusBlock)              * )(HReadSpbResource;
  NTSTATUS(ANDLE DeviceHandle,VOID *SpbResource,ULONG Length,VOID *Buffer,LARGE_INTEGER *ByteOffset,HANDLE EventHandle,IO_STATUS_BLOCK *IoStatusBlock)              * )(HWriteSpbResource;
  NTSTATUS(ANDLE DeviceHandle,VOID *SpbResource,ULONG IoControlCode,ULONG InBufferSize,VOID *InputBuffer,ULONG OutBufferSize,VOID *OutputBuffer,HANDLE EventHandle,IO_STATUS_BLOCK *IoStatusBlock)              * )(HSpbResourceIoControl;
} DXGK_SPB_INTERFACE, *PDXGK_SPB_INTERFACE;

Angehörige

Size

Die Größe dieser Struktur in Byte.

Version

Die Versionsnummer der SPB-Schnittstelle. Versionsnummernkonstanten werden in Dispmprt.h definiert (z. B. DXGK_SPB_INTERFACE_VERSION_1).

Context

Ein Zeiger auf einen Kontext, der vom Display miniport-Treiber bereitgestellt wird.

InterfaceReference

Ein Zeiger auf eine Schnittstellenverweisfunktion, die vom Display miniport-Treiber implementiert wird.

InterfaceDereference

Ein Zeiger auf eine Schnittstellen-Ableitungsfunktion, die vom Display miniport-Treiber implementiert wird.

OpenSpbResource

Öffnet eine SpB-Ressource (Simple Peripheral Bus). Alle Eingabeparameter werden vom Display miniport-Treiber bereitgestellt.

OpenSpbResource-Parameter Beschreibung
DeviceHandle- Handle, das einen Anzeigeadapter darstellt. Der Display-Miniporttreiber hat diesen Handle zuvor im DeviceHandle Member der DXGKRNL_INTERFACE-Struktur abgerufen, die an die DxgkDdiStartDevice--Funktion übergeben wurde.
SpbReourceId- Die Ressourcen-ID des SPB-Ressourcenhubs.
SpbResourceSubName Optionaler Zeiger auf den Unicode SPB-Ressourcenunternamen.
DesiredAccess- Ein ACCESS_MASK Wert, der den angeforderten Zugriff auf die SPB-Ressource bestimmt. Weitere Informationen finden Sie im parameter DesiredAccess der funktion ZwCreateFile.
ShareAccess- Typ des Freigabezugriffs für die Datei. Weitere Informationen finden Sie im parameter ShareAccess von ZwCreateFile.
OpenOptions- Die Beim Öffnen der SPB-Ressource anzuwendenden Optionen. Weitere Informationen finden Sie im parameter CreateOptions von ZwCreateFile.
SpbResource- Ein Zeiger auf einen Puffer, der zum Zurückgeben des Handles an die SPB-Ressource verwendet wird.

CloseSpbResource

Schließt eine SPB-Ressource. Alle Eingabeparameter werden vom Display miniport-Treiber bereitgestellt.

Das Schließen eines geöffneten Objekthandle bewirkt, dass dieses Handle ungültig wird. Das System erhöht auch die Handleanzahl für das Objekt und überprüft, ob das Objekt gelöscht werden kann. Das System löscht das Objekt erst, wenn alle Ziehpunkte des Objekts geschlossen sind und keine referenzierten Zeiger verbleiben.

Der Treiber muss CloseSpbResource- aufrufen, um jedes Handle zu schließen, das es mit OpenSpbResource- geöffnet hat, sobald das Handle nicht mehr erforderlich ist.

Aufrufer von CloseSpbResource- sollten nicht davon ausgehen, dass diese Funktion vor der Rückgabe automatisch auf den Abschluss aller E/A-Vorgänge wartet.

CloseSpbResource-Parameter Beschreibung
DeviceHandle- Ein Handle, das einen Anzeigeadapter darstellt. Der Display-Miniporttreiber hat diesen Handle zuvor im DeviceHandle Member der DXGKRNL_INTERFACE-Struktur abgerufen, die an die DxgkDdiStartDevice--Funktion übergeben wurde.
SpbResource- Ein Zeiger auf eine SPB-Ressource, die der Anzeigeminiporttreiber mit der OpenSpbResource-funktion geöffnet hat.

ReadSpbResource

Liest Daten aus einer geöffneten SPB-Ressource. Alle Eingabeparameter werden vom Display miniport-Treiber bereitgestellt.

Wenn der Aufruf von OpenSpbResource eines der OpenOptions Flags FILE_SYNCHRONOUS_IO_ALERT oder FILE_SYNCHRONOUS_IO_NONALERT (definiert in Wdm.h) festgelegt hat, behält der E/A-Manager die aktuelle Dateiposition bei. Wenn ja, kann der Aufrufer von ReadSpbResource- angeben, dass der aktuelle Dateipositionsoffset anstelle eines expliziten ByteOffset--Werts verwendet werden soll. Diese Spezifikation kann mithilfe einer der folgenden Methoden erfolgen:

  • Geben Sie einen Zeiger auf einen LARGE_INTEGER Wert an, wobei der HighPart-Member auf -1 festgelegt ist, und das LowPart-Element, das auf den vom System definierten Wert FILE_USE_FILE_POINTER_POSITION (definiert in Wdm.h) festgelegt ist.
  • Übergeben Sie einen NULL- Zeiger für ByteOffset-.

ReadSpbResource aktualisiert die aktuelle Dateiposition, indem die Anzahl der gelesenen Bytes hinzugefügt wird, wenn der Lesevorgang abgeschlossen ist, wenn sie die aktuelle Dateiposition verwendet, die vom E/A-Manager verwaltet wird.

Selbst wenn der E/A-Manager die aktuelle Dateiposition verwaltet, kann der Aufrufer diese Position zurücksetzen, indem ein expliziter ByteOffset- wert an ReadSpbResourceübergeben wird. Dadurch wird die aktuelle Dateiposition automatisch an den wert ByteOffset, der Lesevorgang ausgeführt, und anschließend wird die Position entsprechend der Anzahl der tatsächlich gelesenen Bytes aktualisiert. Mit dieser Technik erhält der Aufrufer den Atomar-Seek-and-Read-Dienst.

OpenSpbResource-Parameter Beschreibung
DeviceHandle- Ein Handle, das einen Anzeigeadapter darstellt. Der Display-Miniporttreiber hat diesen Handle zuvor im DeviceHandle Member der DXGKRNL_INTERFACE-Struktur abgerufen, die an die DxgkDdiStartDevice--Funktion übergeben wurde.
SpbResource- Ein Zeiger auf eine SPB-Ressource, die der Anzeigeminiporttreiber mit der OpenSpbResource-funktion geöffnet hat.
Länge Die Größe des Puffers in Bytes, auf den der parameter Buffer verweist.
Puffer- Ein Zeiger auf einen Puffer, der die aus der angegebenen SPB-Ressource gelesenen Daten empfängt.
ByteOffset- Ein optionaler Zeiger auf eine Variable, der den Anfangsbyte-Offset in der SPB-Ressource angibt, in der der Lesevorgang beginnt. Wenn versucht wird, über das Ende der Datei hinaus zu lesen, gibt ReadSpbResource- einen Fehler zurück.
EventHandle- Ein optionales Handle für ein vom Aufrufer erstelltes Ereignis. Wenn dieser Parameter angegeben wird, wird der Aufrufer in einen Wartezustand versetzt, bis der Lesevorgang abgeschlossen ist, und das angegebene Ereignis wird auf den zustand Signaled festgelegt. Dieser Parameter kann NULL-sein.
IoStatusBlock- Ein Zeiger auf eine IO_STATUS_BLOCK Struktur, die den endgültigen Abschlussstatus und Informationen zum angeforderten Lesevorgang empfängt. Das Information Mitglied der IO_STATUS_BLOCK Struktur empfängt die Anzahl der Bytes, die tatsächlich aus der SPB-Ressource gelesen werden.

WriteSpbResource

Schreibt Daten in eine geöffnete SPB-Ressource.

Wenn der Aufruf der OpenSpbResource--Funktion nur das DesiredAccess Flag FILE_APPEND_DATAfestgelegt hat, wird der ByteOffset Parameter ignoriert. In diesem Fall werden Daten im Puffer, auf die der Parameter Buffer verweist, für Length Bytes beginnend am aktuellen Ende der Datei geschrieben.

Wenn der Aufruf von OpenSpbResource eines der CreateOptions Flags, FILE_SYNCHRONOUS_IO_ALERT oder FILE_SYNCHRONOUS_IO_NONALERTfestlegen, behält der E/A-Manager die aktuelle Dateiposition bei. Wenn ja, kann der Aufrufer von WriteSpbResource- angeben, dass der aktuelle Dateipositionsoffset anstelle eines expliziten ByteOffset--Werts verwendet werden soll. Diese Spezifikation kann mithilfe einer der folgenden Methoden erfolgen:

  • Geben Sie einen Zeiger auf einen LARGE_INTEGER Wert an, wobei der HighPart Member auf -1 festgelegt ist, und das LowPart Member auf den vom System definierten Wert FILE_USE_FILE_POINTER_POSITION (definiert in Wdm.h).
  • Übergeben Sie einen NULL- Zeiger für ByteOffset-.

WriteSpbResource aktualisiert die aktuelle Dateiposition, indem die Anzahl von Bytes hinzugefügt wird, die geschrieben werden, wenn sie den Schreibvorgang abgeschlossen hat, wenn sie die aktuelle Dateiposition verwendet, die vom E/A-Manager verwaltet wird.

Selbst wenn der E/A-Manager die aktuelle Dateiposition verwaltet, kann der Aufrufer diese Position zurücksetzen, indem ein expliziter ByteOffset- wert an WriteSpbResourceübergeben wird. Dadurch wird die aktuelle Dateiposition automatisch in den wert ByteOffset Wert geändert, der Schreibvorgang ausgeführt, und anschließend wird die Position entsprechend der Anzahl der tatsächlich geschriebenen Bytes aktualisiert. Diese Technik bietet dem Aufrufer einen atomaren Such- und Schreibdienst.

Es ist auch möglich, dass ein Schreibvorgang am aktuellen Ende der Datei gestartet wird, indem für ByteOffset ein Zeiger auf einen LARGE_INTEGER Wert angegeben wird, wobei HighPart- auf -1 und LowPart- auf FILE_WRITE_TO_END_OF_FILEfestgelegt ist. Dies funktioniert unabhängig davon, ob der E/A-Manager die aktuelle Dateiposition aufrecht erhält.

WriteSpbResource-Parameter Beschreibung
DeviceHandle- Ein Handle, das einen Anzeigeadapter darstellt. Der Display-Miniporttreiber hat diesen Handle zuvor im DeviceHandle Member der DXGKRNL_INTERFACE-Struktur abgerufen, die an die DxgkDdiStartDevice--Funktion übergeben wurde.
SpbResource- Ein Zeiger auf eine SPB-Ressource, die der Anzeigeminiporttreiber mit der OpenSpbResource-funktion geöffnet hat.
Länge Die Größe des Puffers in Bytes, auf den der parameter Buffer verweist.
Puffer- Ein Zeiger auf einen vom Aufrufer zugewiesenen Puffer, der die daten enthält, die in die angegebene SPB-Ressource geschrieben werden sollen.
ByteOffset- Ein optionaler Zeiger auf eine Variable, der den Anfangsbyte-Offset in der SPB-Ressource angibt, in der der Schreibvorgang beginnt. Wenn die Parameter Length und ByteOffset einen Schreibvorgang über das aktuelle Ende der Dateimarke angeben, WriteSpbResource die Datei automatisch erweitert und die End-of-File-Markierung aktualisiert; Alle Bytes, die nicht explizit zwischen solchen alten und neuen End-of-File-Markierungen geschrieben werden, werden als Null definiert.
EventHandle- Ein optionales Handle für ein vom Aufrufer erstelltes Ereignis. Wenn dieser Parameter angegeben wird, wird der Aufrufer in einen Wartezustand versetzt, bis der Schreibvorgang abgeschlossen ist und das angegebene Ereignis auf den zustand Signaled festgelegt wird. Dieser Parameter kann NULL-sein.
IoStatusBlock- Ein Zeiger auf eine IO_STATUS_BLOCK Struktur, die den endgültigen Abschlussstatus und Informationen zum angeforderten Schreibvorgang empfängt. Das Information Mitglied der IO_STATUS_BLOCK-Struktur erhält die Anzahl der Bytes, die tatsächlich in die SPB-Ressource geschrieben wurden.

SpbResourceIoControl

Führt einen E/A-Steuerungsvorgang für eine offene SpB-Ressource (Simple Peripheral Bus) aus. Alle Eingabeparameter werden vom Display miniport-Treiber bereitgestellt.

Wenn der Aufrufer die Datei für asynchrone E/A (mit keinem FILE_SYNCHRONOUS_XXX Create/Open Option Set) geöffnet hat, wird das angegebene Ereignis (sofern vorhanden) auf den Signaled Zustand festgelegt, wenn der Gerätesteuerungsvorgang abgeschlossen ist. Andernfalls wird das durch den DeviceHandle Parameter angegebene Dateiobjekt auf den zustand Signaled festgelegt.

SpbResourceIoControl-Parameter Beschreibung
DeviceHandle- Ein Handle, das einen Anzeigeadapter darstellt. Der Display-Miniporttreiber hat diesen Handle zuvor im DeviceHandle Member der DXGKRNL_INTERFACE-Struktur abgerufen, die an die DxgkDdiStartDevice--Funktion übergeben wurde.
SpbResource- Ein Zeiger auf eine SPB-Ressource, die der Anzeigeminiporttreiber mit der OpenSpbResource-funktion geöffnet hat.
IoControlCode- Ein Geräte-E/A-Steuerungscode (IOCTL_XXX), der angibt, auf welchem Geräte-E/A-Steuerungsvorgang ausgeführt werden soll, in der Regel vom zugrunde liegenden Gerätetreiber. Der Wert dieses Parameters bestimmt das Format und die erforderliche Länge des InputBuffer- und OutputBuffer Parameter sowie welche der folgenden Parameterpaare erforderlich sind.
InBufferSize- Die Größe des Puffers in Byte, auf den der InputBuffer-Parameter verweist. Dieser Wert wird ignoriert, wenn InputBuffer-NULL-ist.
InputBuffer- Ein Zeiger auf einen vom Aufrufer zugewiesenen Eingabepuffer, der gerätespezifische Informationen enthält, die dem Zielgerät zugewiesen werden sollen. Wenn der IoControlCode Parameter einen Vorgang angibt, der keine Eingabedaten erfordert, kann dieser Zeiger NULL-werden.
OutBufferSize- Die Größe des Puffers in Bytes, auf den der OutputBuffer-Parameter verweist. Dieser Wert wird ignoriert, wenn OutputBuffer-NULL-ist.
OutputBuffer- Ein Zeiger auf einen vom Aufrufer zugewiesenen Ausgabepuffer, in dem Informationen vom Zielgerät zurückgegeben werden. Wenn der IoControlCode Parameter einen Vorgang angibt, der keine Ausgabedaten erzeugt, kann dieser Zeiger NULL-werden.
EventHandle- Ein optionales Handle für ein vom Aufrufer erstelltes Ereignis. Wenn dieser Parameter angegeben wird, wird der Aufrufer in einen Wartezustand versetzt, bis der angeforderte Vorgang abgeschlossen ist, und das angegebene Ereignis wird auf den Signaled Zustand festgelegt. Dieser Parameter kann NULL-sein.
IoStatusBlock- Ein Zeiger auf eine Variable, die den endgültigen Abschlussstatus und Informationen zum angeforderten E/A-Steuerungsvorgang empfängt. Bei erfolgreichen Aufrufen, die Daten zurückgeben, wird die Anzahl der in den Puffer geschriebenen Bytes zurückgegeben, auf die der OutputBuffer Parameter verweist, im Information Element der IO_STATUS_BLOCK Struktur zurückgegeben.

Bemerkungen

Um die Funktionen dieser Struktur zu verwenden, geben Sie zuerst die Size und Version Member der DXGK_SPB_INTERFACE Struktur an. Rufen Sie dann die DxgkCbQueryServices--Funktion auf, wobei der ServicesType-Parameter auf einen Wert von DxgkServicesFirmwareTablefestgelegt ist, und legen Sie den parameter Interface auf die Adresse fest (in PINTERFACE) der DXGK_SPB_INTERFACE-Struktur umwandeln.

Weitere Informationen zur SPB-Architektur finden Sie unter Simple Peripheral Buses und SPB Peripheral Driver Design Guide**.

Anforderungen

Anforderung Wert
mindestens unterstützte Client- Windows 8
mindestens unterstützte Server- Windows Server 2012
Header- dispmprt.h (include Dispmprt.h)