Função MapViewOfFile3 (memoryapi.h)

Mapeia uma exibição de um arquivo ou uma seção com backup de pagefile para o espaço de endereço do processo especificado.

Usando essa função, você pode: para novas alocações, especificar um intervalo de espaço de endereço virtual e uma restrição de alinhamento de potência de 2; especificar um número arbitrário de parâmetros estendidos; especifique um nó NUMA preferencial para a memória física como um parâmetro estendido; e especificam uma operação de espaço reservado (especificamente, substituição).

Para especificar o nó NUMA, consulte o parâmetro ExtendedParameters .

Sintaxe

PVOID MapViewOfFile3(
  [in]                HANDLE                 FileMapping,
  [in]                HANDLE                 Process,
  [in, optional]      PVOID                  BaseAddress,
  [in]                ULONG64                Offset,
  [in]                SIZE_T                 ViewSize,
  [in]                ULONG                  AllocationType,
  [in]                ULONG                  PageProtection,
  [in, out, optional] MEM_EXTENDED_PARAMETER *ExtendedParameters,
  [in]                ULONG                  ParameterCount
);

Parâmetros

[in] FileMapping

Um HANDLE para uma seção que deve ser mapeada para o espaço de endereço do processo especificado.

[in] Process

Um HANDLE para um processo no qual a seção será mapeada.

[in, optional] BaseAddress

O endereço base desejado da exibição. O endereço é arredondado para baixo até o limite de 64k mais próximo.

Observação

Se esse parâmetro for NULL, o sistema escolherá o endereço base.

Se BaseAddress não for NULL, qualquer MEM_ADDRESS_REQUIREMENTS fornecida deverá consistir em todos os zeros.

[in] Offset

O deslocamento do início da seção. Isso deve estar alinhado a 64k.

[in] ViewSize

O número de bytes a serem mapeados. Um valor zero (0) especifica que toda a seção deve ser mapeada.

O tamanho deve ser sempre um múltiplo do tamanho da página.

[in] AllocationType

O tipo de alocação de memória. Esse parâmetro pode ser zero (0) ou um dos valores a seguir.

Valor	Significado
MEM_RESERVE 0x00002000	Mapeia uma exibição reservada.
MEM_REPLACE_PLACEHOLDER 0x00004000	Substitui um espaço reservado por uma exibição mapeada. Somente exibições de seção com suporte de dados/pf são compatíveis (sem imagens, memória física etc.). Quando você substitui um espaço reservado, BaseAddress e ViewSize devem corresponder exatamente aos do espaço reservado e qualquer estrutura de MEM_ADDRESS_REQUIREMENTS fornecida deve consistir em todos os zeros. Depois de substituir um espaço reservado por uma exibição mapeada, para liberar essa exibição mapeada de volta para um espaço reservado, consulte o parâmetro UnmapFlags de UnmapViewOfFileEx e UnmapViewOfFile2. Um espaço reservado é um tipo de região de memória reservada. Os requisitos de alinhamento de 64k em Offset e BaseAddress não se aplicam quando esse sinalizador é especificado.
MEM_LARGE_PAGES 0x20000000	Mapeia uma exibição de página grande. Esse sinalizador especifica que a exibição deve ser mapeada usando suporte a páginas grandes. O tamanho do modo de exibição deve ser um múltiplo do tamanho de uma página grande relatada pela função GetLargePageMinimum e o objeto de mapeamento de arquivo deve ter sido criado usando a opção SEC_LARGE_PAGES . Se você fornecer um valor não nulo para o parâmetro BaseAddress , o valor deverá ser um múltiplo de GetLargePageMinimum.

[in] PageProtection

A proteção de página desejada.

Para objetos de mapeamento de arquivo criados com o atributo SEC_IMAGE , o parâmetro PageProtection não tem efeito e deve ser definido como qualquer valor válido, como PAGE_READONLY.

[in, out, optional] ExtendedParameters

Um ponteiro opcional para um ou mais parâmetros estendidos do tipo MEM_EXTENDED_PARAMETER. Cada um desses valores de parâmetro estendidos pode ter um campo Tipo de MemExtendedParameterAddressRequirements ou MemExtendedParameterNumaNode. Se nenhum parâmetro estendido MemExtendedParameterNumaNode for fornecido, o comportamento será o mesmo que para as funções VirtualAlloc/MapViewOfFile (ou seja, o nó NUMA preferido para as páginas físicas é determinado com base no processador ideal do thread que primeiro acessa a memória).

[in] ParameterCount

O número de parâmetros estendidos apontados por ExtendedParameters.

Retornar valor

Retorna o endereço base do modo de exibição mapeado, se bem-sucedido. Caso contrário, retorna NULL e o erro estendido status está disponível usando GetLastError.

Comentários

Essa API ajuda a dar suporte a jogos de alto desempenho e aplicativos de servidor, que têm requisitos específicos em relação ao gerenciamento de seu espaço de endereço virtual. Por exemplo, mapeando memória sobre uma região reservada anteriormente; isso é útil para implementar um buffer de anel de encapsulamento automático. E alocar memória com alinhamento específico; por exemplo, para permitir que seu aplicativo confirme regiões grandes/enormes mapeadas por página sob demanda.

Exemplos

Para obter um exemplo de código, consulte Cenário 1 em VirtualAlloc2.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 10, versão 1803 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2016 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	memoryapi.h (inclua Windows.h)
Biblioteca	onecore.lib
DLL	Kernel32.dll

Confira também

VirtualAlloc2

Mapviewoffile

MapViewOfFile2

MapViewOfFileNuma2