Função AllocateUserPhysicalPages (memoryapi.h)

Artigo
02/28/2024

Aloca páginas de memória física a serem mapeadas e não mapeadas em qualquer região do AWE ( Address Windowing Extensions ) de um processo especificado.

Windows de 64 bits em sistemas baseados em Itanium: Devido à diferença nos tamanhos de página, Não há suporte para AllocateUserPhysicalPages em aplicativos de 32 bits.

Sintaxe

BOOL AllocateUserPhysicalPages(
  [in]      HANDLE     hProcess,
  [in, out] PULONG_PTR NumberOfPages,
  [out]     PULONG_PTR PageArray
);

Parâmetros

[in] hProcess

Um identificador para um processo.

A função aloca memória que pode ser mapeada posteriormente dentro do espaço de endereço virtual desse processo. O identificador deve ter o direito de acesso PROCESS_VM_OPERATION . Para obter mais informações, consulte Direitos de acesso e segurança do processo.

[in, out] NumberOfPages

O tamanho da memória física a ser alocada, em páginas.

Para determinar o tamanho da página do computador, use a função GetSystemInfo . Na saída, esse parâmetro recebe o número de páginas realmente alocadas, o que pode ser menor do que o número solicitado.

[out] PageArray

Um ponteiro para uma matriz para armazenar os números de quadro de página da memória alocada.

O tamanho da matriz alocada deve ser pelo menos o NumberOfPages vezes o tamanho do tipo de dados ULONG_PTR .

Não tente modificar esse buffer. Ele contém dados do sistema operacional e a corrupção pode ser catastrófica. As informações no buffer não são úteis para um aplicativo.

Retornar valor

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

Menos páginas do que as solicitadas podem ser alocadas. O chamador deve marcar o valor do parâmetro NumberOfPages no retorno para ver quantas páginas são alocadas. Todos os números de quadro de página alocados são colocados sequencialmente na memória apontada pelo parâmetro UserPfnArray .

Se a função falhar, o valor retornado será FALSE e nenhum quadro será alocado. Para obter informações de erro estendidas, chame GetLastError.

Comentários

A função AllocateUserPhysicalPages é usada para alocar memória física que pode ser mapeada posteriormente dentro do espaço de endereço virtual do processo. O privilégio SeLockMemoryPrivilege deve ser habilitado no token do chamador ou a função falhará com ERROR_PRIVILEGE_NOT_HELD. Para obter mais informações, consulte Constantes de privilégio.

A memória alocada por essa função deve estar fisicamente presente no sistema. Depois que a memória é alocada, ela é bloqueada e indisponível para o restante do sistema de gerenciamento de memória virtual.

As páginas físicas não podem ser mapeadas simultaneamente em mais de um endereço virtual.

As páginas físicas podem residir em qualquer endereço físico. Você não deve fazer suposições sobre a contígua das páginas físicas.

Para compilar um aplicativo que usa essa função, defina a macro _WIN32_WINNT como 0x0500 ou posterior. Para obter mais informações, consulte Usando os cabeçalhos do Windows.

AllocateUserPhysicalPages2, adicionado ao SDK em uma versão posterior, é o mesmo que AllocateUserPhysicalPages , mas adiciona os parâmetros ExtendedParameters e ExtendedParameterCount .

Exemplos

Para obter um exemplo, consulte Exemplo de AWE.

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	memoryapi.h (inclua Windows.h, Memoryapi.h)
Biblioteca	onecore.lib
DLL	Kernel32.dll