Função GetWsChangesEx (psapi.h)

Artigo
03/05/2024

Recupera informações estendidas sobre as páginas que foram adicionadas ao conjunto de trabalho do processo especificado desde a última vez em que essa função ou a função InitializeProcessForWsWatch foi chamada.

Sintaxe

BOOL GetWsChangesEx(
  [in]      HANDLE                         hProcess,
  [out]     PPSAPI_WS_WATCH_INFORMATION_EX lpWatchInfoEx,
  [in, out] PDWORD                         cb
);

Parâmetros

[in] hProcess

Um identificador para o processo. O identificador deve ter o acesso de PROCESS_QUERY_INFORMATION correto. Para obter mais informações, consulte Direitos de Acesso e Segurança do Processo.

[out] lpWatchInfoEx

Um ponteiro para um buffer alocado pelo usuário que recebe uma matriz de
PSAPI_WS_WATCH_INFORMATION_EX estruturas. A matriz é encerrada com uma estrutura cujo membro FaultingPc é NULL.

[in, out] cb

O tamanho do buffer lpWatchInfoEx , em bytes.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame a função GetLastError.

A função GetLastError retornará ERROR_INSUFFICIENT_BUFFER se o buffer lpWatchInfoEx não for grande o suficiente para conter todos os registros de alteração do conjunto de trabalho; o buffer é retornado vazio. Realocar um bloco maior de memória para o buffer e chamar novamente.

Comentários

O sistema operacional usa um buffer por processo para manter registros de alteração do conjunto de trabalho. Se mais de um aplicativo (ou vários threads no mesmo aplicativo) chamar essa função com o mesmo identificador de processo, nenhum aplicativo terá uma contabilidade completa das alterações do conjunto de trabalho porque cada chamada esvazia o buffer.

O sistema operacional não registra novos registros de alteração enquanto está processando a consulta (e esvaziando o buffer). Essa função define o código de erro como NO_MORE_ENTRIES se uma consulta simultânea for recebida enquanto estiver processando outra consulta.

Se o buffer ficar cheio, nenhum novo registro será adicionado ao buffer até que essa função ou a função InitializeProcessForWsWatch seja chamada. Você deve chamar GetWsChangesEx com frequência suficiente para evitar uma possível perda de dados. Se os registros forem perdidos, a matriz será encerrada com uma estrutura cujo membro FaultingPc é NULL e cujo membro FaultingVa está definido como o número de registros que foram perdidos.

A partir do Windows 7 e do Windows Server 2008 R2, o Psapi.h estabelece números de versão para as funções PSAPI. O número de versão do PSAPI afeta o nome usado para chamar a função e a biblioteca que um programa deve carregar.

Se PSAPI_VERSION for 2 ou superior, essa função será definida como K32GetWsChangesEx no Psapi.h e exportada em Kernel32.lib e Kernel32.dll. Se PSAPI_VERSION for 1, essa função será definida como GetWsChangesEx no Psapi.h e exportada em Psapi.lib e Psapi.dll como um wrapper que chama K32GetWsChangesEx.

Programas que devem ser executados em versões anteriores do Windows, bem como no Windows 7 e versões posteriores, sempre devem chamar essa função como GetWsChangesEx. Para garantir a resolução correta de símbolos, adicione Psapi.lib à macro TARGETLIBS e compile o programa com -DPSAPI_VERSION=1. Para usar a vinculação dinâmica em tempo de execução, carregue Psapi.dll.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	psapi.h
Biblioteca	Kernel32.lib no Windows 7 e Windows Server 2008 R2; Psapi.lib (se PSAPI_VERSION=1) no Windows 7 e no Windows Server 2008 R2; Psapi.lib no Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP
DLL	Kernel32.dll no Windows 7 e no Windows Server 2008 R2; Psapi.dll (se PSAPI_VERSION=1) no Windows 7 e no Windows Server 2008 R2; Psapi.dll no Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP