estrutura CREATEFILE2_EXTENDED_PARAMETERS (fileapi.h)
Contém parâmetros estendidos opcionais para CreateFile2.
Sintaxe
typedef struct _CREATEFILE2_EXTENDED_PARAMETERS {
DWORD dwSize;
DWORD dwFileAttributes;
DWORD dwFileFlags;
DWORD dwSecurityQosFlags;
LPSECURITY_ATTRIBUTES lpSecurityAttributes;
HANDLE hTemplateFile;
} CREATEFILE2_EXTENDED_PARAMETERS, *PCREATEFILE2_EXTENDED_PARAMETERS, *LPCREATEFILE2_EXTENDED_PARAMETERS;
Membros
dwSize
Contém o tamanho dessa estrutura, sizeof(CREATEFILE2_EXTENDED_PARAMETERS).
dwFileAttributes
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.
Nota
Quando CreateFile2 abre um arquivo existente, ele geralmente combina os sinalizadores de arquivo com os atributos de arquivo do arquivo existente e ignora todos os atributos de arquivo fornecidos como parte de dwFlagsAndAttributes. Os casos especiais são detalhados em criando e abrindo arquivos.
Alguns dos atributos e sinalizadores de arquivo a seguir só podem se aplicar a arquivos e não necessariamente a todos os outros tipos de dispositivos que CreateFile2 podem abrir. Para obter informações adicionais, consulte a seção comentários da página de referência CreateFile2 e Criando e abrindo arquivos.
Para obter acesso mais avançado a atributos de arquivo, consulte SetFileAttributes. Para obter uma lista completa de todos os atributos de arquivo com seus valores e descrições, consulte Constantes de Atributo de Arquivo.
dwFileFlags
Esse parâmetro 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.
| Bandeira | Significado |
|---|---|
|
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. |
|
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. |
|
Um mapa de dispositivo é um mapeamento entre os nomes de dispositivos DOS e dispositivos no sistema e é usado ao resolver nomes dos DOS. Existem mapas de dispositivo separados para cada usuário no sistema e os usuários podem gerenciar seus próprios mapas de dispositivo. Normalmente, durante a representação, o mapa do dispositivo do usuário representado seria usado. No entanto, quando esse sinalizador é definido, o mapa do dispositivo do usuário do processo é usado em vez disso. |
|
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 CreateFile2 usando o sinalizador FILE_FLAG_NO_BUFFERING, para obter detalhes, consulte de Buffer de Arquivos. |
|
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. |
|
O ponto de nova análise normal processamento não ocorrerá; CreateFile2 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. |
|
O arquivo está sendo aberto e um bloqueio oportunista (oplock) no arquivo está sendo solicitado como uma única operação atômica. O sistema de arquivos verifica se há oplocks antes de executar a operação de criação e falhará na criação com um último código de erro de ERROR_CANNOT_BREAK_OPLOCK se o resultado for interromper um oplock existente.
Se você usar esse sinalizador e sua chamada para a função CreateFile2 retornar com êxito, você deverá solicitar um oplock no arquivo chamando deviceiocontrol no novo identificador de arquivo com FSCTL_REQUEST_OPLOCK ou um dos outros Operações de Bloqueio Oportunista. Se você executar outras operações do sistema de arquivos no arquivo antes de solicitar um oplock, poderá ocorrer um deadlock. Um deadlock é especialmente provável se você chamar uma API do sistema de arquivos que usa o nome do arquivo em vez de um identificador, como GetFileAttributes. Observação: Você pode chamar com segurança a função CloseHandle no identificador de arquivo sem primeiro solicitar um oplock. |
|
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 seção deste tópico. |
|
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. |
|
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. |
|
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.
Windows Server 2008 R2 e Windows Server 2008: Esse sinalizador não tem suporte antes do Windows Server 2012. |
|
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 com versões anteriores) 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. |
|
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. |
dwSecurityQosFlags
O parâmetro dwSecurityQosFlags especifica informações do SQOS. Para obter mais informações, consulte níveis de representação.
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.
Esse parâmetro pode ser NULL.
Se esse parâmetro for NULL, o identificador retornado por CreateFile2 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.
createFile2 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.
Para obter mais informações, consulte a seção Comentários do tópico CreateFile2.
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, CreateFile2 ignora esse parâmetro.
Ao abrir um novo arquivo criptografado, o arquivo herda a lista de controle de acesso discricionário de seu diretório pai. Para obter informações adicionais, consulte de Criptografia de Arquivo.
Observações
Para compilar um aplicativo que usa a estrutura CREATEFILE2_EXTENDED_PARAMETERS, defina a macro _WIN32_WINNT como 0x0602 ou posterior. Para obter mais informações, consulte Usando os cabeçalhos do Windows.
Comportamento de cache
Vários dos valores possíveis para o membro dwFileFlags são usados para controlar ou afetar como os dados associados ao identificador são armazenados em cache pelo sistema. Eles são:
- FILE_FLAG_NO_BUFFERING
- FILE_FLAG_RANDOM_ACCESS
- FILE_FLAG_SEQUENTIAL_SCAN
- FILE_FLAG_WRITE_THROUGH
- FILE_ATTRIBUTE_TEMPORARY
Se nenhum desses sinalizadores for especificado, o sistema usará um esquema de cache de uso geral padrão. Caso contrário, o cache do sistema se comportará conforme especificado para cada sinalizador.
Alguns desses sinalizadores não devem ser combinados. Por exemplo, combinar FILE_FLAG_RANDOM_ACCESS com FILE_FLAG_SEQUENTIAL_SCAN é autodestrutivo.
Especificar o sinalizador FILE_FLAG_SEQUENTIAL_SCAN pode aumentar o desempenho de aplicativos que leem arquivos grandes usando acesso sequencial. Os ganhos de desempenho podem ser ainda mais perceptíveis para aplicativos que leem arquivos grandes principalmente sequencialmente, mas ocasionalmente pulam para frente em pequenos intervalos de bytes. Se um aplicativo mover o ponteiro de arquivo para acesso aleatório, o melhor desempenho de cache provavelmente não ocorrerá. No entanto, a operação correta ainda está garantida.
Os sinalizadores FILE_FLAG_WRITE_THROUGH e FILE_FLAG_NO_BUFFERING são independentes e podem ser combinados.
Se FILE_FLAG_WRITE_THROUGH for usado, mas FILE_FLAG_NO_BUFFERING também não for especificado, para que o cache do sistema esteja em vigor, os dados serão gravados no cache do sistema, mas liberados para o disco sem atraso.
Se FILE_FLAG_WRITE_THROUGH e FILE_FLAG_NO_BUFFERING forem especificados, para que o cache do sistema não esteja em vigor, os dados serão imediatamente liberados para o disco sem passar pelo cache do sistema Windows. O sistema operacional também solicita uma gravação do cache de hardware local do disco rígido para mídia persistente.
Nota
Nem todo o hardware de disco rígido dá suporte a essa funcionalidade de gravação.
O uso adequado do sinalizador de FILE_FLAG_NO_BUFFERING requer considerações especiais sobre o aplicativo. Para obter mais informações, consulte de Buffer de Arquivos.
Uma solicitação de gravação por meio de FILE_FLAG_WRITE_THROUGH também faz com que o NTFS libere quaisquer alterações de metadados, como uma atualização de carimbo de data/hora ou uma operação de renomeação, resultante do processamento da solicitação. Por esse motivo, o sinalizador FILE_FLAG_WRITE_THROUGH geralmente é usado com o sinalizador FILE_FLAG_NO_BUFFERING como uma substituição para chamar a função FlushFileBuffers após cada gravação, o que pode causar penalidades de desempenho desnecessárias. Usar esses sinalizadores juntos evita essas penalidades. Para obter informações gerais sobre o cache de arquivos e metadados, consulte Cache de Arquivos.
Quando FILE_FLAG_NO_BUFFERING é combinado com FILE_FLAG_OVERLAPPED, os sinalizadores dão o máximo de desempenho assíncrono, pois a E/S não depende das operações síncronas do gerenciador de memória. No entanto, algumas operações de E/S levam mais tempo, pois os dados não estão sendo mantidos no cache. Além disso, os metadados de arquivo ainda podem ser armazenados em cache (por exemplo, ao criar um arquivo vazio). Para garantir que os metadados sejam liberados para o disco, use a função FlushFileBuffers.
Especificar o atributo FILE_ATTRIBUTE_TEMPORARY faz com que os sistemas de arquivos evitem gravar dados de volta no armazenamento em massa se houver memória de cache suficiente disponível, pois um aplicativo exclui um arquivo temporário depois que um identificador é fechado. Nesse caso, o sistema pode evitar totalmente a gravação dos dados. Embora não controle diretamente o cache de dados da mesma forma que os sinalizadores mencionados anteriormente, o atributo FILE_ATTRIBUTE_TEMPORARY diz ao sistema para manter o máximo possível no cache do sistema sem gravar e, portanto, pode ser preocupante para determinados aplicativos.
Identificadores de E/S síncronos e assíncronos
CreateFile2 fornece a criação de um identificador de arquivo ou dispositivo que seja síncrono ou assíncrono. Um identificador síncrono se comporta de modo que as chamadas de função de E/S usando esse identificador sejam bloqueadas até que sejam concluídas, enquanto um identificador de arquivo assíncrono possibilita que o sistema retorne imediatamente das chamadas de função de E/S, independentemente de terem concluído a operação de E/S ou não. Conforme indicado anteriormente, esse comportamento síncrono versus assíncrono é determinado especificando FILE_FLAG_OVERLAPPED no membro dwFileFlags da estrutura CREATEFILE2_EXTENDED_PARAMETERS passada no parâmetro pCreateExParams. Há várias complexidades e possíveis armadilhas ao usar E/S assíncrona; para obter mais informações, consulte de E/S síncrono e assíncrono.
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] |
| cabeçalho | fileapi.h (inclua Windows.h) |