Função CreateFile2FromAppW (fileapifromapp.h)

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

Sintaxe

WINSTORAGEAPI HANDLE CreateFile2FromAppW(
  LPCWSTR                           lpFileName,
  DWORD                             dwDesiredAccess,
  DWORD                             dwShareMode,
  DWORD                             dwCreationDisposition,
  LPCREATEFILE2_EXTENDED_PARAMETERS pCreateExParams
) noexcept;

Parâmetros

lpFileName

O nome do arquivo ou dispositivo a ser criado ou aberto.

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 obter informações sobre como recusar 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_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, gravado, 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.

Se esse parâmetro for zero e a função for bem-sucedida, o arquivo ou dispositivo não poderá ser compartilhado e não poderá ser aberto novamente até que o identificador para o arquivo ou dispositivo seja fechado. Para obter mais informações, consulte a seção Comentários.

Não é possível solicitar um modo de compartilhamento que entre em conflito com o modo de acesso especificado em uma solicitação existente que tenha um identificador aberto. Essa função falharia e a função GetLastError retornaria ERROR_SHARING_VIOLATION.

Para habilitar um processo para compartilhar um arquivo ou dispositivo enquanto outro processo tiver o arquivo ou dispositivo aberto, use uma combinação compatível de um ou mais dos valores a seguir. Para obter mais informações sobre combinações válidas desse parâmetro com o parâmetro dwDesiredAccess , consulte Criando e abrindo arquivos.

Nota As opções de compartilhamento para cada identificador aberto permanecem em vigor até que esse identificador seja fechado, independentemente do contexto do processo.

 

Valor	Significado
0 0x00000000	Impede que outros processos abram um arquivo ou dispositivo se solicitarem acesso de exclusão, leitura ou gravação. O acesso exclusivo a um arquivo ou diretório só será concedido se o aplicativo tiver acesso de gravação ao arquivo.
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 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 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á. Se um arquivo ou diretório estiver sendo aberto e esse sinalizador não for especificado e o chamador não tiver acesso de gravação ao arquivo ou diretório, 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á.

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.

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.
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 do ú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 do ú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 do último erro será definido como ERROR_FILE_NOT_FOUND (2).
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 do ú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 .

pCreateExParams

Ponteiro para uma estrutura de CREATEFILE2_EXTENDED_PARAMETERS opcional.

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 especificado.

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

Requisitos

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