Função CreateFileMapping2 (memoryapi.h)
Cria ou abre um objeto de mapeamento de arquivo nomeado ou sem nome para um arquivo especificado. Você pode especificar um nó NUMA preferencial para a memória física como um parâmetro estendido; consulte o parâmetro ExtendedParameters .
Sintaxe
HANDLE CreateFileMapping2(
HANDLE File,
SECURITY_ATTRIBUTES *SecurityAttributes,
ULONG DesiredAccess,
ULONG PageProtection,
ULONG AllocationAttributes,
ULONG64 MaximumSize,
PCWSTR Name,
MEM_EXTENDED_PARAMETER *ExtendedParameters,
ULONG ParameterCount
);
Parâmetros
File
Tipo: _In_ HANDLE
Um identificador para o arquivo do qual criar um objeto de mapeamento de arquivo.
O arquivo deve ser aberto com direitos de acesso compatíveis com os sinalizadores de proteção especificados pelo parâmetro flProtect . Não é necessário, mas é recomendável que os arquivos que você pretende mapear sejam abertos para acesso exclusivo. Para obter mais informações, consulte Segurança de arquivo e direitos de acesso.
Se hFile for INVALID_HANDLE_VALUE, o processo de chamada também deverá especificar um tamanho para o objeto de mapeamento de arquivo nos parâmetros dwMaximumSizeHigh e dwMaximumSizeLow . Nesse cenário, CreateFileMapping cria um objeto de mapeamento de arquivo de um tamanho especificado que é apoiado pelo arquivo de paginação do sistema em vez de por um arquivo no sistema de arquivos.
SecurityAttributes
Tipo: _In_opt_ SECURITY_ATTRIBUTES*
Um ponteiro para uma estrutura SECURITY_ATTRIBUTES que determina se um identificador retornado pode ser herdado por processos filho. O membro lpSecurityDescriptor da estrutura SECURITY_ATTRIBUTES especifica um descritor de segurança para um novo objeto de mapeamento de arquivo.
Se lpAttributes for NULL, o identificador não poderá ser herdado e o objeto de mapeamento de arquivo obterá um descritor de segurança padrão. As ACL (listas de controle de acesso) no descritor de segurança padrão para um objeto de mapeamento de arquivo vêm do token primário ou de representação do criador. Para obter mais informações, consulte Segurança de mapeamento de arquivos e direitos de acesso.
DesiredAccess
Tipo: _In_ ULONG
A máscara de acesso desejada para o identificador de mapeamento de arquivo retornado. Para obter uma lista de direitos de acesso, consulte Direitos de acesso e segurança de mapeamento de arquivos.
PageProtection
Tipo: _In_ ULONG
Especifica a proteção de página do objeto de mapeamento de arquivo. Todas as exibições mapeadas do objeto devem ser compatíveis com essa proteção.
Esse parâmetro pode usar um dos valores a seguir.
AllocationAttributes
Tipo: _In_ ULONG
Você pode especificar um ou mais dos atributos a seguir para o objeto de mapeamento de arquivo. Consulte também o parâmetro PageProtection .
| Valor | Significado |
|---|---|
|
Se o objeto de mapeamento de arquivo for apoiado pelo arquivo de paginação do sistema operacional (o parâmetro hfile é INVALID_HANDLE_VALUE), especifica que quando uma exibição do arquivo é mapeada em um espaço de endereço do processo, todo o intervalo de páginas é confirmado em vez de reservado. O sistema deve ter páginas committable suficientes para manter todo o mapeamento. Caso contrário, CreateFileMapping falhará.
Esse atributo não tem efeito para objetos de mapeamento de arquivo que são apoiados por arquivos de imagem executáveis ou arquivos de dados (o parâmetro hfile é um identificador para um arquivo). SEC_COMMIT não pode ser combinado com SEC_RESERVE. Se nenhum atributo for especificado, SEC_COMMIT será assumido. |
|
Especifica que o arquivo especificado pelo parâmetro hFile é um arquivo de imagem executável.
O atributo SEC_IMAGE deve ser combinado com um valor de proteção de página, como PAGE_READONLY. No entanto, esse valor de proteção de página não tem efeito sobre as exibições do arquivo de imagem executável. A proteção de página para exibições de um arquivo de imagem executável é determinada pelo próprio arquivo executável. Nenhum outro atributo é válido com SEC_IMAGE. |
|
Especifica que o arquivo que o parâmetro hFile especifica é um arquivo de imagem executável que não será executado e o arquivo de imagem carregado não terá nenhuma execução de verificações de integridade forçadas.
Além disso, mapear uma exibição de um objeto de mapeamento de arquivo criado com o atributo SEC_IMAGE_NO_EXECUTE não invocará retornos de chamada de driver registrados usando a API de kernel PsSetLoadImageNotifyRoutine .
O atributo SEC_IMAGE_NO_EXECUTE deve ser combinado com o valor de proteção de página PAGE_READONLY . Nenhum outro atributo é válido com SEC_IMAGE_NO_EXECUTE. Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Não há suporte para esse valor antes do Windows Server 2012 e do Windows 8. |
|
Permite que páginas grandes sejam usadas para objetos de mapeamento de arquivo que são apoiados pelo arquivo de paginação do sistema operacional (o parâmetro hfile é INVALID_HANDLE_VALUE). Esse atributo não tem suporte para objetos de mapeamento de arquivo que são apoiados por arquivos de imagem executáveis ou arquivos de dados (o parâmetro hFile é um identificador para uma imagem executável ou arquivo de dados).
O tamanho máximo do objeto de mapeamento de arquivo deve ser um múltiplo do tamanho mínimo de uma página grande retornada pela função GetLargePageMinimum . Se não estiver, CreateFileMapping falhará. Ao mapear uma exibição de um objeto de mapeamento de arquivo criado com SEC_LARGE_PAGES, o endereço base e o tamanho da exibição também devem ser múltiplos do tamanho mínimo da página grande. SEC_LARGE_PAGES requer que o privilégio SeLockMemoryPrivilege seja habilitado no token do chamador. Se SEC_LARGE_PAGES for especificado, SEC_COMMIT também deverá ser especificado. Windows Server 2003: Esse valor não tem suporte até o Windows Server 2003 com SP1. Windows XP: Não há suporte para esse valor. |
|
Define todas as páginas como não em cache.
Os aplicativos não devem usar esse atributo, exceto quando explicitamente necessários para um dispositivo. Usar as funções interligadas com memória mapeada com SEC_NOCACHE pode resultar em uma exceção EXCEPTION_ILLEGAL_INSTRUCTION . SEC_NOCACHE requer que o atributo SEC_RESERVE ou SEC_COMMIT seja definido. |
|
Se o objeto de mapeamento de arquivo é apoiado pelo arquivo de paginação do sistema operacional (o parâmetro hfile é INVALID_HANDLE_VALUE), especifica que quando uma exibição do arquivo é mapeada em um espaço de endereço de processo, todo o intervalo de páginas é reservado para uso posterior pelo processo em vez de confirmado.
As páginas reservadas podem ser confirmadas em chamadas subsequentes para a função VirtualAlloc . Depois que as páginas são confirmadas, elas não podem ser liberadas ou descompactadas com a função VirtualFree . Esse atributo não tem efeito para objetos de mapeamento de arquivo que são apoiados por arquivos de imagem executáveis ou arquivos de dados (o parâmetro hfile é um identificador para um arquivo). SEC_RESERVE não pode ser combinado com SEC_COMMIT. |
|
Define todas as páginas a serem combinadas com gravação.
Os aplicativos não devem usar esse atributo, exceto quando explicitamente necessários para um dispositivo. O uso das funções interligadas com memória mapeada com SEC_WRITECOMBINE pode resultar em uma exceção EXCEPTION_ILLEGAL_INSTRUCTION . SEC_WRITECOMBINE requer que o atributo SEC_RESERVE ou SEC_COMMIT seja definido. Windows Server 2003 e Windows XP: Esse sinalizador não tem suporte até o Windows Vista. |
MaximumSize
Tipo: _In_ ULONG64
O tamanho máximo do objeto de mapeamento de arquivo.
Se esse parâmetro for 0 (zero), o tamanho máximo do objeto de mapeamento de arquivo será igual ao tamanho atual do arquivo que hFile identifica.
Uma tentativa de mapear um arquivo com um comprimento de 0 (zero) falha com um código de erro de ERROR_FILE_INVALID. Você deve testar arquivos com um comprimento de 0 (zero) e rejeitar esses arquivos.
Name
Tipo: _In_opt_ PCWSTR
O nome do objeto de mapeamento de arquivo.
Se esse parâmetro corresponder ao nome de um objeto de mapeamento existente, a função solicitará acesso ao objeto com a proteção especificada por flProtect .
Se esse parâmetro for NULL, o objeto de mapeamento de arquivo será criado sem um nome.
Se lpName corresponder ao nome de um evento existente, semáforo, mutex, temporizador de espera ou objeto de trabalho, a função falhará e a função GetLastError retornará ERROR_INVALID_HANDLE. Isso ocorre porque esses objetos compartilham o mesmo namespace.
O nome pode ter um prefixo "Global" ou "Local" para criar explicitamente o objeto no namespace global ou de sessão. O restante do nome pode conter qualquer caractere, exceto o caractere de barra invertida (\). A criação de um objeto de mapeamento de arquivo no namespace global de uma sessão diferente de zero de sessão requer o privilégio SeCreateGlobalPrivilege . Para obter mais informações, consulte Namespaces de objeto kernel.
A troca rápida de usuários é implementada usando sessões de Serviços de Terminal. O primeiro usuário a fazer logon usa a sessão 0 (zero), o próximo usuário a fazer logon usa a sessão 1 (uma) e assim por diante. Os nomes de objeto kernel devem seguir as diretrizes descritas para os Serviços de Terminal para que os aplicativos possam dar suporte a vários usuários.
ExtendedParameters
Tipo: _Inout_updates_opt_(ParameterCount) MEM_EXTENDED_PARAMETER*
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 Tipo de MemExtendedParameterAddressRequirements ou MemExtendedParameterNumaNode. Se nenhum parâmetro estendido MemExtendedParameterNumaNode for fornecido, o comportamento será o mesmo que para as funções VirtualAlloc/MapViewOfFile (ou seja, o nó NUMA preferido para as páginas físicas é determinado com base no processador ideal do thread que primeiro acessa a memória).
ParameterCount
Em ULONG ParameterCount
O número de parâmetros estendidos apontados por ExtendedParameters.
Valor retornado
Se a função for bem-sucedida, o valor retornado será um identificador para o objeto de mapeamento de arquivo recém-criado.
Se o objeto existir antes da chamada de função, a função retornará um identificador para o objeto existente (com seu tamanho atual, não o tamanho especificado) e GetLastError retornará ERROR_ALREADY_EXISTS.
Se a função falhar, o valor retornado será NULL. Para obter informações de erro estendidas, chame GetLastError.
Comentários
Confira os Comentários de CreateFileMapping.
Exemplos
Para obter um exemplo, consulte Criando memória compartilhada nomeada ou Criando um mapeamento de arquivo usando páginas grandes.
Requisitos
| Cliente mínimo com suporte | Windows 10 Build 20348 |
| Servidor mínimo com suporte | Windows 10 Build 20348 |
| Plataforma de Destino | Windows |
| Cabeçalho | memoryapi.h (inclua Windows.h, Memoryapi.h) |
| Biblioteca | onecore.lib |
| DLL | Kernel32.dll |
Confira também
Criando um objeto de mapeamento de arquivo