Compartilhar via


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.

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
Desabilita operações abertas subsequentes em um objeto para solicitar qualquer tipo de acesso a esse objeto.
FILE_SHARE_DELETE
0x00000004
Habilita as operações abertas subsequentes em um objeto para solicitar o acesso de exclusão.

Caso contrário, outros processos não poderão abrir o objeto se solicitarem acesso de exclusão.

Se esse sinalizador não for especificado, mas o objeto tiver sido aberto para acesso de exclusão, a função falhará.

FILE_SHARE_READ
0x00000001
Habilita operações abertas subsequentes em um objeto para solicitar acesso de leitura.

Caso contrário, outros processos não poderão abrir o objeto se solicitarem acesso de leitura.

Se esse sinalizador não for especificado, mas o objeto tiver sido aberto para acesso de leitura, a função falhará.

FILE_SHARE_WRITE
0x00000002
Habilita operações abertas subsequentes em um objeto para solicitar acesso de gravação.

Caso contrário, outros processos não poderão abrir o objeto se solicitarem acesso de gravação.

Se esse sinalizador não for especificado, mas o objeto tiver sido aberto para acesso de gravação ou tiver um mapeamento de arquivo com acesso de gravação, a função falhará.

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

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 terá êxito e o código de último erro será definido como zero.

Para obter mais informações, confira a seção Comentários deste tópico.

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 de ú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 de ú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 especificado não existir, a função falhará e o código de último erro será definido como ERROR_FILE_NOT_FOUND (2).

Para obter mais informações, confira a seção Comentários deste tópico.

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 de ú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 .

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

Observação  

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.

 
Os atributos e sinalizadores de arquivo a seguir são usados apenas para objetos de arquivo, não para outros tipos de objetos que CreateFileTransacted abre (informações adicionais podem ser encontradas na seção Comentários deste tópico). Para obter acesso mais avançado aos 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
FILE_ATTRIBUTE_ARCHIVE
32 (0x20)
O arquivo deve ser arquivado. Os aplicativos usam esse atributo para marcar arquivos para backup ou remoção.
FILE_ATTRIBUTE_ENCRYPTED
16384 (0x4000)
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.

FILE_ATTRIBUTE_HIDDEN
2 (0x2)
O arquivo está oculto. Não inclua em uma listagem de diretório comum.
FILE_ATTRIBUTE_NORMAL
128 (0x80)
O arquivo não tem outros atributos definidos. Este atributo é válido apenas quando usado sozinho.
FILE_ATTRIBUTE_OFFLINE
4096 (0x1000)
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.
FILE_ATTRIBUTE_READONLY
1 (0x1)
O arquivo é somente leitura. Os aplicativos podem ler o arquivo, mas não podem gravá-lo ou excluí-lo.
FILE_ATTRIBUTE_SYSTEM
4 (0x4)
O arquivo faz parte ou é usado exclusivamente por um sistema operacional.
FILE_ATTRIBUTE_TEMPORARY
256 (0x100)
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
FILE_FLAG_BACKUP_SEMANTICS
0x02000000
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.

FILE_FLAG_DELETE_ON_CLOSE
0x04000000
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.

FILE_FLAG_NO_BUFFERING
0x20000000
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:

  • O acesso a arquivos deve começar em deslocamentos de bytes dentro de um arquivo que são múltiplos inteiros do tamanho do setor de volume.
  • O acesso a arquivos deve ser para números de bytes que são múltiplos inteiros do tamanho do setor de volume. Por exemplo, se o tamanho do setor for de 512 bytes, um aplicativo poderá solicitar leituras e gravações de 512, 1024, 1536 ou 2048 bytes, mas não de 335, 981 ou 7171 bytes.
  • Os endereços de buffer para operações de leitura e gravação devem ser alinhados ao setor, o que significa alinhado em endereços na memória que são múltiplos inteiros do tamanho do setor de volume. Dependendo do disco, esse requisito pode não ser imposto.
Uma maneira de alinhar buffers em múltiplos inteiros do tamanho do setor de volume é usar VirtualAlloc para alocar os buffers. Ele aloca memória alinhada em endereços que são múltiplos inteiros do tamanho da página de memória do sistema operacional. Como os tamanhos da página de memória e do setor de volume são potências de 2, essa memória também é alinhada em endereços que são múltiplos inteiros de um tamanho de setor de volume. As páginas de memória têm 4 ou 8 KB de tamanho; os setores são 512 bytes (discos rígidos), 2.048 bytes (CD) ou 4.096 bytes (discos rígidos) e, portanto, os setores de volume nunca podem ser maiores que as páginas de memória.

Um aplicativo pode determinar um tamanho de setor de volume chamando a função GetDiskFreeSpace .

FILE_FLAG_OPEN_NO_RECALL
0x00100000
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.
FILE_FLAG_OPEN_REPARSE_POINT
0x00200000
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.
FILE_FLAG_OVERLAPPED
0x40000000
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 .

FILE_FLAG_POSIX_SEMANTICS
0x01000000
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.
FILE_FLAG_RANDOM_ACCESS
0x10000000
O arquivo deve ser acessado aleatoriamente. O sistema pode usar isso como uma dica para otimizar o cache de arquivo.
FILE_FLAG_SESSION_AWARE
0x00800000
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.

FILE_FLAG_SEQUENTIAL_SCAN
0x08000000
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.

FILE_FLAG_WRITE_THROUGH
0x80000000
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.

Sinalizador de segurança Significado
SECURITY_ANONYMOUS
Representa um cliente no nível de representação anônima.
SECURITY_CONTEXT_TRACKING
O modo de acompanhamento de segurança é dinâmico. Se esse sinalizador não for especificado, o modo de controle de segurança será estático.
SECURITY_DELEGATION
Representa um cliente no nível de representação delegação.
SECURITY_EFFECTIVE_ONLY
Somente os aspectos habilitados do contexto de segurança do cliente estão disponíveis para o servidor. Se você não especificar esse sinalizador, todos os aspectos do contexto de segurança do cliente estarão disponíveis.

Isso permite que o cliente limite os grupos e privilégios que um servidor pode usar ao representar o cliente.

SECURITY_IDENTIFICATION
Representa um cliente no nível de representação de identificação.
SECURITY_IMPERSONATION
Represente um cliente no nível de representação. Esse é o comportamento padrão se nenhum outro sinalizador for especificado junto com o sinalizador SECURITY_SQOS_PRESENT .

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

Valor Significado
TXFS_MINIVERSION_COMMITTED_VIEW
0x0000
A exibição do arquivo a partir de seu último commit.
TXFS_MINIVERSION_DIRTY_VIEW
0xFFFF
A exibição do arquivo como ele está sendo modificado pela transação.
TXFS_MINIVERSION_DEFAULT_VIEW
0xFFFE
A exibição confirmada ou sujo do arquivo, dependendo do contexto. Uma transação que está modificando o arquivo obtém a exibição sujo, enquanto uma transação que não está modificando o arquivo obtém a exibição confirmada.

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 FILE_FLAG_OPEN_REPARSE_POINT não for especificado:
  • 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.
Não há garantia de que uma gravação de vários setores seja atômica, a menos que você esteja usando uma transação (ou seja, o identificador criado é um identificador transacionado). Uma gravação de setor único é atômica. As gravações de vários setores armazenadas em cache nem sempre podem ser gravadas no disco; portanto, especifique FILE_FLAG_WRITE_THROUGH para garantir que uma gravação de vários setores inteira seja gravada no disco sem cache.

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
No Windows 8 e Windows Server 2012, essa função é compatível com as tecnologias a seguir.
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

CloseHandle

CopyFileTransacted

CreateDirectoryTransacted

DeleteFileTransacted

Descompactação e compactação de arquivo

Criptografia de Arquivo

Funções de gerenciamento de arquivos

Segurança de arquivo e direitos de acesso

Fluxos de arquivos

FindFirstFileTransacted

Funções

GetFileAttributesTransacted

MoveFileTransacted

Tópicos de visão geral

Considerações sobre programação do NTFS transacional

ReadFile

NTFS Transacional (TxF)

WriteFile