Partilhar via

Classe CFtpConnection

  • Artigo

Gerencia sua conexão FTP com um servidor de Internet e permite a manipulação direta de diretórios e arquivos nesse servidor.

Sintaxe

class CFtpConnection : public CInternetConnection

Membros

Construtores públicos

Nome Descrição
CFtpConnection::CFtpConnection Constrói um objeto CFtpConnection.

Métodos públicos

Nome Descrição
CFtpConnection::Command Envia um comando diretamente para um servidor FTP.
CFtpConnection::CreateDirectory Cria um diretório no servidor.
CFtpConnection::GetCurrentDirectory Obtém o diretório atual para essa conexão.
CFtpConnection::GetCurrentDirectoryAsURL Obtém o diretório atual para essa conexão como uma URL.
CFtpConnection::GetFile Obtém um arquivo do servidor conectado
CFtpConnection::OpenFile Abre um arquivo no servidor conectado.
CFtpConnection::PutFile Coloca um arquivo no servidor.
CFtpConnection::Remove Remove um arquivo do servidor.
CFtpConnection::RemoveDirectory Remove o diretório especificado do servidor.
CFtpConnection::Rename Renomeia um arquivo no servidor.
CFtpConnection::SetCurrentDirectory Define o diretório FTP atual.

Comentários

O FTP é um dos três serviços de Internet reconhecidos pelas classes WinInet do MFC.

Para se comunicar com um servidor de Internet FTP, primeiro você deve criar uma instância de CInternetSession e então criar um objeto CFtpConnection. Você nunca cria um objeto CFtpConnection diretamente; em vez disso, chame CInternetSession::GetFtpConnection, que cria o objeto CFtpConnection e retorna um ponteiro para ele.

Para saber mais sobre como CFtpConnection funciona com as outras classes de Internet do MFC, confira o artigo Programação na Internet com o WinInet. Para mais informações sobre como se comunicar com os outros dois serviços com suporte, HTTP e gopher, confira as classes CHttpConnection e CGopherConnection.

Exemplo

Veja o exemplo na visão geral da classe CFtpFileFind.

Hierarquia de herança

CObject

CInternetConnection

CFtpConnection

Requisitos

Cabeçalho: afxinet.h

CFtpConnection::CFtpConnection

Essa função membro é chamada para construir um objeto CFtpConnection.

CFtpConnection(
    CInternetSession* pSession,
    HINTERNET hConnected,
    LPCTSTR pstrServer,
    DWORD_PTR dwContext);

CFtpConnection(
    CInternetSession* pSession,
    LPCTSTR pstrServer,
    LPCTSTR pstrUserName = NULL,
    LPCTSTR pstrPassword = NULL,
    DWORD_PTR dwContext = 0,
    INTERNET_PORT nPort = INTERNET_INVALID_PORT_NUMBER,
    BOOL bPassive = FALSE);

Parâmetros

pSession
Descarte o objeto CInternetSession.

hConnected
O identificador do Windows da sessão de Internet atual.

pstrServer
Um ponteiro para uma cadeia de caracteres contendo o nome do servidor FTP.

dwContext
O identificador de contexto da operação. dwContext identifica as informações de status da operação retornadas por CInternetSession::OnStatusCallback. O padrão é definido como 1; no entanto, você pode atribuir explicitamente uma ID de contexto específica para a operação. O objeto e qualquer trabalho que ele fizer serão associados a essa ID de contexto.

pstrUserName
Ponteiro para uma cadeia de caracteres terminada em nulo que especifica o nome do usuário para fazer logon. Se NULL, o padrão será anônimo.

pstrPassword
Um ponteiro para uma cadeia de caracteres terminada em nulo que especifica a senha a ser usada para fazer logon. Se pstrPassword e pstrUserName forem NULL, a senha anônima padrão será o nome de email do usuário. Se pstrPassword for NULL (ou uma cadeia de caracteres vazia), mas pstrUserName não for NULL, uma senha em branco será usada. A seguinte tabela descreve o comportamento para as quatro configurações possíveis de pstrUserName e pstrPassword:

pstrUserName pstrPassword Nome de usuário enviado ao servidor FTP Senha enviada ao servidor FTP
NULL ou " " NULL ou " " "anonymous" Nome de email do usuário
Cadeia de caracteres não NULL NULL ou " " pstrUserName " "
Cadeia de caracteres NULL não NULL ERROR ERROR
Cadeia de caracteres não NULL Cadeia de caracteres não NULL pstrUserName pstrPassword

nPort
Um número que identifica a porta TCP/IP a ser usada no servidor.

bPassive
Especifica o modo passivo ou ativo para esta sessão FTP. Se definido como TRUE, define o dwFlag da API Win32 como INTERNET_FLAG_PASSIVE.

Comentários

Você nunca cria um objeto CFtpConnection diretamente. Em vez disso, chame CInternetSession::GetFtpConnection, que cria o objeto CFptConnection.

CFtpConnection::Command

Envia um comando diretamente para um servidor FTP.

CInternetFile* Command(
    LPCTSTR pszCommand,
    CmdResponseType eResponse = CmdRespNone,
    DWORD dwFlags = FTP_TRANSFER_TYPE_BINARY,
    DWORD_PTR dwContext = 1);

Parâmetros

pszCommand
Um ponteiro para uma cadeia de caracteres que contém o comando a ser enviado.

eResponse
Especifica se uma resposta é esperada do servidor FTP. Pode ser um dos seguintes valores:

  • CmdRespNone Nenhuma resposta é esperada.
  • CmdRespRead Uma resposta é esperada.
  • CmdRespWrite Não usado.

O CmdResponseType é um membro do CFtpConnection, definido em afxinet.h.

dwFlags
Um valor que contém os sinalizadores que controlam essa função. Para uma lista completa, confira FTPCommand.

dwContext
Um ponteiro para um valor que contém um valor definido pelo aplicativo usado para identificar o contexto do aplicativo em retornos de chamada.

Valor de Devolução

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

Essa função de membro emula a funcionalidade da função FTPCommand, conforme descrito no SDK do Windows.

Se ocorrer um erro, o MFC gerará uma exceção do tipo CInternetException.

CFtpConnection::CreateDirectory

Chame essa função de membro para criar um diretório no servidor conectado.

BOOL CreateDirectory(LPCTSTR pstrDirName);

Parâmetros

pstrDirName
Um ponteiro para uma cadeia de caracteres que contém o nome do diretório a ser criado.

Valor de Devolução

Diferente de zero se tiver êxito; caso contrário, 0. Se a chamada falhar, a função do Windows GetLastError poderá ser chamada para determinar a causa do erro.

Comentários

Use GetCurrentDirectory para determinar o diretório de trabalho atual para essa conexão com o servidor. Não suponha que o sistema remoto tenha conectado você ao diretório raiz.

O parâmetro pstrDirName pode ser um nome de arquivo parcial ou totalmente qualificado em relação ao diretório atual. Uma barra invertida (\) ou uma barra (/) pode ser usada como separador de diretório para qualquer nome. CreateDirectory converte os separadores de nome de diretório nos caracteres apropriados antes de eles serem usados.

CFtpConnection::GetCurrentDirectory

Chame essa função de membro para obter o nome do diretório atual.

BOOL GetCurrentDirectory(CString& strDirName) const;

BOOL GetCurrentDirectory(
    LPTSTR pstrDirName,
    LPDWORD lpdwLen) const;

Parâmetros

strDirName
Uma referência a uma cadeia de caracteres que receberá o nome do diretório.

pstrDirName
Um ponteiro para uma cadeia de caracteres que receberá o nome do diretório.

lpdwLen
Um ponteiro para um DWORD que contém as seguintes informações:

Na entrada: o tamanho do buffer referenciado por pstrDirName.

No retorno: o número de caracteres armazenados em pstrDirName. Se a função de membro falhar e ERROR_INSUFFICIENT_BUFFER for retornado, lpdwLen conterá o número de bytes que o aplicativo deve alocar para receber a cadeia de caracteres.

Valor de Devolução

Diferente de zero se tiver êxito; caso contrário, 0. Se a chamada falhar, a função Win32 GetLastError poderá ser chamada para determinar a causa do erro.

Comentários

Para obter o nome do diretório como uma URL, chame GetCurrentDirectoryAsURL.

Os parâmetros pstrDirName ou strDirName podem ser nomes de arquivo parcialmente qualificados em relação ao diretório atual ou totalmente qualificados. Uma barra invertida (\) ou uma barra (/) pode ser usada como separador de diretório para qualquer nome. GetCurrentDirectory converte os separadores de nome de diretório nos caracteres apropriados antes de eles serem usados.

CFtpConnection::GetCurrentDirectoryAsURL

Chame essa função de membro para obter o nome do diretório atual como uma URL.

BOOL GetCurrentDirectoryAsURL(CString& strDirName) const;

BOOL GetCurrentDirectoryAsURL(
    LPTSTR pstrName,
    LPDWORD lpdwLen) const;

Parâmetros

strDirName
Uma referência a uma cadeia de caracteres que receberá o nome do diretório.

pstrDirName
Um ponteiro para uma cadeia de caracteres que receberá o nome do diretório.

lpdwLen
Um ponteiro para um DWORD que contém as seguintes informações:

Na entrada: o tamanho do buffer referenciado por pstrDirName.

No retorno: o número de caracteres armazenados em pstrDirName. Se a função de membro falhar e ERROR_INSUFFICIENT_BUFFER for retornado, lpdwLen conterá o número de bytes que o aplicativo deve alocar para receber a cadeia de caracteres.

Valor de Devolução

Diferente de zero se tiver êxito; caso contrário, 0. Se a chamada falhar, a função Win32 GetLastError poderá ser chamada para determinar a causa do erro.

Comentários

GetCurrentDirectoryAsURL se comporta do mesmo modo que GetCurrentDirectory

O parâmetro strDirName pode ser nomes de arquivo parcialmente qualificados em relação ao diretório atual ou totalmente qualificados. Uma barra invertida (\) ou uma barra (/) pode ser usada como separador de diretório para qualquer nome. GetCurrentDirectoryAsURL converte os separadores de nome de diretório nos caracteres apropriados antes de eles serem usados.

CFtpConnection::GetFile

Chame essa função de membro para obter um arquivo de um servidor FTP e armazená-lo no computador local.

BOOL GetFile(
    LPCTSTR pstrRemoteFile,
    LPCTSTR pstrLocalFile,
    BOOL bFailIfExists = TRUE,
    DWORD dwAttributes = FILE_ATTRIBUTE_NORMAL,
    DWORD dwFlags = FTP_TRANSFER_TYPE_BINARY,
    DWORD_PTR dwContext = 1);

Parâmetros

pstrRemoteFile
Um ponteiro para uma cadeia de caracteres terminada em nulo que contém o nome de um arquivo a ser recuperado do servidor FTP.

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

bFailIfExists
Indica se o nome do arquivo já pode ser usado por um arquivo existente. Se o nome do arquivo local já existir e esse parâmetro for TRUE, GetFile falhará. Caso contrário, GetFile apagará a cópia existente do arquivo.

dwAttributes
Indica os atributos do arquivo. Pode ser qualquer combinação dos sinalizadores FILE_ATTRIBUTE_* a seguir.

  • FILE_ATTRIBUTE_ARCHIVE O arquivo é um arquivo de arquivo morto. Os aplicativos usam esse atributo para marcar arquivos para backup ou remoção.

  • FILE_ATTRIBUTE_COMPRESSED O arquivo ou diretório é compactado. Para um arquivo, a compactação significa que todos os dados no arquivo são compactados. Para um diretório, a compactação é o padrão para arquivos e subdiretórios que acabam de ser criados.

  • FILE_ATTRIBUTE_DIRECTORY O arquivo é um diretório.

  • FILE_ATTRIBUTE_NORMAL O arquivo ou diretório não tem nenhum outro conjunto de atributos. Este atributo é válido apenas quando usado sozinho. Todos os outros atributos de arquivo substituem FILE_ATTRIBUTE_NORMAL:

  • FILE_ATTRIBUTE_HIDDEN O arquivo está oculto. Ele não deve ser incluído em uma listagem de diretórios comuns.

  • FILE_ATTRIBUTE_READONLY O arquivo é somente leitura. Os aplicativos podem ler o arquivo, mas não podem gravá-lo nem excluí-lo.

  • FILE_ATTRIBUTE_SYSTEM O arquivo faz parte do sistema operacional ou é usado exclusivamente pelo sistema operacional.

  • FILE_ATTRIBUTE_TEMPORARY O arquivo está sendo usado para armazenamento temporário. Os aplicativos devem gravar no arquivo somente se absolutamente necessário. A maioria dos dados do arquivo permanece na memória sem ser liberada para a mídia porque o arquivo será excluído em breve.

dwFlags
Especifica as condições sob as quais a transferência ocorre. Esse parâmetro pode ser qualquer um dos valores dwFlags descritos em FtpGetFile no SDK do Windows.

dwContext
O identificador de contexto para a recuperação de arquivo. Confira Comentários para obter mais informações sobre dwContext.

Valor de Devolução

Diferente de zero se tiver êxito; caso contrário, 0. Se a chamada falhar, a função Win32 GetLastError poderá ser chamada para determinar a causa do erro.

Comentários

GetFile é uma rotina de alto nível que lida com toda a sobrecarga associada à leitura de um arquivo de um servidor FTP e ao armazená-lo localmente. Os aplicativos que recuperam apenas dados de arquivo ou que exigem um controle forte sobre a transferência de arquivo devem usar OpenFile e CInternetFile::Read em vez disso.

Se dwFlags for FILE_TRANSFER_TYPE_ASCII, a conversão de dados de arquivo também converterá caracteres de controle e formatação em equivalentes do Windows. A transferência padrão é o modo binário, em que o arquivo é baixado no mesmo formato em que é armazenado no servidor.

Tanto pstrRemoteFile quanto pstrLocalFile podem ser nomes de arquivo parcialmente qualificados em relação ao diretório atual ou totalmente qualificados. Uma barra invertida (\) ou uma barra (/) pode ser usada como separador de diretório para qualquer nome. GetFile converte os separadores de nome de diretório nos caracteres apropriados antes de eles serem usados.

Substitua o padrão dwContext para definir um valor de sua escolha para o identificador de contexto. O identificador de contexto está associado a essa operação específica do objeto CFtpConnection criado por seu objeto CInternetSession. O valor é retornado para CInternetSession::OnStatusCallback para fornecer status na operação com a qual ele é identificado. Confira o artigo Primeiras etapas da Internet: WinInet para mais informações sobre o identificador de contexto.

CFtpConnection::OpenFile

Chame essa função de membro para abrir um arquivo localizado em um servidor FTP para leitura ou gravação.

CInternetFile* OpenFile(
    LPCTSTR pstrFileName,
    DWORD dwAccess = GENERIC_READ,
    DWORD dwFlags = FTP_TRANSFER_TYPE_BINARY,
    DWORD_PTR dwContext = 1);

Parâmetros

pstrFileName
Um ponteiro para uma cadeia de caracteres que contém o nome do arquivo a ser aberto.

dwAccess
Determina como o arquivo será acessado. Pode ser GENERIC_READ ou GENERIC_WRITE, mas não ambos.

dwFlags
Especifica as condições sob as quais ocorrem transferências subsequentes. Pode ser qualquer uma das seguintes constantes FTP_TRANSFER_*:

  • FTP_TRANSFER_TYPE_ASCII O arquivo é transferido usando o método de transferência FTP ASCII (Tipo A). Converte informações de controle e formatação em equivalentes locais.

  • FTP_TRANSFER_TYPE_BINARY O arquivo transfere dados usando o método de transferência de Imagem (Tipo I) do FTP. O arquivo transfere dados exatamente como existem, sem alterações. Esse é o método de transferência padrão.

dwContext
O identificador de contexto para abrir o arquivo. Confira Comentários para obter mais informações sobre dwContext.

Valor de Devolução

Um ponteiro para um objeto CInternetFile.

Comentários

OpenFile deve ser usado nas seguintes situações:

  • Um aplicativo tem dados que precisam ser enviados e criados como um arquivo no servidor FTP, mas esses dados não estão em um arquivo local. Depois de OpenFile abrir um arquivo, o aplicativo usará CInternetFile::Write para enviar os dados do arquivo FTP para o servidor.

  • Um aplicativo deve recuperar um arquivo do servidor e colocá-lo na memória controlada pelo aplicativo, em vez de gravá-lo em disco. O aplicativo usa CInternetFile::Read depois de usar OpenFile para abrir o arquivo.

  • Um aplicativo precisa de um bom nível de controle sobre uma transferência de arquivo. Por exemplo, o aplicativo pode querer exibir um controle de progresso indicando o progresso do status de transferência de arquivo ao baixar um arquivo.

Depois de chamar OpenFile e até chamarCInternetFile::Close, o aplicativo só pode chamar CInternetFile::Read, CInternetFile::Write, CInternetConnection::Close ou CFtpFileFind::FindFile. As chamadas para outras funções FTP para a mesma sessão FTP falharão e definirão o código de erro como FTP_ETRANSFER_IN_PROGRESS.

O parâmetro pstrFileName pode ser um nome de arquivo parcialmente qualificado em relação ao diretório atual ou totalmente qualificado. Uma barra invertida (\) ou uma barra (/) pode ser usada como separador de diretório para qualquer nome. OpenFile converte os separadores de nome de diretório nos caracteres apropriados antes de usá-los.

Substitua o padrão dwContext para definir um valor de sua escolha para o identificador de contexto. O identificador de contexto está associado a essa operação específica do objeto CFtpConnection criado por seu objeto CInternetSession. O valor é retornado para CInternetSession::OnStatusCallback para fornecer status na operação com a qual ele é identificado. Confira o artigo Primeiras etapas da Internet: WinInet para mais informações sobre o identificador de contexto.

CFtpConnection::PutFile

Chame essa função de membro para armazenar um arquivo em um servidor FTP.

BOOL PutFile(
    LPCTSTR pstrLocalFile,
    LPCTSTR pstrRemoteFile,
    DWORD dwFlags = FTP_TRANSFER_TYPE_BINARY,
    DWORD_PTR dwContext = 1);

Parâmetros

pstrLocalFile
Um ponteiro para uma cadeia de caracteres que contém o nome do arquivo a ser enviado do sistema local.

pstrRemoteFile
Um ponteiro para uma cadeia de caracteres que contém o nome do arquivo a ser criado no servidor FTP.

dwFlags
Especifica as condições sob as quais ocorre a transferência do arquivo. Pode ser qualquer uma das constantes FTP_TRANSFER_* descritas em OpenFile.

dwContext
O identificador de contexto para colocar o arquivo. Confira Comentários para obter mais informações sobre dwContext.

Valor de Devolução

Diferente de zero se tiver êxito; caso contrário, 0. Se a chamada falhar, a função Win32 GetLastError poderá ser chamada para determinar a causa do erro.

Comentários

PutFile é uma rotina de alto nível que manipula todas as operações associadas ao armazenamento de um arquivo em um servidor FTP. Os aplicativos que enviam apenas dados ou que exigem um controle mais forte sobre a transferência de arquivo devem usar OpenFile e CInternetFile::Write.

Substitua o padrão dwContext para definir o identificador de contexto como um valor de sua escolha. O identificador de contexto está associado a essa operação específica do objeto CFtpConnection criado por seu objeto CInternetSession. O valor é retornado para CInternetSession::OnStatusCallback para fornecer status na operação com a qual ele é identificado. Confira o artigo Primeiras etapas da Internet: WinInet para mais informações sobre o identificador de contexto.

CFtpConnection::Remove

Chame essa função de membro para excluir o arquivo especificado do servidor conectado.

BOOL Remove(LPCTSTR pstrFileName);

Parâmetros

pstrFileName
Um ponteiro para uma cadeia de caracteres que contém o nome do arquivo a ser removido.

Valor de Devolução

Diferente de zero se tiver êxito; caso contrário, 0. Se a chamada falhar, a função Win32 GetLastError poderá ser chamada para determinar a causa do erro.

Comentários

O parâmetro pstrFileName pode ser um nome de arquivo parcialmente qualificado em relação ao diretório atual ou totalmente qualificado. Uma barra invertida (\) ou uma barra (/) pode ser usada como separador de diretório para qualquer nome. A função Remove converte os separadores de nome do diretório nos caracteres apropriados antes de eles serem usados.

CFtpConnection::RemoveDirectory

Chame essa função de membro para remover o diretório especificado do servidor conectado.

BOOL RemoveDirectory(LPCTSTR pstrDirName);

Parâmetros

pstrDirName
Um ponteiro para uma cadeia de caracteres que contém o diretório a ser removido.

Valor de Devolução

Diferente de zero se tiver êxito; caso contrário, 0. Se a chamada falhar, a função Win32 GetLastError poderá ser chamada para determinar a causa do erro.

Comentários

Use GetCurrentDirectory para determinar o diretório de trabalho atual do servidor. Não suponha que o sistema remoto tenha conectado você ao diretório raiz.

O parâmetro pstrDirName pode ser um nome de arquivo parcial ou totalmente qualificado em relação ao diretório atual. Uma barra invertida (\) ou uma barra (/) pode ser usada como separador de diretório para qualquer nome. RemoveDirectory converte os separadores de nome de diretório nos caracteres apropriados antes de eles serem usados.

CFtpConnection::Rename

Chame essa função de membro para renomear o arquivo especificado no servidor conectado.

BOOL Rename(
    LPCTSTR pstrExisting,
    LPCTSTR pstrNew);

Parâmetros

pstrExisting
Um ponteiro para uma cadeia de caracteres que contém o nome atual do arquivo a ser renomeado.

pstrNew
Um ponteiro para uma cadeia de caracteres contendo o nome de um arquivo.

Valor de Devolução

Diferente de zero se tiver êxito; caso contrário, 0. Se a chamada falhar, a função Win32 GetLastError poderá ser chamada para determinar a causa do erro.

Comentários

Os parâmetros pstrExisting e pstrNew podem ser um nome de arquivo parcialmente qualificado em relação ao diretório atual ou totalmente qualificado. Uma barra invertida (\) ou uma barra (/) pode ser usada como separador de diretório para qualquer nome. Rename converte os separadores de nome de diretório nos caracteres apropriados antes de eles serem usados.

CFtpConnection::SetCurrentDirectory

Chame essa função de membro para alterar para um diretório diferente no servidor FTP.

BOOL SetCurrentDirectory(LPCTSTR pstrDirName);

Parâmetros

pstrDirName
Um ponteiro para uma cadeia de caracteres contendo o nome do diretório.

Valor de Devolução

Diferente de zero se tiver êxito; caso contrário, 0. Se a chamada falhar, a função Win32 GetLastError poderá ser chamada para determinar a causa do erro.

Comentários

O parâmetro pstrDirName pode ser um nome de arquivo parcial ou totalmente qualificado em relação ao diretório atual. Uma barra invertida (\) ou uma barra (/) pode ser usada como separador de diretório para qualquer nome. SetCurrentDirectory converte os separadores de nome de diretório nos caracteres apropriados antes de eles serem usados.

Use GetCurrentDirectory para determinar o diretório de trabalho atual do servidor FTP. Não suponha que o sistema remoto tenha conectado você ao diretório raiz.

Confira também

Classe CInternetConnection
Gráfico da hierarquia
Classe CInternetConnection
Classe CInternetSession