InitializeContext function

Initializes a CONTEXT structure inside a buffer with the necessary size and alignment.

Syntax


BOOL WINAPI InitializeContext(
  _Out_opt_  PVOID Buffer,
  _In_       DWORD ContextFlags,
  _Out_opt_  PCONTEXT *Context,
  _Inout_    PWORD ContextLength
);

Parameters

Buffer [out, optional]

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 [in]

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.

Context [out, optional]

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.

ContextLength [in, out]

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.

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_XSTATEContextFlag 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.

Windows Phone 8.1: This API is supported.

Requirements

Minimum supported client

Windows 7 with SP1 [desktop apps | Windows Store apps]

Minimum supported server

Windows Server 2008 R2 with SP1 [desktop apps | Windows Store apps]

Header

WinBase.h (include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

See also

Intel AVX
CONTEXT
Working with XState Context
CopyContext

 

 

Community Additions

ADD
Show:
© 2014 Microsoft