Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

GetWsChanges function

Retrieves information about the pages that have been added to the working set of the specified process since the last time this function or the InitializeProcessForWsWatch function was called.

To retrieve extended information, use the GetWsChangesEx function.

Syntax


BOOL WINAPI GetWsChanges(
  _In_   HANDLE hProcess,
  _Out_  PPSAPI_WS_WATCH_INFORMATION lpWatchInfo,
  _In_   DWORD cb
);

Parameters

hProcess [in]

A handle to the process. The handle must have the PROCESS_QUERY_INFORMATION access right. For more information, see Process Security and Access Rights.

lpWatchInfo [out]

A pointer to a user-allocated buffer that receives an array of PSAPI_WS_WATCH_INFORMATION structures. The array is terminated with a structure whose FaultingPc member is NULL.

cb [in]

The size of the lpWatchInfo buffer, in bytes.

Return value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

GetLastError returns ERROR_INSUFFICIENT_BUFFER if the lpWatchInfo buffer is not large enough to contain all the working set change records; the buffer is returned empty. Reallocate a larger block of memory for the buffer and call again.

Remarks

The operating system uses one buffer per process to maintain working set change records. If more than one application (or multiple threads in the same application) calls this function with the same process handle, neither application will have a complete accounting of the working set changes because each call empties the buffer.

The operating system does not record new change records while it is processing the query (and emptying the buffer). The function sets the error code to NO_MORE_ENTRIES if a concurrent query is received while it is processing another query.

If the buffer becomes full, no new records are added to the buffer until this function or the InitializeProcessForWsWatch function is called. You should call this method with enough frequency to prevent possible data loss. If records are lost, the array is terminated with a structure whose FaultingPc member is NULL and whose FaultingVa member is set to the number of records that were lost.

Windows Server 2003 and Windows XP:  If records are lost, the array is terminated with a structure whose FaultingPc member is NULL and whose FaultingVa member is 1.

Starting with Windows 7 and Windows Server 2008 R2, Psapi.h establishes version numbers for the PSAPI functions. The PSAPI version number affects the name used to call the function and the library that a program must load.

If PSAPI_VERSION is 2 or greater, this function is defined as K32GetWsChanges in Psapi.h and exported in Kernel32.lib and Kernel32.dll. If PSAPI_VERSION is 1, this function is defined as GetWsChanges in Psapi.h and exported in Psapi.lib and Psapi.dll as a wrapper that calls K32GetWsChanges.

Programs that must run on earlier versions of Windows as well as Windows 7 and later versions should always call this function as GetWsChanges. To ensure correct resolution of symbols, add Psapi.lib to the TARGETLIBS macro and compile the program with -DPSAPI_VERSION=1. To use run-time dynamic linking, load Psapi.dll.

Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Psapi.h

Library

Kernel32.lib on Windows 7 and Windows Server 2008 R2;
Psapi.lib (if PSAPI_VERSION=1) on Windows 7 and Windows Server 2008 R2;
Psapi.lib on Windows Server 2008, Windows Vista, Windows Server 2003, and Windows XP

DLL

Kernel32.dll on Windows 7 and Windows Server 2008 R2;
Psapi.dll (if PSAPI_VERSION=1) on Windows 7 and Windows Server 2008 R2;
Psapi.dll on Windows Server 2008, Windows Vista, Windows Server 2003, and Windows XP

See also

EnumProcesses
InitializeProcessForWsWatch
PSAPI Functions
PSAPI_WS_WATCH_INFORMATION
Working Set Information

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.