CreateFileMapping

9/8/2008

Essa função cria um nomeado ou sem nome arquivo-objeto mapeamento para o arquivo especificado.

Syntax

HANDLE CreateFileMapping(
  HANDLE hFile,
  LPSECURITY_ATTRIBUTES lpFileMappingAttributes,
  DWORD flProtect,
  DWORD dwMaximumSizeHigh,
  DWORD dwMaximumSizeLow,
  LPCTSTR lpName 
);

Parameters

• hFile
  [no] Identificador para o arquivo a partir da qual criar um objeto mapeamento. O arquivo deve ser aberto com um compatível modo de acesso com os sinalizadores de proteção especificados pelo flProtect parâmetro. Abrir arquivos que você pretende mapa (n.); mapear (v.) para acessar exclusivo. Se dois manipula para o arquivo estiver aberto no mesmo tempo, inconsistências entre o arquivo e a exibição mapeada dele pode ocorrer. A menos que você tenha preparado para sincronizar entre as duas alças, não use FILE_SHARE_READ ou FILE_SHARE_WRITE quando você chamar a função CreateFile.

  Se este parâmetro for definido como INVALID_HANDLE_VALUE (HANDLE), o processo de chamada deve também especificar um mapeamento tamanho objeto in a dwMaximumSizeHigh e o dwMaximumSizeLow Parâmetros. A função cria um arquivo-objeto mapeamento do tamanho especificado, feito por físico memória, em vez de um nomeado arquivo na sistema de arquivos. O arquivo-objeto mapeamento pode ser compartilhada por nome. Em Windows Embedded CE, memória utilizada para o objeto mapeamento não é parte do espaço de processo virtual MB 32.

  O valor deste parâmetro pode ser proveniente de um CreateFile ou a função CreateFileForMapping. No entanto, o identificador de arquivo difere entre essa função e a função CloseHandle.

• lpFileMappingAttributes
  [no] Ignorado. Deve ser definido como NULL.

• flProtect
  [no] A proteção desejada para a exibição arquivo, quando o arquivo é mapeado. A seguinte tabela mostra os valores possíveis.

  For Windows Embedded CE:

  ** Para informações sobre o comportamento desses valores quando esta função é usada com a função MapViewOfFile , consulte Modified Kernel APIs.**

  Valor	Descrição
  PAGE_READONLY	Fornece acessar Read-Only à região confirmada de páginas. Uma tentativa de gravação para ou executar a região confirmada resulta em um violação de acesso. O arquivo especificado por hFile Deve ter sido criado com GENERIC_READ acessar. Não é possível especificar PAGE_READONLY sem um identificador de arquivo.
  PAGE_READWRITE	Ler fornece-acesso de gravação para a região confirmada de páginas. O arquivo especificado por hFile Deve ter sido criado com acessar GENERIC_READ e GENERIC_WRITE.
  PAGE_WRITECOPY	Não suportado.

  Além disso, um aplicativo pode especificar determinados atributos seção combinando uma ou mais atributo seção valores com um da acima valores de proteção página, usando o operador bit a bit OR. A seguinte tabela mostra valores atributo seção possíveis.

  Valor	Descrição
  SEC_COMMIT	Aloca físico armazenamento em memória o arquivo de paginação no disco para todas as páginas de uma seção ou. Essa é a configuração padrão.
  SEC_IMAGE	Não suportado.
  SEC_NOCACHE	Não suportado.
  SEC_RESERVE	Não suportado.

• dwMaximumSizeHigh
  [no] Especifica o alto - ordem 32 bits do tamanho máximo do arquivo - objeto mapeamento.

  Se você pretende aumentar o arquivo, especificar o tamanho máximo de arquivo para que o kernel pode reserva a quantidade de memória correto.

• dwMaximumSizeLow
  [no] Especifica o baixo - ordem 32 bits do tamanho máximo do arquivo - objeto mapeamento. Se esse parâmetro e dwMaximumSizeHigh ** são definidas como zero, o tamanho máximo do arquivo-objeto mapeamento é igual a atual tamanho do arquivo especificado por hFile.

  Se dwMaximumSizeLow ** está definido para zero, a função retornará um erro que indica um inválido parâmetro.

• lpName
  [no] Ponteiro longo para um seqüência de caracteres NULL-Terminated especificando o nome do objeto de mapeamento. O nome pode conter qualquer caractere.

  Se este parâmetro corresponda ao nome de um nomeado existente objeto mapeamento, a função solicitações acessar para o objeto mapeamento com a proteção especificada por flProtect.

  Cada tipo objeto, such as memória mapas, semáforos, eventos, mensagem filas, exclusões mútuas e timers de monitoração, tem sua própria separar espaço para nome. Seqüências de caracteres vazia (" ") são tratados como nomeado objetos. Em plataformas com base em Área de trabalho Windows, sincronização objetos todos compartilhar o mesmo namespace.

Return Value

Um identificador para o arquivo-objeto mapeamento indica sucesso. Se o objeto existia antes de chamada de função, a função retornará um identificador para o objeto existente. Com sua atual tamanho, não o tamanho especificado e GetLastError retornará ERROR_ALREADY_EXISTS. NULL Indica falha. Para informações de erro estendidas get, chamar GetLastError.

For Windows Embedded CE:

Para Windows Embedded CE, se dwMaximumSizeLow está definido para zero, a função retorna ERROR_INVALID_PARAMETER. **

Remarks

Esta função pode arquivos mapa (n.); mapear (v.) de um total 64-bit tamanho. A função MapViewOfFile pode criar modos de exibição se o atual processo tem suficiente virtual espaço de endereço contê-los. Evitar as restrições de recursos direcionar-ROM e mapfiles não-paginável que são maior do que 4 GB.

Um arquivo Memory-mapped não deve ser acessado usando o ReadFile ou a função WriteFile. Isso pode resultar em inconsistências entre o arquivo e o arquivo Memory-mapped.

Duas alças graváveis para o mesmo arquivo não podem ser aberto no mesmo tempo para evitar inconsistências entre o arquivo e a exibição mapeada dele. Para os dois processos para compartilhar os dados em um arquivo Memory-mapped, eles devem ambas as mapa (n.); mapear (v.) memória o arquivo.

Se você chamar essa função com um identificador de CreateFileForMapping e ele falhar por algum motivo, o identificador está fechado. Para exemplo, qualquer tentar usar o CloseHandle função em um identificador de arquivo que foi retornada do CreateFileForMapping e, em seguida, usado em uma falha chamar para essa função automaticamente retornar FALSE. Em vez disso, a fecha automaticamente kernel o identificador especificado em hFile.

Essa função não trabalho em Windows Embedded CE Dispositivos que não suporte paginação por demanda.

Após um arquivo - objeto mapeamento foi criado, o tamanho do arquivo não deve exceder o tamanho do arquivo - objeto mapeamento. Em caso afirmativo, nem todos os arquivo conteúdo está disponível para o compartilhamento.

Se um aplicativo especifica um tamanho para o arquivo-objeto mapeamento que é maior do que o tamanho do nomeado arquivo no disco, o arquivo no disco é aprimorado para coincidir com o tamanho especificado do arquivo-objeto mapeamento. Se o arquivo não pode ser aprimorado, o arquivo-objeto mapeamento não foi criado. GetLastError Retorna ERROR_DISK_FULL.

O identificador que essa função retorna tem acesso completo para o novo arquivo-objeto mapeamento. Ele pode ser usado com qualquer função que requer um identificador para um arquivo-objeto mapeamento. Arquivo-objetos mapeamento podem ser compartilhados por meio de criação processo.

Arquivo alças que foram usados para criar arquivo - objetos mapeamento não devem ser usado em chamadas subseqüentes ao arquivo E/S funções, como ReadFile e WriteFile. Em geral, se um identificador de arquivo foi usado em um bem-sucedido chamar para esta função, não use esse identificador, a menos que você primeiro fechar o correspondente arquivo-objeto mapeamento.

Criando um arquivo-objeto mapeamento cria o potencial para mapeamento uma exibição do arquivo, mas não mapa (n.); mapear (v.) a exibição. MapViewOfFile Mapeia uma exibição de um arquivo para o espaço de endereço de um processo.

Com uma exceção importante, arquivo exibições derivado de um único arquivo-objeto mapeamento são coerente ou idênticos, em um tempo especificado. Se processos múltiplo têm alças do mesmo arquivo-objeto mapeamento, eles verão uma exibição coerente dos dados quando eles mapa (n.); mapear (v.) uma exibição do arquivo.

A exceção tem a ver com remoto arquivos. Embora esta função funciona com remoto arquivos, ele não manter eles coerente. De exemplo, se dois computadores mapa (n.); mapear (v.) um arquivo como gravável, tanto os dois alteração a mesma página, cada computador vê apenas sua própria exibição como ela grava a página. Quando os dados são atualizados no disco, ele não será mesclado.

Para totalmente fechar um arquivo-objeto mapeamento, um aplicativo deve desmapeamento mapeados todos os modos de exibição do arquivo-objeto mapeamento por chamado de função UnmapViewOfFile e fechar o arquivo-manipulador de objeto mapeamento por chamado CloseHandle. A ordem na qual essas funções são chamado não importa. A chamar para UnmapViewOfFile é necessário porque mapeado modos de exibição de um arquivo-objeto mapeamento manter interno manipula aberto para o objeto e um arquivo - objeto mapeamento não fechar até aberto todas as alças para ela sejam fechadas.

O CreateFileForMapping função abre um arquivo e retorna um identificador de arquivo que é passado para essa função. Essa função retorna um identificador para o mapeamento de arquivo. Para Windows Embedded CE, é necessário somente para fechar o identificador mapeamento como o identificador de arquivo é automaticamente fechada quando você fechar o identificador mapeamento.

Se o arquivo que está sendo mapeado é um ROM descompactado arquivo e ele é mapeado com acessar PAGE_READONLY, o arquivo é acessado diretamente do ROM sem usando qualquer memória RAM para armazenar em cache de dados.

Security Note:

Para se proteger contra um violação de acesso, use manipulação estruturada de exceções para proteger qualquer codificar que grava ou lê de uma exibição Memory-mapped.As informações em um arquivo Memory-mapped legível podem ser ler por outros processos no sistema.Fazer não confidencial armazenar informações em um arquivo Memory-mapped.As informações em um arquivo Memory-mapped gravável podem ser gravadas por outros processos no sistema.Você deve validar todos os dados que você ler de uma memória mapeados arquivo.

Para implementar um mapeamento-função criação do objeto que falhará se o objeto já existe, um aplicativo pode usar o seguinte codificar:

hMap = CreateFileMapping(...);
if (hMap != NULL && GetLastError() == ERROR_ALREADY_EXISTS)
{
   CloseHandle(hMap);
   hMap = NULL;
}
return hMap;

Requirements

Header	winbase.h
Library	coredll.lib
Windows Embedded CE	Windows CE 1.01 and later
Windows Mobile	Windows Mobile Version 5.0 and later

See Also

Reference

File Mapping Functions
CloseHandle
CreateFileForMapping
MapViewOfFile
ReadFile
UnmapViewOfFile
WriteFile

Other Resources

Modified Kernel APIs
VirtualAlloc