Função MapViewOfFile3 (memoryapi.h)

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 ser alinhado ou alinhado a GetLargePageMinimum quando MEM_LARGE_PAGES é usado em AllocationType. Além disso, o deslocamento deve ser alinhado à página com o tamanho da página subjacente concedido por VirtualAlloc2 quando MEM_REPLACE_PLACEHOLDER é usado em AllocationType.

[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. Os requisitos de alinhamento de 64k em de Deslocamento não se aplicam quando esse sinalizador é especificado.

[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