Função CreateFileFromAppW (fileapifromapp.h)

Artigo
03/09/2023

Cria ou abre um arquivo ou dispositivo de E/S. O comportamento dessa função é idêntico a CreateFile, exceto que essa função segue o modelo de segurança do aplicativo Plataforma Universal do Windows.

Sintaxe

WINSTORAGEAPI HANDLE CreateFileFromAppW(
  LPCWSTR               lpFileName,
  DWORD                 dwDesiredAccess,
  DWORD                 dwShareMode,
  LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  DWORD                 dwCreationDisposition,
  DWORD                 dwFlagsAndAttributes,
  HANDLE                hTemplateFile
) noexcept;

Parâmetros

lpFileName

O nome do arquivo ou dispositivo a ser criado ou aberto. Você pode usar barras (/) ou barras invertidas (\) nesse nome.

Na versão ANSI dessa função, o nome é limitado a MAX_PATH caracteres. Para estender esse limite para 32.767 caracteres largos, chame a versão Unicode da função e preencha "\\?\" para o caminho. Para obter mais informações, confira Nomear arquivos, caminhos e namespaces.

Para obter informações sobre nomes de dispositivos especiais, consulte Definindo um nome de dispositivo MS-DOS.

Para criar um fluxo de arquivos, especifique o nome do arquivo, dois-pontos e, em seguida, o nome do fluxo. Para obter mais informações, consulte Fluxos de arquivos.

Para a versão unicode dessa função (CreateFileFromAppW), você pode aceitar remover a limitação de MAX_PATH sem acrescentar "\\?\". Consulte a seção "Limitação máxima de comprimento do caminho" de Arquivos de Nomenclatura, Caminhos e Namespaces para obter detalhes.

dwDesiredAccess

O acesso solicitado ao arquivo ou dispositivo, que pode ser resumido como leitura, gravação, ambos ou nenhum zero).

Os valores mais usados são GENERIC_READ, GENERIC_WRITE ou ambos (GENERIC_READ | GENERIC_WRITE). Para obter mais informações, consulte Direitos de Acesso Genéricos, Segurança de Arquivos e Direitos de Acesso, Constantes de Direitos de Acesso a Arquivos e ACCESS_MASK.

Se esse parâmetro for zero, o aplicativo poderá consultar determinados metadados, como atributos de arquivo, diretório ou dispositivo sem acessar esse arquivo ou dispositivo, mesmo que GENERIC_READ acesso tenha sido negado.

Não é possível solicitar um modo de acesso que entre em conflito com o modo de compartilhamento especificado pelo parâmetro dwShareMode em uma solicitação aberta que já tenha um identificador aberto.

dwShareMode

O modo de compartilhamento solicitado do arquivo ou dispositivo, que pode ser lido, gravar, ambos, excluir, todos eles ou nenhum (consulte a tabela a seguir). As solicitações de acesso a atributos ou atributos estendidos não são afetadas por esse sinalizador.

Valor	Significado
0 0x00000000	Impede que outros processos abram um arquivo ou dispositivo se solicitarem acesso de exclusão, leitura ou gravação.
FILE_SHARE_DELETE 0x00000004	Permite que as operações abertas subsequentes em um arquivo ou dispositivo solicitem o acesso de exclusão. Caso contrário, outros processos não poderão abrir o arquivo ou o dispositivo se solicitarem acesso de exclusão. Se esse sinalizador não for especificado, mas o arquivo ou dispositivo tiver sido aberto para acesso de exclusão, a função falhará. Nota Excluir acesso permite operações de exclusão e renomeação.
FILE_SHARE_READ 0x00000001	Habilita as operações abertas subsequentes em um arquivo ou dispositivo para solicitar acesso de leitura. Caso contrário, outros processos não poderão abrir o arquivo ou o dispositivo se solicitarem acesso de leitura. Se esse sinalizador não for especificado, mas o arquivo ou dispositivo tiver sido aberto para acesso de leitura, a função falhará.
FILE_SHARE_WRITE 0x00000002	Habilita operações abertas subsequentes em um arquivo ou dispositivo para solicitar acesso de gravação. Caso contrário, outros processos não poderão abrir o arquivo ou o dispositivo se solicitarem acesso de gravação. Se esse sinalizador não for especificado, mas o arquivo ou dispositivo tiver sido aberto para acesso de gravação ou tiver um mapeamento de arquivo com acesso de gravação, a função falhará.

lpSecurityAttributes

Um ponteiro para uma estrutura SECURITY_ATTRIBUTES que contém dois membros de dados separados, mas relacionados: um descritor de segurança opcional e um valor booliano que determina se o identificador retornado pode ser herdado por processos filho.

Este parâmetro pode ser NULL.

Se esse parâmetro for NULL, o identificador retornado não poderá ser herdado por nenhum processo filho que o aplicativo possa criar e o arquivo ou dispositivo associado ao identificador retornado obterá um descritor de segurança padrão.

O membro lpSecurityDescriptor da estrutura especifica um SECURITY_DESCRIPTOR para um arquivo ou dispositivo. Se esse membro for NULL, o arquivo ou dispositivo associado ao identificador retornado será atribuído a um descritor de segurança padrão.

Essa função ignora o membro lpSecurityDescriptor ao abrir um arquivo ou dispositivo existente, mas continua a usar o membro bInheritHandle .

O membro bInheritHandle da estrutura especifica se o identificador retornado pode ser herdado.

dwCreationDisposition

Uma ação a ser tomada em um arquivo ou dispositivo que existe ou não existe.

Para dispositivos que não sejam arquivos, esse parâmetro geralmente é definido como OPEN_EXISTING.

Para obter mais informações, consulte a seção Comentários.

Esse parâmetro deve ser um dos seguintes valores, que não podem ser combinados:

Valor	Significado
CREATE_ALWAYS 2	Cria um novo arquivo, sempre. Se o arquivo especificado existir e for gravável, a função truncará o arquivo, a função terá êxito e o código de último erro será definido como ERROR_ALREADY_EXISTS (183). Se o arquivo especificado não existir e for um caminho válido, um novo arquivo será criado, a função terá êxito e o código de último erro será definido como zero. Para obter mais informações, confira a seção Comentários deste tópico.
CREATE_NEW 1	Cria um novo arquivo, somente se ele ainda não existir. Se o arquivo especificado existir, a função falhará e o código de último erro será definido como ERROR_FILE_EXISTS (80). Se o arquivo especificado não existir e for um caminho válido para um local gravável, um novo arquivo será criado.
OPEN_ALWAYS 4	Abre um arquivo, sempre. Se o arquivo especificado existir, a função terá êxito e o código de último erro será definido como ERROR_ALREADY_EXISTS (183). Se o arquivo especificado não existir e for um caminho válido para um local gravável, a função criará um arquivo e o código de último erro será definido como zero.
OPEN_EXISTING 3	Abre um arquivo ou dispositivo, somente se ele existir. Se o arquivo ou dispositivo especificado não existir, a função falhará e o código de último erro será definido como ERROR_FILE_NOT_FOUND (2). Para obter mais informações sobre dispositivos, consulte a seção Comentários.
TRUNCATE_EXISTING 5	Abre um arquivo e o trunca para que seu tamanho seja zero bytes, somente se ele existir. Se o arquivo especificado não existir, a função falhará e o código de último erro será definido como ERROR_FILE_NOT_FOUND (2). O processo de chamada deve abrir o arquivo com o GENERIC_WRITE bit definido como parte do parâmetro dwDesiredAccess .

dwFlagsAndAttributes

Os atributos e sinalizadores de arquivo ou dispositivo FILE_ATTRIBUTE_NORMAL sendo o valor padrão mais comum para arquivos.

Esse parâmetro pode incluir qualquer combinação dos atributos de arquivo disponíveis (FILE_ATTRIBUTE_*). Todos os outros atributos de arquivo substituem FILE_ATTRIBUTE_NORMAL.

Esse parâmetro também pode conter combinações de sinalizadores (FILE_FLAG_*) para controlar o comportamento de cache de arquivos ou dispositivos, modos de acesso e outros sinalizadores de finalidade especial. Eles combinam com qualquer valor FILE_ATTRIBUTE_* .

Esse parâmetro também pode conter informações de SQOS (Qualidade de Serviço de Segurança) especificando o sinalizador SECURITY_SQOS_PRESENT . Informações adicionais de sinalizadores relacionados ao SQOS são apresentadas na tabela seguindo os atributos e tabelas de sinalizadores.

Atributo	Significado
FILE_ATTRIBUTE_ARCHIVE 32 (0x20)	O arquivo deve ser arquivado. Os aplicativos usam esse atributo para marcar arquivos para backup ou remoção.
FILE_ATTRIBUTE_ENCRYPTED 16384 (0x4000)	O arquivo ou diretório está criptografado. Para um arquivo, isso significa que todos os dados do arquivo são criptografados. Para um diretório, isso significa que a criptografia é o padrão para arquivos e subdiretórios recém-criados. Para obter mais informações, consulte Criptografia de Arquivo. Esse sinalizador não terá efeito se FILE_ATTRIBUTE_SYSTEM também for especificado. Esse sinalizador não tem suporte nas edições Home, Home Premium, Starter ou ARM do Windows.
FILE_ATTRIBUTE_HIDDEN 2 (0x2)	O arquivo está oculto. Não inclua em uma listagem de diretório comum.
FILE_ATTRIBUTE_NORMAL 128 (0x80)	O arquivo não tem outros atributos definidos. Este atributo é válido apenas quando usado sozinho.
FILE_ATTRIBUTE_OFFLINE 4096 (0x1000)	Os dados de um arquivo não estão disponíveis imediatamente. Esse atributo indica que os dados do arquivo são movidos fisicamente para o armazenamento offline. Esse atributo é usado pelo Armazenamento Remoto, o software de gerenciamento de armazenamento hierárquico. Os aplicativos não devem alterar esse atributo arbitrariamente.
FILE_ATTRIBUTE_READONLY 1 (0x1)	O arquivo é somente leitura. Os aplicativos podem ler o arquivo, mas não podem gravá-lo ou excluí-lo.
FILE_ATTRIBUTE_SYSTEM 4 (0x4)	O arquivo faz parte ou é usado exclusivamente por um sistema operacional.
FILE_ATTRIBUTE_TEMPORARY 256 (0x100)	O arquivo está sendo usado para armazenamento temporário. Para obter mais informações, consulte a seção Comportamento de cache deste tópico.

Sinalizador	Significado
FILE_FLAG_BACKUP_SEMANTICS 0x02000000	O arquivo está sendo aberto ou criado para uma operação de backup ou restauração. O sistema garante que o processo de chamada substitua as verificações de segurança de arquivo quando o processo tiver privilégios de SE_BACKUP_NAME e SE_RESTORE_NAME . Para obter mais informações, consulte Alterando privilégios em um token. Você deve definir esse sinalizador para obter um identificador para um diretório. Um identificador de diretório pode ser passado para algumas funções em vez de um identificador de arquivo. Para obter mais informações, consulte a seção Comentários.
FILE_FLAG_DELETE_ON_CLOSE 0x04000000	O arquivo deve ser excluído imediatamente depois que todos os seus identificadores forem fechados, o que inclui o identificador especificado e os outros identificadores abertos ou duplicados. Se houver identificadores abertos existentes em um arquivo, a chamada falhará, a menos que todos tenham sido abertos com o modo de compartilhamento FILE_SHARE_DELETE . Solicitações abertas subsequentes do arquivo falharão, a menos que o modo de compartilhamento FILE_SHARE_DELETE seja especificado.
FILE_FLAG_NO_BUFFERING 0x20000000	O arquivo ou dispositivo está sendo aberto sem cache do sistema para leituras e gravações de dados. Esse sinalizador não afeta o cache de disco rígido nem os arquivos mapeados de memória. Há requisitos estritos para trabalhar com êxito com arquivos abertos com essa função usando o sinalizador FILE_FLAG_NO_BUFFERING , para obter detalhes, consulte Buffer de arquivos.
FILE_FLAG_OPEN_NO_RECALL 0x00100000	Os dados do arquivo são solicitados, mas devem continuar localizados no armazenamento remoto. Ele não deve ser transportado de volta para o armazenamento local. Esse sinalizador é usado por sistemas de armazenamento remoto.
0x00200000 FILE_FLAG_OPEN_REPARSE_POINT	O processamento normal de ponto de nova análise não ocorrerá; essa função tentará abrir o ponto de nova análise. Quando um arquivo é aberto, um identificador de arquivo é retornado, independentemente de o filtro que controla ou não o ponto de nova análise estar operacional. Esse sinalizador não pode ser usado com o sinalizador CREATE_ALWAYS . Se o arquivo não for um ponto de nova análise, esse sinalizador será ignorado. Para obter mais informações, consulte a seção Comentários.
FILE_FLAG_OVERLAPPED 0x40000000	O arquivo ou dispositivo está sendo aberto ou criado para E/S assíncrona. Quando as operações de E/S subsequentes forem concluídas nesse identificador, o evento especificado na estrutura OVERLAPPED será definido como o estado sinalizado. Se esse sinalizador for especificado, o arquivo poderá ser usado para operações simultâneas de leitura e gravação. Se esse sinalizador não for especificado, as operações de E/S serão serializadas, mesmo que as chamadas para as funções de leitura e gravação especifiquem uma estrutura OVERLAPPED . Para obter informações sobre considerações ao usar um identificador de arquivo criado com esse sinalizador, consulte a seção Identificadores de E/S síncronos e assíncronos deste tópico.
FILE_FLAG_POSIX_SEMANTICS 0x0100000	O acesso ocorrerá de acordo com as regras POSIX. Isso inclui permitir vários arquivos com nomes, diferentes apenas no caso, para sistemas de arquivos que dão suporte a essa nomenclatura. Use cuidado ao usar essa opção, pois os arquivos criados com esse sinalizador podem não estar acessíveis por aplicativos gravados para MS-DOS ou Windows de 16 bits.
FILE_FLAG_RANDOM_ACCESS 0x10000000	O acesso destina-se a ser aleatório. O sistema pode usar isso como uma dica para otimizar o cache de arquivo. Esse sinalizador não terá efeito se o sistema de arquivos não oferecer suporte a E/S armazenada em cache e FILE_FLAG_NO_BUFFERING. Para obter mais informações, consulte a seção Comportamento de cache deste tópico.
FILE_FLAG_SESSION_AWARE 0x00800000	O arquivo ou dispositivo está sendo aberto com reconhecimento de sessão. Se esse sinalizador não for especificado, os dispositivos por sessão (como um dispositivo que usa o Redirecionamento USB RemoteFX) não poderão ser abertos por processos em execução na sessão 0. Esse sinalizador não tem efeito para os chamadores que não estão na sessão 0. Esse sinalizador tem suporte apenas em edições de servidor do Windows.
FILE_FLAG_SEQUENTIAL_SCAN 0x08000000	O acesso destina-se a ser sequencial do início ao fim. O sistema pode usar isso como uma dica para otimizar o cache de arquivo. Esse sinalizador não deve ser usado se o read-behind (ou seja, verificações inversas) for usado. Esse sinalizador não terá efeito se o sistema de arquivos não oferecer suporte a E/S armazenada em cache e FILE_FLAG_NO_BUFFERING. Para obter mais informações, consulte a seção Comportamento de cache deste tópico.
FILE_FLAG_WRITE_THROUGH 0x80000000	As operações de gravação não passarão por nenhum cache intermediário, elas irão diretamente para o disco. Para obter informações adicionais, consulte a seção Comportamento de cache deste tópico.

O parâmetro dwFlagsAndAttributestambém pode especificar informações do SQOS. Para obter mais informações, consulte Níveis de representação. Quando o aplicativo de chamada especifica o sinalizador SECURITY_SQOS_PRESENT como parte de dwFlagsAndAttributes, ele também pode conter um ou mais dos valores a seguir.

Sinalizador de segurança	Significado
SECURITY_ANONYMOUS	Representa um cliente no nível de representação anônima.
SECURITY_CONTEXT_TRACKING	O modo de acompanhamento de segurança é dinâmico. Se esse sinalizador não for especificado, o modo de controle de segurança será estático.
SECURITY_DELEGATION	Representa um cliente no nível de representação delegação.
SECURITY_EFFECTIVE_ONLY	Somente os aspectos habilitados do contexto de segurança do cliente estão disponíveis para o servidor. Se você não especificar esse sinalizador, todos os aspectos do contexto de segurança do cliente estarão disponíveis. Isso permite que o cliente limite os grupos e privilégios que um servidor pode usar ao representar o cliente.
SECURITY_IDENTIFICATION	Representa um cliente no nível de representação de identificação.
SECURITY_IMPERSONATION	Represente um cliente no nível de representação. Esse é o comportamento padrão se nenhum outro sinalizador for especificado junto com o sinalizador SECURITY_SQOS_PRESENT .

hTemplateFile

Um identificador válido para um arquivo de modelo com o direito de acesso GENERIC_READ . O arquivo de modelo fornece atributos de arquivo e atributos estendidos para o arquivo que está sendo criado.

Este parâmetro pode ser NULL.

Ao abrir um arquivo existente, esse parâmetro é ignorado.

Ao abrir um novo arquivo criptografado, o arquivo herda a lista de controle de acesso discricionário de seu diretório pai. Para obter mais informações, consulte Criptografia de Arquivo.

Retornar valor

Se a função for bem-sucedida, o valor retornado será um identificador aberto para o arquivo, dispositivo, pipe nomeado ou slot de email especificados.

Se houver falha na função, o valor retornado será INVALID_HANDLE_VALUE. Para obter informações de erro estendidas, chame GetLastError.

Requisitos


Cliente mínimo com suporte	Windows 10, versão 1803
Cabeçalho	fileapifromapp.h

Share via