CFtpConnection 類別
管理與網際網路伺服器的 FTP 連線,並允許直接操作該伺服器上的目錄和檔案。
語法
class CFtpConnection : public CInternetConnection
成員
公用建構函式
名稱 | 描述 |
---|---|
CFtp連線ion::CFtp連線ion | 建構 CFtpConnection 物件。 |
公用方法
名稱 | 描述 |
---|---|
CFtp連線ion::Command | 將命令直接傳送至 FTP 伺服器。 |
CFtp連線ion::CreateDirectory | 在伺服器上建立目錄。 |
CFtp連線ion::GetCurrentDirectory | 取得這個連接的目前目錄。 |
CFtp連線ion::GetCurrentDirectoryAsURL | 取得此連線的目前目錄做為 URL。 |
CFtp連線ion::GetFile | 從連接的伺服器取得檔案 |
CFtp連線ion::OpenFile | 開啟連線伺服器上的檔案。 |
CFtp連線ion::P utFile | 將檔案放在伺服器上。 |
CFtp連線ion::Remove | 從伺服器移除檔案。 |
CFtp連線ion::RemoveDirectory | 從伺服器移除指定的目錄。 |
CFtp連線ion::Rename | 重新命名伺服器上的檔案。 |
CFtp連線ion::SetCurrentDirectory | 設定目前的 FTP 目錄。 |
備註
FTP 是 MFC WinInet 類別所辨識的三個網際網路服務之一。
若要與 FTP 網際網路伺服器通訊,您必須先建立 CInternetSession 的 實例,然後建立 CFtpConnection
物件。 您永遠不會直接建立 CFtpConnection
物件,而是呼叫 CInternetSession::GetFtp連線ion ,這會建立 CFtpConnection
物件並傳回它的指標。
若要深入瞭解如何使用 CFtpConnection
其他 MFC 網際網路類別,請參閱使用 WinInet 進行網際網路程式設計一文 。 如需與其他兩個支援服務 HTTP 和 gopher 通訊的詳細資訊,請參閱 CHttp連線ion 和 CGopher 類別連線ion 。
範例
請參閱 CFtpFileFind 類別概觀中的 範例。
繼承階層架構
CFtpConnection
需求
標頭: afxinet.h
CFtp連線ion::CFtp連線ion
呼叫這個成員函式來建構 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);
參數
pSession
相關 CInternetSession 物件的指標。
h連線ed
目前網際網路會話的 Windows 控制碼。
pstrServer
包含 FTP 伺服器名稱之字串的指標。
dwCoNtext
作業的內容識別碼。 dwCoNtext 會識別 CInternetSession::OnStatusCallback 所 傳回的作業狀態資訊。 預設值設定為 1;不過,您可以明確指派作業的特定內容識別碼。 物件及其執行的任何工作都會與該內容識別碼相關聯。
pstrUserName
Null 終止字串的指標,指定要登入的使用者名稱。 如果為 Null,則預設值為匿名。
pstrPassword
Null 終止字串的指標,指定要用來登入的密碼。 如果 pstrPassword 和 pstrUserName 都是 Null,則預設的匿名密碼是使用者的電子郵件名稱。 如果 pstrPassword 為 Null(或空字串),但 pstrUserName 不是 Null,則會使用空白密碼。 下表描述 pstrUserName 和 pstrPassword 四種可能設定 的行為:
pstrUserName | pstrPassword | 傳送至 FTP 伺服器的使用者名稱 | 傳送至 FTP 伺服器的密碼 |
---|---|---|---|
Null 或 」 | Null 或 」 | 「anonymous」 | 使用者的電子郵件名稱 |
非 Null 字串 | Null 或 」 | pstrUserName | " " |
Null 非 Null 字串 | 錯誤 | 錯誤 | |
非 Null 字串 | 非 Null 字串 | pstrUserName | pstrPassword |
nPort
數位,識別伺服器上要使用的 TCP/IP 埠。
bPassive
指定這個 FTP 會話的被動或主動模式。 如果設定為 TRUE,則會將 WIN32 API dwFlag 設定為 INTERNET_FLAG_PASSIVE。
備註
您永遠不會直接建立 CFtpConnection
物件。 請改為呼叫 CInternetSession::GetFtp連線ion ,以建立 CFptConnection
物件。
CFtp連線ion::Command
將命令直接傳送至 FTP 伺服器。
CInternetFile* Command(
LPCTSTR pszCommand,
CmdResponseType eResponse = CmdRespNone,
DWORD dwFlags = FTP_TRANSFER_TYPE_BINARY,
DWORD_PTR dwContext = 1);
參數
pszCommand
包含要傳送至命令的字串指標。
eResponse
指定是否預期來自 FTP 伺服器的回應。 可以是下列值之一:
CmdRespNone
沒有預期的回應。CmdRespRead
預期會有回應。CmdRespWrite
未使用。
CmdResponseType 是 CFtp連線ion 的成員,定義于 afxinet.h 。
dwFlags
一個值,包含控制此函式的旗標。 如需完整清單,請參閱 FTPCommand 。
dwCoNtext
值的指標,包含應用程式定義的值,用以識別回呼中的應用程式內容。
傳回值
如果成功則為非零;否則為 0。
備註
此成員函式會模擬 FTPCommand 函式的功能 ,如 Windows SDK 中所述。
如果發生錯誤,MFC 會擲回 CInternetException 類型的 例外狀況 。
CFtp連線ion::CreateDirectory
呼叫此成員函式,以在連接的伺服器上建立目錄。
BOOL CreateDirectory(LPCTSTR pstrDirName);
參數
pstrDirName
字串的指標,其中包含要建立的目錄名稱。
傳回值
如果成功則為非零;否則為 0。 如果呼叫失敗,可能會呼叫 Windows 函式 GetLastError 來判斷錯誤的原因。
備註
使用 GetCurrentDirectory
來判斷此伺服器連線的目前工作目錄。 請勿假設遠端系統已將您連線到根目錄。
參數 pstrDirName
可以是相對於目前目錄的部分或完整檔案名。 反斜線 (\) 或正斜線 (/) 可用來做為任一名稱的目錄分隔符號。 CreateDirectory
在使用目錄名稱分隔符號之前,會將目錄名稱分隔符號轉譯為適當的字元。
CFtp連線ion::GetCurrentDirectory
呼叫這個成員函式以取得目前目錄的名稱。
BOOL GetCurrentDirectory(CString& strDirName) const;
BOOL GetCurrentDirectory(
LPTSTR pstrDirName,
LPDWORD lpdwLen) const;
參數
strDirName
將接收目錄名稱之字串的參考。
pstrDirName
將接收目錄名稱之字串的指標。
lpdwLen
包含下列資訊的 DWORD 指標:
在專案上:pstrDirName 所 參考的緩衝區大小。
傳回時:儲存至 pstrDirName 的字元數。 如果成員函式失敗並傳回ERROR_INSUFFICIENT_BUFFER,則 lpdwLen 會包含應用程式必須配置的位元組數目,才能接收字串。
傳回值
如果成功則為非零;否則為 0。 如果呼叫失敗,可能會呼叫 Win32 函式 GetLastError 來判斷錯誤的原因。
備註
若要改為以 URL 的形式取得目錄名稱,請呼叫 GetCurrentDirectoryAsURL 。
pstrDirName 或 strDirName 參數 可以是相對於目前目錄或完整名稱的部分限定檔案名。 反斜線 (\) 或正斜線 (/) 可用來做為任一名稱的目錄分隔符號。 GetCurrentDirectory
在使用目錄名稱分隔符號之前,會將目錄名稱分隔符號轉譯為適當的字元。
CFtp連線ion::GetCurrentDirectoryAsURL
呼叫此成員函式,以取得目前目錄的名稱作為 URL。
BOOL GetCurrentDirectoryAsURL(CString& strDirName) const;
BOOL GetCurrentDirectoryAsURL(
LPTSTR pstrName,
LPDWORD lpdwLen) const;
參數
strDirName
將接收目錄名稱之字串的參考。
pstrDirName
將接收目錄名稱之字串的指標。
lpdwLen
包含下列資訊的 DWORD 指標:
在專案上:pstrDirName 所 參考的緩衝區大小。
傳回時:儲存至 pstrDirName 的字元數。 如果成員函式失敗並傳回ERROR_INSUFFICIENT_BUFFER,則 lpdwLen 會包含應用程式必須配置的位元組數目,才能接收字串。
傳回值
如果成功則為非零;否則為 0。 如果呼叫失敗,可能會呼叫 Win32 函式 GetLastError 來判斷錯誤的原因。
備註
GetCurrentDirectoryAsURL
行為與 GetCurrentDirectory 相同
參數 strDirName 可以是相對於目前目錄或完整部分限定檔案名。 反斜線 (\) 或正斜線 (/) 可用來做為任一名稱的目錄分隔符號。 GetCurrentDirectoryAsURL
在使用目錄名稱分隔符號之前,會將目錄名稱分隔符號轉譯為適當的字元。
CFtp連線ion::GetFile
呼叫此成員函式以從 FTP 伺服器取得檔案,並將其儲存在本機電腦上。
BOOL GetFile(
LPCTSTR pstrRemoteFile,
LPCTSTR pstrLocalFile,
BOOL bFailIfExists = TRUE,
DWORD dwAttributes = FILE_ATTRIBUTE_NORMAL,
DWORD dwFlags = FTP_TRANSFER_TYPE_BINARY,
DWORD_PTR dwContext = 1);
參數
pstrRemoteFile
Null 終止字串的指標,其中包含要從 FTP 伺服器擷取的檔案名。
pstrLocalFile
Null 終止字串的指標,其中包含在本機系統上建立的檔案名。
bFailIfExists
指出現有檔案是否已經使用檔案名。 如果本機檔案名已經存在,且此參數為 TRUE,則 GetFile
失敗。 否則, GetFile
將會清除檔案的現有複本。
dwAttributes
指出檔案的屬性。 這可以是下列FILE_ATTRIBUTE_* 旗標的任何組合。
FILE_ATTRIBUTE_ARCHIVE檔案是封存檔案。 應用程式會使用此屬性來標記檔案以進行備份或移除。
FILE_ATTRIBUTE_COMPRESSED檔案或目錄已壓縮。 對於檔案,壓縮表示檔案中的所有資料都會壓縮。 對於目錄,壓縮是新建立檔案和子目錄的預設值。
FILE_ATTRIBUTE_DIRECTORY檔案是目錄。
FILE_ATTRIBUTE_NORMAL 檔案沒有設定其他屬性。 此屬性只有在單獨使用時才有效。 所有其他檔案屬性都會覆寫FILE_ATTRIBUTE_NORMAL:
FILE_ATTRIBUTE_HIDDEN檔案已隱藏。 它不會包含在一般目錄清單中。
FILE_ATTRIBUTE_READONLY檔案是唯讀的。 應用程式可以讀取檔案,但無法寫入或刪除它。
FILE_ATTRIBUTE_SYSTEM 檔案是 或 的一部分,由作業系統獨佔使用。
FILE_ATTRIBUTE_TEMPORARY檔案正用於暫存儲存體。 只有在絕對必要的情況下,應用程式才應該寫入檔案。 大部分檔案的資料會保留在記憶體中,而不會排清到媒體,因為檔案很快就會被刪除。
dwFlags
指定傳輸發生的條件。 此參數可以是 Windows SDK 中 FtpGetFile 中所述 的任何 dwFlags 值。
dwCoNtext
檔案擷取的內容識別碼。 如需 dwCoNtext 的詳細資訊 , 請參閱 。
傳回值
如果成功則為非零;否則為 0。 如果呼叫失敗,可能會呼叫 Win32 函式 GetLastError 來判斷錯誤的原因。
備註
GetFile
是一個高階常式,可處理從 FTP 伺服器讀取檔案並將它儲存在本機的所有額外負荷。 只擷取檔案資料或需要密切控制檔案傳輸的應用程式,應該改用 OpenFile
和 CInternetFile::Read 。
如果 dwFlags 是FILE_TRANSFER_TYPE_ASCII,則檔案資料的翻譯也會將控制項和格式化字元轉換成 Windows 對等專案。 預設傳輸為二進位模式,檔案會以與儲存在伺服器上相同的格式下載。
pstrRemoteFile 和 pstrLocalFile 可以是相對於目前目錄或完整名稱的部分限定檔案名。 反斜線 (\) 或正斜線 (/) 可用來做為任一名稱的目錄分隔符號。 GetFile
在使用目錄名稱分隔符號之前,會將目錄名稱分隔符號轉譯為適當的字元。
覆寫 dwCoNtext 預設值,將內容識別碼設定為您選擇的值。 內容識別碼會與其 CInternetSession 物件所 建立之 CFtpConnection
物件的這個特定作業相關聯。 值會傳回至 CInternetSession::OnStatusCallback ,以提供其識別作業的狀態。 如需內容識別碼的詳細資訊,請參閱網際網路第一個步驟:WinInet 一文 。
CFtp連線ion::OpenFile
呼叫此成員函式以開啟位於 FTP 伺服器上的檔案以進行讀取或寫入。
CInternetFile* OpenFile(
LPCTSTR pstrFileName,
DWORD dwAccess = GENERIC_READ,
DWORD dwFlags = FTP_TRANSFER_TYPE_BINARY,
DWORD_PTR dwContext = 1);
參數
pstrFileName
字串的指標,其中包含要開啟之檔案名。
dwAccess
決定如何存取檔案。 可以是GENERIC_READ或GENERIC_WRITE,但不能同時兩者。
dwFlags
指定後續傳輸發生的情況。 這可以是下列任一FTP_TRANSFER_* 常數:
FTP_TRANSFER_TYPE_ASCII使用 FTP ASCII (類型 A) 傳輸方法的檔案傳輸。 將控制項和格式資訊轉換為本機對等專案。
FTP_TRANSFER_TYPE_BINARY檔案會使用 FTP 的影像 (Type I) 傳輸方法傳輸資料。 檔案會完全如其存在而傳輸資料,且沒有任何變更。 這是預設傳輸方法。
dwCoNtext
開啟檔案的內容識別碼。 如需 dwCoNtext 的詳細資訊 , 請參閱 。
傳回值
CInternetFile 物件的指標 。
備註
OpenFile
應該在下列情況下使用:
應用程式具有必須在 FTP 伺服器上以檔案的形式傳送和建立的資料,但該資料不在本機檔案中。 開啟檔案之後
OpenFile
,應用程式會使用 CInternetFile::Write 將 FTP 檔案資料傳送至伺服器。應用程式必須從伺服器擷取檔案,並將它放入應用程式控制的記憶體中,而不是將它寫入磁片。 應用程式會在使用
OpenFile
之後使用 CInternetFile::Read 來開啟檔案。應用程式需要對檔案傳輸進行精細的控制。 例如,應用程式可能會想要顯示進度控制項,指出下載檔案時檔案傳輸狀態的進度。
呼叫 OpenFile
和 直到呼叫 CInternetFile::Close
之後,應用程式只能呼叫 CInternetFile::Read 、 CInternetFile::Write 或 CInternetConnection::Close
CFtpFileFind::FindFile 。 呼叫相同 FTP 會話的其他 FTP 函式將會失敗,並將錯誤碼設定為FTP_ETRANSFER_IN_PROGRESS。
pstrFileName 參數可以是相對於目前目錄或完整名稱的部分限定檔名。 反斜線 (\) 或正斜線 (/) 可用來做為任一名稱的目錄分隔符號。 OpenFile
在使用它之前,會將目錄名稱分隔符號轉譯為適當的字元。
覆寫 dwCoNtext 預設值,將內容識別碼設定為您選擇的值。 內容識別碼會與其 CInternetSession 物件所 建立之 CFtpConnection
物件的這個特定作業相關聯。 值會傳回至 CInternetSession::OnStatusCallback ,以提供其識別作業的狀態。 如需內容識別碼的詳細資訊,請參閱網際網路第一個步驟:WinInet 一文 。
CFtp連線ion::P utFile
呼叫這個成員函式,將檔案儲存在 FTP 伺服器上。
BOOL PutFile(
LPCTSTR pstrLocalFile,
LPCTSTR pstrRemoteFile,
DWORD dwFlags = FTP_TRANSFER_TYPE_BINARY,
DWORD_PTR dwContext = 1);
參數
pstrLocalFile
字串的指標,其中包含要從本機系統傳送的檔案名。
pstrRemoteFile
字串的指標,其中包含在 FTP 伺服器上建立的檔案名。
dwFlags
指定檔案傳輸所依據的條件。 可以是 OpenFile 中所述 的任何FTP_TRANSFER_* 常數。
dwCoNtext
放置檔案的內容識別碼。 如需 dwCoNtext 的詳細資訊 , 請參閱 。
傳回值
如果成功則為非零;否則為 0。 如果呼叫失敗,可能會呼叫 Win32 函式 GetLastError 來判斷錯誤的原因。
備註
PutFile
是一個高階常式,可處理與將檔案儲存在 FTP 伺服器上相關聯的所有作業。 只傳送資料或需要更仔細控制檔案傳輸的應用程式,應該使用 OpenFile 和 CInternetFile::Write 。
覆寫預設值, dwContext
將內容識別碼設定為您選擇的值。 內容識別碼會與其 CInternetSession 物件所 建立之 CFtpConnection
物件的這個特定作業相關聯。 值會傳回至 CInternetSession::OnStatusCallback ,以提供其識別作業的狀態。 如需內容識別碼的詳細資訊,請參閱網際網路第一個步驟:WinInet 一文 。
CFtp連線ion::Remove
呼叫這個成員函式,從連接的伺服器中刪除指定的檔案。
BOOL Remove(LPCTSTR pstrFileName);
參數
pstrFileName
字串的指標,其中包含要移除的檔案名。
傳回值
如果成功則為非零;否則為 0。 如果呼叫失敗,可能會呼叫 Win32 函式 GetLastError 來判斷錯誤的原因。
備註
pstrFileName 參數可以是相對於目前目錄或完整名稱的部分限定檔名。 反斜線 (\) 或正斜線 (/) 可用來做為任一名稱的目錄分隔符號。 函 Remove
式會在使用目錄名稱分隔符號之前,將目錄名稱分隔符號轉譯為適當的字元。
CFtp連線ion::RemoveDirectory
呼叫這個成員函式,從連接的伺服器中移除指定的目錄。
BOOL RemoveDirectory(LPCTSTR pstrDirName);
參數
pstrDirName
字串的指標,其中包含要移除的目錄。
傳回值
如果成功則為非零;否則為 0。 如果呼叫失敗,可能會呼叫 Win32 函式 GetLastError 來判斷錯誤的原因。
備註
使用 GetCurrentDirectory 來判斷伺服器的目前工作目錄。 請勿假設遠端系統已將您連線到根目錄。
pstrDirName 參數可以是相對於目前目錄的部分或完整檔案名。 反斜線 (\) 或正斜線 (/) 可用來做為任一名稱的目錄分隔符號。 RemoveDirectory
在使用目錄名稱分隔符號之前,會將目錄名稱分隔符號轉譯為適當的字元。
CFtp連線ion::Rename
呼叫這個成員函式,以重新命名連線伺服器上的指定檔案。
BOOL Rename(
LPCTSTR pstrExisting,
LPCTSTR pstrNew);
參數
pstrExisting
字串的指標,其中包含要重新命名之檔案的目前名稱。
pstrNew
字串的指標,其中包含檔案的新名稱。
傳回值
如果成功則為非零;否則為 0。 如果呼叫失敗,可能會呼叫 Win32 函式 GetLastError 來判斷錯誤的原因。
備註
pstrExisting 和 pstrNew 參數可以是相對於目前目錄或完整名稱的部分限定檔案名。 反斜線 (\) 或正斜線 (/) 可用來做為任一名稱的目錄分隔符號。 Rename
在使用目錄名稱分隔符號之前,會將目錄名稱分隔符號轉譯為適當的字元。
CFtp連線ion::SetCurrentDirectory
呼叫此成員函式,以變更為 FTP 伺服器上的不同目錄。
BOOL SetCurrentDirectory(LPCTSTR pstrDirName);
參數
pstrDirName
包含目錄名稱之字串的指標。
傳回值
如果成功則為非零;否則為 0。 如果呼叫失敗,可能會呼叫 Win32 函式 GetLastError 來判斷錯誤的原因。
備註
pstrDirName 參數可以是相對於目前目錄的部分或完整檔案名。 反斜線 (\) 或正斜線 (/) 可用來做為任一名稱的目錄分隔符號。 SetCurrentDirectory
在使用目錄名稱分隔符號之前,會將目錄名稱分隔符號轉譯為適當的字元。
使用 GetCurrentDirectory 來判斷 FTP 伺服器的目前工作目錄。 請勿假設遠端系統已將您連線到根目錄。
另請參閱
CInternetConnection 類別
階層架構圖表
CInternetConnection 類別
CInternetSession 類別
意見反應
https://aka.ms/ContentUserFeedback。
即將登場:在 2024 年,我們將逐步淘汰 GitHub 問題作為內容的意見反應機制,並將它取代為新的意見反應系統。 如需詳細資訊,請參閱:提交並檢視相關的意見反應