# uvnetplus **Repository Path**: ztwlla/uvnetplus ## Basic Information - **Project Name**: uvnetplus - **Description**: No description available - **Primary Language**: C++ - **License**: MulanPubL-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 1 - **Created**: 2020-09-14 - **Last Updated**: 2026-05-27 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # uvNetPlus + 基于libuv实现一些网络协议的封装 ## 编译 + C++20标准 + CMake构建系统 + Windows: Visual Studio 2022+ + Linux: GCC 10+ / Clang 12+ ## 协议实现情况 | 协议 | 客户端 | 服务端 | |----- |----- |----- | | tcp(tls) | yes | yes | | tcppool(tls) | yes | no | | http(https) | yes | yes | | ws(wss) | yes | yes | | soap | yes | yes | | ftp(ftps) | yes | yes | | udp | yes | yes | | kcp | yes | yes | ## 示例程序 项目内置了完整的示例程序，位于 `samples/` 目录下： | 示例 | 文件 | 说明 | |----- |----- |----- | | TCP客户端 | samples/tcp/tcp_client_demo.cpp | TCP连接与收发 | | TCP服务端 | samples/tcp/tcp_server_demo.cpp | TCP监听与广播 | | TCP连接池 | samples/tcp/tcp_pool_demo.cpp | 连接池管理 | | TCP Agent | samples/tcp/tcp_agent_demo.cpp | 连接代理管理 | | TLS客户端 | samples/tcp/tls_client_demo.cpp | TLS加密客户端 | | TLS服务端 | samples/tcp/tls_server_demo.cpp | TLS加密服务端 | | HTTP客户端 | samples/http/http_client_demo.cpp | HTTP请求 | | HTTP/WS服务端 | samples/http/http_ws_server_demo.cpp | HTTP+WebSocket服务端 | | WebSocket客户端 | samples/http/websocket_client_demo.cpp | WebSocket连接 | | UDP客户端 | samples/udp/udp_client_demo.cpp | UDP收发 | | UDP服务端 | samples/udp/udp_server_demo.cpp | UDP监听 | | UDP广播 | samples/udp/udp_broadcast_demo.cpp | UDP广播 | | UDP多播 | samples/udp/udp_multicast_demo.cpp | UDP多播 | | FTP服务端 | samples/ftp/ftp_server_demo.cpp | FTP服务端（含PASV数据连接） | | FTP客户端 | samples/ftp/ftp_client_demo.cpp | FTP客户端（含上传/下载） | 外部仓库： * https://gitee.com/ztwlla/uvMoudles.git * https://github.com/BigPig0/uvMoudles.git ## 第三方库 * libUV: https://github.com/libuv/libuv.git * mbedtls: https://github.com/Mbed-TLS/mbedtls (TLS支持) * ikcp: https://github.com/skywind3000/kcp (KCP协议支持) --- ## 设计说明 ### 目录结构 ``` uvnetplus/ ├── uvnetplus.h # 主入口头文件，包含CNet核心类 ├── uvnetplus.cpp # CNetImpl实现 ├── uvnetpuclic.h # 公共定义（PROTOCOL枚举） ├── uvnetprivate.h # 内部私有定义 │ ├── uvnetplus_tcp_interface.h # TCP接口定义 ├── uvnetplus_tcppool_interface.h # TCP连接池接口定义 ├── uvnetplus_http_interface.h # HTTP接口定义 ├── uvnetplus_ws_interface.h # WebSocket接口定义 ├── uvnetplus_soap_interface.h # SOAP接口定义 ├── uvnetplus_ftp_interface.h # FTP接口定义 ├── uvnetplus_udp_interface.h # UDP接口定义 ├── uvnetplus_kcp_interface.h # KCP接口定义 ├── uvnettls.h # TLS接口定义 │ ├── tcp/ # TCP模块实现 │ ├── net_utils.h/cpp # 网络工具函数 │ ├── tcp_client.h/cpp # TCP客户端实现 │ ├── tcp_server.h/cpp # TCP服务端实现 │ ├── tcp_agent.h/cpp # TCP连接代理 │ └── tcp_pool.h/cpp # TCP连接池实现 │ ├── http/ # HTTP模块实现 │ ├── http_common.h/cpp # HTTP公共定义（CHttpMsg、方法/版本转换） │ ├── http_base.h # 内部模板基类CHttpBase（头管理、Socket生命周期） │ │ │ ├── http_client.h/cpp # HTTP客户端管理器（CHttpClientImpl） │ ├── http_request.h/cpp # HTTP/1.1请求实现（CHttpRequestImpl） │ ├── http2_request.h/cpp # HTTP/2请求实现（CHttp2RequestImpl） │ ├── http_response.h/cpp # HTTP响应实现（CHttpResponseImpl，支持HTTP/1.1和HTTP/2） │ │ │ ├── http_protocol_handler.h # 协议处理器接口（IHttpProtocolHandler） │ ├── http_server_connect.h/cpp # 服务端连接管理（CHttpServerConnect） │ ├── http_handler.h/cpp # HTTP/1.1协议处理器（CHttpHandler） │ ├── http_router.h/cpp # URL路由服务（CHttpRouter） │ ├── http_server.h/cpp # HTTP服务端实现（CHttpServerImpl） │ │ │ ├── http2_handler.h/cpp # HTTP/2服务端协议处理器（CHttp2Handler） │ ├── http2_client_handler.h/cpp # HTTP/2客户端协议处理器（CHttp2ClientHandler） │ ├── h2_frame.h # HTTP/2帧定义和工具函数 │ └── h2_hpack.h/cpp # HPACK头压缩编解码器 │ ├── websocket/ # WebSocket模块实现 │ └── websocket.h/cpp # WebSocket客户端/连接实现 │ ├── soap/ # SOAP模块实现 │ ├── soap_client.h/cpp # SOAP客户端实现 │ └── soap_server.h/cpp # SOAP服务端实现 │ ├── ftp/ # FTP模块实现 │ ├── ftp_common.h/cpp # FTP公共定义（命令枚举、文件类型等） │ ├── ftp_client.h/cpp # FTP客户端管理器实现 │ ├── ftp_connect.h/cpp # FTP连接实现（控制通道与数据通道） │ ├── ftp_connect_pool.h/cpp # FTP连接池实现 │ ├── ftp_server.h/cpp # FTP服务端实现 │ └── ftp_response.h/cpp # FTP响应实现（继承CFtpResponse，含协议处理与PASV数据连接） │ ├── udp/ # UDP模块实现 │ ├── udp_socket.h/cpp # UDP套接字实现 │ └── udp_server.h/cpp # UDP服务端实现 │ ├── kcp/ # KCP模块实现 │ ├── ikcp.h/c # KCP协议库（内置） │ ├── kcp_client.h/cpp # KCP客户端实现 │ └── kcp_server.h/cpp # KCP服务端实现 │ ├── tls/ # TLS模块实现 │ ├── tls_engine.h # TLS引擎接口 │ └── mbed_tls_engine.h/cpp # 基于mbedtls的实现 │ ├── samples/ # 示例程序 │ ├── tcp/ # TCP/TLS示例 │ ├── http/ # HTTP/WebSocket示例 │ ├── udp/ # UDP示例 │ └── ftp/ # FTP示例 │ └── old/ # 旧版文件（已废弃） ``` ### 整体架构 ``` ┌─────────────────────────────────────────────────────────────┐ │ uvNetPlus │ ├─────────────────────────────────────────────────────────────┤ │ CNet (事件循环核心) - uvnetplus.h │ │ ├── CNetImpl (实现类) - uvnetplus.cpp │ │ │ ├── uv_loop_t (libuv事件循环) │ │ │ ├── uv_async_t (异步事件通知) │ │ │ └── 事件线程 (内部loop时创建) │ ├─────────────────────────────────────────────────────────────┤ │ 传输层 │ │ ├── TCP层 (tcp/) │ │ │ ├── CTcpSocket (TCP客户端) │ │ │ ├── CTcpServer (TCP服务端) │ │ │ └── CTcpAgent (连接池管理) │ │ ├── TCP连接池层 (tcp/tcp_pool.h/cpp) │ │ │ ├── CTcpConnPool (连接池) │ │ │ └── CTcpPoolAgent (单地址连接管理) │ │ └── UDP层 (udp/) │ │ ├── CUdpSocket (UDP套接字) │ │ └── CUdpServer (UDP服务端) │ ├─────────────────────────────────────────────────────────────┤ │ 应用层 (基于传输层实现) │ │ ├── HTTP层 (http/) ← 基于CTcpConnPool │ │ │ ├── 接口层 (uvnetplus_http_interface.h) │ │ │ │ ├── CHttpClient (HTTP客户端接口) │ │ │ │ ├── CHttpServer (HTTP服务端接口) │ │ │ │ ├── CHttpRequest (HTTP请求接口) │ │ │ │ ├── CHttpResponse(HTTP响应接口) │ │ │ │ └── CHttpMsg (HTTP消息数据结构) │ │ │ ├── 实现层 │ │ │ │ ├── CHttpClientImpl (客户端管理器) │ │ │ │ ├── CHttpServerImpl (服务端管理器) │ │ │ │ ├── CHttpRequestImpl (HTTP/1.1请求) │ │ │ │ ├── CHttp2RequestImpl (HTTP/2请求) │ │ │ │ ├── CHttpResponseImpl (响应，支持HTTP/1.1和HTTP/2)│ │ │ │ └── CHttpBase (内部模板基类，头管理) │ │ │ └── 协议层 (HTTP/2支持) │ │ │ ├── CHttp2Handler (服务端HTTP/2连接处理器) │ │ │ ├── CHttp2ClientHandler (客户端HTTP/2连接处理器) │ │ │ ├── HpackCodec (HPACK头部压缩) │ │ │ └── H2::Frame (HTTP/2帧定义) │ │ ├── WebSocket层 (websocket/) ← 基于HTTP层 │ │ │ ├── CWebSocketClient (WS客户端) │ │ │ └── CWebSocket (WS连接，服务端通过HTTP升级获得) │ │ ├── SOAP层 (soap/) ← 基于HTTP层 │ │ │ ├── CSoapClient (SOAP客户端) │ │ │ └── CSoapRequest (SOAP请求) │ │ ├── KCP层 (kcp/) ← 基于UDP层 │ │ │ ├── CKcpSocket (KCP客户端) │ │ │ └── CKcpServer (KCP服务端) │ │ └── FTP层 (ftp/) ← 基于TCP层 │ │ ├── CFtpClient (FTP客户端管理器) │ │ ├── CFtpConnect (FTP连接，控制+数据通道) │ │ ├── CFtpConnectPool (FTP连接池) │ │ ├── CFtpServer (FTP服务端) │ │ ├── CFtpSession (FTP会话，含PASV数据连接) │ │ └── CFtpResponse (FTP响应) │ ├─────────────────────────────────────────────────────────────┤ │ 安全层 │ │ └── TLS层 (tls/) ← 基于mbedtls │ │ └── CTlsEngine (TLS引擎) │ └─────────────────────────────────────────────────────────────┘ ``` ### 核心设计模式 #### 1. 事件驱动架构 - **CNet/CNetImpl**: 核心事件循环封装 - 支持外部传入`uv_loop_t`或内部自动创建 - 内部创建时自动启动事件循环线程 - 使用`uv_async_t`实现跨线程事件通知 - 通过`UV_ASYNC_EVENT`枚举定义所有异步事件类型 ```cpp enum class UV_ASYNC_EVENT { LOOP_CLOSE, // 事件循环关闭 TCP_CONNECT, // TCP客户端连接 TCP_SEND, // TCP发送数据 TCP_LISTEN, // TCP服务端监听 TCP_CLTCLOSE, // TCP客户端关闭 TCP_SVRCLOSE, // TCP服务端关闭 TCPCONN_INIT, // TCP连接池初始化 TCPCONN_REQUEST, // TCP连接池请求 // ... }; ``` #### 2. 接口与实现分离 所有公开类采用纯虚接口设计，实现类以`Impl`后缀命名： - `CTcpSocket` (接口) ← `CTcpSocketImpl` (实现) - `CTcpServer` (接口) ← `CTcpServerImpl` (实现) - `CHttpClient` (接口) ← `CHttpClientImpl` (实现) - `CHttpServer` (接口) ← `CHttpServerImpl` (实现) - `CHttpRequest` (接口) ← `CHttpRequestImpl` / `CHttp2RequestImpl` (实现) - `CHttpResponse` (接口) ← `CHttpResponseImpl` (实现) - `CFtpConnect` (接口) ← `CFtpConnectImpl` (实现) 接口定义在 `uvnetplus_xxx_interface.h` 文件中，实现在对应的模块目录中。 **HTTP模块的特殊设计**： - `CHttpRequest`和`CHttpResponse`是纯虚接口，对HTTP/1.1和HTTP/2协议透明 - `CHttpBase`是内部模板基类，实现共享功能（头管理、Socket生命周期），不对外暴露 - `CHttpRequestImpl`（HTTP/1.1）和`CHttp2RequestImpl`（HTTP/2）都继承自`CHttpBase` - `CHttpResponseImpl`同时支持HTTP/1.1和HTTP/2，根据连接协议自动选择发送方式 #### 3. 回调机制 所有异步操作通过 `std::function` 回调通知结果： ```cpp using EventCB = std::function; using RecvCB = std::function; using ErrorCB = std::function; ``` #### 4. 智能指针与内存管理 - 内部对象生命周期使用 `std::unique_ptr` 管理（如 `CFtpServer` 中的会话列表） - 与 libuv C库交互的部分保留原始指针 - 回调参数中的指针为观察者语义，不转移所有权 - 工厂方法返回 `std::shared_ptr`，对象生命周期由智能指针自动管理 #### 5. 枚举类型 使用 C++20 `enum class` 提供类型安全： ```cpp enum class FTP_CMD : int { USER, PASS, PWD, CWD, LIST, NLST, RETR, STOR, ... }; enum class FTP_DATA_MOD : int { PASV = 0, PORT = 1 }; enum class FTP_FILE_TYPE : int { ASCII = 0, BINARY = 1 }; ``` ### 模块详解 #### TCP模块 (tcp/) **CTcpSocket - TCP客户端** - 支持IPv4/IPv6 - 支持本地地址绑定 - 支持TLS加密 (编译时开启USE_TLS) - 发送队列管理，支持数据拷贝或引用 - 自动接收模式可配置 **CTcpServer - TCP服务端** - 支持监听指定IP和端口 - 自动管理客户端连接列表 - 支持TLS服务端 (需要配置证书和私钥) **CTcpAgent - 简单连接池** - 管理空闲连接 - 定时检测超时连接 #### TCP连接池模块 (tcp/tcp_pool.h/cpp) **CTcpConnPool - 高级连接池** - 按目标地址(host:port)分组管理 - 每组连接由CTcpPoolAgent管理 - 支持DNS解析域名 - 配置参数： - `maxConns`: 最大连接数 (默认512) - `maxIdle`: 最大空闲连接数 (默认100) - `timeOut`: 空闲超时时间 (默认20秒) - `maxRequest`: 最大等待请求数 **CTcpPoolAgent - 单地址连接管理** - 维护busy和idle两个连接列表 - 负责DNS解析 - 连接复用与超时清理 #### HTTP模块 (http/) HTTP模块采用分层架构设计，支持HTTP/1.1和HTTP/2协议： ##### 公共接口层 (uvnetplus_http_interface.h) **CHttpClient** - HTTP客户端接口（纯虚类） - 工厂方法：`CHttpClient::Create(net)` - 核心方法： - `Request()` - 发起HTTP/1.1请求 - `RequestH2()` - 发起HTTP/2请求（优先使用HTTP/2，服务器不支持时降级到HTTP/1.1） - `SetTls()` - 配置HTTPS支持 **CHttpRequest** - HTTP请求接口（纯虚类） - 表示一个HTTP请求/响应对（客户端视角） - 核心方法： - `SetHeader()` / `GetHeader()` - 头部管理 - `Write()` - 发送请求体数据（支持流式传输） - `End()` - 结束请求 - 回调事件： - `OnResponse` - 接收响应头 - `OnData` - 接收响应体数据（支持chunked和流式） - `OnEnd` - 响应完成 - `OnError` - 请求错误 **CHttpResponse** - HTTP响应接口（纯虚类） - 表示一个HTTP响应（服务端视角） - 核心方法： - `SetHeader()` / `GetHeader()` - 头部管理 - `WriteHead()` - 发送响应头 - `Write()` - 发送响应体数据（支持流式传输） - `End()` - 结束响应 - `UpgradeWebSocket()` - 升级到WebSocket协议 **CHttpMsg** - HTTP消息数据结构 - 存储解析后的HTTP消息（请求或响应） - 成员： - `method` / `url` / `version` - 请求行 - `statusCode` / `statusMessage` - 状态行 - `headers` - 头部字典 - `content` - 消息体 - `chunked` / `contentLen` - 传输模式 **CHttpServer** - HTTP服务端接口（纯虚类） - 工厂方法：`CHttpServer::Create(net)` - 核心方法： - `Listen()` - 监听端口 - `On()` - 注册路由处理器 - 回调事件： - `OnRequest` - 处理HTTP请求 - `OnUpgrade` - 处理协议升级（如WebSocket） ##### 实现层 **内部基类 (http_base.h)** `CHttpBase` - 模板基类（内部使用，不对外暴露） - 继承自公共接口（`CHttpRequest`或`CHttpResponse`） - 实现共享功能： - HTTP头部管理（`SetHeader`、`GetHeader`、`WriteHead`） - TCP Socket生命周期管理（`tcpSocket`成员） - 派生类： - `CHttpRequestImpl` - HTTP/1.1客户端请求 - `CHttp2RequestImpl` - HTTP/2客户端请求 - `CHttpResponseImpl` - 服务端响应（同时支持HTTP/1.1和HTTP/2） **客户端实现** `CHttpClientImpl` (http_client.h/cpp) - 实现`CHttpClient`接口 - 管理连接池（`CTcpConnPool`）和HTTP/2会话（`H2ClientSession`） - 负责请求分发： - `Request()` - 创建`CHttpRequestImpl`对象，通过连接池获取TCP连接 - `RequestH2()` - 创建`CHttp2RequestImpl`对象，复用或创建HTTP/2连接 `CHttpRequestImpl` (http_request.h/cpp) - 继承自`CHttpBase` - 实现HTTP/1.1客户端请求处理： - 构造HTTP/1.1请求头（`GET /path HTTP/1.1\r\n...`） - 解析HTTP/1.1响应（状态行、头部、chunked/定长body） - 管理请求/响应生命周期 `CHttp2RequestImpl` (http2_request.h/cpp) - 继承自`CHttpBase` - 实现HTTP/2客户端请求处理： - 通过`CHttp2ClientHandler`发送HEADERS帧和DATA帧 - 接收并解析HTTP/2响应帧 - 管理流级别的状态（streamId、窗口控制） `CHttp2ClientHandler` (http2_client_handler.h/cpp) - **连接级别**的HTTP/2协议处理器（客户端） - 管理一个TCP连接上的多个HTTP/2流（多路复用） - 职责： - 发送/接收HTTP/2帧（SETTINGS、HEADERS、DATA、PING、GOAWAY等） - HPACK头部压缩/解压缩 - 流ID分配和流状态管理 - 连接级别的流量控制（窗口管理） - 与`CHttp2RequestImpl`的关系： - 一个`CHttp2ClientHandler`对应一个TCP连接 - 一个连接上可以有多个`CHttp2RequestImpl`对象（多个并发请求） - `CHttp2RequestImpl`通过`m_handler`指针调用Handler发送数据 **服务端实现** `CHttpServerImpl` (http_server.h/cpp) - 实现`CHttpServer`接口 - 管理TCP服务端（`CTcpServer`）和连接列表（`m_conns`） - 集成路由功能（`CHttpRouter`） `IHttpProtocolHandler` (http_protocol_handler.h) - 协议处理器接口（纯虚类） - 定义协议处理的统一接口： - `OnData()` - 处理接收到的数据 - `Shutdown()` - 关闭协议处理器 - 派生类： - `CHttpHandler` - HTTP/1.1协议处理器 - `CHttp2Handler` - HTTP/2协议处理器 `CHttpServerConnect` (http_server_connect.h/cpp) - 表示服务端的一个客户端连接 - 职责： - 管理TCP Socket - 协议检测（HTTP/1.1或HTTP/2） - 委托给对应的协议处理器（`CHttpHandler`或`CHttp2Handler`） - 管理WebSocket升级 - 成员： - `m_client` - TCP Socket - `m_protocol` - 连接协议（HTTP/1.1或HTTP/2） - `m_handler` - 协议处理器（`IHttpProtocolHandler`） - `m_ws` - WebSocket对象（升级后） `CHttpHandler` (http_handler.h/cpp) - 实现`IHttpProtocolHandler`接口 - HTTP/1.1协议处理器 - 职责： - 解析HTTP/1.1请求（请求行、头部、内容） - 支持chunked传输编码 - 管理请求/响应对（`CHttpMsg`和`CHttpResponseImpl`） `CHttpResponseImpl` (http_response.h/cpp) - 继承自`CHttpBase` - 实现服务端响应处理（同时支持HTTP/1.1和HTTP/2）： - HTTP/1.1：构造响应头（`HTTP/1.1 200 OK\r\n...`），支持chunked编码 - HTTP/2：通过`CHttp2Handler`发送HEADERS帧和DATA帧 - 自动检测连接协议并选择正确的发送方式 `CHttp2Handler` (http2_handler.h/cpp) - 实现`IHttpProtocolHandler`接口 - **连接级别**的HTTP/2协议处理器（服务端） - 管理一个TCP连接上的多个HTTP/2流（多路复用） - 职责： - 接收/解析HTTP/2帧（SETTINGS、HEADERS、DATA、PING、GOAWAY等） - HPACK头部压缩/解压缩 - 流状态管理（`Http2Stream`） - 连接级别的流量控制和安全限制（防洪泛） - 与`CHttpResponseImpl`的关系： - 一个`CHttp2Handler`对应一个TCP连接 - 一个连接上可以有多个流（多个请求/响应对） - 每个流有一个`Http2Stream`对象，包含`request`（`CHttpMsg`）和`response`（`CHttpResponseImpl`） **HTTP/2支持** `h2_frame.h` - HTTP/2帧定义 - 帧类型枚举（`FrameType`） - 帧标志（`FrameFlags`） - 错误码（`ErrorCode`） - 帧头结构（`FrameHeader`） - 工具函数（序列化/反序列化） `h2_hpack.h/cpp` - HPACK头部压缩 - `HpackCodec` - HPACK编解码器 - 动态表管理 - 静态表查找 - Huffman编码/解码 ##### 架构关系图 ``` 客户端： CHttpClient (接口) └── CHttpClientImpl (实现) ├── CTcpConnPool (HTTP/1.1连接池) │ └── CHttpRequestImpl (HTTP/1.1请求) │ └── CHttpBase (头管理、Socket) └── CHttp2ClientHandler (HTTP/2连接处理器) └── CHttp2RequestImpl (HTTP/2请求) └── CHttpBase (头管理、Socket) 服务端： CHttpServer (接口) └── CHttpServerImpl (实现) └── CHttpServerConnect (连接管理) │ ├── 协议检测 → 委托给协议处理器 │ ├── HTTP/1.1: CHttpHandler (实现 IHttpProtocolHandler) │ └── 管理 CHttpMsg + CHttpResponseImpl │ └── CHttpBase │ └── HTTP/2: CHttp2Handler (实现 IHttpProtocolHandler) └── Http2Stream (流管理) ├── request: CHttpMsg └── response: CHttpResponseImpl └── CHttpBase ``` ##### 设计要点 1. **接口与实现分离**：公共接口定义在`uvnetplus_http_interface.h`，实现类在`http/`目录中 2. **协议透明**：`CHttpRequest`和`CHttpResponse`接口对HTTP/1.1和HTTP/2透明，用户无需关心底层协议 3. **连接复用**：HTTP/1.1使用连接池（`CTcpConnPool`），HTTP/2使用多路复用（一个连接多个流） 4. **流式传输**：支持chunked编码（HTTP/1.1）和流式帧（HTTP/2），适合大文件传输 5. **协议升级**：支持h2c升级（HTTP/1.1 → HTTP/2）和WebSocket升级 6. **分层设计**： - **接口层**：纯虚类，定义用户API - **基类层**：`CHttpBase`模板，实现共享功能 - **实现层**：具体协议实现（HTTP/1.1、HTTP/2） - **协议层**：`IHttpProtocolHandler`接口，统一协议处理 - `CHttpHandler` - HTTP/1.1协议处理器 - `CHttp2Handler` - HTTP/2协议处理器（连接级别状态机） - `CHttp2ClientHandler` - HTTP/2客户端协议处理器 #### WebSocket模块 (websocket/) WebSocket与HTTP共用同一个服务端，通过HTTP Upgrade机制升级连接。 **CWebSocketClient - WebSocket客户端** - 基于CHttpClient实现握手 - 支持ws://和wss://协议 - 支持自定义请求头 - 支持子协议协商 - 自动处理Ping/Pong心跳 **CHttpServer.UpgradeWebSocket() - 服务端WebSocket升级** - 在OnUpgrade回调中调用response->UpgradeWebSocket() - 自动发送101 Switching Protocols响应 - 返回CWebSocket对象用于后续通信 - HTTP和WebSocket共用同一端口 **CWebSocket - WebSocket连接** - 支持文本和二进制消息 - 支持分片传输 - 自动处理帧编解码 - 内置SHA1和Base64实现，无需额外依赖 **使用示例** ```cpp // 服务端：HTTP和WebSocket共用端口 Http::CHttpServer* svr = Http::CHttpServer::Create(net); svr->OnUpgrade = [](Http::CHttpServer* svr, Http::CHttpMsg* req, Http::CHttpResponse* res) { auto upgrade = req->headers.find("Upgrade"); if(upgrade != req->headers.end() && strcasecmp(upgrade->second.c_str(), "websocket") == 0) { WebSocket::CWebSocket* ws = res->UpgradeWebSocket(); if(ws) { ws->OnMessage = [](WebSocket::CWebSocket* ws, const char* data, uint64_t len, WebSocket::WS_OPCODE opcode) { ws->Send(data, len, opcode); // 回显 }; } } }; svr->Listen("0.0.0.0", 8080); // 客户端 WebSocket::CWebSocketClient* ws = WebSocket::CWebSocketClient::Create(net); ws->OnConnect = [](WebSocket::CWebSocketClient* ws, std::string err) { if(err.empty()) ws->SendText("Hello", 5); }; ws->Connect("ws://127.0.0.1:8080/ws"); ``` #### SOAP模块 (soap/) **CSoapClient - SOAP客户端** - 基于CHttpClient发送SOAP请求 - 基于WSDL解析生成SOAP请求 - 支持参数编码 (转义或CDATA) **CSoapServer - SOAP服务端** - 基于CHttpServer实现SOAP服务 - 支持WSDL文件发布 (?wsdl) - 支持操作处理函数注册 - 自动解析SOAP请求和生成响应 - 支持SOAP Fault错误响应 **使用示例** ```cpp // 创建HTTP服务端 Http::CHttpServer* httpSvr = Http::CHttpServer::Create(net); httpSvr->Listen("0.0.0.0", 8080); // 创建SOAP服务端 std::string wsdl = "..."; Http::CSoapServer::Create(httpSvr, wsdl, "/soap", [](Http::CSoapServer* svr, std::string err) { if(err.empty()) { svr->OnOperation("Add", [](Http::CSoapServer* svr, std::string op, std::map inParams, std::map& outParams, std::string& error) { int a = atoi(inParams["a"].c_str()); int b = atoi(inParams["b"].c_str()); outParams["result"] = std::to_string(a + b); }); } }); ``` #### UDP模块 (udp/) **CUdpSocket - UDP套接字** - 支持IPv4/IPv6 - 支持广播和多播 - 可配置TTL和多播参数 **CUdpServer - UDP服务端** - 监听指定端口接收数据 - 支持向任意地址发送数据 - 支持多播组管理 #### KCP模块 (kcp/) **CKcpSocket - KCP客户端** - 基于CUdpSocket实现可靠传输 - 可配置传输参数 (nodelay, interval, resend等) - 支持自定义会话ID (conv) **CKcpServer - KCP服务端** - 基于CUdpSocket实现 - 自动管理多个KCP连接 - 基于conv区分不同客户端 - 支持连接参数配置 **KcpConfig - KCP配置** - `nodelay`: 是否启用无延迟模式 - `interval`: 内部更新间隔(ms) - `resend`: 快速重传阈值 - `sndwnd/rcvwnd`: 发送/接收窗口大小 - `mtu`: 最大传输单元 **ikcp库** - KCP协议的C语言实现，已内置在kcp/目录 - 来源: https://github.com/skywind3000/kcp #### FTP模块 (ftp/) **CFtpClient - FTP客户端管理器** - 创建和管理FTP连接 - 支持单连接和连接池两种模式 **CFtpConnect - FTP连接** - 基于TCP实现FTP协议控制通道 - 支持被动模式(PASV)和主动模式(PORT)数据传输 - 文件操作: 上传(STOR)、下载(RETR) - 目录操作: 列表(LIST/NLST)、创建(MKD)、删除(RMD)、切换(CWD) - 文件管理: 删除(DELE)、重命名(RNFR/RNTO)、获取大小(SIZE) - 支持ASCII和BINARY文件类型 - 支持UTF-8字符编码 - 支持FTPS (编译时开启USE_TLS) **CFtpConnectPool - FTP连接池** - 复用已登录的FTP连接 - 自动管理连接分配和回收 - 线程安全的请求队列 **CFtpServer - FTP服务端** - 基于CTcpServer和CTcpAgent实现 - 完整的PASV被动模式数据连接支持 - 每个会话独立的数据端口监听 - 支持常见FTP命令: - 认证: USER, PASS - 目录: PWD, CWD, CDUP, MKD, RMD - 文件列表: LIST, NLST (通过PASV数据连接传输) - 文件传输: RETR, STOR (通过PASV数据连接传输) - 文件管理: DELE, RNFR, RNTO, SIZE - 传输控制: TYPE, PASV, PORT - 系统: SYST, FEAT, OPTS, NOOP, QUIT - 支持TLS加密 (FTPS) **CFtpSession - FTP会话管理** - 管理单个客户端的FTP会话 - 处理控制连接的命令解析和响应 - 管理PASV数据连接的生命周期: - 创建临时TCP监听器接受数据连接 - 处理命令与数据连接的时序协调 - 数据传输完成后自动清理 **CFtpResponse - FTP响应** - 封装服务端对请求的响应 **使用示例** ```cpp // FTP服务端 Ftp::CFtpServer* ftpSvr = Ftp::CFtpServer::Create(net); ftpSvr->OnListen = [](Ftp::CFtpServer* svr, std::string err) { if(err.empty()) Log::info("FTP server started"); }; ftpSvr->SetKeepAlive(300); ftpSvr->Listen("0.0.0.0", 2121); // FTP客户端（使用CFtpParam结构体） Ftp::CFtpClient* ftp = Ftp::CFtpClient::Create(net); Ftp::CFtpParam param; param.host = "127.0.0.1"; param.port = 2121; param.user = "anonymous"; param.pwd = "anonymous"; param.dataMod = Ftp::FTP_DATA_MOD::PASV; param.onSuccess = [](Ftp::CFtpConnect* conn) { // 登录成功，列出文件 conn->List([](Ftp::CFtpConnect* c, std::list files) { for(auto& f : files) Log::info("%s %8llu %s", f.isDir ? "DIR " : "FILE", static_cast(f.size), f.name.c_str()); }); // 下载文件 conn->Download("file.txt", [](Ftp::CFtpConnect* c, char* data, uint32_t len) { Log::info("Downloaded %u bytes", len); }); // 上传文件 const char* content = "Hello FTP"; conn->Upload("upload.txt", const_cast(content), 9, [](Ftp::CFtpConnect* c) { Log::info("Upload complete"); }); }; param.onError = [](Ftp::CFtpConnect* conn, Ftp::CFtpMsg* msg) { Log::error("FTP error: %d %s", msg->replyCode, msg->replyStr.c_str()); }; ftp->Connect(param); ``` #### TLS模块 (tls/) **CTlsEngine - TLS引擎接口** - 基于mbedtls实现TLS加密 - 支持客户端和服务端模式 - 支持证书验证配置 **使用方式** - 客户端: 调用 `CTcpSocket::UseTls()` 启用TLS - 服务端: 调用 `CTcpServer::UseTls()` 并配置证书/私钥 ### TLS支持 编译时定义`USE_TLS`宏启用TLS功能（使用mbedtls库）： - 客户端支持证书验证 - 服务端支持证书/私钥配置 - 支持CA证书配置 (内存/文件/目录) ### 线程模型 1. **单事件循环线程**: 所有I/O操作在事件循环线程中执行 2. **异步事件通知**: 外部线程通过`AddEvent()`投递事件 3. **线程安全**: 发送队列使用mutex保护 ### 使用示例 ```cpp // 创建网络环境 CNet* net = CNet::Create(); // 自动创建事件循环线程 // TCP客户端 CTcpSocket* tcp = CTcpSocket::Create(net); tcp->OnConnect = [](CTcpSocket* skt, std::string err) { if(err.empty()) { skt->Send("Hello", 5); } }; tcp->OnRecv = [](CTcpSocket* skt, char *data, int len) { // 处理接收数据 }; tcp->Connect("127.0.0.1", 8080); // HTTP客户端 Http::CHttpClient http(net); http.Request("example.com", 80, nullptr, [](Http::CHttpRequest* req, void* usr, std::string err) { if(req) { req->End(); // 发送空请求 req->OnResponse = [](Http::CHttpRequest* req, Http::CHttpMsg* res) { // 处理响应 }; } }); // HTTP服务端（同时支持WebSocket） Http::CHttpServer* svr = Http::CHttpServer::Create(net); svr->OnRequest = [](Http::CHttpServer* svr, Http::CHttpMsg* req, Http::CHttpResponse* res) { res->End("Hello World", 11); }; svr->OnUpgrade = [](Http::CHttpServer* svr, Http::CHttpMsg* req, Http::CHttpResponse* res) { auto upgrade = req->headers.find("Upgrade"); if(upgrade != req->headers.end() && strcasecmp(upgrade->second.c_str(), "websocket") == 0) { WebSocket::CWebSocket* ws = res->UpgradeWebSocket(); if(ws) { ws->OnMessage = [](WebSocket::CWebSocket* ws, const char* data, uint64_t len, WebSocket::WS_OPCODE opcode) { ws->Send(data, len, opcode); // 回显 }; } } }; svr->Listen("0.0.0.0", 8080); // WebSocket客户端 WebSocket::CWebSocketClient* ws = WebSocket::CWebSocketClient::Create(net); ws->OnConnect = [](WebSocket::CWebSocketClient* ws, std::string err) { if(err.empty()) { ws->SendText("Hello WebSocket", 15); } }; ws->OnMessage = [](WebSocket::CWebSocket* ws, const char* data, uint64_t len, WebSocket::WS_OPCODE opcode) { // 处理接收消息 }; ws->Connect("ws://127.0.0.1:8080/ws"); // UDP服务端 CUdpSocket* udp = CUdpSocket::Create(net); udp->OnRecv = [](CUdpSocket* skt, const char* data, int len, const char* addr, uint16_t port) { skt->Send(data, len, addr, port); // 回显 }; udp->Bind("0.0.0.0", 8080); // KCP客户端 KCP::CKcpSocket* kcp = KCP::CKcpSocket::Create(net); kcp->OnConnect = [](KCP::CKcpSocket* skt) { skt->Send("Hello KCP", 9); }; kcp->OnRecv = [](KCP::CKcpSocket* skt, const char* data, int len) { // 处理接收数据 }; kcp->Connect("127.0.0.1", 8080); // KCP服务端 KCP::CKcpServer* kcpSvr = KCP::CKcpServer::Create(net); kcpSvr->OnConnection = [](KCP::CKcpServer* svr, KCP::CKcpSocket* client) { client->OnRecv = [](KCP::CKcpSocket* skt, const char* data, int len) { skt->Send(data, len); // 回显 }; }; kcpSvr->Listen("0.0.0.0", 8080); ```