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 類別
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應