Função CreateDirectoryTransactedA (winbase.h)

Artigo
11/20/2024

[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 um novo diretório como uma operação transacionada, com os atributos de um diretório de modelo especificado. Se o sistema de arquivos subjacente der suporte à segurança em arquivos e diretórios, a função aplicará um descritor de segurança especificado ao novo diretório. O novo diretório mantém os outros atributos do diretório de modelo especificado.

Sintaxe

BOOL CreateDirectoryTransactedA(
  [in, optional] LPCSTR                lpTemplateDirectory,
  [in]           LPCSTR                lpNewDirectory,
  [in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  [in]           HANDLE                hTransaction
);

Parâmetros

[in, optional] lpTemplateDirectory

O caminho do diretório a ser usado como um modelo ao criar o novo diretório. Esse parâmetro pode ser NULL.

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.

O diretório 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.

[in] lpNewDirectory

O caminho do diretório a ser criado.

Ponta

[in, optional] lpSecurityAttributes

Um ponteiro para uma estrutura SECURITY_ATTRIBUTES. O lpSecurityDescriptor membro da estrutura especifica um descritor de segurança para o novo diretório.

Se lpSecurityAttributes for NULL, o diretório obterá um descritor de segurança padrão. As ACL (listas de controle de acesso) no descritor de segurança padrão para um 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 esse parâmetro tenha um efeito. Isso é indicado quando GetVolumeInformation retorna FS_PERSISTENT_ACLS.

[in] hTransaction

Um identificador para a transação. Esse identificador é retornado pela função CreateTransaction.

Valor de retorno

Se a função for bem-sucedida, o valor retornado não será zero.

Se a função falhar, o valor retornado será zero (0). Para obter informações de erro estendidas, chame GetLastError. Os possíveis erros incluem o seguinte.

Código de retorno	Descrição
ERROR_ALREADY_EXISTS	O diretório especificado já existe.
ERROR_EFS_NOT_ALLOWED_IN_TRANSACTION	Você não pode criar um diretório filho com um diretório pai que tenha a criptografia desabilitada.
ERROR_PATH_NOT_FOUND	Um ou mais diretórios intermediários não existem. Essa função só cria o diretório final no caminho.

Observações

A função CreateDirectoryTransacted permite criar diretórios que herdam informações de fluxo de outros diretórios. Essa função é útil, por exemplo, quando você está usando diretórios Macintosh, que têm um fluxo de recursos necessário para identificar corretamente o conteúdo do diretório como um atributo.

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 sistema de arquivos, um novo diretório herda os atributos de compactação e criptografia de seu diretório pai.

Essa função falhará com ERROR_EFS_NOT_ALLOWED_IN_TRANSACTION se você tentar criar um diretório filho com um diretório pai que tenha a criptografia desabilitada.

Você pode obter um identificador para um diretório chamando a função CreateFileTransacted com o sinalizador FILE_FLAG_BACKUP_SEMANTICS definido.

No Windows 8 e no Windows Server 2012, essa função é compatível com as tecnologias a seguir.

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

O SMB 3.0 não dá suporte ao TxF.

Nota

O cabeçalho winbase.h define CreateDirectoryTransacted como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do 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