Função CreateFileTransactedA (winbase.h)
[A Microsoft recomenda fortemente que os desenvolvedores utilizem meios alternativos para alcançar as necessidades do aplicativo. Muitos cenários para os quais o TxF foi desenvolvido podem ser obtidos por meio de técnicas mais simples e prontamente disponíveis. Além disso, o TxF pode não estar disponível em versões futuras do Microsoft Windows. Para obter mais informações e alternativas ao TxF, consulte Alternativas para usar o NTFS transacional.]
Cria ou abre um arquivo, fluxo de arquivos ou diretório como uma operação transacionada. A função retorna um identificador que pode ser usado para acessar o objeto.
Para executar essa operação como uma operação não transacionada ou para acessar objetos diferentes de arquivos (por exemplo, pipes nomeados, dispositivos físicos, emailslots), use a função CreateFile.
Para obter mais informações sobre transações, consulte a seção Comentários deste tópico.
Sintaxe
HANDLE CreateFileTransactedA(
[in] LPCSTR lpFileName,
[in] DWORD dwDesiredAccess,
[in] DWORD dwShareMode,
[in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes,
[in] DWORD dwCreationDisposition,
[in] DWORD dwFlagsAndAttributes,
[in, optional] HANDLE hTemplateFile,
[in] HANDLE hTransaction,
[in, optional] PUSHORT pusMiniVersion,
PVOID lpExtendedParameter
);
Parâmetros
[in] lpFileName
O nome de um objeto a ser criado ou aberto.
O objeto deve residir no computador local; caso contrário, a função falhará e o último código de erro será definido como ERROR_TRANSACTIONS_UNSUPPORTED_REMOTE.
Por padrão, o nome é limitado a MAX_PATH caracteres. Para estender esse limite para 32.767 caracteres de largura, acrescente "\\?\" ao caminho. Para obter mais informações, consulte Arquivos de Nomenclatura, Caminhos e Namespaces.
Ponta
A partir do Windows 10, versão 1607, 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.
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.
[in] dwDesiredAccess
O acesso ao objeto, 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 de direitos de acesso genéricos e de direitos de acesso e segurança de arquivos.
Se esse parâmetro for zero, o aplicativo poderá consultar atributos de arquivo, diretório ou dispositivo sem acessar esse arquivo ou dispositivo. Para obter mais informações, consulte a seção Comentários deste tópico.
Não é possível solicitar um modo de acesso que entre em conflito com o modo de compartilhamento especificado em uma solicitação aberta que tenha um identificador aberto. Para obter mais informações, consulte Criando e abrindo arquivos.
[in] dwShareMode
O modo de compartilhamento de um objeto, que pode ser lido, gravar, ambos, excluir, todos eles ou nenhum (consulte a tabela a seguir).
Se esse parâmetro for zero e CreateFileTransacted for bem-sucedido, o objeto não poderá ser compartilhado e não poderá ser aberto novamente até que o identificador seja fechado. Para obter mais informações, consulte a seção Comentários deste tópico.
Não é possível solicitar um modo de compartilhamento que entre em conflito com o modo de acesso especificado em uma solicitação aberta que tenha um identificador aberto, pois isso resultaria na seguinte violação de compartilhamento: ERROR_SHARING_VIOLATION. Para obter mais informações, consulte Criando e abrindo arquivos.
Para habilitar um processo para compartilhar um objeto enquanto outro processo tiver o objeto aberto, use uma combinação de um ou mais dos valores a seguir para especificar o modo de acesso que eles podem solicitar para abrir o objeto.
[in, optional] lpSecurityAttributes
Um ponteiro para uma estrutura de SECURITY_ATTRIBUTES que contém um descritor de segurança opcional e também determina se o identificador retornado pode ou não ser herdado por processos filho. O parâmetro pode ser NULL.
Se o parâmetro lpSecurityAttributes for NULL, o identificador retornado por CreateFileTransacted não poderá ser herdado por nenhum processo filho que seu aplicativo possa criar e o objeto associado ao identificador retornado obterá um descritor de segurança padrão.
O bInheritHandle membro da estrutura especifica se o identificador retornado pode ser herdado.
O lpSecurityDescriptor membro da estrutura especifica um de descritor de segurança para um objeto, mas também pode ser NULL.
Se membro lpSecurityDescriptor for NULL, o objeto associado ao identificador retornado recebe um descritor de segurança padrão.
Para obter mais informações, consulte a seção Comentários deste tópico.
[in] dwCreationDisposition
Uma ação para executar arquivos que existem e não existem.
Para obter mais informações, consulte a seção Comentários deste tópico.
Esse parâmetro deve ser um dos seguintes valores, que não podem ser combinados.
[in] dwFlagsAndAttributes
Os atributos e sinalizadores de arquivo FILE_ATTRIBUTE_NORMAL sendo o valor padrão mais comum.
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 de comportamento de buffer, modos de acesso e outros sinalizadores de finalidade especial. Elas combinam-se com quaisquer valores 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 as tabelas de atributos e sinalizadores.
Quando CreateFileTransacted 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.
| 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 Directory Handles. |
|
O arquivo deve ser excluído imediatamente após o último identificador de gravador transacionado para o arquivo ser fechado, desde que a transação ainda esteja ativa. Se um arquivo tiver sido marcado para exclusão e um identificador de gravador transacionado ainda estiver aberto após a conclusão da transação, o arquivo não será excluído.
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. |
|
O arquivo está sendo aberto sem cache do sistema. Esse sinalizador não afeta o cache de disco rígido ou os arquivos mapeados de memória. Quando combinado com FILE_FLAG_OVERLAPPED, o sinalizador fornece 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. Para liberar os metadados para o disco, use a função Um aplicativo deve atender a determinados requisitos ao trabalhar com arquivos abertos com FILE_FLAG_NO_BUFFERING:
Um aplicativo pode determinar um tamanho do setor de volume chamando a função GetDiskFreeSpace. |
|
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á; CreateFileTransacted 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. |
|
O arquivo está sendo aberto ou criado para E/S assíncrona. Quando a operação é concluída, 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. O sistema não mantém o ponteiro de arquivo, portanto, você deve passar a posição do arquivo para as funções de leitura e gravação na estrutura OVERLAPPED ou atualizar o ponteiro de arquivo. 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. |
|
O arquivo deve ser acessado 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 arquivo deve ser acessado aleatoriamente. O sistema pode usar isso como uma dica para otimizar o cache de arquivos. |
|
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 arquivo deve ser acessado sequencialmente do início ao fim. O sistema pode usar isso como uma dica para otimizar o cache de arquivos. Se um aplicativo mover o ponteiro de arquivo para acesso aleatório, o cache ideal poderá não ocorrer. No entanto, a operação correta ainda está garantida.
Especificar esse sinalizador 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 ignoram pequenos intervalos de bytes. 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. |
|
As operações de gravação não passarão por nenhum cache intermediário, elas irão diretamente para o disco.
Se 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 atraso. Se FILE_FLAG_NO_BUFFERING também for especificado, 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. O sistema operacional também solicita uma gravação por meio do cache de disco rígido para mídia persistente. No entanto, nem todo hardware dá suporte a essa funcionalidade de gravação. |
O parâmetro dwFlagsAndAttributes também pode especificar informações de Qualidade de Serviço de Segurança. 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.
[in, optional] 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, CreateFileTransacted ignora o arquivo de modelo.
Ao abrir um novo arquivo criptografado por EFS, o arquivo herda a DACL de seu diretório pai.
[in] hTransaction
Um identificador para a transação. Esse identificador é retornado pela função
[in, optional] pusMiniVersion
A miniversão a ser aberta. Se a transação especificada em hTransaction não for a transação que está modificando o arquivo, esse parâmetro deverá ser NULL. Caso contrário, esse parâmetro pode ser um identificador de miniversão retornado pelo código de controle FSCTL_TXFS_CREATE_MINIVERSION ou um dos valores a seguir.
lpExtendedParameter
Esse parâmetro é reservado e deve ser NULL.
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.
Observações
Ao usar o identificador retornado por CreateFileTransacted, use a versão transacionada das funções de E/S do arquivo em vez das funções de E/S de arquivo padrão, quando apropriado. Para obter mais informações, consulte considerações de programação paraNTFS transacionais.
Ao abrir um identificador transacionado em um diretório, esse identificador deve ter permissões FILE_WRITE_DATA (FILE_ADD_FILE) e FILE_APPEND_DATA (FILE_ADD_SUBDIRECTORY). Elas são incluídas em permissões de FILE_GENERIC_WRITE. Você deve abrir diretórios com menos permissões se estiver usando apenas o identificador para criar arquivos ou subdiretórios; caso contrário, podem ocorrer violações de compartilhamento.
Não é possível abrir um arquivo com FILE_EXECUTE nível de acesso quando esse arquivo faz parte de outra transação (ou seja, outro aplicativo o abriu chamando CreateFileTransacted). Isso significa que CreateFileTransacted falhar se o nível de acesso FILE_EXECUTE ou FILE_ALL_ACCESS for especificado
Quando um aplicativo não transacionado chama CreateFileTransacted com MAXIMUM_ALLOWED especificado para lpSecurityAttributes, um identificador é aberto com o mesmo nível de acesso todas as vezes. Quando um aplicativo transacionado chama CreateFileTransacted com MAXIMUM_ALLOWED especificado para lpSecurityAttributes, um identificador é aberto com uma quantidade diferente de acesso com base em se o arquivo está bloqueado por uma transação. Por exemplo, se o aplicativo de chamada tiver FILE_EXECUTE nível de acesso para um arquivo, o aplicativo só obterá esse acesso se o arquivo que está sendo aberto não estiver bloqueado por uma transação ou estiver bloqueado por uma transação e o aplicativo já for um leitor transacionado para esse arquivo.
Consulte NTFS transacional para obter uma descrição completa das operações transacionadas.
Use a função CloseHandle para fechar um identificador de objeto retornado por CreateFileTransacted quando o identificador não for mais necessário e antes de confirmar ou reverter a transação.
Alguns sistemas de arquivos, como o sistema de arquivos NTFS, dão suporte à compactação ou criptografia para arquivos e diretórios individuais. Em volumes formatados para esse tipo de sistema de arquivos, um novo arquivo herda os atributos de compactação e criptografia de seu diretório.
Você não pode usar CreateFileTransacted para controlar a compactação em um arquivo ou diretório. Para obter mais informações, consulte de compactação e descompactação de arquivos e de Criptografia de Arquivo.
Comportamento simbólico de vínculo — se a chamada para essa função criar um novo arquivo, não haverá nenhuma alteração no comportamento.
Se FILE_FLAG_OPEN_REPARSE_POINT for especificado:
- Se um arquivo existente for aberto e for um link simbólico, o identificador retornado será um identificador para o link simbólico.
- Se TRUNCATE_EXISTING ou FILE_FLAG_DELETE_ON_CLOSE forem especificados, o arquivo afetado será um link simbólico.
- Se um arquivo existente for aberto e for um link simbólico, o identificador retornado será um identificador para o destino.
- Se CREATE_ALWAYS, TRUNCATE_EXISTINGou FILE_FLAG_DELETE_ON_CLOSE forem especificados, o arquivo afetado será o destino.
Conforme indicado anteriormente, se o parâmetro lpSecurityAttributes for NULL, o identificador retornado por CreateFileTransacted não poderá ser herdado por nenhum processo filho que seu aplicativo possa criar. As seguintes informações sobre esse parâmetro também se aplicam:
- Se bInheritHandle não for FALSE, que é qualquer valor diferente de zero, o identificador poderá ser herdado. Portanto, é fundamental que esse membro da estrutura seja inicializado corretamente para FALSE se você não pretende que o identificador seja herdável.
- As ACL (listas de controle de acesso) no descritor de segurança padrão para um arquivo ou diretório são herdadas de seu diretório pai.
- O sistema de arquivos de destino deve dar suporte à segurança em arquivos e diretórios para que o lpSecurityDescriptor tenha um efeito sobre eles, o que pode ser determinado usando GetVolumeInformation
| Tecnologia | Suportado |
|---|---|
| Protocolo SMB (Bloco de Mensagens do Servidor) 3.0 | Não |
| TFO (Failover Transparente) do SMB 3.0 | Não |
| SMB 3.0 com Compartilhamentos de Arquivos de Expansão (SO) | Não |
| Sistema de Arquivos de Volume Compartilhado de Cluster (CsvFS) | Não |
| ReFS (Sistema de Arquivos Resiliente) | Não |
Observe que o SMB 3.0 não dá suporte ao TxF.
Arquivos
Se você tentar criar um arquivo em uma unidade disquete que não tenha um disquete ou uma unidade de CD-ROM que não tenha um CD, o sistema exibirá uma mensagem para o usuário inserir um disco ou um CD. Para impedir que o sistema exiba essa mensagem, chame a função SetErrorMode com SEM_FAILCRITICALERRORS.Para obter mais informações, consulte Criando e abrindo arquivos.
Se você renomear ou excluir um arquivo e restaurá-lo pouco depois, o sistema pesquisará no cache informações de arquivo para restaurar. As informações armazenadas em cache incluem seu par de nomes curto/longo e tempo de criação.
Se você chamar CreateFileTransacted em um arquivo que está pendente de exclusão como resultado de uma chamada anterior para DeleteFile, a função falhará. O sistema operacional atrasa a exclusão de arquivos até que todos os identificadores do arquivo sejam fechados. GetLastError retorna ERROR_ACCESS_DENIED.
O parâmetro dwDesiredAccess pode ser zero, permitindo que o aplicativo consulte atributos de arquivo sem acessar o arquivo se o aplicativo estiver em execução com configurações de segurança adequadas. Isso é útil para testar a existência de um arquivo sem abri-lo para acesso de leitura e/ou gravação ou para obter outras estatísticas sobre o arquivo ou diretório. Consulte Obter e definir informações de arquivo e getFileInformationByHandle.
Quando um aplicativo cria um arquivo em uma rede, é melhor usar GENERIC_READ | GENERIC_WRITE do que usar GENERIC_WRITE sozinho. O código resultante é mais rápido, pois o redirecionador pode usar o gerenciador de cache e enviar menos SMBs com mais dados. Essa combinação também evita um problema em que gravar em um arquivo em uma rede pode ocasionalmente retornar ERROR_ACCESS_DENIED.
fluxos de arquivos
Em sistemas de arquivos NTFS, você pode usar CreateFileTransacted para criar fluxos separados em um arquivo.Para obter mais informações, consulte de Fluxos de Arquivos.
Diretórios de
Um aplicativo não pode criar um diretório usando CreateFileTransacted, portanto, somente o valor OPEN_EXISTING é válido para dwCreationDisposition para esse caso de uso. Para criar um diretório, o aplicativo deve chamar CreateDirectoryTransacted, CreateDirectory ou CreateDirectoryEx.Para abrir um diretório usando CreateFileTransacted, especifique o sinalizador FILE_FLAG_BACKUP_SEMANTICS como parte de dwFlagsAndAttributes. As verificações de segurança apropriadas ainda se aplicam quando esse sinalizador é usado sem privilégios de SE_BACKUP_NAME e SE_RESTORE_NAME.
Ao usar CreateFileTransacted para abrir um diretório durante a desfragmentação de um volume de sistema de arquivos FAT ou FAT32, não especifique o direito de acesso MAXIMUM_ALLOWED. O acesso ao diretório será negado se isso for feito. Em vez disso, especifique o acesso GENERIC_READ direito.
Para obter mais informações, consulte About Directory Management.
Nota
O cabeçalho winbase.h define CreateFileTransacted como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows Vista [somente aplicativos da área de trabalho] |
| servidor com suporte mínimo | Windows Server 2008 [somente aplicativos da área de trabalho] |
| da Plataforma de Destino |
Windows |
| cabeçalho | winbase.h (inclua Windows.h) |
| biblioteca | Kernel32.lib |
| de DLL |
Kernel32.dll |
Consulte também
de compactação e descompactação de arquivos
Funções de gerenciamento de arquivos
de Direitos de Acesso e Segurança de Arquivos
de Fluxos de Arquivos
Funções
Tópicos de visão geral
considerações de programação para transacionais do NTFS