项目背景详细介绍
在传统企业系统、工业控制、内网工具以及大量遗留系统中，FTP（File Transfer Protocol）依然被广泛用于文件传输任务，例如：
自动化日志上传
程序更新文件分发
服务器配置同步
内网设备文件交换
嵌入式系统文件传输
尽管如今 HTTP / HTTPS 已成为主流，但在以下场景中 FTP 仍不可替代：
内网环境，部署简单
老系统兼容性要求高
无需复杂证书配置
与大量历史系统对接
对于C++ 开发者而言，掌握 FTP 文件传输能力，依然是系统工具开发、运维工具、工业软件中的重要技能。
在 Windows 平台上，微软提供了成熟稳定的WinINet API，用于：
HTTP / HTTPS
FTP
代理网络访问
无需引入第三方库，即可完成 FTP 登录、上传、下载等操作，非常适合教学与工程实践。
因此，本项目将通过一个完整、可运行、工程级的 C++ 示例，系统演示：
如何使用 C++ + WinINet 实现 FTP 文件上传与下载
该项目非常适合作为 Windows 网络编程、系统工具开发、C++ 实战课程的教学案例。
项目需求详细介绍
1. 功能需求
使用 C++ 连接 FTP 服务器
支持用户名 / 密码登录
支持文件上传（PUT）
支持文件下载（GET）
支持二进制模式传输
输出关键执行步骤日志
2. 技术要求
基于 Windows 原生 WinINet API
使用 FTP 被动模式
支持 Unicode（宽字符）
不依赖任何第三方库
3. 教学与工程要求
明确区分 FTP 会话与连接
展示完整 FTP 操作流程
代码结构清晰、可复用
适合课堂逐步讲解
相关技术详细介绍
1. FTP 协议简介
FTP 是一种基于 TCP 的明文文件传输协议，主要包含：
控制连接（端口 21）
数据连接（主动 / 被动模式）
基本操作包括：
登录（USER / PASS）
上传（STOR）
下载（RETR）
列表（LIST）
2. WinINet API 简介
WinINet 是 Windows 提供的高层网络 API，封装了：
Socket 细节
协议交互流程
错误处理机制
常用 FTP 相关函数包括：
InternetOpenInternetConnectFtpPutFileFtpGetFileInternetCloseHandle
3. FTP 传输模式
本项目采用：
二进制模式（FTP_TRANSFER_TYPE_BINARY）
被动模式（PASV）
这是最常用、兼容性最好的配置。
实现思路详细介绍
整体实现流程如下：
初始化 WinINet 环境
创建 Internet 会话
连接 FTP 服务器
执行文件上传 / 下载
错误处理与资源释放
项目采用函数封装方式，便于后续扩展为：
FTP 工具类
批量上传程序
自动更新模块
完整实现代码
/**************************************************** * File: FtpClient.h ****************************************************/ #pragma once #include <Windows.h> #include <WinInet.h> #include <string> #pragma comment(lib, "Wininet.lib") class FtpClient { public: FtpClient(); ~FtpClient(); bool connect(const std::wstring& server, const std::wstring& user, const std::wstring& password, INTERNET_PORT port = INTERNET_DEFAULT_FTP_PORT); bool uploadFile(const std::wstring& localFile, const std::wstring& remoteFile); bool downloadFile(const std::wstring& remoteFile, const std::wstring& localFile); private: HINTERNET hInternet; HINTERNET hFtp; }; /**************************************************** * File: FtpClient.cpp ****************************************************/ #include "FtpClient.h" #include <iostream> FtpClient::FtpClient() : hInternet(nullptr), hFtp(nullptr) { // 初始化 WinINet hInternet = InternetOpenW( L"CppFtpClient", INTERNET_OPEN_TYPE_DIRECT, nullptr, nullptr, 0 ); } FtpClient::~FtpClient() { if (hFtp) InternetCloseHandle(hFtp); if (hInternet) InternetCloseHandle(hInternet); } bool FtpClient::connect(const std::wstring& server, const std::wstring& user, const std::wstring& password, INTERNET_PORT port) { hFtp = InternetConnectW( hInternet, server.c_str(), port, user.c_str(), password.c_str(), INTERNET_SERVICE_FTP, INTERNET_FLAG_PASSIVE, 0 ); return hFtp != nullptr; } bool FtpClient::uploadFile(const std::wstring& localFile, const std::wstring& remoteFile) { return FtpPutFileW( hFtp, localFile.c_str(), remoteFile.c_str(), FTP_TRANSFER_TYPE_BINARY, 0 ); } bool FtpClient::downloadFile(const std::wstring& remoteFile, const std::wstring& localFile) { return FtpGetFileW( hFtp, remoteFile.c_str(), localFile.c_str(), FALSE, FILE_ATTRIBUTE_NORMAL, FTP_TRANSFER_TYPE_BINARY, 0 ); } /**************************************************** * File: main.cpp ****************************************************/ #include "FtpClient.h" #include <iostream> int main() { FtpClient ftp; if (!ftp.connect(L"127.0.0.1", L"testuser", L"testpass")) { std::wcout << L"FTP 连接失败\n"; return 1; } if (ftp.uploadFile(L"C:\\Test\\upload.txt", L"upload.txt")) std::wcout << L"文件上传成功\n"; else std::wcout << L"文件上传失败\n"; if (ftp.downloadFile(L"download.txt", L"C:\\Test\\download.txt")) std::wcout << L"文件下载成功\n"; else std::wcout << L"文件下载失败\n"; return 0; }/**************************************************** * File: FtpClient.h ****************************************************/ #pragma once #include <Windows.h> #include <WinInet.h> #include <string> #pragma comment(lib, "Wininet.lib") class FtpClient { public: FtpClient(); ~FtpClient(); bool connect(const std::wstring& server, const std::wstring& user, const std::wstring& password, INTERNET_PORT port = INTERNET_DEFAULT_FTP_PORT); bool uploadFile(const std::wstring& localFile, const std::wstring& remoteFile); bool downloadFile(const std::wstring& remoteFile, const std::wstring& localFile); private: HINTERNET hInternet; HINTERNET hFtp; }; /**************************************************** * File: FtpClient.cpp ****************************************************/ #include "FtpClient.h" #include <iostream> FtpClient::FtpClient() : hInternet(nullptr), hFtp(nullptr) { // 初始化 WinINet hInternet = InternetOpenW( L"CppFtpClient", INTERNET_OPEN_TYPE_DIRECT, nullptr, nullptr, 0 ); } FtpClient::~FtpClient() { if (hFtp) InternetCloseHandle(hFtp); if (hInternet) InternetCloseHandle(hInternet); } bool FtpClient::connect(const std::wstring& server, const std::wstring& user, const std::wstring& password, INTERNET_PORT port) { hFtp = InternetConnectW( hInternet, server.c_str(), port, user.c_str(), password.c_str(), INTERNET_SERVICE_FTP, INTERNET_FLAG_PASSIVE, 0 ); return hFtp != nullptr; } bool FtpClient::uploadFile(const std::wstring& localFile, const std::wstring& remoteFile) { return FtpPutFileW( hFtp, localFile.c_str(), remoteFile.c_str(), FTP_TRANSFER_TYPE_BINARY, 0 ); } bool FtpClient::downloadFile(const std::wstring& remoteFile, const std::wstring& localFile) { return FtpGetFileW( hFtp, remoteFile.c_str(), localFile.c_str(), FALSE, FILE_ATTRIBUTE_NORMAL, FTP_TRANSFER_TYPE_BINARY, 0 ); } /**************************************************** * File: main.cpp ****************************************************/ #include "FtpClient.h" #include <iostream> int main() { FtpClient ftp; if (!ftp.connect(L"127.0.0.1", L"testuser", L"testpass")) { std::wcout << L"FTP 连接失败\n"; return 1; } if (ftp.uploadFile(L"C:\\Test\\upload.txt", L"upload.txt")) std::wcout << L"文件上传成功\n"; else std::wcout << L"文件上传失败\n"; if (ftp.downloadFile(L"download.txt", L"C:\\Test\\download.txt")) std::wcout << L"文件下载成功\n"; else std::wcout << L"文件下载失败\n"; return 0; }
