Função FtpGetFileA (wininet.h)

Artigo
11/20/2024

Recupera um arquivo do servidor FTP e o armazena sob o nome de arquivo especificado, criando um novo arquivo local no processo.

Sintaxe

BOOL FtpGetFileA(
  [in] HINTERNET hConnect,
  [in] LPCSTR    lpszRemoteFile,
  [in] LPCSTR    lpszNewFile,
  [in] BOOL      fFailIfExists,
  [in] DWORD     dwFlagsAndAttributes,
  [in] DWORD     dwFlags,
  [in] DWORD_PTR dwContext
);

Parâmetros

[in] hConnect

Manipule para uma sessão FTP.

[in] lpszRemoteFile

Ponteiro para uma cadeia de caracteres terminada em nulo que contém o nome do arquivo a ser recuperado.

[in] lpszNewFile

Ponteiro para uma cadeia de caracteres terminada em nulo que contém o nome do arquivo a ser criado no sistema local.

[in] fFailIfExists

Indica se a função deve continuar se já existir um arquivo local do nome especificado. Se fFailIfExists for verdadeiro e o arquivo local existir, FtpGetFile falhará.

[in] dwFlagsAndAttributes

Atributos de arquivo para o novo arquivo. Esse parâmetro pode ser qualquer combinação dos sinalizadores FILE_ATTRIBUTE_* usados pela função CreateFile .

[in] dwFlags

Controla como a função lidará com o download do arquivo. O primeiro conjunto de valores de sinalizador indica as condições sob as quais a transferência ocorre. Esses sinalizadores de tipo de transferência podem ser usados em combinação com o segundo conjunto de sinalizadores que controlam o cache.

O aplicativo pode selecionar um desses valores de tipo de transferência.

Valor	Significado
FTP_TRANSFER_TYPE_ASCII	Transfere o arquivo usando o método de transferência ASCII (Tipo A) do FTP. As informações de controle e formatação são convertidas em equivalentes locais.
FTP_TRANSFER_TYPE_BINARY	Transfere o arquivo usando o método de transferência de Imagem (Tipo I) do FTP. O arquivo é transferido exatamente como existe sem alterações. Esse é o método de transferência padrão.
FTP_TRANSFER_TYPE_UNKNOWN	O padrão é FTP_TRANSFER_TYPE_BINARY.
INTERNET_FLAG_TRANSFER_ASCII	Transfere o arquivo como ASCII.
INTERNET_FLAG_TRANSFER_BINARY	Transfere o arquivo como binário.

Os sinalizadores a seguir determinam como o cache desse arquivo será feito. Qualquer combinação dos sinalizadores a seguir pode ser usada com o sinalizador de tipo de transferência.

Valor	Significado
INTERNET_FLAG_HYPERLINK	Força um recarregamento se não houver tempo expirado e nenhum tempo LastModified retornado do servidor ao determinar se o item deve ser recarregado da rede.
INTERNET_FLAG_NEED_FILE	Faz com que um arquivo temporário seja criado se o arquivo não puder ser armazenado em cache.
INTERNET_FLAG_RELOAD	Força um download da listagem de arquivo, objeto ou diretório solicitado do servidor de origem, não do cache.
INTERNET_FLAG_RESYNCHRONIZE	Recarrega recursos HTTP se o recurso tiver sido modificado desde a última vez em que foi baixado. Todos os recursos FTP são recarregados. Windows XP e Windows Server 2003 R2 e anteriores: recursos do Gopher também são recarregados.

[in] dwContext

Ponteiro para uma variável que contém o valor definido pelo aplicativo que associa essa pesquisa a qualquer dado do aplicativo. Isso 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 TRUE se tiver êxito ou false caso contrário. Para obter uma mensagem de erro específica, chame GetLastError.

Observações

FtpGetFile é uma rotina de alto nível que manipula toda a contabilidade e sobrecarga associada à leitura de um arquivo de um servidor FTP e ao armazená-lo localmente. Um aplicativo que precisa recuperar apenas dados de arquivo ou que requer controle próximo sobre a transferência de arquivo deve usar as funções FtpOpenFile e InternetReadFile.

Se o parâmetro dwFlags especificar FTP_TRANSFER_TYPE_ASCII, a tradução dos dados do arquivo converterá caracteres de controle e formatação em equivalentes locais. A transferência padrão é o modo binário, em que o arquivo é baixado no mesmo formato que é armazenado no servidor.

Tanto lpszRemoteFile quanto lpszNewFile podem ser nomes de arquivo parcial ou totalmente qualificados em relação ao diretório atual.

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

Funções WinINet

Compartilhar via