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.
Observação
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. 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 pode abrir. Para obter informações adicionais, consulte a seção Comentários da CreateFile2 página de referência 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.
| Atributo | Significado |
|---|---|
|
O arquivo deve ser arquivado. Os aplicativos usam esse atributo para marcar arquivos para backup ou remoção. |
|
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. Não há suporte para esse sinalizador nas edições Home, Home Premium, Starter ou ARM do Windows. Não há suporte para esse sinalizador quando chamado de um aplicativo da Windows Store. |
|
O arquivo está oculto. Não inclua-o em uma listagem de diretório comum. |
|
Um arquivo ou diretório configurado com integridade. Para um arquivo, todos os fluxos de dados no arquivo têm integridade. Para um diretório, integridade é o padrão para arquivos e subdiretórios recém-criados, a menos que o chamador especifique o contrário.
Esse sinalizador só tem suporte no sistema de arquivos ReFS. |
|
O arquivo não tem outros atributos definidos. Este atributo é válido apenas quando usado sozinho. |
|
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. |
|
O arquivo é somente leitura. Os aplicativos podem ler o arquivo, mas não podem gravá-lo ou excluí-lo. |
|
O arquivo faz parte ou é usado exclusivamente por um sistema operacional. |
|
O arquivo está sendo usado para armazenamento temporário.
Para obter mais informações, consulte a seção Comportamento do cache deste tópico. |
dwFileFlags
Esse parâmetro pode conter combinações de sinalizadores (FILE_FLAG_*) para controle do comportamento de cache de arquivos ou dispositivos, modos de acesso e outros sinalizadores de finalidade especial.
| Sinalizador | 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 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. |
|
Um mapa de dispositivo é um mapeamento entre os nomes de dispositivos dos DOS e os 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. |
|
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 rígidos para trabalhar com êxito com arquivos abertos com CreateFile2 usando o sinalizador FILE_FLAG_NO_BUFFERING , para obter detalhes, consulte 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 processamento normal de ponto de nova análise 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 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. |
|
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, a primeira operação que você deve executar no identificador de arquivo será solicitar um oplock chamando a função DeviceIOControl e, em seguida, passar FSCTL_REQUEST_OPLOCK ou uma das outras Operações de Bloqueio Oportunistas. Se você executar outras operações do sistema de arquivos com o identificador de arquivo antes de solicitar um oplock, poderá ocorrer um deadlock. Nota 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 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 gravados para MS-DOS ou Windows de 16 bits. |
|
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. |
|
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: Não há suporte para esse sinalizador 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 arquivo.
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 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. |
|
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.
Este 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 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.
CreateFile2 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.
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 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, 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 Criptografia de Arquivo.
Comentários
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 intervalos pequenos de bytes. Se um aplicativo mover o ponteiro do arquivo para acesso aleatório, o melhor desempenho de cache provavelmente não ocorrerá. No entanto, a operação correta ainda é 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 serão liberados para o disco sem demora.
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.
Observação
Nem todo 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 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 fornecem desempenho máximo 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 ele 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 que usam esse identificador sejam bloqueadas até que sejam concluídas, enquanto um identificador de arquivo assíncrono possibilita que o sistema retorne imediatamente de 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 dentro do 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 E/S síncrona e assíncrona.
Requisitos
| Cliente mínimo com suporte | Windows 8 [aplicativos da área de trabalho | Aplicativos UWP] |
| Servidor mínimo com suporte | Windows Server 2012 [aplicativos da área de trabalho | Aplicativos UWP] |
| Cabeçalho | fileapi.h (inclua Windows.h) |