CFtpConnection – třída
Spravuje připojení FTP k internetovému serveru a umožňuje přímou manipulaci s adresáři a soubory na daném serveru.
Syntaxe
class CFtpConnection : public CInternetConnection
Členové
Veřejné konstruktory
Název | Popis |
---|---|
CFtpConnection::CFtpConnection | CFtpConnection Vytvoří objekt. |
Veřejné metody
Název | Popis |
---|---|
CFtpConnection::Command | Odešle příkaz přímo na server FTP. |
CFtpConnection::CreateDirectory | Vytvoří adresář na serveru. |
CFtpConnection::GetCurrentDirectory | Získá aktuální adresář pro toto připojení. |
CFtpConnection::GetCurrentDirectoryAsURL | Získá aktuální adresář pro toto připojení jako adresu URL. |
CFtpConnection::GetFile | Získá soubor z připojeného serveru. |
CFtpConnection::OpenFile | Otevře soubor na připojeném serveru. |
CFtpConnection::P utFile | Umístí soubor na server. |
CFtpConnection::Remove | Odebere soubor ze serveru. |
CFtpConnection::RemoveDirectory | Odebere zadaný adresář ze serveru. |
CFtpConnection::Rename | Přejmenuje soubor na serveru. |
CFtpConnection::SetCurrentDirectory | Nastaví aktuální adresář FTP. |
Poznámky
FTP je jednou ze tří internetových služeb rozpoznaných třídami winInet mfc.
Pokud chcete komunikovat s internetovým serverem FTP, musíte nejprve vytvořit instanci CInternetSession a pak vytvořit CFtpConnection
objekt. Nikdy nevytvoříte CFtpConnection
objekt přímo; místo toho zavolejte CInternetSession::GetFtpConnection, který objekt vytvoří CFtpConnection
a vrátí ukazatel na něj.
Další informace o tom, jak CFtpConnection
funguje s ostatními internetovými třídami MFC, najdete v článku Internetové programování pomocí winInetu. Další informace o komunikaci s dalšími dvěma podporovanými službami, HTTP a gopher, najdete v třídách CHttpConnection a CGopherConnection.
Příklad
Podívejte se na příklad v přehledu třídy CFtpFileFind .
Hierarchie dědičnosti
CFtpConnection
Požadavky
Hlavička: afxinet.h
CFtpConnection::CFtpConnection
Tato členová funkce je volána k vytvoření objektu 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);
Parametry
PSession
Ukazatel na související objekt CInternetSession .
hConnected
Popisovač Windows aktuální internetové relace.
pstrServer
Ukazatel na řetězec obsahující název serveru FTP.
dwContext
Identifikátor kontextu operace. dwContext identifikuje informace o stavu operace vrácené CInternetSession::OnStatusCallback. Výchozí hodnota je nastavená na hodnotu 1; Pro operaci však můžete explicitně přiřadit konkrétní ID kontextu. Objekt a jakákoli práce, kterou provede, se přidružuje k danému ID kontextu.
pstrUserName
Ukazatel na řetězec ukončený hodnotou null, který určuje jméno uživatele, který se má přihlásit. Pokud má hodnotu NULL, výchozí hodnota je anonymní.
pstrPassword
Ukazatel na řetězec ukončený hodnotou null, který určuje heslo, které se má použít pro přihlášení. Pokud jsou hodnoty pstrPassword i pstrUserName null, výchozí anonymní heslo je e-mailové jméno uživatele. Pokud je pstrPassword NULL (nebo prázdný řetězec), ale pstrUserName není NULL, použije se prázdné heslo. Následující tabulka popisuje chování čtyř možných nastavení pstrUserName a pstrPassword:
pstrUserName | pstrPassword | Uživatelské jméno odeslané na server FTP | Heslo odeslané na server FTP |
---|---|---|---|
NULL nebo " | NULL nebo " | "anonymní" | E-mailové jméno uživatele |
Řetězec bez hodnoty NULL | NULL nebo " | pstrUserName | " " |
Řetězec null bez hodnoty NULL | CHYBA | CHYBA | |
Řetězec bez hodnoty NULL | Řetězec bez hodnoty NULL | pstrUserName | pstrPassword |
nPort
Číslo, které identifikuje port TCP/IP, který se má použít na serveru.
bPassive
Určuje pasivní nebo aktivní režim pro tuto relaci FTP. Pokud je nastavená hodnota TRUE, nastaví dwFlag rozhraní API Win32 na INTERNET_FLAG_PASSIVE.
Poznámky
Nikdy nevytvoříte CFtpConnection
objekt přímo. Místo toho volejte CInternetSession::GetFtpConnection, který vytvoří CFptConnection
objekt.
CFtpConnection::Command
Odešle příkaz přímo na server FTP.
CInternetFile* Command(
LPCTSTR pszCommand,
CmdResponseType eResponse = CmdRespNone,
DWORD dwFlags = FTP_TRANSFER_TYPE_BINARY,
DWORD_PTR dwContext = 1);
Parametry
pszCommand
Ukazatel na řetězec obsahující příkaz, který se má odeslat.
eResponse
Určuje, jestli se od serveru FTP očekává odpověď. Může to být jedna z následujících hodnot:
CmdRespNone
Neočekává se žádná odpověď.CmdRespRead
Očekává se odpověď.CmdRespWrite
Nepoužívá se.
CmdResponseType je člen CFtpConnection definovaný v afxinet.h.
dwFlags
Hodnota obsahující příznaky, které řídí tuto funkci. Úplný seznam najdete v tématu FTPCommand.
dwContext
Ukazatel na hodnotu obsahující hodnotu definovanou aplikací, která se používá k identifikaci kontextu aplikace v zpětných voláních.
Návratová hodnota
Nenulové, pokud je úspěšné; jinak 0.
Poznámky
Tato členová funkce emuluje funkci FTPCommand , jak je popsáno v sadě Windows SDK.
Pokud dojde k chybě, MFC vyvolá výjimku typu CInternetException.
CFtpConnection::CreateDirectory
Voláním této členské funkce vytvořte adresář na připojeném serveru.
BOOL CreateDirectory(LPCTSTR pstrDirName);
Parametry
pstrDirName
Ukazatel na řetězec obsahující název adresáře, který se má vytvořit.
Návratová hodnota
Nenulové, pokud je úspěšné; jinak 0. Pokud volání selže, funkce Windows GetLastError může být volána k určení příčiny chyby.
Poznámky
Slouží GetCurrentDirectory
k určení aktuálního pracovního adresáře pro toto připojení k serveru. Nepředpokládáte, že vzdálený systém vás připojil ke kořenovému adresáři.
Parametr pstrDirName
může být buď částečně, nebo plně kvalifikovaný název souboru vzhledem k aktuálnímu adresáři. Zpětné lomítko (\) nebo lomítko (/) lze použít jako oddělovač adresáře pro oba názvy. CreateDirectory
před jejich použitím přeloží oddělovače názvů adresářů na příslušné znaky.
CFtpConnection::GetCurrentDirectory
Voláním této členské funkce získáte název aktuálního adresáře.
BOOL GetCurrentDirectory(CString& strDirName) const;
BOOL GetCurrentDirectory(
LPTSTR pstrDirName,
LPDWORD lpdwLen) const;
Parametry
strDirName
Odkaz na řetězec, který obdrží název adresáře.
pstrDirName
Ukazatel na řetězec, který obdrží název adresáře.
lpdwLen
Ukazatel na DWORD, který obsahuje následující informace:
Při zadání: Velikost vyrovnávací paměti odkazované pomocí pstrDirName.
Při návratu: Počet znaků uložených v pstrDirName. Pokud členová funkce selže a ERROR_INSUFFICIENT_BUFFER je vrácena, pak lpdwLen obsahuje počet bajtů, které aplikace musí přidělit, aby získal řetězec.
Návratová hodnota
Nenulové, pokud je úspěšné; jinak 0. Pokud volání selže, může být volána funkce Win32 GetLastError k určení příčiny chyby.
Poznámky
Pokud chcete místo toho získat název adresáře jako adresu URL, zavolejte GetCurrentDirectoryAsURL.
Parametry pstrDirName nebo strDirName mohou být buď částečně kvalifikované názvy souborů vzhledem k aktuálnímu adresáři, nebo plně kvalifikované. Zpětné lomítko (\) nebo lomítko (/) lze použít jako oddělovač adresáře pro oba názvy. GetCurrentDirectory
před jejich použitím přeloží oddělovače názvů adresářů na příslušné znaky.
CFtpConnection::GetCurrentDirectoryAsURL
Voláním této členské funkce získáte název aktuálního adresáře jako adresu URL.
BOOL GetCurrentDirectoryAsURL(CString& strDirName) const;
BOOL GetCurrentDirectoryAsURL(
LPTSTR pstrName,
LPDWORD lpdwLen) const;
Parametry
strDirName
Odkaz na řetězec, který obdrží název adresáře.
pstrDirName
Ukazatel na řetězec, který obdrží název adresáře.
lpdwLen
Ukazatel na DWORD, který obsahuje následující informace:
Při zadání: Velikost vyrovnávací paměti odkazované pomocí pstrDirName.
Při návratu: Počet znaků uložených v pstrDirName. Pokud členová funkce selže a ERROR_INSUFFICIENT_BUFFER je vrácena, pak lpdwLen obsahuje počet bajtů, které aplikace musí přidělit, aby získal řetězec.
Návratová hodnota
Nenulové, pokud je úspěšné; jinak 0. Pokud volání selže, může být volána funkce Win32 GetLastError k určení příčiny chyby.
Poznámky
GetCurrentDirectoryAsURL
chová se stejně jako GetCurrentDirectory.
Parametr strDirName může být buď částečně kvalifikovaný název souboru vzhledem k aktuálnímu adresáři, nebo plně kvalifikovaný. Zpětné lomítko (\) nebo lomítko (/) lze použít jako oddělovač adresáře pro oba názvy. GetCurrentDirectoryAsURL
před jejich použitím přeloží oddělovače názvů adresářů na příslušné znaky.
CFtpConnection::GetFile
Voláním této členské funkce získáte soubor ze serveru FTP a uložíte ho na místním počítači.
BOOL GetFile(
LPCTSTR pstrRemoteFile,
LPCTSTR pstrLocalFile,
BOOL bFailIfExists = TRUE,
DWORD dwAttributes = FILE_ATTRIBUTE_NORMAL,
DWORD dwFlags = FTP_TRANSFER_TYPE_BINARY,
DWORD_PTR dwContext = 1);
Parametry
pstrRemoteFile
Ukazatel na řetězec ukončený hodnotou null obsahující název souboru, který se má načíst ze serveru FTP.
pstrLocalFile
Ukazatel na řetězec ukončený hodnotou null obsahující název souboru, který se má vytvořit v místním systému.
bFailIfExists
Označuje, zda již název souboru může být používán existujícím souborem. Pokud název místního souboru již existuje a tento parametr je TRUE, GetFile
selže. GetFile
V opačném případě vymaže existující kopii souboru.
dwAttributes
Označuje atributy souboru. Může se jednat o libovolnou kombinaci následujících příznaků FILE_ATTRIBUTE_*.
FILE_ATTRIBUTE_ARCHIVE Soubor je archivní soubor. Aplikace tento atribut používají k označení souborů pro zálohování nebo odebrání.
FILE_ATTRIBUTE_COMPRESSED Soubor nebo adresář jsou komprimované. Komprese pro soubor znamená, že všechna data v souboru jsou komprimovaná. U adresáře je komprese výchozí hodnotou pro nově vytvořené soubory a podadresáře.
FILE_ATTRIBUTE_DIRECTORY Soubor je adresář.
FILE_ATTRIBUTE_NORMAL Soubor nemá žádné další atributy. Tento atribut je platný pouze v případě, že se používá samostatně. Všechny ostatní atributy souboru přepíší FILE_ATTRIBUTE_NORMAL:
FILE_ATTRIBUTE_HIDDEN Soubor je skrytý. Není zahrnuta do běžného seznamu adresářů.
FILE_ATTRIBUTE_READONLY Soubor je jen pro čtení. Aplikace můžou soubor číst, ale nemůžou do něj zapisovat ani je odstraňovat.
FILE_ATTRIBUTE_SYSTEM Soubor je součástí nebo je používán výhradně operačním systémem.
FILE_ATTRIBUTE_TEMPORARY Soubor se používá pro dočasné úložiště. Aplikace by měly do souboru zapisovat pouze v případě, že je to naprosto nezbytné. Většina dat souboru zůstává v paměti, aniž by se vyprázdnila na médiu, protože soubor bude brzy odstraněn.
dwFlags
Určuje podmínky, za kterých probíhá přenos. Tento parametr může být libovolný z hodnot dwFlags popsaných v souboru FtpGetFile v sadě Windows SDK.
dwContext
Identifikátor kontextu pro načtení souboru. Další informace o dwContext naleznete v části Poznámky.
Návratová hodnota
Nenulové, pokud je úspěšné; jinak 0. Pokud volání selže, může být volána funkce Win32 GetLastError k určení příčiny chyby.
Poznámky
GetFile
je rutina vysoké úrovně, která zpracovává všechny režijní náklady spojené se čtením souboru ze serveru FTP a jeho místním uložením. Aplikace, které načítají pouze data souboru nebo které vyžadují kontrolu nad přenosem souborů, by měly místo toho používat OpenFile
a CInternetFile::Read .
Pokud je dwFlags FILE_TRANSFER_TYPE_ASCII, překlad dat souborů také převede ovládací prvky a formátovací znaky na ekvivalenty Systému Windows. Výchozí přenos je binární režim, ve kterém se soubor stáhne ve stejném formátu, ve kterém je uložený na serveru.
PstrRemoteFile i pstrLocalFile mohou být buď částečně kvalifikované názvy souborů vzhledem k aktuálnímu adresáři, nebo plně kvalifikované. Zpětné lomítko (\) nebo lomítko (/) lze použít jako oddělovač adresáře pro oba názvy. GetFile
před jejich použitím přeloží oddělovače názvů adresářů na příslušné znaky.
Přepište výchozí hodnotu dwContext a nastavte identifikátor kontextu na hodnotu podle vašeho výběru. Identifikátor kontextu je přidružen k této konkrétní operaci objektu CFtpConnection
vytvořeného jeho CInternetSession objektu. Hodnota je vrácena do CInternetSession::OnStatusCallback poskytnout stav operace, se kterou je identifikován. Další informace o identifikátoru kontextu najdete v článku Internet First Steps: WinInet .
CFtpConnection::OpenFile
Voláním této členské funkce otevřete soubor umístěný na serveru FTP pro čtení nebo zápis.
CInternetFile* OpenFile(
LPCTSTR pstrFileName,
DWORD dwAccess = GENERIC_READ,
DWORD dwFlags = FTP_TRANSFER_TYPE_BINARY,
DWORD_PTR dwContext = 1);
Parametry
pstrFileName
Ukazatel na řetězec obsahující název souboru, který se má otevřít.
dwAccess
Určuje, jak bude soubor přístupný. Může to být GENERIC_READ nebo GENERIC_WRITE, ale ne obojí.
dwFlags
Určuje podmínky, za kterých dojde k následným přenosům. Může to být libovolná z následujících konstant FTP_TRANSFER_*:
FTP_TRANSFER_TYPE_ASCII Přenosy souborů pomocí metody přenosu FTP ASCII (Typ A). Převede informace o ovládacím prvku a formátování na místní ekvivalenty.
FTP_TRANSFER_TYPE_BINARY Soubor přenáší data pomocí metody přenosu obrázku FTP (typ I). Soubor přenáší data přesně tak, jak existuje, beze změn. Toto je výchozí metoda přenosu.
dwContext
Identifikátor kontextu pro otevření souboru. Další informace o dwContext naleznete v části Poznámky.
Návratová hodnota
Ukazatel na objekt CInternetFile .
Poznámky
OpenFile
by měly být použity v následujících situacích:
Aplikace má data, která je potřeba odeslat a vytvořit jako soubor na serveru FTP, ale tato data nejsou v místním souboru. Po
OpenFile
otevření souboru aplikace použije CInternetFile::Write k odeslání dat souboru FTP na server.Aplikace musí načíst soubor ze serveru a umístit ho do paměti řízené aplikací místo zápisu na disk. Aplikace používá CInternetFile::Read po použití
OpenFile
k otevření souboru.Aplikace potřebuje plnou kontrolu nad přenosem souborů. Aplikace může například chtít zobrazit ovládací prvek průběhu označující průběh stavu přenosu souborů při stahování souboru.
Po volání OpenFile
a do volání může aplikace volat CInternetFile::Close
pouze CInternetFile::Read, CInternetFile::Write, CInternetConnection::Close
nebo CFtpFileFind::FindFile. Volání jiných funkcí FTP pro stejnou relaci FTP selžou a nastaví kód chyby na FTP_ETRANSFER_IN_PROGRESS.
Parametr pstrFileName může být buď částečně kvalifikovaný název souboru vzhledem k aktuálnímu adresáři, nebo plně kvalifikovaný. Zpětné lomítko (\) nebo lomítko (/) lze použít jako oddělovač adresáře pro oba názvy. OpenFile
před použitím přeloží oddělovače názvů adresářů na příslušné znaky.
Přepište výchozí hodnotu dwContext a nastavte identifikátor kontextu na hodnotu podle vašeho výběru. Identifikátor kontextu je přidružen k této konkrétní operaci objektu CFtpConnection
vytvořeného jeho CInternetSession objektu. Hodnota je vrácena do CInternetSession::OnStatusCallback poskytnout stav operace, se kterou je identifikován. Další informace o identifikátoru kontextu najdete v článku Internet First Steps: WinInet .
CFtpConnection::P utFile
Voláním této členské funkce uložíte soubor na server FTP.
BOOL PutFile(
LPCTSTR pstrLocalFile,
LPCTSTR pstrRemoteFile,
DWORD dwFlags = FTP_TRANSFER_TYPE_BINARY,
DWORD_PTR dwContext = 1);
Parametry
pstrLocalFile
Ukazatel na řetězec obsahující název souboru, který se má odeslat z místního systému.
pstrRemoteFile
Ukazatel na řetězec obsahující název souboru, který se má vytvořit na serveru FTP.
dwFlags
Určuje podmínky, za kterých probíhá přenos souboru. Může to být libovolná konstanta FTP_TRANSFER_* popsaná v souboru OpenFile.
dwContext
Identifikátor kontextu pro umístění souboru. Další informace o dwContext naleznete v části Poznámky.
Návratová hodnota
Nenulové, pokud je úspěšné; jinak 0. Pokud volání selže, může být volána funkce Win32 GetLastError k určení příčiny chyby.
Poznámky
PutFile
je rutina vysoké úrovně, která zpracovává všechny operace spojené s ukládáním souboru na server FTP. Aplikace, které odesílají pouze data nebo které vyžadují větší kontrolu nad přenosem souborů, by měly používat OpenFile a CInternetFile::Write.
dwContext
Přepište výchozí nastavení pro nastavení identifikátoru kontextu na hodnotu podle vašeho výběru. Identifikátor kontextu je přidružen k této konkrétní operaci objektu CFtpConnection
vytvořeného jeho CInternetSession objektu. Hodnota je vrácena do CInternetSession::OnStatusCallback poskytnout stav operace, se kterou je identifikován. Další informace o identifikátoru kontextu najdete v článku Internet First Steps: WinInet .
CFtpConnection::Remove
Voláním této členské funkce odstraníte zadaný soubor z připojeného serveru.
BOOL Remove(LPCTSTR pstrFileName);
Parametry
pstrFileName
Ukazatel na řetězec obsahující název souboru, který chcete odebrat.
Návratová hodnota
Nenulové, pokud je úspěšné; jinak 0. Pokud volání selže, může být volána funkce Win32 GetLastError k určení příčiny chyby.
Poznámky
Parametr pstrFileName může být buď částečně kvalifikovaný název souboru vzhledem k aktuálnímu adresáři, nebo plně kvalifikovaný. Zpětné lomítko (\) nebo lomítko (/) lze použít jako oddělovač adresáře pro oba názvy. Funkce Remove
před jejich používáním přeloží oddělovače názvů adresářů na příslušné znaky.
CFtpConnection::RemoveDirectory
Voláním této členské funkce odeberete zadaný adresář z připojeného serveru.
BOOL RemoveDirectory(LPCTSTR pstrDirName);
Parametry
pstrDirName
Ukazatel na řetězec obsahující adresář, který se má odebrat.
Návratová hodnota
Nenulové, pokud je úspěšné; jinak 0. Pokud volání selže, může být volána funkce Win32 GetLastError k určení příčiny chyby.
Poznámky
K určení aktuálního pracovního adresáře serveru použijte GetCurrentDirectory . Nepředpokládáte, že vzdálený systém vás připojil ke kořenovému adresáři.
Parametr pstrDirName může být buď částečně, nebo plně kvalifikovaný název souboru vzhledem k aktuálnímu adresáři. Zpětné lomítko (\) nebo lomítko (/) lze použít jako oddělovač adresáře pro oba názvy. RemoveDirectory
před jejich použitím přeloží oddělovače názvů adresářů na příslušné znaky.
CFtpConnection::Rename
Voláním této členské funkce přejmenujte zadaný soubor na připojeném serveru.
BOOL Rename(
LPCTSTR pstrExisting,
LPCTSTR pstrNew);
Parametry
pstrExisting
Ukazatel na řetězec obsahující aktuální název souboru, který se má přejmenovat.
pstrNew
Ukazatel na řetězec obsahující nový název souboru.
Návratová hodnota
Nenulové, pokud je úspěšné; jinak 0. Pokud volání selže, může být volána funkce Win32 GetLastError k určení příčiny chyby.
Poznámky
Parametry pstrExisting a pstrNew mohou být buď částečně kvalifikovaným názvem souboru vzhledem k aktuálnímu adresáři, nebo plně kvalifikovaným. Zpětné lomítko (\) nebo lomítko (/) lze použít jako oddělovač adresáře pro oba názvy. Rename
před jejich použitím přeloží oddělovače názvů adresářů na příslušné znaky.
CFtpConnection::SetCurrentDirectory
Voláním této členské funkce přejděte na jiný adresář na serveru FTP.
BOOL SetCurrentDirectory(LPCTSTR pstrDirName);
Parametry
pstrDirName
Ukazatel na řetězec obsahující název adresáře.
Návratová hodnota
Nenulové, pokud je úspěšné; jinak 0. Pokud volání selže, může být volána funkce Win32 GetLastError k určení příčiny chyby.
Poznámky
Parametr pstrDirName může být buď částečně, nebo plně kvalifikovaný název souboru vzhledem k aktuálnímu adresáři. Zpětné lomítko (\) nebo lomítko (/) lze použít jako oddělovač adresáře pro oba názvy. SetCurrentDirectory
před jejich použitím přeloží oddělovače názvů adresářů na příslušné znaky.
K určení aktuálního pracovního adresáře serveru FTP použijte GetCurrentDirectory . Nepředpokládáte, že vzdálený systém vás připojil ke kořenovému adresáři.
Viz také
CInternetConnection – třída
Graf hierarchie
CInternetConnection – třída
CInternetSession – třída