Função MapViewOfFile3 (memoryapi.h)

  • Artigo

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

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).

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

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

[in] Offset

O deslocamento do início da seção.

O deslocamento deve estar alinhado em 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 um modo de exibição reservado.
MEM_REPLACE_PLACEHOLDER
0x00004000
 Substitui um espaço reservado por uma exibição mapeada. Há suporte apenas para exibições de seção com suporte de dados/pf (sem imagens, memória física etc.). Quando você substitui um espaço reservado, BaseAddress e ViewSize deve 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 UnmapFlagsUnmapViewOfFileEx e UnmapViewOfFile2.

Um espaço reservado é um tipo de região de memória reservada.

Os requisitos de alinhamento de 64k no de Deslocamento 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 o modo de exibição deve ser mapeado usando suporte de página grande. O tamanho da 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 Type de MemExtendedParameterAddressRequirements ou MemExtendedParameterNumaNode. Se nenhum MemExtendedParameterNumaNode parâmetro estendido for fornecido, o comportamento será o mesmo das funções MapViewOfFile (ou seja, o nó NUMA preferencial 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.

Valor de retorno

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

Observações

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.

Usando essa função para novas alocações, você pode:

  • 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
  • especificar um nó NUMA preferencial para a memória física como um parâmetro estendido
  • especificar uma operação de espaço reservado (especificamente, substituição).

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

Exemplos

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

Requisitos

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

Consulte também

VirtualAlloc2

MapViewOfFile

MapViewOfFile2

MapViewOfFileNuma2