InitializeContext2-Funktion (winbase.h)

Artikel
03/03/2024

Initialisiert eine CONTEXT-Struktur in einem Puffer mit der erforderlichen Größe und Ausrichtung mit der Option zum Angeben eines XSTATE-Komprimierungsformats.

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 Puffergröße zu bestimmen, die erforderlich ist, um einen Kontextdatensatz mit den angegebenen ContextFlags zu enthalten.

ContextFlags

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

Beachten SieCONTEXT_XSTATE nicht Teil von CONTEXT_FULL oder CONTEXT_ALL ist. 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 des Puffers empfängt.

Hinweis Aufgrund der Ausrichtungsanforderungen von CONTEXT-Strukturen befindet sich der in Kontext 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 buffer in Bytes verweist. Wenn der Puffer nicht groß genug ist, um die angegebenen Teile des KONTEXTs zu enthalten, schlägt die Funktion fehl, GetLastError gibt ERROR_INSUFFICIENT_BUFFER zurück, und ContextLength ist auf die erforderliche Größe des Puffers festgelegt. Wenn die Funktion mit einem anderen Fehler als ERROR_INSUFFICIENT_BUFFER fehlschlägt, ist der Inhalt von ContextLength nicht definiert.

XStateCompactionMask

Stellt die XState-Komprimierungsmaske bereit, die beim Zuweisen der Kontextstruktur verwendet werden soll. Dieser Parameter wird nur verwendet, wenn CONTEXT_XSTATE für ContextFlags bereitgestellt wird und das System XState im Komprimierungsmodus aktiviert hat.

Rückgabewert

Diese Funktion gibt BEI erfolgreicher Ausführung TRUE zurück, andernfalls FALSE. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

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 ändern kann, je nachdem, welche Prozessorfeatures auf dem System aktiviert sind.

Rufen Sie zunächst diese Funktion auf, wobei der ContextFlags-Parameter auf die maximale Anzahl von Features festgelegt ist, die Sie verwenden möchten, und den Buffer-Parameter auf NULL. Die Funktion gibt die erforderliche Puffergröße in Bytes im ContextLength-Parameter zurück. Weisen Sie genügend Speicherplatz für die Daten im Puffer zu, und rufen Sie die Funktion erneut auf, um den Kontext zu initialisieren. Nach erfolgreichem Abschluss dieser Routine wird der ContextFlags-Member der Context-Struktur initialisiert, aber der verbleibende Inhalt der Struktur ist nicht definiert. Einige im ContextFlags-Parameter angegebene Bits werden möglicherweise nicht in Context-ContextFlags> festgelegt, wenn sie vom System nicht unterstützt werden. Anwendungen können anschließend Bits aus dem ContextFlags-Element von CONTEXT entfernen, dürfen sie jedoch nie hinzufü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 keine Header und Bibliotheksdateien verfügbar sind, mit denen sie arbeiten können. In dieser Situation muss ein Aufrufer die erforderlichen Funktionen aus dieser Dokumentation deklarieren und Zeiger darauf mithilfe von GetModuleHandle auf „Kernel32.dll“ gefolgt von Aufrufen von GetProcAddress abrufen. Weitere Informationen finden Sie unter Arbeiten mit dem XState-Kontext .

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