Função CreateFileFromAppW (fileapifromapp.h)
Cria ou abre um arquivo ou dispositivo de E/S. O comportamento dessa função é idêntico a CreateFile, exceto pelo fato de essa função aderir ao modelo de segurança de aplicativo da 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 de largura, chame a versão Unicode da função e prenda "\\?\" para o caminho. Para obter mais informações, consulte Arquivos de Nomenclatura, Caminhos e Namespaces.
Para obter informações sobre nomes de dispositivos especiais, consulte Definindo umde nome de dispositivo MS-DOS.
Para criar um fluxo de arquivos, especifique o nome do arquivo, um dois-pontos e, em seguida, o nome do fluxo. Para obter mais informações, consulte de Fluxos de Arquivos.
Para a versão unicode dessa função (CreateFileFromAppW), você pode optar por remover a limitação de MAX_PATH sem acrescentar "\\?\". Consulte a seção "Limitação máxima do 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_WRITEou ambos (GENERIC_READ | GENERIC_WRITE). Para obter mais informações, consulte genéricos de direitos de acesso, de direitos de acesso e segurança de arquivos, 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 se GENERIC_READ acesso tivesse 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
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 | Habilita operações abertas subsequentes em um arquivo ou dispositivo para solicitar acesso de exclusão. Caso contrário, outros processos não poderão abrir o arquivo ou o dispositivo se solicitarem o acesso de exclusão. Se esse sinalizador não for especificado, mas o arquivo ou dispositivo tiver sido aberto para exclusão de acesso, a função falhará. Observação Excluir acesso permite operações de exclusão e renomeação. |
| FILE_SHARE_READ 0x00000001 | Permite que as operações abertas subsequentes em um arquivo ou dispositivo solicitem 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 de 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.
Esse 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 lpSecurityDescriptor membro da estrutura especifica um SECURITY_DESCRIPTOR para um arquivo ou dispositivo. Se esse membro estiver NULL, o arquivo ou dispositivo associado ao identificador retornado recebe 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 bInheritHandle membro 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 será bem-sucedida e o código de último erro será definido como zero. Para obter mais informações, consulte 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 trunca-o 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 do último erro será definido como ERROR_FILE_NOT_FOUND (2). O processo de chamada deve abrir o arquivo com o |
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 controle do comportamento de cache de arquivo ou dispositivo, modos de acesso e outros sinalizadores de finalidade especial. Elas combinam-se com quaisquer valores de
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 as tabelas de atributos e sinalizadores.
| Bandeira | 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 quaisquer outras alças abertas ou duplicadas. Se houver identificadores abertos existentes em um arquivo, a chamada falhará, a menos que todas elas tenham sido abertas com o modo de compartilhamento FILE_SHARE_DELETE. As solicitações abertas subsequentes para o arquivo falham, 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 ou 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 de 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. |
| FILE_FLAG_OPEN_REPARSE_POINT 0x00200000 | O ponto de nova análise normal processamento 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 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 de 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íncrono e assíncrono 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 que são gravados para o Windows de MS-DOS ou 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 arquivos. Esse sinalizador não terá efeito se o sistema de arquivos não der 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 arquivos. Esse sinalizador não deverá ser usado se o read-behind (ou seja, verificações inversa) for usado. Esse sinalizador não terá efeito se o sistema de arquivos não der 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
| 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 de 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 GENERIC_READ direito de acesso. O arquivo de modelo fornece atributos de arquivo e atributos estendidos para o arquivo que está sendo criado.
Esse 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 de Criptografia de Arquivo.
Valor de retorno
Se a função for bem-sucedida, o valor retornado será um identificador aberto para o arquivo, dispositivo, pipe nomeado ou slot de email especificado.
Se a função falhar, o valor retornado será INVALID_HANDLE_VALUE. Para obter informações de erro estendidas, chame GetLastError.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows 10, versão 1803 |
| cabeçalho | fileapifromapp.h |