InitializeContext2-Funktion (winbase.h)

Artikel
07/16/2024

Initialisiert eine CONTEXT- Struktur innerhalb eines Puffers mit der erforderlichen Größe und Ausrichtung, wobei die Option zum Angeben eines XSTATE-Komprimierungsformats möglich ist.

Syntax

BOOL InitializeContext2(
  [out, optional] PVOID    Buffer,
                  DWORD    ContextFlags,
  [out, optional] PCONTEXT *Context,
  [in, out]       PDWORD   ContextLength,
                  ULONG64  XStateCompactionMask
);

Parameter

[out, optional] Buffer

Ein Zeiger auf einen Puffer, in dem eine CONTEXT--Struktur initialisiert werden soll. Dieser Parameter kann NULL- sein, um die zum Speichern eines Kontextdatensatzes erforderliche Puffergröße mit dem angegebenen ContextFlags-zu bestimmen.

ContextFlags

Ein Wert, der angibt, welche Teile der Context-Struktur initialisiert werden sollen. Dieser Parameter beeinflusst die Größe der initialisierten Context-Struktur.

HinweisCONTEXT_XSTATE gehört nicht zu CONTEXT_FULL oder CONTEXT_ALL. Sie muss separat angegeben werden, wenn ein XState-Kontext gewünscht wird.

[out, optional] Context

Ein Zeiger auf eine Variable, die die Adresse der initialisierten CONTEXT- Struktur innerhalb der Buffer-empfängt.

Hinweis Aufgrund der Ausrichtungsanforderungen CONTEXT Strukturen liegt der in Context zurückgegebene Wert möglicherweise nicht am Anfang des angegebenen Puffers.

[in, out] ContextLength

Gibt bei der Eingabe die Länge des Puffers an, auf den Pufferin Byte verweist. Wenn der Puffer nicht groß genug ist, um die angegebenen Teile des CONTEXT-zu enthalten, schlägt die Funktion fehl, GetLastError gibt ERROR_INSUFFICIENT_BUFFERzurück, und ContextLength- auf die erforderliche Größe des Puffers festgelegt ist. Wenn die Funktion mit einem anderen Fehler als ERROR_INSUFFICIENT_BUFFERfehlschlägt, sind die Inhalte ContextLength- nicht definiert.

XStateCompactionMask

Stellt die XState-Komprimierungsmaske bereit, die beim Zuordnen der Context-Struktur verwendet werden soll. Dieser Parameter wird nur verwendet, wenn CONTEXT_XSTATEContextFlags- bereitgestellt wird und das System XState im Komprimierungsmodus aktiviert hat.

Rückgabewert

Diese Funktion gibt bei erfolgreicher Ausführung TRUE zurück, andernfalls FALSE. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.

Bemerkungen

InitializeContext- kann verwendet werden, um eine CONTEXT- Struktur innerhalb eines Puffers mit den erforderlichen Größen- und Ausrichtungsmerkmalen zu initialisieren. Diese Routine ist erforderlich, wenn die CONTEXT_XSTATEContextFlag- angegeben wird, da sich die erforderliche Kontextgröße und Ausrichtung je nach aktivierter Prozessorfeatures auf dem System ändern kann.

Rufen Sie zunächst diese Funktion mit dem parameter ContextFlags auf die maximale Anzahl von Features auf, die Sie verwenden werden, und den parameter BufferNULL. Die Funktion gibt die erforderliche Puffergröße in Byte im ContextLength Parameter zurück. Weisen Sie genügend Speicherplatz für die Daten im Buffer- zu, und rufen Sie die Funktion erneut auf, um die Context-zu initialisieren. Nach erfolgreichem Abschluss dieser Routine wird das ContextFlags Member der Context-Struktur initialisiert, aber die restlichen Inhalte der Struktur sind nicht definiert. Einige bits, die im ContextFlags Parameter angegeben sind, werden möglicherweise nicht in Contextfestgelegt –>ContextFlags, wenn sie vom System nicht unterstützt werden. Anwendungen können anschließend, aber niemals Bits aus dem ContextFlags Member von CONTEXThinzufügen.

Windows 7 mit SP1 und Windows Server 2008 R2 mit SP1: Die AVX-API- wird zuerst unter Windows 7 mit SP1 und Windows Server 2008 R2 mit SP1 implementiert. Da es kein SDK für SP1 gibt, bedeutet dies, dass es keine verfügbaren Header- und Bibliotheksdateien gibt, mit denen sie arbeiten können. In diesem Fall muss ein Aufrufer die erforderlichen Funktionen aus dieser Dokumentation deklarieren und Zeiger mit GetModuleHandle- für "Kernel32.dll" abrufen, gefolgt von Aufrufen von GetProcAddress. Weitere Informationen finden Sie unter Arbeiten mit XState Context.

Wenn XState im Komprimierungsmodus aktiviert ist, kann die Angabe einer XStateCompactionMask-, die nur eine Teilmenge der aktivierten XState-Komponenten enthält, die Puffergröße verringern, die zum Speichern des Context-erforderlich ist. Dies ist besonders nützlich, wenn das System viele XState-Komponenten aktiviert hat, aber das Context- nur verwendet wird, um eine kleine Anzahl von XState-Komponenten zu beeinflussen. Der vollständige Satz aktivierter XState-Komponenten kann durch Aufrufen GetEnabledXStateFeaturesabgerufen werden. Diese Funktion kopiert die angegebene XState-Komprimierungsmaske an die relevante Position in der XState-Kopfzeile.