Função FtpFindFirstFileA (wininet.h)

Pesquisa o diretório especificado da sessão FTP fornecida. Entradas de arquivo e diretório são retornadas ao aplicativo na estrutura WIN32_FIND_DATA.

Sintaxe

HINTERNET FtpFindFirstFileA(
  [in]  HINTERNET          hConnect,
  [in]  LPCSTR             lpszSearchFile,
  [out] LPWIN32_FIND_DATAA lpFindFileData,
  [in]  DWORD              dwFlags,
  [in]  DWORD_PTR          dwContext
);

Parâmetros

[in] hConnect

Manipular para uma sessão FTP retornada de InternetConnect.

[in] lpszSearchFile

Ponteiro para um cadeia de caracteresterminada nula que especifica um caminho de diretório ou nome de arquivo válido para o sistema de arquivos do servidor FTP. A cadeia de caracteres pode conter caracteres curinga, mas nenhum espaço em branco é permitido. Se o valor de lpszSearchFile for NULL ou se for uma cadeia de caracteres vazia, a função encontrará o primeiro arquivo no diretório atual no servidor.

[out] lpFindFileData

Ponteiro para uma estrutura WIN32_FIND_DATA que recebe informações sobre o arquivo ou diretório encontrado.

[in] dwFlags

Controla o comportamento dessa função. Esse parâmetro pode ser uma combinação dos valores a seguir.

INTERNET_FLAG_HYPERLINK

INTERNET_FLAG_NEED_FILE

INTERNET_FLAG_NO_CACHE_WRITE

INTERNET_FLAG_RELOAD

INTERNET_FLAG_RESYNCHRONIZE

[in] dwContext

Ponteiro para uma variável que especifica o valor definido pelo aplicativo que associa essa pesquisa a qualquer dado do aplicativo. Esse parâmetro será usado somente se o aplicativo já tiver chamado InternetSetStatusCallback para configurar uma função de retorno de chamada de status.

Valor de retorno

Retorna um identificador válido para a solicitação se a enumeração de diretório foi iniciada com êxito ou retorna NULL caso contrário. Para obter uma mensagem de erro específica, chame GetLastError. Se GetLastError retornar ERROR_INTERNET_EXTENDED_ERROR, como no caso em que a função não encontrar arquivos correspondentes, chame a função InternetGetLastResponseInfo para recuperar o texto de erro estendido, conforme documentado em Tratamento de Erros.

Observações

Para FtpFindFirstFile, os tempos de arquivo retornados na estrutura WIN32_FIND_DATA estão no fuso horário local, não em um formato UTC (tempo universal coordenado).

FtpFindFirstFile é semelhante à função FindFirstFile. No entanto, observe que apenas um FtpFindFirstFile pode ocorrer de cada vez em uma determinada sessão FTP. As enumerações, portanto, são correlacionadas com o identificador de sessão FTP. Isso ocorre porque o protocolo FTP permite apenas uma enumeração de diretório por sessão.

Depois de chamar FtpFindFirstFile e até chamar InternetCloseHandle, o aplicativo não poderá chamar FtpFindFirstFile novamente no identificador de sessão FTP especificado. Se uma chamada for feita para FtpFindFirstFile nesse identificador, a função falhará com ERROR_FTP_TRANSFER_IN_PROGRESS. Depois que o aplicativo de chamada tiver terminado de usar o identificador HINTERNET retornado por FtpFindFirstFile, ele deverá ser fechado usando a função InternetCloseHandle.

Depois de iniciar uma enumeração de diretório com FtpFindFirstFile, a função InternetFindNextFile pode ser usada para continuar a enumeração.

Como o protocolo FTP não fornece meios padrão de enumeração, algumas das informações comuns sobre arquivos, como data e hora de criação de arquivo, nem sempre estão disponíveis ou corretas. Quando isso acontece, FtpFindFirstFile e InternetFindNextFile preencher informações indisponíveis com uma melhor suposição com base nas informações disponíveis. Por exemplo, as datas de criação e de último acesso geralmente são as mesmas da data de modificação do arquivo.

O aplicativo não pode chamar FtpFindFirstFile entre chamadas para FtpOpenFile e InternetCloseHandle.

Assim como todos os outros aspectos da API WinINet, essa função não pode ser chamada com segurança de dentro do DllMain ou dos construtores e destruidores de objetos globais.

Observação WinINet não dá suporte a implementações de servidor. Além disso, ele não deve ser usado de um serviço. Para implementações ou serviços de servidor, use do Microsoft Windows HTTP Services (WinHTTP).

 

Nota

O cabeçalho wininet.h define FtpFindFirstFile 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 2000 Professional [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows 2000 Server [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	wininet.h
biblioteca	Wininet.lib
de DLL	Wininet.dll

Consulte também

sessões FTP

do WinINet Functions