Função CreateFileTransactedA (winbase.h)
[A Microsoft recomenda fortemente que os desenvolvedores utilizem meios alternativos para atender às 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, confira Alternativas ao uso do 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 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 caracteres MAX_PATH. Para estender esse limite para 32.767 caracteres largos, preencha "\\?\" para o caminho. Para obter mais informações, confira Nomear arquivos, caminhos e namespaces.
Dica
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 de comprimento do caminho" de Arquivos de Nomenclatura, Caminhos e Namespaces para obter detalhes.
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.
[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_WRITE ou ambos (GENERIC_READ | GENERIC_WRITE). Para obter mais informações, consulte Direitos de Acesso Genéricos e Segurança de Arquivos e Direitos de Acesso.
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, confira 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 Como criar e abrir 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, confira 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 Como criar e abrir 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 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 membro bInheritHandle da estrutura especifica se o identificador retornado pode ser herdado.
O membro lpSecurityDescriptor da estrutura especifica um descritor de segurança para um objeto, mas também pode ser NULL.
Se o membro lpSecurityDescriptor for NULL, o objeto associado ao identificador retornado será atribuído a um descritor de segurança padrão.
CreateFileTransacted ignora o membro lpSecurityDescriptor ao abrir um arquivo existente, mas continua a usar o membro bInheritHandle .
Para obter mais informações, confira a seção Comentários deste tópico.
[in] dwCreationDisposition
Uma ação a ser tomada em arquivos que existem e não existem.
Para obter mais informações, confira a seção Comentários deste tópico.
Esse parâmetro deve ser um dos valores a seguir, 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 controlar o comportamento de buffer, modos de acesso e outros sinalizadores de finalidade especial. Eles combinam 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 os atributos e tabelas de 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. Casos especiais são detalhados em Criando e abrindo arquivos.
| 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. |
|
O arquivo está oculto. Não inclua em uma listagem de diretório comum. |
|
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. Os sistemas de arquivos evitam 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. Caso contrário, os dados serão gravados depois que o identificador for fechado. |
| 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 Identificadores de diretório. |
|
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 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. |
|
O arquivo está sendo aberto sem cache do sistema. Esse sinalizador não afeta o cache de disco rígido nem 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 do arquivo ainda podem ser armazenados em cache. Para liberar os metadados para o disco, use a função FlushFileBuffers.
Um aplicativo deve atender a determinados requisitos ao trabalhar com arquivos abertos com FILE_FLAG_NO_BUFFERING:
Um aplicativo pode determinar um tamanho de 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 processamento normal de ponto de nova análise 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 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. |
|
O arquivo está sendo aberto ou criado para E/S assíncrona. Quando a operação for concluída, o evento especificado na estrutura OVERLAPPED será definido como o estado sinalizado. Operações que levam um tempo significativo para processar ERROR_IO_PENDING de retorno.
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 do 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 gravados para MS-DOS ou Windows de 16 bits. |
|
O arquivo deve ser acessado aleatoriamente. O sistema pode usar isso como uma dica para otimizar o cache de arquivo. |
|
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 de 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 arquivo. Se um aplicativo mover o ponteiro do arquivo para acesso aleatório, o cache ideal poderá não ocorrer. No entanto, a operação correta ainda é garantida.
Especificar esse sinalizador pode aumentar o desempenho para 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 oferecer 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 a 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 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, 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 CreateTransaction .
[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.
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 especificados.
Se houver falha na função, o valor retornado será INVALID_HANDLE_VALUE. Para obter informações de erro estendidas, chame GetLastError.
Comentários
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 para NTFS transacional.
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 estão incluídas em permissões de FILE_GENERIC_WRITE . Você deverá 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.
Você não pode 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 Compactação e descompactação de arquivos e Criptografia de Arquivos.
Comportamento simbólico do link – se a chamada para essa função criar um novo arquivo, não haverá 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_EXISTING ou 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 de 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 do 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 | Com suporte |
|---|---|
| Protocolo SMB (SMB) 3.0 | No |
| TFO (Failover transparente) do SMB 3.0 | No |
| SMB 3.0 com compartilhamentos de arquivos de expansão (SO) | No |
| Sistema de arquivos de Volume Compartilhado Clusterizado (CsvFS) | No |
| ReFS (Sistema de Arquivos Resiliente) | No |
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 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 Como criar e abrir arquivos.
Se você renomear ou excluir um arquivo e restaurá-lo logo 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 Obtendo e definindo 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 Fluxos de arquivos.
Diretórios
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 Sobre o Gerenciamento de Diretórios.
Observação
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. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows Vista [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2008 [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | winbase.h (inclua Windows.h) |
| Biblioteca | Kernel32.lib |
| DLL | Kernel32.dll |
Confira também
Descompactação e compactação de arquivo
Funções de gerenciamento de arquivos
Segurança de arquivo e direitos de acesso
Funções
Tópicos de visão geral