CFtpConnection 類別

管理與因特網伺服器的 FTP 連線，並允許直接操作該伺服器上的目錄和檔案。

語法

class CFtpConnection : public CInternetConnection

成員

公用建構函式

名稱	描述
CFtpConnection：：CFtpConnection	建構 CFtpConnection 物件。

公用方法

名稱	描述
CFtpConnection：：Command	將命令直接傳送至 FTP 伺服器。
CFtpConnection：：CreateDirectory	在伺服器上建立目錄。
CFtpConnection：：GetCurrentDirectory	取得這個連接的目前目錄。
CFtpConnection：：GetCurrentDirectoryAsURL	取得此連線的目前目錄做為URL。
CFtpConnection：：GetFile	從連接的伺服器取得檔案
CFtpConnection：：OpenFile	開啟連線伺服器上的檔案。
CFtpConnection：:P utFile	將檔案放在伺服器上。
CFtpConnection：：Remove	從伺服器移除檔案。
CFtpConnection：：RemoveDirectory	從伺服器移除指定的目錄。
CFtpConnection：：Rename	重新命名伺服器上的檔案。
CFtpConnection：：SetCurrentDirectory	設定目前的 FTP 目錄。

備註

FTP 是 MFC WinInet 類別所辨識的三個因特網服務之一。

若要與 FTP 因特網伺服器通訊，您必須先建立 CInternetSession 的實例，然後建立 CFtpConnection 物件。 您永遠不會直接建立 CFtpConnection 物件，而是呼叫 CInternetSession：：GetFtpConnection，這會建立 CFtpConnection 物件並傳回它的指標。

若要深入瞭解如何使用CFtpConnection其他 MFC 因特網類別，請參閱使用 WinInet 進行因特網程式設計一文。 如需與其他兩個支援服務通訊的詳細資訊，請參閱 CHttpConnection 和 CGopherConnection 類別。

範例

請參閱 CFtpFileFind 類別概觀中的範例。

繼承階層架構

CObject

CInternetConnection

CFtpConnection

需求

標頭： afxinet.h

CFtpConnection：：CFtpConnection

呼叫這個成員函式來建構 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 物件的指標。

hConnected
目前因特網會話的 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：：GetFtpConnection，以建立 CFptConnection 物件。

CFtpConnection：：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 是 CFtpConnection 的成員，定義於 afxinet.h。

dwFlags
一個值，包含控制此函式的旗標。 如需完整清單，請參閱 FTPCommand。

dwContext
值的指標，包含應用程式定義的值，用以識別回呼中的應用程式內容。

傳回值

如果成功則為非零；否則為 0。

備註

此成員函式會模擬 FTPCommand 函式的功能，如 Windows SDK 中所述。

如果發生錯誤，MFC 會擲回 CInternetException 類型的 例外狀況。

CFtpConnection：：CreateDirectory

呼叫此成員函式，以在連接的伺服器上建立目錄。

BOOL CreateDirectory(LPCTSTR pstrDirName);

參數

pstrDirName
字串的指標，其中包含要建立的目錄名稱。

傳回值

如果成功則為非零；否則為 0。 如果呼叫失敗，可能會呼叫 Windows 函式 GetLastError 來判斷錯誤的原因。

備註

使用 GetCurrentDirectory 來判斷此伺服器連線的目前工作目錄。 請勿假設遠端系統已將您連線到根目錄。

參數 pstrDirName 可以是相對於目前目錄的部分或完整檔名。 反斜杠 （\） 或正斜線 （/） 可用來做為任一名稱的目錄分隔符。 CreateDirectory 在使用目錄名稱分隔符之前，會將目錄名稱分隔符轉譯為適當的字元。

CFtpConnection：：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 在使用目錄名稱分隔符之前，會將目錄名稱分隔符轉譯為適當的字元。

CFtpConnection：：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 在使用目錄名稱分隔符之前，會將目錄名稱分隔符轉譯為適當的字元。

CFtpConnection：：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 一文。

CFtpConnection：：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::CloseCFtpFileFind：：FindFile。 呼叫相同 FTP 工作階段的其他 FTP 函式將會失敗，並將錯誤碼設定為FTP_ETRANSFER_IN_PROGRESS。

pstrFileName 參數可以是相對於目前目錄或完整名稱的部分限定檔名。 反斜杠 （\） 或正斜線 （/） 可用來做為任一名稱的目錄分隔符。 OpenFile 在使用它之前，會將目錄名稱分隔符轉譯為適當的字元。

覆寫 dwContext 預設值，將內容識別碼設定為您選擇的值。 內容標識符會與其 CInternetSession 物件所建立之CFtpConnection對象的這個特定作業相關聯。 值會傳回至 CInternetSession：：OnStatusCallback ，以提供其識別作業的狀態。 如需內容標識碼的詳細資訊，請參閱因特網第一個步驟：WinInet 一文。

CFtpConnection：: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 一文。

CFtpConnection：：Remove

呼叫這個成員函式，從連接的伺服器中刪除指定的檔案。

BOOL Remove(LPCTSTR pstrFileName);

參數

pstrFileName
字串的指標，其中包含要移除的檔名。

傳回值

如果成功則為非零；否則為 0。 如果呼叫失敗，可能會呼叫 Win32 函式 GetLastError 來判斷錯誤的原因。

備註

pstrFileName 參數可以是相對於目前目錄或完整名稱的部分限定檔名。 反斜杠 （\） 或正斜線 （/） 可用來做為任一名稱的目錄分隔符。 函 Remove 式會在使用目錄名稱分隔符之前，將目錄名稱分隔符轉譯為適當的字元。

CFtpConnection：：RemoveDirectory

呼叫這個成員函式，從連接的伺服器中移除指定的目錄。

BOOL RemoveDirectory(LPCTSTR pstrDirName);

參數

pstrDirName
字串的指標，其中包含要移除的目錄。

傳回值

如果成功則為非零；否則為 0。 如果呼叫失敗，可能會呼叫 Win32 函式 GetLastError 來判斷錯誤的原因。

備註

使用 GetCurrentDirectory 來判斷伺服器的目前工作目錄。 請勿假設遠端系統已將您連線到根目錄。

pstrDirName 參數可以是相對於目前目錄的部分或完整檔名。 反斜杠 （\） 或正斜線 （/） 可用來做為任一名稱的目錄分隔符。 RemoveDirectory 在使用目錄名稱分隔符之前，會將目錄名稱分隔符轉譯為適當的字元。

CFtpConnection：：Rename

呼叫這個成員函式，以重新命名連線伺服器上的指定檔案。

BOOL Rename(
    LPCTSTR pstrExisting,
    LPCTSTR pstrNew);

參數

pstrExisting
字串的指標，其中包含要重新命名之檔案的目前名稱。

pstrNew
字串的指標，其中包含檔案的新名稱。

傳回值

如果成功則為非零；否則為 0。 如果呼叫失敗，可能會呼叫 Win32 函式 GetLastError 來判斷錯誤的原因。

備註

pstrExisting 和 pstrNew 參數可以是相對於目前目錄或完整名稱的部分限定檔名。 反斜杠 （\） 或正斜線 （/） 可用來做為任一名稱的目錄分隔符。 Rename 在使用目錄名稱分隔符之前，會將目錄名稱分隔符轉譯為適當的字元。

CFtpConnection：：SetCurrentDirectory

呼叫此成員函式，以變更為FTP伺服器上的不同目錄。

BOOL SetCurrentDirectory(LPCTSTR pstrDirName);

參數

pstrDirName
包含目錄名稱之字串的指標。

傳回值

如果成功則為非零；否則為 0。 如果呼叫失敗，可能會呼叫 Win32 函式 GetLastError 來判斷錯誤的原因。

備註

pstrDirName 參數可以是相對於目前目錄的部分或完整檔名。 反斜杠 （\） 或正斜線 （/） 可用來做為任一名稱的目錄分隔符。 SetCurrentDirectory 在使用目錄名稱分隔符之前，會將目錄名稱分隔符轉譯為適當的字元。

使用 GetCurrentDirectory 來判斷 FTP 伺服器的目前工作目錄。 請勿假設遠端系統已將您連線到根目錄。

另請參閱

CInternetConnection 類別
階層架構圖表
CInternetConnection 類別
CInternetSession 類別