Classe CFtpConnection

Gere a sua ligação FTP a um servidor de Internet e permite a manipulação direta de diretórios e ficheiros nesse servidor.

Sintaxe

class CFtpConnection : public CInternetConnection

Membros

Construtores Públicos

Métodos Públicos

Observações

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

Para comunicar com um servidor FTP na Internet, deve primeiro criar uma instância de CIntinternetSession e, em seguida, criar um CFtpConnection objeto. Nunca crias um CFtpConnection objeto diretamente; em vez disso, chamas CInternetSession::GetFtpConnection, que cria o CFtpConnection objeto e devolve um ponteiro para ele.

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

Example

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

Hierarquia de herança

CObject

Conexão Cinternet

CFtpConnection

Requerimentos

Cabeçalho: afxinet.h

CFtpConnection::CFtpConnection

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

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
Um ponteiro para o objeto relacionado CInternetSession .

hLigado
O handle do Windows da sessão atual da Internet.

pstrServer
Um apontador para uma string contendo o nome do servidor FTP.

dwContext
O identificador de contexto da operação. dwContext identifica a informação de estado da operação devolvida por CInternetSession::OnStatusCallback. O padrão é definido para 1; no entanto, pode atribuir explicitamente um ID de contexto específico para a operação. O objeto e qualquer trabalho que ele faça estarão associados a esse ID de contexto.

pstrUserName
Apontador para uma cadeia terminada por null que especifica o nome do utilizador a iniciar sessão. Se for NULL, o padrão é anónimo.

pstrPassword
Um ponteiro para uma cadeia terminada por null que especifica a palavra-passe a usar para iniciar sessão. Se tanto pstrPassword como pstrUserName forem NULL, a palavra-passe anónima padrão é o nome de email do utilizador. Se pstrPassword for NULL (ou uma cadeia vazia) mas pstrUserName não for NULL, usa-se uma palavra-passe em branco. A tabela seguinte descreve o comportamento para as quatro possíveis definições de pstrUserName e pstrPassword:

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

bPassiva
Especifica modo passivo ou ativo para esta sessão FTP. Se definido para TRUE, define a API dwFlag do Win32 para INTERNET_FLAG_PASSIVE.

Observações

Nunca se cria um CFtpConnection objeto diretamente. Em vez disso, chame CInternetSession::GetFtpConnection, que cria o CFptConnection objeto.

CFtpConnection::Comando

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 apontador para uma cadeia que contém o comando a enviar.

eResposta
Especifica se se espera uma resposta do servidor FTP. Pode ser um dos seguintes valores:

• CmdRespNone Não se espera resposta.
• CmdRespRead Espera-se uma resposta.
• CmdRespWrite Não utilizado.

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

dwBandeiras
Um valor que contém as bandeiras que controlam esta função. Para uma lista completa, consulte FTPCommand.

dwContext
Um ponteiro para um valor contendo um valor definido pela aplicação usado para identificar o contexto da aplicação em callbacks.

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, 0.

Observações

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

Se ocorrer um erro, o MFC lança uma exceção do tipo CInternetException.

CFtpConnection::CreateDirectory

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

BOOL CreateDirectory(LPCTSTR pstrDirName);

Parâmetros

pstrDirName
Um ponteiro para uma string contendo o nome do diretório a criar.

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, 0. Se a chamada falhar, pode ser chamada a função GetLastError do Windows para determinar a causa do erro.

Observações

GetCurrentDirectory Use para determinar o diretório funcional atual desta ligação ao servidor. Não presuma que o sistema remoto o ligou à diretoria raiz.

O pstrDirName parâmetro pode ser um nome de ficheiro parcial ou totalmente qualificado em relação ao diretório atual. Uma barra inversa (\) ou barra para a frente (/) pode ser usada como separador de diretórios para qualquer um dos nomes. CreateDirectory traduz os separadores de nomes de diretório para os caracteres apropriados antes de serem usados.

CFtpConnection::GetCurrentDirectory

Chame esta função 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 que receberá o nome do diretório.

pstrDirName
Um apontador para uma string que receberá o nome do diretório.

lpdwLen
Um apontador para um DWORD que contém a seguinte informação:

Na entrada: O tamanho do buffer referenciado por pstrDirName.

No retorno: O número de caracteres armazenados em pstrDirName. Se a função membro falhar e ERROR_INSUFFICIENT_BUFFER for devolvido, então lpdwLen contém o número de bytes que a aplicação deve alocar para receber a cadeia.

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, 0. Se a chamada falhar, pode ser chamada a função Win32 GetLastError para determinar a causa do erro.

Observações

Para obter o nome do diretório como URL, ligue para GetCurrentDirectoryAsURL.

Os parâmetros pstrDirName ou strDirName podem ser nomes de ficheiros parcialmente qualificados em relação ao diretório atual ou totalmente qualificados. Uma barra inversa (\) ou barra para a frente (/) pode ser usada como separador de diretórios para qualquer um dos nomes. GetCurrentDirectory traduz os separadores de nomes de diretório para os caracteres apropriados antes de serem usados.

CFtpConnection::GetCurrentDirectoryAsURL

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

BOOL GetCurrentDirectoryAsURL(CString& strDirName) const;

BOOL GetCurrentDirectoryAsURL(
    LPTSTR pstrName,
    LPDWORD lpdwLen) const;

Parâmetros

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

pstrDirName
Um apontador para uma string que receberá o nome do diretório.

lpdwLen
Um apontador para um DWORD que contém a seguinte informação:

Na entrada: O tamanho do buffer referenciado por pstrDirName.

No retorno: O número de caracteres armazenados em pstrDirName. Se a função membro falhar e ERROR_INSUFFICIENT_BUFFER for devolvido, então lpdwLen contém o número de bytes que a aplicação deve alocar para receber a cadeia.

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, 0. Se a chamada falhar, pode ser chamada a função Win32 GetLastError para determinar a causa do erro.

Observações

GetCurrentDirectoryAsURL comporta-se da mesma forma que o GetCurrentDirectory

O parâmetro strDirName pode ser nomes de ficheiros parcialmente qualificados em relação ao diretório atual ou totalmente qualificados. Uma barra inversa (\) ou barra para a frente (/) pode ser usada como separador de diretórios para qualquer um dos nomes. GetCurrentDirectoryAsURL traduz os separadores de nomes de diretório para os caracteres apropriados antes de serem usados.

CFtpConnection::GetFile

Chame esta função membro para obter um ficheiro de um servidor FTP e armazená-lo na máquina 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 apontador para uma cadeia terminada em null contendo o nome de um ficheiro para recuperar do servidor FTP.

pstrLocalFile
Um ponteiro para uma cadeia terminada por null contendo o nome do ficheiro a criar no sistema local.

bFalhaSeExistir
Indica se o nome do ficheiro já pode ser usado por um ficheiro existente. Se o nome local do ficheiro já existir, e este parâmetro for VERDADEIRO, GetFile falha. Caso contrário, GetFile apagará a cópia existente do ficheiro.

dwAttributes
Indica os atributos do ficheiro. Isto pode ser qualquer combinação das seguintes FILE_ATTRIBUTE_* bandeiras.

• FILE_ATTRIBUTE_ARCHIVE O ficheiro é um ficheiro de arquivo. As aplicações usam este atributo para marcar ficheiros para backup ou remoção.

• FILE_ATTRIBUTE_COMPRESSED O ficheiro ou diretório é comprimido. Para um ficheiro, compressão significa que todos os dados do ficheiro são comprimidos. Para um diretório, a compactação é o padrão para arquivos e subdiretórios recém-criados.

• FILE_ATTRIBUTE_DIRECTORY O ficheiro é um diretório.

• FILE_ATTRIBUTE_NORMAL O ficheiro não tem outros atributos definidos. Este atributo é válido apenas se usado isoladamente. Todos os outros atributos do ficheiro sobrepõem-se FILE_ATTRIBUTE_NORMAL:

• FILE_ATTRIBUTE_HIDDEN O ficheiro está escondido. Não deve ser incluído numa lista de diretórios comum.

• FILE_ATTRIBUTE_READONLY O ficheiro é apenas de leitura. As aplicações podem ler o ficheiro, mas não podem escrever nele nem apagá-lo.

• FILE_ATTRIBUTE_SYSTEM O ficheiro faz parte ou é usado exclusivamente pelo sistema operativo.

• FILE_ATTRIBUTE_TEMPORARY O ficheiro está a ser usado para armazenamento temporário. As aplicações devem escrever no ficheiro apenas se for absolutamente necessário. A maior parte dos dados do ficheiro permanece na memória sem ser esvaziada para o suporte, pois o ficheiro será rapidamente eliminado.

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

dwContext
O identificador de contexto para a recuperação do ficheiro. Consulte Observações para mais informações sobre dwContext.

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, 0. Se a chamada falhar, pode ser chamada a função Win32 GetLastError para determinar a causa do erro.

Observações

GetFile é uma rotina de alto nível que gere toda a sobrecarga associada à leitura de um ficheiro de um servidor FTP e ao seu armazenamento localmente. Aplicações que apenas recuperam dados de ficheiros, ou que exigem controlo próximo sobre a transferência de ficheiros, devem usar OpenFile em vez disso um CInternetFile::Read .

Se o dwFlags for FILE_TRANSFER_TYPE_ASCII, a tradução dos dados do ficheiro também converte caracteres de controlo e formatação para equivalentes no Windows. A transferência por defeito é o modo binário, onde o ficheiro é descarregado no mesmo formato em que é armazenado no servidor.

Tanto o pstrRemoteFile como o pstrLocalFile podem ser nomes de ficheiros parcialmente qualificados em relação ao diretório atual ou totalmente qualificados. Uma barra inversa (\) ou barra para a frente (/) pode ser usada como separador de diretórios para qualquer um dos nomes. GetFile traduz os separadores de nomes de diretório para os caracteres apropriados antes de serem usados.

Substitua o padrão dwContext para definir o identificador de contexto para um valor à sua escolha. O identificador de contexto está associado a esta operação específica do CFtpConnection objeto criada pelo seu objeto CInternetSession . O valor é devolvido ao CInternetSession::OnStatusCallback para fornecer o estado da operação com a qual foi identificado. Consulte o artigo Internet First Steps: WinInet para mais informações sobre o identificador de contexto.

CFtpConnection::OpenFile

Chame esta função membro para abrir um ficheiro localizado num servidor FTP para leitura ou escrita.

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 string contendo o nome do ficheiro a ser aberto.

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

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

• FTP_TRANSFER_TYPE_ASCII O ficheiro é transferido usando o método FTP ASCII (Tipo A). Converte informações de controlo e formatação para equivalentes locais.

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

dwContext
O identificador de contexto para abrir o ficheiro. Consulte Observações para mais informações sobre dwContext.

Valor de retorno

Um ponteiro para um objeto CInternetFile .

Observações

OpenFile devem ser usados nas seguintes situações:

• Uma aplicação tem dados que precisam de ser enviados e criados como ficheiro no servidor FTP, mas esses dados não estão num ficheiro local. Uma vez OpenFile aberto um ficheiro, a aplicação utiliza CInternetFile::Write para enviar os dados do ficheiro FTP para o servidor.

• Uma aplicação deve recuperar um ficheiro do servidor e colocá-lo na memória controlada pela aplicação, em vez de o gravar no disco. A aplicação utiliza o CInternetFile::Read após o uso OpenFile para abrir o ficheiro.

• Uma aplicação precisa de um nível fino de controlo sobre uma transferência de ficheiros. Por exemplo, a aplicação pode querer mostrar um controlo de progresso que indica o progresso do estado da transferência de ficheiros durante o download de um ficheiro.

Após chamar OpenFile e até chamar CInternetFile::Close, a aplicação só pode chamar CInternetFile::Read, CInternetFile::Write, CInternetConnection::Close, ou CFtpFileFind::FindFile. Chamadas a outras funções FTP para a mesma sessão FTP falham e o código de erro é definido para FTP_ETRANSFER_IN_PROGRESS.

O parâmetro pstrFileName pode ser um nome de ficheiro parcialmente qualificado em relação ao diretório atual ou totalmente qualificado. Uma barra inversa (\) ou barra para a frente (/) pode ser usada como separador de diretórios para qualquer um dos nomes. OpenFile traduz os separadores de nomes do diretório para os caracteres apropriados antes de o utilizar.

Substitua o padrão dwContext para definir o identificador de contexto para um valor à sua escolha. O identificador de contexto está associado a esta operação específica do CFtpConnection objeto criada pelo seu objeto CInternetSession . O valor é devolvido ao CInternetSession::OnStatusCallback para fornecer o estado da operação com a qual foi identificado. Consulte o artigo Internet First Steps: WinInet para mais informações sobre o identificador de contexto.

CFtpConnection::P utFile

Chame esta função membro para armazenar um ficheiro num servidor FTP.

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

Parâmetros

pstrLocalFile
Um apontador para uma string contendo o nome do ficheiro a enviar a partir do sistema local.

pstrRemoteFile
Um ponteiro para uma string contendo o nome do ficheiro a criar no servidor FTP.

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

dwContext
O identificador de contexto para colocar o ficheiro. Consulte Observações para mais informações sobre dwContext.

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, 0. Se a chamada falhar, pode ser chamada a função Win32 GetLastError para determinar a causa do erro.

Observações

PutFile é uma rotina de alto nível que gere todas as operações associadas ao armazenamento de um ficheiro num servidor FTP. Aplicações que apenas enviam dados, ou que exigem controlo mais próximo da transferência de ficheiros, devem usar OpenFile e CInternetFile::Write.

Substitua o dwContext padrão para definir o identificador de contexto para um valor à sua escolha. O identificador de contexto está associado a esta operação específica do CFtpConnection objeto criada pelo seu objeto CInternetSession . O valor é devolvido ao CInternetSession::OnStatusCallback para fornecer o estado da operação com a qual foi identificado. Consulte o artigo Internet First Steps: WinInet para mais informações sobre o identificador de contexto.

CFtpConnection::Remover

Chame esta função membro para eliminar o ficheiro especificado do servidor ligado.

BOOL Remove(LPCTSTR pstrFileName);

Parâmetros

pstrFileName
Um apontador para uma string contendo o nome do ficheiro a remover.

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, 0. Se a chamada falhar, pode ser chamada a função Win32 GetLastError para determinar a causa do erro.

Observações

O parâmetro pstrFileName pode ser um nome de ficheiro parcialmente qualificado em relação ao diretório atual ou totalmente qualificado. Uma barra inversa (\) ou barra para a frente (/) pode ser usada como separador de diretórios para qualquer um dos nomes. A Remove função traduz os separadores de nomes de diretórios para os caracteres apropriados antes de serem utilizados.

CFtpConnection::RemoveDirectory

Chame esta função membro para remover o diretório especificado do servidor ligado.

BOOL RemoveDirectory(LPCTSTR pstrDirName);

Parâmetros

pstrDirName
Um apontador para uma string contendo o diretório a ser removido.

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, 0. Se a chamada falhar, pode ser chamada a função Win32 GetLastError para determinar a causa do erro.

Observações

Use o GetCurrentDirectory para determinar o diretório atual de funcionamento do servidor. Não presuma que o sistema remoto o ligou à diretoria raiz.

O parâmetro pstrDirName pode ser um nome de ficheiro parcial ou totalmente qualificado em relação ao diretório atual. Uma barra inversa (\) ou barra para a frente (/) pode ser usada como separador de diretórios para qualquer um dos nomes. RemoveDirectory traduz os separadores de nomes de diretório para os caracteres apropriados antes de serem usados.

CFtpConnection::Renomeação

Chame esta função membro para renomear o ficheiro especificado no servidor conectado.

BOOL Rename(
    LPCTSTR pstrExisting,
    LPCTSTR pstrNew);

Parâmetros

pstrExisting
Um ponteiro para uma string contendo o nome atual do ficheiro a ser renomeado.

pstrNew
Um apontador para uma string contendo o novo nome do ficheiro.

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, 0. Se a chamada falhar, pode ser chamada a função Win32 GetLastError para determinar a causa do erro.

Observações

Os parâmetros pstrExisting e pstrNew podem ser um nome de ficheiro parcialmente qualificado em relação ao diretório atual ou totalmente qualificados. Uma barra inversa (\) ou barra para a frente (/) pode ser usada como separador de diretórios para qualquer um dos nomes. Rename traduz os separadores de nomes de diretório para os caracteres apropriados antes de serem usados.

CFtpConnection::SetCurrentDirectory

Chame esta função membro para mudar para um diretório diferente no servidor FTP.

BOOL SetCurrentDirectory(LPCTSTR pstrDirName);

Parâmetros

pstrDirName
Um ponteiro para uma string contendo o nome do diretório.

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, 0. Se a chamada falhar, pode ser chamada a função Win32 GetLastError para determinar a causa do erro.

Observações

O parâmetro pstrDirName pode ser um nome de ficheiro parcial ou totalmente qualificado em relação ao diretório atual. Uma barra inversa (\) ou barra para a frente (/) pode ser usada como separador de diretórios para qualquer um dos nomes. SetCurrentDirectory traduz os separadores de nomes de diretório para os caracteres apropriados antes de serem usados.

Use o GetCurrentDirectory para determinar o diretório atual de funcionamento de um servidor FTP. Não presuma que o sistema remoto o ligou à diretoria raiz.

Consulte também

Classe CInternetConnection
Gráfico de Hierarquia
Classe CInternetConnection
Classe CInternetSession