Função MapViewOfFileEx (memoryapi.h)
Mapeia uma exibição de um mapeamento de arquivo para o espaço de endereço de um processo de chamada. Opcionalmente, um chamador pode especificar um endereço de memória base sugerido para o modo de exibição.
Para especificar o nó NUMA para a memória física, consulte MapViewOfFileExNuma.
Sintaxe
LPVOID MapViewOfFileEx(
[in] HANDLE hFileMappingObject,
[in] DWORD dwDesiredAccess,
[in] DWORD dwFileOffsetHigh,
[in] DWORD dwFileOffsetLow,
[in] SIZE_T dwNumberOfBytesToMap,
[in, optional] LPVOID lpBaseAddress
);
Parâmetros
[in] hFileMappingObject
Um identificador para um objeto de mapeamento de arquivo. As funções CreateFileMapping e OpenFileMapping retornam esse identificador.
[in] dwDesiredAccess
O tipo de acesso a um objeto de mapeamento de arquivo, que determina a proteção de página das páginas. Esse parâmetro pode ser um dos valores a seguir ou uma combinação OR bit a bit de vários valores, quando apropriado.
Usando OR bit a bit, você pode combinar os valores acima com esses valores.
| Valor | Significado |
|---|---|
|
Uma exibição de cópia na gravação do arquivo é mapeada. O objeto de mapeamento de arquivo deve ter sido criado com PAGE_READONLY, PAGE_READ_EXECUTE, PAGE_WRITECOPY, PAGE_EXECUTE_WRITECOPY, PAGE_READWRITE ou proteção de PAGE_EXECUTE_READWRITE .
Quando um processo grava em uma página de cópia na gravação, o sistema copia a página original para uma nova página privada para o processo. A nova página é apoiada pelo arquivo de paginação. A proteção da nova página muda de cópia na gravação para leitura/gravação. Quando o acesso de cópia na gravação é especificado, a cobrança de confirmação do sistema e do processo tomada é para todo o modo de exibição porque o processo de chamada pode potencialmente gravar em cada página no modo de exibição, tornando todas as páginas privadas. O conteúdo da nova página nunca é gravado no arquivo original e é perdido quando o modo de exibição é não mapeado. |
|
Começando com Windows 10, versão 1703, esse sinalizador especifica que o modo de exibição deve ser mapeado 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 lpBaseAddress, o valor deverá ser um múltiplo de GetLargePageMinimum. |
|
Uma exibição executável do arquivo é mapeada (a memória mapeada pode ser executada como código). O objeto de mapeamento de arquivo deve ter sido criado com PAGE_EXECUTE_READ, PAGE_EXECUTE_WRITECOPY ou proteção de PAGE_EXECUTE_READWRITE .
Windows Server 2003 e Windows XP: Esse valor está disponível a partir do Windows XP com SP2 e Windows Server 2003 com SP1. |
|
Define todos os locais no arquivo mapeado como destinos inválidos para o CFG (Control Flow Guard). Esse sinalizador é semelhante a PAGE_TARGETS_INVALID. Use esse sinalizador em combinação com o FILE_MAP_EXECUTE direito de execução de acesso. Qualquer chamada indireta para locais nessas páginas falhará nas verificações do CFG e o processo será encerrado. O comportamento padrão para páginas executáveis alocadas deve ser marcado como destinos de chamada válidos para CFG. |
Para objetos de mapeamento de arquivo criados com o atributo SEC_IMAGE , o parâmetro dwDesiredAccess não tem efeito e deve ser definido como qualquer valor válido, como FILE_MAP_READ.
Para obter mais informações sobre o acesso a objetos de mapeamento de arquivo, consulte Segurança de mapeamento de arquivos e direitos de acesso.
[in] dwFileOffsetHigh
O DWORD de alta ordem do deslocamento de arquivo em que a exibição deve começar.
[in] dwFileOffsetLow
O DWORD de baixa ordem do deslocamento de arquivo em que a exibição deve começar. A combinação de deslocamentos altos e baixos deve especificar um deslocamento dentro do mapeamento de arquivo. Eles também devem corresponder à granularidade de alocação de memória do sistema. Ou seja, o deslocamento deve ser um múltiplo da granularidade de alocação. Para obter a granularidade de alocação de memória do sistema, use a função GetSystemInfo , que preenche os membros de uma estrutura SYSTEM_INFO .
[in] dwNumberOfBytesToMap
O número de bytes de um mapeamento de arquivo a ser mapeado para uma exibição. Todos os bytes devem estar dentro do tamanho máximo especificado por CreateFileMapping. Se esse parâmetro for 0 (zero), o mapeamento se estenderá do deslocamento especificado até o final do mapeamento de arquivo.
[in, optional] lpBaseAddress
Um ponteiro para o endereço de memória no espaço de endereço do processo de chamada em que o mapeamento começa. Isso deve ser um múltiplo da granularidade de alocação de memória do sistema ou a função falha. Para determinar a granularidade de alocação de memória do sistema, use a função GetSystemInfo . Se não houver espaço de endereço suficiente no endereço especificado, a função falhará.
Se lpBaseAddress for NULL, o sistema operacional escolherá o endereço de mapeamento. Nesse cenário, a função é equivalente à função MapViewOfFile .
Embora seja possível especificar um endereço seguro agora (não usado pelo sistema operacional), não há garantia de que o endereço permanecerá seguro ao longo do tempo. Portanto, é melhor permitir que o sistema operacional escolha o endereço. Nesse caso, você não armazenaria ponteiros no arquivo mapeado de memória, armazenaria deslocamentos da base do mapeamento de arquivo para que o mapeamento possa ser usado em qualquer endereço.
Retornar valor
Se a função for bem-sucedida, o valor retornado será o endereço inicial da exibição mapeada.
Se a função falhar, o valor retornado será NULL. Para obter informações de erro estendidas, chame GetLastError.
Comentários
O mapeamento de um arquivo torna a parte especificada do arquivo visível no espaço de endereço do processo de chamada.
Para arquivos maiores que o espaço de endereço, você só pode mapear uma pequena parte dos dados do arquivo ao mesmo tempo. Quando a primeira exibição for concluída, você a desmapeará e mapeará uma nova exibição.
Para obter o tamanho de uma exibição, use a função VirtualQueryEx .
O conteúdo inicial das páginas em um objeto de mapeamento de arquivo apoiado pelo arquivo de página é 0 (zero).
Normalmente, o endereço sugerido é usado para especificar que um arquivo deve ser mapeado no mesmo endereço em vários processos. Isso requer que a região do espaço de endereço esteja disponível em todos os processos envolvidos. Nenhuma outra alocação de memória pode ocorrer na região usada para mapeamento, incluindo o uso da função VirtualAlloc ou VirtualAllocEx para reservar memória.
Se o parâmetro lpBaseAddress especificar um deslocamento base, a função terá êxito se a região de memória especificada ainda não estiver em uso pelo processo de chamada. O sistema não garante que a mesma região de memória esteja disponível para o arquivo mapeado de memória em outros processos de 32 bits.
Várias exibições de um arquivo (ou um objeto de mapeamento de arquivo e seu arquivo mapeado) serão coerentes se contiverem dados idênticos em um momento especificado. Isso ocorrerá se as exibições de arquivo forem derivadas do mesmo objeto de mapeamento de arquivo. Um processo pode duplicar um identificador de objeto de mapeamento de arquivo em outro processo usando a função DuplicateHandle ou outro processo pode abrir um objeto de mapeamento de arquivo pelo nome usando a função OpenFileMapping .
Com uma exceção importante, as exibições de arquivo derivadas de qualquer objeto de mapeamento de arquivo com o mesmo arquivo são coerentes ou idênticas em um momento específico. A coerência é garantida para exibições dentro de um processo e para exibições mapeadas por processos diferentes.
A exceção está relacionada a arquivos remotos. Embora MapViewOfFileEx funcione com arquivos remotos, ele não os mantém coerentes. Por exemplo, se dois computadores mapearem um arquivo como gravável e ambos alterarem a mesma página, cada computador verá apenas suas próprias gravações na página. Quando os dados são atualizados no disco, eles não são mesclados.
Não há garantia de que uma exibição mapeada de um arquivo seja coerente com um arquivo sendo acessado pela função ReadFile ou WriteFile .
Para proteger-se contra exceções EXCEPTION_IN_PAGE_ERROR , use o tratamento de exceções estruturadas para proteger qualquer código que grave ou leia de uma exibição mapeada de memória de um arquivo diferente do arquivo de página. Para obter mais informações, consulte Leitura e gravação de um modo de exibição de arquivo.
Ao modificar um arquivo por meio de uma exibição mapeada, o carimbo de data/hora da última modificação pode não ser atualizado automaticamente. Se necessário, o chamador deve usar SetFileTime para definir o carimbo de data/hora.
Para ter um arquivo com permissões executáveis, um aplicativo deve chamar CreateFileMapping com PAGE_EXECUTE_READWRITE ou PAGE_EXECUTE_READ e, em seguida, chamar MapViewOfFileEx com FILE_MAP_EXECUTE | FILE_MAP_WRITE ou FILE_MAP_EXECUTE | FILE_MAP_READ.
Em Windows Server 2012, essa função é compatível com as tecnologias a seguir.
| Tecnologia | Com suporte |
|---|---|
| Protocolo SMB (SMB) 3.0 | Sim |
| TFO (Failover transparente) do SMB 3.0 | Sim |
| SMB 3.0 com compartilhamentos de arquivos de expansão (SO) | Sim |
| Sistema de arquivos de Volume Compartilhado Clusterizado (CsvFS) | Sim |
| ReFS (Sistema de Arquivos Resiliente) | Sim |
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 |
Confira também
Criando uma exibição de arquivo
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de