Função MapViewOfFile (memoryapi.h)

Mapeia uma exibição de um mapeamento de arquivo no espaço de endereço de um processo de chamada.

Para especificar um endereço base sugerido para o modo de exibição, use a função MapViewOfFileEx . No entanto, essa prática não é recomendada.

Sintaxe

LPVOID MapViewOfFile(
  [in] HANDLE hFileMappingObject,
  [in] DWORD  dwDesiredAccess,
  [in] DWORD  dwFileOffsetHigh,
  [in] DWORD  dwFileOffsetLow,
  [in] SIZE_T dwNumberOfBytesToMap
);

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.

Valor Significado
FILE_MAP_ALL_ACCESS
Uma exibição de leitura/gravação do arquivo é mapeada. O objeto de mapeamento de arquivo deve ter sido criado com PAGE_READWRITE ou PAGE_EXECUTE_READWRITE proteção.

Quando usado com a função MapViewOfFile , FILE_MAP_ALL_ACCESS é equivalente a FILE_MAP_WRITE.

FILE_MAP_READ
Uma exibição somente leitura do arquivo é mapeada. Uma tentativa de gravar no modo de exibição de arquivo resulta em uma violação de acesso.

O objeto de mapeamento de arquivo deve ter sido criado com proteção PAGE_READONLY, PAGE_READWRITE, PAGE_EXECUTE_READ ou PAGE_EXECUTE_READWRITE .

FILE_MAP_WRITE
Uma exibição de leitura/gravação do arquivo é mapeada. O objeto de mapeamento de arquivo deve ter sido criado com PAGE_READWRITE ou PAGE_EXECUTE_READWRITE proteção.

Quando usados com MapViewOfFile, (FILE_MAP_WRITE | FILE_MAP_READ) e FILE_MAP_ALL_ACCESS são equivalentes a FILE_MAP_WRITE.

 

Usando OR bit a bit, você pode combinar os valores acima com esses valores.

Valor Significado
FILE_MAP_COPY
Uma exibição de cópia na gravação do arquivo é mapeada. O objeto de mapeamento de arquivo deve ter sido criado com proteção PAGE_READONLY, PAGE_READ_EXECUTE, PAGE_WRITECOPY, PAGE_EXECUTE_WRITECOPY, PAGE_READWRITE ou PAGE_EXECUTE_READWRITE .

Quando um processo é gravado em uma página de cópia na gravação, o sistema copia a página original para uma nova página que é 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, o custo de confirmação do sistema e do processo tomado é para todo o modo de exibição, pois 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 de volta no arquivo original e é perdido quando o modo de exibição é não mapeado.

FILE_MAP_EXECUTE
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 PAGE_EXECUTE_READWRITE proteção.

Windows Server 2003 e Windows XP: Esse valor está disponível a partir do Windows XP com SP2 e Windows Server 2003 com SP1.

FILE_MAP_LARGE_PAGES
A partir do Windows 10, versão 1703, 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 lpBaseAddress, o valor deverá ser um múltiplo de GetLargePageMinimum.

Nota: Nas versões do sistema operacional antes do Windows 10, versão 1703, o sinalizador FILE_MAP_LARGE_PAGES não tem efeito. Nessas versões, o modo de exibição será mapeado automaticamente usando páginas grandes se a seção tiver sido criada com o conjunto de sinalizadores SEC_LARGE_PAGES .
FILE_MAP_TARGETS_INVALID
Define todos os locais no arquivo mapeado como destinos inválidos para o CFG (Control Flow Guard). Este sinalizador é semelhante a PAGE_TARGETS_INVALID. Use esse sinalizador em combinação com o FILE_MAP_EXECUTE direito de acesso de execução. Qualquer chamada indireta para locais nessas páginas falhará nas verificações do CFG e o processo será encerrado. O comportamento padrão das 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 arquivos, consulte Segurança de Mapeamento de Arquivos e Direitos de Acesso.

[in] dwFileOffsetHigh

Um DWORD de alta ordem do deslocamento de arquivo em que a exibição começa.

[in] dwFileOffsetLow

Um 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 o modo de 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.

Retornar valor

Se a função for bem-sucedida, o valor retornado será o endereço inicial do modo de exibição mapeado.

Se a função falhar, o valor retornado será NULL. Para obter informações de erro estendidas, chame GetLastError.

Comentários

Mapear um arquivo torna a parte especificada de um 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 o primeiro modo de exibição for concluído, você poderá desapinhá-lo e mapear uma nova exibição.

Para obter o tamanho de uma exibição, use a função VirtualQuery .

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 de qualquer objeto de mapeamento de arquivo com o mesmo 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 MapViewOfFile funcione com arquivos remotos, ele não os mantém coerentes. Por exemplo, se dois computadores mapearem um arquivo como gravável e ambos mudarem a mesma página, cada computador só verá suas próprias gravações na página. Quando os dados são atualizados no disco, eles não são mesclados.

Não é garantido que uma exibição mapeada de um arquivo seja coerente com um arquivo que está sendo acessado pela função ReadFile ou WriteFile .

Não armazene ponteiros no arquivo mapeado de memória; armazene deslocamentos da base do mapeamento de arquivo para que o mapeamento possa ser usado em qualquer endereço.

Para se proteger contra exceções EXCEPTION_IN_PAGE_ERROR , use o tratamento de exceção estruturado para proteger qualquer código que grava ou lê 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.

Se um objeto de mapeamento de arquivo for apoiado pelo arquivo de paginação (CreateFileMapping é chamado com o parâmetro hFile definido como INVALID_HANDLE_VALUE), o arquivo de paginação deve ser grande o suficiente para manter todo o mapeamento. Se não estiver, MapViewOfFile falhará. O conteúdo inicial das páginas em um objeto de mapeamento de arquivo apoiado pelo arquivo de paginação é 0 (zero).

Quando um objeto de mapeamento de arquivo que é apoiado pelo arquivo de paginação é criado, o chamador pode especificar se MapViewOfFile deve reservar e confirmar páginas ao mesmo tempo (SEC_COMMIT) ou simplesmente reservar páginas (SEC_RESERVE). O mapeamento do arquivo torna todo o intervalo de endereços virtuais mapeado indisponível para outras alocações no processo. Depois que uma página do intervalo reservado for confirmada, ela não poderá ser liberada ou descompactada chamando VirtualFree. Páginas reservadas e confirmadas são liberadas quando o modo de exibição é não mapeado e o objeto de mapeamento de arquivo é fechado. Para obter detalhes, consulte as funções UnmapViewOfFile e CloseHandle .

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 MapViewOfFile 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 (Bloco de Mensagens do Servidor) 3.0 Yes
TFO (Failover Transparente) SMB 3.0 Yes
SMB 3.0 com compartilhamentos de arquivos de expansão (SO) Yes
Sistema de Arquivos de Volume Compartilhado de Cluster (CsvFS) Yes
ReFS (Sistema de Arquivos Resiliente) Yes
 

Quando csvFs é pausado, essa chamada pode falhar com um erro indicando que há um conflito de bloqueio.

Exemplos

Para obter um exemplo, consulte Criando Memória Compartilhada Nomeada.

Requisitos

   
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

Createfilemapping

Criando uma exibição de arquivo

Duplicatehandle

Getsysteminfo

MapViewOfFileEx

Funções de gerenciamento da memória

OpenFileMapping

SYSTEM_INFO

Unmapviewoffile