InitializeContext2 function (winbase.h)

Article
10/20/2021

Initializes a CONTEXT structure inside a buffer with the necessary size and alignment, with the option to specify an XSTATE compaction mask.

Syntax

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

Parameters

[out, optional] Buffer

A pointer to a buffer within which to initialize a CONTEXT structure. This parameter can be NULL to determine the buffer size required to hold a context record with the specified ContextFlags.

ContextFlags

A value indicating which portions of the Context structure should be initialized. This parameter influences the size of the initialized Context structure.

Note CONTEXT_XSTATE is not part of CONTEXT_FULL or CONTEXT_ALL. It must be specified separately if an XState context is desired.

[out, optional] Context

A pointer to a variable which receives the address of the initialized CONTEXT structure within the Buffer.

Note Due to alignment requirements of CONTEXT structures, the value returned in Context may not be at the beginning of the supplied buffer.

[in, out] ContextLength

On input, specifies the length of the buffer pointed to by Buffer, in bytes. If the buffer is not large enough to contain the specified portions of the CONTEXT, the function fails, GetLastError returns ERROR_INSUFFICIENT_BUFFER, and ContextLength is set to the required size of the buffer. If the function fails with an error other than ERROR_INSUFFICIENT_BUFFER, the contents of ContextLength are undefined.

XStateCompactionMask

Supplies the XState compaction mask to use when allocating the Context structure. This parameter is only used when CONTEXT_XSTATE is supplied to ContextFlags and the system has XState enabled in compaction mode.

Return value

This function returns TRUE if successful, otherwise FALSE. To get extended error information, call GetLastError.

Remarks

InitializeContext can be used to initialize a CONTEXT structure within a buffer with the required size and alignment characteristics. This routine is required if the CONTEXT_XSTATE ContextFlag is specified since the required context size and alignment may change depending on which processor features are enabled on the system.

First, call this function with the ContextFlags parameter set to the maximum number of features you will be using and the Buffer parameter to NULL. The function returns the required buffer size in bytes in the ContextLength parameter. Allocate enough space for the data in the Buffer and call the function again to initialize the Context. Upon successful completion of this routine, the ContextFlags member of the Context structure is initialized, but the remaining contents of the structure are undefined. Some bits specified in the ContextFlags parameter may not be set in Context->ContextFlags if they are not supported by the system. Applications may subsequently remove, but must never add, bits from the ContextFlags member of CONTEXT.

Windows 7 with SP1 and Windows Server 2008 R2 with SP1: The AVX API is first implemented on Windows 7 with SP1 and Windows Server 2008 R2 with SP1 . Since there is no SDK for SP1, that means there are no available headers and library files to work with. In this situation, a caller must declare the needed functions from this documentation and get pointers to them using GetModuleHandle on "Kernel32.dll", followed by calls to GetProcAddress. See Working with XState Context for details.

When XState is enabled in compaction mode, specifying an XStateCompactionMask that contains only a subset of the enabled XState components can decrease the buffer size required to store the Context. This is particularly useful if the system has many XState components enabled, but the Context will only be used to affect a small number of XState components. The full set of enabled XState components can be obtained by calling GetEnabledXStateFeatures. This function copies the specified XState compaction mask into the relevant location in the XState header.

Requirements

Requirement	Value
Minimum supported client	Windows 10 Build 20348
Minimum supported server	Windows 10 Build 20348
Header	winbase.h