Função GetWsChanges (psapi.h)

Artigo
03/01/2024

Recupera informações 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.

Para recuperar informações estendidas, use a função GetWsChangesEx .

Sintaxe

BOOL GetWsChanges(
  [in]  HANDLE                      hProcess,
  [out] PPSAPI_WS_WATCH_INFORMATION lpWatchInfo,
  [in]  DWORD                       cb
);

Parâmetros

[in] hProcess

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

[out] lpWatchInfo

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

[in] cb

O tamanho do buffer lpWatchInfo , 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 GetLastError.

GetLastError retornará ERROR_INSUFFICIENT_BUFFER se o buffer lpWatchInfo 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). A 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 esse método com frequência suficiente para evitar a 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.

Windows Server 2003 e Windows XP: Se os registros forem perdidos, a matriz será encerrada com uma estrutura cujo membro FaultingPc é NULL e cujo membro FaultingVa é 1.

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 maior, essa função será definida como K32GetWsChanges em Psapi.h e exportada em Kernel32.lib e Kernel32.dll. Se PSAPI_VERSION for 1, essa função será definida como GetWsChanges em Psapi.h e exportada em Psapi.lib e Psapi.dll como um wrapper que chama K32GetWsChanges.

Os 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 GetWsChanges. 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 XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [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 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