Função FindFirstFileTransactedA (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.]

Pesquisa um diretório para um arquivo ou subdiretório com um nome que corresponde a um nome específico como uma operação transacionada.

Essa função é a forma transacionada da função FindFirstFileEx.

Para obter a versão mais básica dessa função, consulte FindFirstFile.

Sintaxe

HANDLE FindFirstFileTransactedA(
  [in]  LPCSTR             lpFileName,
  [in]  FINDEX_INFO_LEVELS fInfoLevelId,
  [out] LPVOID             lpFindFileData,
  [in]  FINDEX_SEARCH_OPS  fSearchOp,
        LPVOID             lpSearchFilter,
  [in]  DWORD              dwAdditionalFlags,
  [in]  HANDLE             hTransaction
);

Parâmetros

[in] lpFileName

O diretório ou caminho e o nome do arquivo. O nome do arquivo pode incluir caracteres curinga, por exemplo, um asterisco (*) ou um ponto de interrogação (?).

Esse parâmetro não deve ser NULL, uma cadeia de caracteres inválida (por exemplo, uma cadeia de caracteres vazia ou uma cadeia de caracteres que está faltando o caractere nulo de terminação) ou terminar em uma barra invertida à direita (\).

Se a cadeia de caracteres terminar com um curinga, um período (.) ou um nome de diretório, o usuário deverá ter acesso à raiz e a todos os subdiretórios no caminho.

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 arquivo 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] fInfoLevelId

O nível de informações dos dados retornados.

Esse parâmetro é um dos valores de enumeração FINDEX_INFO_LEVELS.

[out] lpFindFileData

Um ponteiro para a estrutura de WIN32_FIND_DATA que recebe informações sobre um arquivo ou subdiretório encontrado.

[in] fSearchOp

O tipo de filtragem a ser executada é diferente da correspondência curinga.

Esse parâmetro é um dos valores de enumeração FINDEX_SEARCH_OPS.

lpSearchFilter

Um ponteiro para os critérios de pesquisa se o fSearchOp especificado precisar de informações de pesquisa estruturadas.

No momento, nenhum dos valores de fSearchOp com suporte exigem informações de pesquisa estendidas. Portanto, esse ponteiro deve ser NULL.

[in] dwAdditionalFlags

Especifica sinalizadores adicionais que controlam a pesquisa.

Valor	Significado
FIND_FIRST_EX_CASE_SENSITIVE 1	As pesquisas diferenciam maiúsculas de minúsculas.

[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 será um identificador de pesquisa usado em uma chamada subsequente para findNextFile ou FindClosee o parâmetro lpFindFileData contém informações sobre o primeiro arquivo ou diretório encontrado.

Se a função falhar ou não localizar arquivos da cadeia de caracteres de pesquisa no parâmetro lpFileName, o valor retornado será INVALID_HANDLE_VALUE e o conteúdo de lpFindFileData será indeterminado. Para obter informações de erro estendidas, chame a função GetLastError.

Observações

A função FindFirstFileTransacted abre um identificador de pesquisa e retorna informações sobre o primeiro arquivo que o sistema de arquivos encontra com um nome que corresponde ao padrão especificado. Esse pode ou não ser o primeiro arquivo ou diretório que aparece em um aplicativo de listagem de diretório (como o comando dir) quando fornecido o mesmo padrão de cadeia de caracteres de nome de arquivo. Isso ocorre porque FindFirstFileTransacted não faz nenhuma classificação dos resultados da pesquisa. Para obter informações adicionais, consulte FindNextFile.

A lista a seguir identifica algumas outras características de pesquisa:

A pesquisa é executada estritamente no nome do arquivo, não em nenhum atributo, como uma data ou um tipo de arquivo.
A pesquisa inclui os nomes de arquivo longos e curtos.
Uma tentativa de abrir uma pesquisa com uma barra invertida à direita sempre falha.
Passar uma cadeia de caracteres inválida, NULL ou uma cadeia de caracteres vazia para o parâmetro lpFileName não é um uso válido dessa função. Os resultados nesse caso são indefinidos.

Observação Em casos raros, as informações de arquivo sobre sistemas de arquivos NTFS podem não estar atualizadas no momento em que você chamar essa função. Para ter certeza de obter as informações de arquivo atuais, chame a função GetFileInformationByHandle.

Se o sistema de arquivos subjacente não der suporte ao tipo de filtragem especificado, além da filtragem de diretório, FindFirstFileTransacted falhará com o erro ERROR_NOT_SUPPORTED. O aplicativo deve usar FINDEX_SEARCH_OPS tipo FileExSearchNameMatch e executar sua própria filtragem.

Depois que o identificador de pesquisa for estabelecido, use-o na função FindNextFile para procurar outros arquivos que correspondam ao mesmo padrão com a mesma filtragem que está sendo executada. Quando o identificador de pesquisa não for necessário, ele deverá ser fechado usando a função FindClose.

Conforme indicado anteriormente, você não pode usar uma barra invertida à direita (\) no lpFileName cadeia de caracteres de entrada para FindFirstFileTransacted, portanto, pode não ser óbvio como pesquisar diretórios raiz. Se você quiser ver arquivos ou obter os atributos de um diretório raiz, as seguintes opções se aplicarão:

Para examinar arquivos em um diretório raiz, você pode usar "C:\*" e percorrer o diretório usando FindNextFile.
Para obter os atributos de um diretório raiz, use a função GetFileAttributes.

Observação Anexar a cadeia de caracteres "\\?\" não permite o acesso ao diretório raiz.

Em compartilhamentos de rede, você pode usar um lpFileName na forma do seguinte: "\\server\service*". No entanto, você não pode usar um lpFileName que aponta para o compartilhamento em si; por exemplo, "\\server\service" não é válido.

Para examinar um diretório que não é um diretório raiz, use o caminho para esse diretório, sem uma barra invertida à direita. Por exemplo, um argumento de "C:\Windows" retorna informações sobre o diretório "C:\Windows", não sobre um diretório ou arquivo em "C:\Windows". Para examinar os arquivos e diretórios em "C:\Windows", use um lpFileName de "C:\Windows\*".

Lembre-se de que algum outro thread ou processo pode criar ou excluir um arquivo com esse nome entre o tempo que você consulta o resultado e o tempo em que você age sobre as informações. Se essa for uma preocupação potencial para seu aplicativo, uma solução possível é usar a função CreateFile com CREATE_NEW (que falha se o arquivo existir) ou OPEN_EXISTING (que falhará se o arquivo não existir).

Se você estiver escrevendo um aplicativo de 32 bits para listar todos os arquivos em um diretório e o aplicativo puder ser executado em um computador de 64 bits, você deve chamar wow64DisableWow64FsRedirection antes de chamar FindFirstFileTransacted e chamar Wow64RevertWow64FsRedirection após a última chamada para FindNextFile. Para obter mais informações, consulte do Redirecionador do Sistema de Arquivos.

Se o caminho apontar para um link simbólico, o buffer de WIN32_FIND_DATA conterá informações sobre o link simbólico, não o destino.

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 FindFirstFileTransacted 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