WinINet (wininet.h/wininet.lib) 提供比 Winsock 更高層的 FTP/HTTP/Gopher 協定封裝，自動處理控制連線、資料連線、被動模式、認證等細節。本文整理 13 個核心 FTP API，涵蓋會話管理、目錄操作、檔案傳輸、清單列舉、重命名等全生命週期操作。
| 類別 | 函數 | 用途 |
|---|---|---|
| 會話管理 | InternetOpen | 初始化 WinINet，取得會話句柄 (User-Agent、Proxy 設定) |
InternetConnect | 建立 FTP/Gopher/HTTP 連線，回傳連線句柄 (主機、帳號、密碼、埠口、被動模式旗標) | |
| 目錄操作 | FtpCreateDirectory | 建立遠端目錄 |
FtpRemoveDirectory | 刪除遠端目錄 (必須為空) | |
FtpSetCurrentDirectory | 切換遠端工作目錄 | |
| 目錄查詢 | FtpGetCurrentDirectory | 取得目前遠端目錄路徑 |
FtpFindFirstFile | 開始列舉，回傳搜尋句柄與第一筆 WIN32_FIND_DATA | |
| 列舉續傳 | InternetFindNextFile | 續傳列舉下一筆 |
| 檔案傳輸 | FtpGetFile | 下載檔案 (支援斷點續傳旗標、屬性保留、回呼進度) |
FtpPutFile | 上傳檔案 | |
FtpDeleteFile | 刪除遠端檔案 | |
FtpRenameFile | 重命名/移動遠端檔案 | |
FtpOpenFile | 開啟遠端檔案讀寫 (支援隨機存取、InternetReadFile/InternetWriteFile) | |
| 命令通道 | FtpCommand | 發送原始 FTP 指令 (如 SITE, STAT, FEAT 等擴展指令) |
// 1. 初始化會話
HINTERNET hSession = InternetOpen("MyFtpClient/1.0", INTERNET_OPEN_TYPE_PRECONFIG, NULL, NULL, 0);
// 2. 連線 FTP 伺服器
HINTERNET hConnect = InternetConnect(hSession, "ftp.example.com", INTERNET_DEFAULT_FTP_PORT,
"username", "password", INTERNET_SERVICE_FTP,
INTERNET_FLAG_PASSIVE, 0); // 被動模式
// 3. 上傳檔案
BOOL ok = FtpPutFile(hConnect, "local.txt", "remote.txt", FTP_TRANSFER_TYPE_BINARY, 0);
// 4. 列舉目錄
WIN32_FIND_DATA findData;
HINTERNET hFind = FtpFindFirstFile(hConnect, "*", &findData, 0, 0);
if (hFind) {
do {
// 處理 findData.cFileName, findData.dwFileSize, findData.ftLastWriteTime...
} while (InternetFindNextFile(hFind, &findData));
InternetCloseHandle(hFind);
}
// 5. 清理
InternetCloseHandle(hConnect);
InternetCloseHandle(hSession);FTP_TRANSFER_TYPE_BINARY (二進位、預設) vs FTP_TRANSFER_TYPE_ASCII (文字、自動換行轉換)INTERNET_FLAG_PASSIVE (預設主動模式)，防火牆/NAT 環境必須啟用FtpGetFile 的 dwFlags 可設 FTP_TRANSFER_TYPE_UNKNOWN 配合 FILE_FLAG_WRITE_THROUGH 實現，但 WinINet 原生支援有限，大檔案建議自行分塊InternetSetStatusCallback 註冊回呼，支援進度、狀態、錯誤通知InternetOpen 的 lpszProxy/lpszProxyBypass 參數| 錯誤碼 | 含義 | 對策 |
|---|---|---|
ERROR_INTERNET_INCORRECT_HANDLE_TYPE | 句柄類型不匹配 | 確認 InternetConnect 回傳句柄傳給 FTP API |
ERROR_INTERNET_LOGIN_FAILURE | 認證失敗 | 檢查帳號密碼、伺服器是否允許 FTP、被動模式設定 |
ERROR_INTERNET_EXTENDED_ERROR | 伺服器回傳錯誤 | 呼叫 InternetGetLastResponseInfo 取得 FTP 回應碼 (如 530, 550) |
ERROR_FILE_NOT_FOUND | 本地/遠端檔案不存在 | 確認路徑大小寫、工作目錄、權限 |
Windows.Networking.BackgroundTransfer (UWP/WinUI 3，支援後台傳輸、電源感知)curl 同源System.Net.WebClient/FtpWebRequest，腳本自動化首選WinINet 適合輕量級 Win32 桌面應用快速整合 FTP 功能，但新專案建議評估更現代、跨平台、支援 TLS 1.3 的替代方案。
