Funzione InitializeContext2 (winbase.h)

Articolo
07/16/2024

Inizializza una struttura CONTEXT all'interno di un buffer con le dimensioni e l'allineamento necessarie, con l'opzione per specificare una maschera di compattazione XSTATE.

Sintassi

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

Parametri

[out, optional] Buffer

Puntatore a un buffer all'interno del quale inizializzare una struttura CONTEXT di . Questo parametro può essere NULL per determinare le dimensioni del buffer necessarie per contenere un record di contesto con l'ContextFlags specificato.

ContextFlags

Valore che indica quali parti della struttura Context devono essere inizializzate. Questo parametro influenza le dimensioni della struttura di context inizializzata .

NotaCONTEXT_XSTATE non fa parte di CONTEXT_FULL o CONTEXT_ALL. Deve essere specificato separatamente se si desidera un contesto XState.

[out, optional] Context

Puntatore a una variabile che riceve l'indirizzo della struttura di CONTEXT inizializzata all'interno dell'buffer .

Nota A causa dei requisiti di allineamento delle strutture di CONTEXT , il valore restituito in Contesto potrebbe non essere all'inizio del buffer fornito.

[in, out] ContextLength

In input, specifica la lunghezza del buffer a cui punta Buffer, in byte. Se il buffer non è sufficientemente grande da contenere le parti specificate delCONTEXT , la funzione ha esito negativo, GetLastError restituisce ERROR_INSUFFICIENT_BUFFERe ContextLength viene impostata sulle dimensioni necessarie del buffer. Se la funzione ha esito negativo con un errore diverso da ERROR_INSUFFICIENT_BUFFER, il contenuto di ContextLength non è definito.

XStateCompactionMask

Fornisce la maschera di compattazione XState da utilizzare per l'allocazione della struttura Context . Questo parametro viene usato solo quando CONTEXT_XSTATE viene fornito a ContextFlags e il sistema ha XState abilitato in modalità compattazione.

Valore restituito

Questa funzione restituisce TRUE se ha esito positivo; in caso contrario, FALSE. Per ottenere informazioni estese sull'errore, chiamare GetLastError.

Osservazioni

InitializeContext può essere usato per inizializzare una struttura CONTEXT di all'interno di un buffer con le caratteristiche di allineamento e dimensioni necessarie. Questa routine è necessaria se il CONTEXT_XSTATEContextFlag viene specificato perché le dimensioni e l'allineamento del contesto necessari possono cambiare a seconda delle funzionalità del processore abilitate nel sistema.

Prima di tutto, chiamare questa funzione con il parametro ContextFlags impostato sul numero massimo di funzionalità che verranno usati e il parametro buffer per NULL. La funzione restituisce le dimensioni del buffer necessarie in byte nel parametro ContextLength. Allocare spazio sufficiente per i dati nel buffer e chiamare di nuovo la funzione per inizializzare Context. Al termine di questa routine, il ContextFlags membro della struttura Context viene inizializzato, ma il contenuto rimanente della struttura non è definito. Alcuni bit specificati nel parametro ContextFlags potrebbero non essere impostati in Context->ContextFlags se non sono supportati dal sistema. Le applicazioni possono successivamente rimuovere, ma non devono mai aggiungere bit dal ContextFlags membro di CONTEXT.

Windows 7 con SP1 e Windows Server 2008 R2 con SP1: L'API AVX viene implementata per la prima volta in Windows 7 con SP1 e Windows Server 2008 R2 con SP1 . Poiché non è disponibile SDK per SP1, significa che non sono disponibili intestazioni e file di libreria da usare. In questo caso, un chiamante deve dichiarare le funzioni necessarie da questa documentazione e ottenere i puntatori usando GetModuleHandle in "Kernel32.dll", seguito dalle chiamate a GetProcAddress. Per informazioni dettagliate, vedere Uso del contesto XState.

Quando XState è abilitato in modalità compattazione, specificando un XStateCompactionMask che contiene solo un subset dei componenti XState abilitati può ridurre le dimensioni del buffer necessarie per archiviare il contesto . Ciò è particolarmente utile se il sistema dispone di molti componenti XState abilitati, ma la context verrà usata solo per influire su un numero ridotto di componenti XState. È possibile ottenere il set completo di componenti XState abilitati chiamando GetEnabledXStateFeatures. Questa funzione copia la maschera di compattazione XState specificata nella posizione pertinente nell'intestazione XState.