Condividi tramite

Classe CFtpConnection

  • Articolo

Gestisce la connessione FTP a un server Internet e consente la manipolazione diretta di directory e file in tale server.

Sintassi

class CFtpConnection : public CInternetConnection

Membri

Costruttori pubblici

Nome Descrizione
CFtpConnection::CFtpConnection Costruisce un oggetto CFtpConnection.

Metodi pubblici

Nome Descrizione
CFtpConnection::Command Invia un comando direttamente a un server FTP.
CFtpConnection::CreateDirectory Crea una directory nel server.
CFtpConnection::GetCurrentDirectory Ottiene la directory corrente per questa connessione.
CFtpConnection::GetCurrentDirectoryAsURL Ottiene la directory corrente per questa connessione come URL.
CFtpConnection::GetFile Ottiene un file dal server connesso
CFtpConnection::OpenFile Apre un file nel server connesso.
CFtpConnection::P utFile Inserisce un file nel server.
CFtpConnection::Remove Rimuove un file dal server.
CFtpConnection::RemoveDirectory Rimuove la directory specificata dal server.
CFtpConnection::Rename Rinomina un file nel server.
CFtpConnection::SetCurrentDirectory Imposta la directory FTP corrente.

Osservazioni:

FTP è uno dei tre servizi Internet riconosciuti dalle classi WinInet MFC.

Per comunicare con un server Internet FTP, è prima necessario creare un'istanza di CInternetSession e quindi creare un CFtpConnection oggetto . Non creare mai un CFtpConnection oggetto direttamente, invece, chiamare CInternetSession::GetFtpConnection, che crea l'oggetto CFtpConnection e restituisce un puntatore.

Per altre informazioni sul CFtpConnection funzionamento delle altre classi Internet MFC, vedere l'articolo Programmazione Internet con WinInet. Per altre informazioni sulla comunicazione con gli altri due servizi supportati, HTTP e gopher, vedere le classi CHttpConnection e CGopherConnection.

Esempio

Vedere l'esempio nella panoramica della classe CFtpFileFind .

Gerarchia di ereditarietà

CObject

CInternetConnection

CFtpConnection

Requisiti

Intestazione: afxinet.h

CFtpConnection::CFtpConnection

Questa funzione membro viene chiamata per costruire un CFtpConnection oggetto .

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);

Parametri

pSession
Puntatore all'oggetto CInternetSession correlato.

hConnected
Handle di Windows della sessione Internet corrente.

pstrServer
Puntatore a una stringa contenente il nome del server FTP.

dwContext
Identificatore di contesto per l'operazione . dwContext identifica le informazioni sullo stato dell'operazione restituite da CInternetSession::OnStatusCallback. Il valore predefinito è impostato su 1; Tuttavia, è possibile assegnare in modo esplicito un ID contesto specifico per l'operazione. L'oggetto e qualsiasi operazione eseguita verrà associato a tale ID contesto.

pstrUserName
Puntatore a una stringa con terminazione Null che specifica il nome dell'utente da accedere. Se NULL, il valore predefinito è anonimo.

pstrPassword
Puntatore a una stringa con terminazione Null che specifica la password da usare per l'accesso. Se pstrPassword e pstrUserName sono NULL, la password anonima predefinita è il nome di posta elettronica dell'utente. Se pstrPassword è NULL (o una stringa vuota) ma pstrUserName non è NULL, viene usata una password vuota. La tabella seguente descrive il comportamento per le quattro possibili impostazioni di pstrUserName e pstrPassword:

pstrUserName pstrPassword Nome utente inviato al server FTP Password inviata al server FTP
NULL o " " NULL o " " "anonimo" Nome di posta elettronica dell'utente
Stringa non NULL NULL o " " pstrUserName " "
Stringa NULL non NULL ERROR ERROR
Stringa non NULL Stringa non NULL pstrUserName pstrPassword

nPort
Numero che identifica la porta TCP/IP da usare nel server.

bPassive
Specifica la modalità passiva o attiva per questa sessione FTP. Se impostato su TRUE, imposta il dwFlag dell'API Win32 su INTERNET_FLAG_PASSIVE.

Osservazioni:

Non si crea mai direttamente un CFtpConnection oggetto. Chiamare invece CInternetSession::GetFtpConnection, che crea l'oggetto CFptConnection .

CFtpConnection::Command

Invia un comando direttamente a un server FTP.

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

Parametri

pszCommand
Puntatore a una stringa contenente il comando da inviare.

eResponse
Specifica se è prevista una risposta dal server FTP. I possibili valori sono i seguenti:

  • CmdRespNone Non è prevista alcuna risposta.
  • CmdRespRead È prevista una risposta.
  • CmdRespWrite Non utilizzato.

CmdResponseType è un membro di CFtpConnection, definito in afxinet.h.

dwFlags
Valore contenente i flag che controllano questa funzione. Per un elenco completo, vedere FTPCommand.

dwContext
Puntatore a un valore contenente un valore definito dall'applicazione usato per identificare il contesto dell'applicazione nei callback.

Valore restituito

Diverso da zero se ha esito positivo; in caso contrario 0.

Osservazioni:

Questa funzione membro emula la funzionalità della funzione FTPCommand , come descritto in Windows SDK.

Se si verifica un errore, MFC genera un'eccezione di tipo CInternetException.

CFtpConnection::CreateDirectory

Chiamare questa funzione membro per creare una directory nel server connesso.

BOOL CreateDirectory(LPCTSTR pstrDirName);

Parametri

pstrDirName
Puntatore a una stringa contenente il nome della directory da creare.

Valore restituito

Diverso da zero se ha esito positivo; in caso contrario 0. Se la chiamata non riesce, è possibile chiamare la funzione Windows GetLastError per determinare la causa dell'errore.

Osservazioni:

Utilizzare GetCurrentDirectory per determinare la directory di lavoro corrente per questa connessione al server. Non presupporre che il sistema remoto abbia connesso l'utente alla directory radice.

Il pstrDirName parametro può essere un nome file parzialmente o completo rispetto alla directory corrente. Una barra rovesciata (\) o una barra (/) può essere usata come separatore di directory per entrambi i nomi. CreateDirectory converte i separatori dei nomi di directory nei caratteri appropriati prima di essere usati.

CFtpConnection::GetCurrentDirectory

Chiamare questa funzione membro per ottenere il nome della directory corrente.

BOOL GetCurrentDirectory(CString& strDirName) const;

BOOL GetCurrentDirectory(
    LPTSTR pstrDirName,
    LPDWORD lpdwLen) const;

Parametri

strDirName
Riferimento a una stringa che riceverà il nome della directory.

pstrDirName
Puntatore a una stringa che riceverà il nome della directory.

lpdwLen
Puntatore a un DWORD contenente le informazioni seguenti:

Nella voce: dimensioni del buffer a cui fa riferimento pstrDirName.

In caso di restituzione: numero di caratteri archiviati in pstrDirName. Se la funzione membro ha esito negativo e ERROR_INSUFFICIENT_BUFFER viene restituito, lpdwLen contiene il numero di byte che l'applicazione deve allocare per ricevere la stringa.

Valore restituito

Diverso da zero se ha esito positivo; in caso contrario 0. Se la chiamata non riesce, è possibile chiamare la funzione Win32 GetLastError per determinare la causa dell'errore.

Osservazioni:

Per ottenere invece il nome della directory come URL, chiamare GetCurrentDirectoryAsURL.

I parametri pstrDirName o strDirName possono essere nomi file parzialmente qualificati rispetto alla directory corrente o completi. Una barra rovesciata (\) o una barra (/) può essere usata come separatore di directory per entrambi i nomi. GetCurrentDirectory converte i separatori dei nomi di directory nei caratteri appropriati prima di essere usati.

CFtpConnection::GetCurrentDirectoryAsURL

Chiamare questa funzione membro per ottenere il nome della directory corrente come URL.

BOOL GetCurrentDirectoryAsURL(CString& strDirName) const;

BOOL GetCurrentDirectoryAsURL(
    LPTSTR pstrName,
    LPDWORD lpdwLen) const;

Parametri

strDirName
Riferimento a una stringa che riceverà il nome della directory.

pstrDirName
Puntatore a una stringa che riceverà il nome della directory.

lpdwLen
Puntatore a un DWORD contenente le informazioni seguenti:

Nella voce: dimensioni del buffer a cui fa riferimento pstrDirName.

In caso di restituzione: numero di caratteri archiviati in pstrDirName. Se la funzione membro ha esito negativo e ERROR_INSUFFICIENT_BUFFER viene restituito, lpdwLen contiene il numero di byte che l'applicazione deve allocare per ricevere la stringa.

Valore restituito

Diverso da zero se ha esito positivo; in caso contrario 0. Se la chiamata non riesce, è possibile chiamare la funzione Win32 GetLastError per determinare la causa dell'errore.

Osservazioni:

GetCurrentDirectoryAsURL si comporta come GetCurrentDirectory

Il parametro strDirName può essere un nome file parzialmente qualificato rispetto alla directory corrente o completo. Una barra rovesciata (\) o una barra (/) può essere usata come separatore di directory per entrambi i nomi. GetCurrentDirectoryAsURL converte i separatori dei nomi di directory nei caratteri appropriati prima di essere usati.

CFtpConnection::GetFile

Chiamare questa funzione membro per ottenere un file da un server FTP e archiviarlo nel computer locale.

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

Parametri

pstrRemoteFile
Puntatore a una stringa con terminazione Null contenente il nome di un file da recuperare dal server FTP.

pstrLocalFile
Puntatore a una stringa con terminazione Null contenente il nome del file da creare nel sistema locale.

bFailIfExists
Indica se il nome del file può essere già utilizzato da un file esistente. Se il nome del file locale esiste già e questo parametro è TRUE, GetFile ha esito negativo. In caso contrario, GetFile cancellerà la copia esistente del file.

dwAttributes
Indica gli attributi del file. Può trattarsi di qualsiasi combinazione dei flag FILE_ATTRIBUTE_* seguenti.

  • FILE_ATTRIBUTE_ARCHIVE Il file è un file di archivio. Le applicazioni usano questo attributo per contrassegnare i file per il backup o la rimozione.

  • FILE_ATTRIBUTE_COMPRESSED Il file o la directory è compresso. Per un file, la compressione indica che tutti i dati nel file sono compressi. Per una directory, la compressione è l'impostazione predefinita per i file e le sottodirectory appena creati.

  • FILE_ATTRIBUTE_DIRECTORY Il file è una directory.

  • FILE_ATTRIBUTE_NORMAL Il file non ha altri attributi impostati. Questo attributo è valido solo se usato da solo. Tutti gli altri attributi di file sostituiscono FILE_ATTRIBUTE_NORMAL:

  • FILE_ATTRIBUTE_HIDDEN Il file è nascosto. Non deve essere incluso in un elenco di directory normale.

  • FILE_ATTRIBUTE_READONLY Il file è di sola lettura. Le applicazioni possono leggere il file, ma non possono scriverlo o eliminarlo.

  • FILE_ATTRIBUTE_SYSTEM Il file fa parte di o viene utilizzato esclusivamente dal sistema operativo.

  • FILE_ATTRIBUTE_TEMPORARY Il file viene usato per l'archiviazione temporanea. Le applicazioni devono scrivere nel file solo se assolutamente necessario. La maggior parte dei dati del file rimane in memoria senza essere scaricata nel supporto perché il file verrà presto eliminato.

dwFlags
Specifica le condizioni in base alle quali si verifica il trasferimento. Questo parametro può essere uno dei valori dwFlags descritti in FtpGetFile in Windows SDK.

dwContext
Identificatore di contesto per il recupero del file. Per altre informazioni su dwContext, vedere Osservazioni.

Valore restituito

Diverso da zero se ha esito positivo; in caso contrario 0. Se la chiamata non riesce, è possibile chiamare la funzione Win32 GetLastError per determinare la causa dell'errore.

Osservazioni:

GetFile è una routine di alto livello che gestisce tutto l'overhead associato alla lettura di un file da un server FTP e all'archiviazione locale. Le applicazioni che recuperano solo i dati dei file o che richiedono un controllo di chiusura sul trasferimento del file devono usare OpenFile e CInternetFile::Read .

Se dwFlags è FILE_TRANSFER_TYPE_ASCII, la conversione dei dati di file converte anche i caratteri di controllo e formattazione in equivalenti di Windows. Il trasferimento predefinito è la modalità binaria, in cui il file viene scaricato nello stesso formato archiviato nel server.

Sia pstrRemoteFile che pstrLocalFile possono essere nomi file parzialmente qualificati rispetto alla directory corrente o completi. Una barra rovesciata (\) o una barra (/) può essere usata come separatore di directory per entrambi i nomi. GetFile converte i separatori dei nomi di directory nei caratteri appropriati prima di essere usati.

Eseguire l'override dell'impostazione predefinita dwContext per impostare l'identificatore di contesto su un valore scelto. L'identificatore di contesto è associato a questa operazione specifica dell'oggetto CFtpConnection creato dal relativo oggetto CInternetSession . Il valore viene restituito a CInternetSession::OnStatusCallback per fornire lo stato sull'operazione con cui viene identificato. Per altre informazioni sull'identificatore di contesto, vedere l'articolo Passaggi preliminari su Internet: WinInet .

CFtpConnection::OpenFile

Chiamare questa funzione membro per aprire un file che si trova in un server FTP per la lettura o la scrittura.

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

Parametri

pstrFileName
Puntatore a una stringa contenente il nome del file da aprire.

dwAccess
Determina la modalità di accesso al file. Può essere GENERIC_READ o GENERIC_WRITE, ma non entrambi.

dwFlags
Specifica le condizioni in base alle quali si verificano i trasferimenti successivi. Può trattarsi di una delle seguenti costanti FTP_TRANSFER_*:

  • FTP_TRANSFER_TYPE_ASCII Il file viene trasferito utilizzando il metodo di trasferimento FTP ASCII (Type A). Converte le informazioni di controllo e formattazione in equivalenti locali.

  • FTP_TRANSFER_TYPE_BINARY Il file trasferisce i dati usando il metodo di trasferimento Image (Type I) ftp. Il file trasferisce i dati esattamente come esistono, senza modifiche. Si tratta del metodo di trasferimento predefinito.

dwContext
Identificatore di contesto per l'apertura del file. Per altre informazioni su dwContext, vedere Osservazioni.

Valore restituito

Puntatore a un oggetto CInternetFile .

Osservazioni:

OpenFile deve essere usato nelle situazioni seguenti:

  • Un'applicazione dispone di dati che devono essere inviati e creati come file nel server FTP, ma che non si trovano in un file locale. Una volta OpenFile aperto un file, l'applicazione usa CInternetFile::Write per inviare i dati del file FTP al server.

  • Un'applicazione deve recuperare un file dal server e inserirlo nella memoria controllata dall'applicazione, anziché scriverlo su disco. L'applicazione usa CInternetFile::Read dopo aver usato OpenFile per aprire il file.

  • Un'applicazione richiede un livello di controllo fine su un trasferimento di file. Ad esempio, l'applicazione potrebbe voler visualizzare un controllo di stato indica lo stato di avanzamento del trasferimento del file durante il download di un file.

Dopo aver chiamato OpenFile e finché non si chiama CInternetFile::Close, l'applicazione può chiamare solo CInternetFile::Read, CInternetFile::Write, CInternetConnection::Closeo CFtpFileFind::FindFile. Le chiamate ad altre funzioni FTP per la stessa sessione FTP avranno esito negativo e impostano il codice di errore su FTP_ETRANSFER_IN_PROGRESS.

Il parametro pstrFileName può essere un nome file parzialmente qualificato rispetto alla directory corrente o completo. Una barra rovesciata (\) o una barra (/) può essere usata come separatore di directory per entrambi i nomi. OpenFile converte i separatori dei nomi di directory nei caratteri appropriati prima di usarlo.

Eseguire l'override dell'impostazione predefinita dwContext per impostare l'identificatore di contesto su un valore scelto. L'identificatore di contesto è associato a questa operazione specifica dell'oggetto CFtpConnection creato dal relativo oggetto CInternetSession . Il valore viene restituito a CInternetSession::OnStatusCallback per fornire lo stato sull'operazione con cui viene identificato. Per altre informazioni sull'identificatore di contesto, vedere l'articolo Passaggi preliminari su Internet: WinInet .

CFtpConnection::P utFile

Chiamare questa funzione membro per archiviare un file in un server FTP.

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

Parametri

pstrLocalFile
Puntatore a una stringa contenente il nome del file da inviare dal sistema locale.

pstrRemoteFile
Puntatore a una stringa contenente il nome del file da creare nel server FTP.

dwFlags
Specifica le condizioni in base alle quali si verifica il trasferimento del file. Può essere una delle costanti FTP_TRANSFER_* descritte in OpenFile.

dwContext
Identificatore di contesto per l'inserimento del file. Per altre informazioni su dwContext, vedere Osservazioni.

Valore restituito

Diverso da zero se ha esito positivo; in caso contrario 0. Se la chiamata non riesce, è possibile chiamare la funzione Win32 GetLastError per determinare la causa dell'errore.

Osservazioni:

PutFile è una routine di alto livello che gestisce tutte le operazioni associate all'archiviazione di un file in un server FTP. Le applicazioni che inviano solo dati o che richiedono un maggiore controllo sul trasferimento dei file devono usare OpenFile e CInternetFile::Write.

Esegue l'override dell'impostazione predefinita dwContext per impostare l'identificatore di contesto su un valore di propria scelta. L'identificatore di contesto è associato a questa operazione specifica dell'oggetto CFtpConnection creato dal relativo oggetto CInternetSession . Il valore viene restituito a CInternetSession::OnStatusCallback per fornire lo stato sull'operazione con cui viene identificato. Per altre informazioni sull'identificatore di contesto, vedere l'articolo Passaggi preliminari su Internet: WinInet .

CFtpConnection::Remove

Chiamare questa funzione membro per eliminare il file specificato dal server connesso.

BOOL Remove(LPCTSTR pstrFileName);

Parametri

pstrFileName
Puntatore a una stringa contenente il nome del file da rimuovere.

Valore restituito

Diverso da zero se ha esito positivo; in caso contrario 0. Se la chiamata non riesce, è possibile chiamare la funzione Win32 GetLastError per determinare la causa dell'errore.

Osservazioni:

Il parametro pstrFileName può essere un nome file parzialmente qualificato rispetto alla directory corrente o completo. Una barra rovesciata (\) o una barra (/) può essere usata come separatore di directory per entrambi i nomi. La Remove funzione converte i separatori dei nomi di directory nei caratteri appropriati prima di essere usati.

CFtpConnection::RemoveDirectory

Chiamare questa funzione membro per rimuovere la directory specificata dal server connesso.

BOOL RemoveDirectory(LPCTSTR pstrDirName);

Parametri

pstrDirName
Puntatore a una stringa contenente la directory da rimuovere.

Valore restituito

Diverso da zero se ha esito positivo; in caso contrario 0. Se la chiamata non riesce, è possibile chiamare la funzione Win32 GetLastError per determinare la causa dell'errore.

Osservazioni:

Usare GetCurrentDirectory per determinare la directory di lavoro corrente del server. Non presupporre che il sistema remoto abbia connesso l'utente alla directory radice.

Il parametro pstrDirName può essere un nome file parzialmente o completo rispetto alla directory corrente. Una barra rovesciata (\) o una barra (/) può essere usata come separatore di directory per entrambi i nomi. RemoveDirectory converte i separatori dei nomi di directory nei caratteri appropriati prima di essere usati.

CFtpConnection::Rename

Chiamare questa funzione membro per rinominare il file specificato nel server connesso.

BOOL Rename(
    LPCTSTR pstrExisting,
    LPCTSTR pstrNew);

Parametri

pstrExisting
Puntatore a una stringa contenente il nome corrente del file da rinominare.

pstrNew
Puntatore a una stringa contenente il nuovo nome del file.

Valore restituito

Diverso da zero se ha esito positivo; in caso contrario 0. Se la chiamata non riesce, è possibile chiamare la funzione Win32 GetLastError per determinare la causa dell'errore.

Osservazioni:

I parametri pstrExisting e pstrNew possono essere un nome file parzialmente qualificato rispetto alla directory corrente o completo. Una barra rovesciata (\) o una barra (/) può essere usata come separatore di directory per entrambi i nomi. Rename converte i separatori dei nomi di directory nei caratteri appropriati prima di essere usati.

CFtpConnection::SetCurrentDirectory

Chiamare questa funzione membro per passare a una directory diversa nel server FTP.

BOOL SetCurrentDirectory(LPCTSTR pstrDirName);

Parametri

pstrDirName
Puntatore a una stringa contenente il nome della directory.

Valore restituito

Diverso da zero se ha esito positivo; in caso contrario 0. Se la chiamata non riesce, è possibile chiamare la funzione Win32 GetLastError per determinare la causa dell'errore.

Osservazioni:

Il parametro pstrDirName può essere un nome file parzialmente o completo rispetto alla directory corrente. Una barra rovesciata (\) o una barra (/) può essere usata come separatore di directory per entrambi i nomi. SetCurrentDirectory converte i separatori dei nomi di directory nei caratteri appropriati prima di essere usati.

Usare GetCurrentDirectory per determinare la directory di lavoro corrente di un server FTP. Non presupporre che il sistema remoto abbia connesso l'utente alla directory radice.

Vedi anche

Classe CInternetConnection
Grafico della gerarchia
Classe CInternetConnection
Classe CInternetSession