Função CreateFileMappingFromApp (memoryapi.h)
Cria ou abre um objeto de mapeamento de arquivo nomeado ou sem nome para um arquivo especificado de um aplicativo da Windows Store.
Sintaxe
HANDLE CreateFileMappingFromApp(
[in] HANDLE hFile,
[in, optional] PSECURITY_ATTRIBUTES SecurityAttributes,
[in] ULONG PageProtection,
[in] ULONG64 MaximumSize,
[in, optional] PCWSTR Name
);
Parâmetros
[in] hFile
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 que o parâmetro flProtect especifica. 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 de Segurança de Arquivos 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, CreateFileMappingFromApp 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.
[in, optional] SecurityAttributes
Um ponteiro para uma estrutura de SECURITY_ATTRIBUTES que determina se um identificador retornado pode ser herdado por processos filho. O lpSecurityDescriptor membro da estrutura SECURITY_ATTRIBUTES especifica um descritor de segurança para um novo objeto de mapeamento de arquivo.
Se SecurityAttributes 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.
[in] PageProtection
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 ser um dos valores a seguir.
Um aplicativo pode especificar um ou mais dos seguintes atributos para o objeto de mapeamento de arquivo combinando-os com um dos valores de proteção de página anteriores.
| 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 para 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 de confirmação suficientes para manter todo o mapeamento. Caso contrário, CreateFileMappingFromApp 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 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 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. |
|
Permite que páginas grandes sejam usadas para objetos de mapeamento de arquivos 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 um 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, CreateFileMappingFromApp 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 de 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. |
|
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 intertravadas 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 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 para um espaço de endereço do processo, todo o intervalo de páginas é reservado para uso posterior pelo processo em vez de confirmado.
Páginas reservadas podem ser confirmadas em chamadas subsequentes para a função VirtualAlloc. Depois que as páginas forem confirmadas, elas não poderão ser liberadas ou descompactadas com a função 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. Usar as funções intertravadas 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. |
[in] MaximumSize
O tamanho máximo do objeto de mapeamento de arquivo.
Uma tentativa de mapear um arquivo com um comprimento de 0 (zero) falha com um código de erro de ERROR_FILE_INVALID. Os aplicativos devem testar arquivos com um comprimento de 0 (zero) e rejeitar esses arquivos.
[in, optional] Name
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 que flProtect especificar.
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 alternância rápida de usuário é implementada usando sessões dos 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.
Valor de retorno
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.
Observações
Depois que um objeto de mapeamento de arquivo é criado, o tamanho do arquivo não deve exceder o tamanho do objeto de mapeamento de arquivo; se isso acontecer, nem todo o conteúdo do arquivo estará disponível para compartilhamento.
Se um aplicativo especificar um tamanho para o objeto de mapeamento de arquivo maior que o tamanho do arquivo nomeado real no disco e se a proteção de página permitir acesso de gravação (ou seja, o parâmetro flProtect especifica PAGE_READWRITE), o arquivo em disco será aumentado para corresponder ao tamanho especificado do objeto de mapeamento de arquivo. Se o arquivo for estendido, o conteúdo do arquivo entre a extremidade antiga do arquivo e o novo final do arquivo não será garantido como zero; o comportamento é definido pelo sistema de arquivos. Se o arquivo no disco não puder ser aumentado, CreateFileMappingFromApp falhar e GetLastError retornará ERROR_DISK_FULL.
O conteúdo inicial das páginas em um objeto de mapeamento de arquivo apoiado pelo arquivo de paginação do sistema operacional é 0 (zero).
O identificador que CreateFileMappingFromApp retorna tem acesso total a um novo objeto de mapeamento de arquivo e pode ser usado com qualquer função que exija um identificador para um objeto de mapeamento de arquivo.
Vários processos podem compartilhar uma exibição do mesmo arquivo usando um único objeto de mapeamento de arquivo compartilhado ou criando objetos de mapeamento de arquivo separados apoiados pelo mesmo arquivo. Um único objeto de mapeamento de arquivo pode ser compartilhado por vários processos por meio da herdação do identificador na criação do processo, duplicação do identificador ou abertura do objeto de mapeamento de arquivo pelo nome. Para obter mais informações, consulte as funções CreateProcess, DuplicateHandle e OpenFileMapping.
A criação de um objeto de mapeamento de arquivo não mapeia a exibição para um espaço de endereço de processo. A função MapViewOfFileEx mapeia uma exibição de um arquivo para um espaço de endereço do processo.
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 CreateFileMappingFromApp funciona 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 verá apenas suas próprias gravações na página. Quando os dados são atualizados no disco, eles não são mesclados.
Um arquivo mapeado e um arquivo que é acessado usando as funções de entrada e saída (E/S) ( ReadFile e WriteFile) não são necessariamente coerentes.
Exibições mapeadas de um objeto de mapeamento de arquivo mantêm referências internas ao objeto e um objeto de mapeamento de arquivo não fecha até que todas as referências a ele sejam liberadas. Portanto, para fechar totalmente um objeto de mapeamento de arquivo, um aplicativo deve desacompactar todas as exibições mapeadas do objeto de mapeamento de arquivo chamando UnmapViewOfFile e fechar o identificador de objeto de mapeamento de arquivo chamando CloseHandle. Essas funções podem ser chamadas em qualquer ordem.
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.
Use o tratamento de exceção estruturado para proteger qualquer código que grava ou lê de um modo de exibição de arquivo. Para obter mais informações, consulte leitura e gravação de uma exibição de arquivo.
Você só poderá solicitar proteção executável com êxito se o aplicativo tiver a funcionalidade codeGeneration
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows 8 [aplicativos da área de trabalho | Aplicativos UWP] |
| servidor com suporte mínimo | Windows Server 2012 [aplicativos da área de trabalho | Aplicativos UWP] |
| da Plataforma de Destino |
Windows |
| cabeçalho | memoryapi.h (inclua Windows.h) |
| biblioteca | onecore.lib |
| de DLL |
Kernel32.dll |
Consulte também
criando um objeto de mapeamento de arquivo
Funções de mapeamento de arquivo
Funções de gerenciamento de memória