高性能 TCP & UDP 通信框架 HP-Socket v3.3.1

　　HP-Socket 是一套通用的高性能 TCP/UDP 通信框架，包含服务端组件、客户端组件和 Agent 组件，广泛适用于各种不同应用场景的 TCP/UDP 通信系统，提供 C/C++、C#、Delphi、E（易语言）、Java、Python 等编程语言接口。HP-Socket 对通信层实现完全封装，应用程序不必关注通信层的任何细节；HP-Socket 提供基于事件通知模型的 API 接口，能非常简单高效地整合到新旧应用程序中。

　　为了让使用者能方便快速地学习和使用 HP-Socket，迅速掌握框架的设计思想和使用方法，特此精心制作了大量 Demo 示例（如：PUSH 模型示例、PULL 模型示例、性能测试示例以及其它编程语言示例）。HP-Socket 目前运行在 Windows 平台，将来会实现跨平台支持。

----------------------------------------------------------------

通用性

• HP-Socket 的唯一职责就是接收和发送字节流，不参与应用程序的协议解析等工作。
• HP-Socket 与应用程序通过接口进行交互，并完全解耦。任何应用只要实现了 HP-Socket 的接口规范都可以无缝整合 HP-Socket。

易用性

　　易用性对所有通用框架都是至关重要的，如果太难用还不如自己重头写一个来得方便。因此，HP-Socket 的接口设计得非常简单和统一。

　　HP-Socket 完全封装了所有底层通信细节，应用程序不必也不能干预底层通信操作。通信连接被抽象为 Connection ID，Connection ID 作为连接的唯一标识提供给应用程序来处理不同的连接。

高性能

　　HP-Socket 作为底层的通用框架，性能是关键指标，绝对不能成为系统的瓶颈。HP-Socket 在设计上充分考虑性能、使用场景、复杂性和易用性等因素，作出以下几点设计决策：

• Client 组件：基于 Event Select 通信模型，在单独线程中执行通信操作，避免与主线程或其他线程相互干扰。每个组件对象管理一个 Socket 连接。
• Server 组件：基于 IOCP 通信模型，并结合缓存池、私有堆（Private Heap）等技术，支持超大规模连接，在高并发场景下实现高效内存管理。
• Agent 组件：对于代理服务器或中转服务器等应用场景，服务器自身也作为客户端向其它服务器发起大规模连接，一个 Agent 组件对象同时可管理多个 Socket 连接；Agent 组件与 Server 组件采用相同的技术架构，可以用作代理服务器或中转服务器的客户端部件。

伸缩性

　　应用程序能够根据不同的容量要求、通信规模和资源状况等现实场景调整 HP-Socket 的各项性能参数（如：工作线程的数量、缓存池的大小、发送模式和接收模式等），优化资源配置，在满足应用需求的同时不必过度浪费资源。

　　 (项目主页：点击这里，下载地址：点击这里)

---

*** v3.3.1更新 ***

> 组件接口调整：

-----------------

1. IClientListener 监听器接口用 IClient* 参数取代 CONNID 参数标识 Client 组件对象
2. 增加 IPullClient 接口，用作 PULL Client 组件的基接口
3. IPullSocket 和 IPullClient 接口增加 Peek() 方法用于窥探缓冲区数据（不会移除缓冲区数据）
4. 增加 IComplexSocketListener 监听器接口，用作 Server/Agent 组件的监听器基接口
5. IComplexSocketListener 提供 OnShutdown 通知方法取代 Server/Agent 组件原来的 OnServerShutdown/OnAgentShutdown
6. IClient组件增加 Get/SetExtra() 方法用于保存自定义附加数据
7. IServer 和 IAgent 组件增加“静默连接处理”相关方法：

   1) DisconnectSilenceConnections()：// 断开超过指定时长的静默连接
   2) GetSilencePeriod()：// 获取某个连接静默时间（毫秒）
   3) SetMarkSilence()：// 设置是否标记静默时间
   4) IsMarkSilence()：// 检测是否标记静默时间

> 增加 UdpCast 通信组件：

-----------------

1. UdpClient / UdpServer 用于 C/S 模式的点对点单播通信，但在某些应用场景下，需要用到组播或广播通信
2. UdpCast 实现了组播或广播通信，UdpCast 提供 IUdpCast 接口，该接口继承自 IClient，有以下接口方法：

   /* 1) 通知接口方法： */
     OnPrepareConnect(IClient* pClient, SOCKET socket)
     OnConnect(IClient* pClient)
     OnSend(IClient* pClient, const BYTE* pData, int iLength)
     OnReceive(IClient* pClient, const BYTE* pData, int iLength)
     OnClose(IClient* pClient)
     OnError(IClient* pClient, EnSocketOperation enOperation, int iErrorCode)
   
   /* 2) 主要操作方法： */
     Start(LPCTSTR pszBindAddress = nullptr, BOOL bAsyncConnect = TRUE /*该参数被忽略*/)
     Stop()
     Connect(LPCTSTR pszRemoteAddress, USHORT usPort, CONNID* pdwConnID = nullptr)
     Send(CONNID dwConnID, const BYTE* pBuffer, int iLength, int iOffset = 0)
     SendPackets(const WSABUF pBuffers[], int iCount)

3. 增加 UdpCast 使用示例：TestUDPCast
   

> 升级说明：

-----------------

1. HP-Socket v3.3.1 在功能上兼容 HP-Socket v3.2.3 版本，但代码级别不完全兼容
2. HP-Socket v3.2.3 升级到 HP-Socket v3.3.1 需要注意以下调整：

   1) Client 组件
     a) IClientListener 监听器接口调整，所有通知方法的参数有调整
     b) PULL Client 用 IPullClient 作为基接口，Fetch()/Peek()方法参数有调整
   2) Agent/Server 组件
     a) OnShutdown 取代 OnServerShutdown/OnAgentShutdown

---

*** v3.2.3更新 ***

> common-src 优化：

-----------------

1. 优化通信组件的同步机制
2. 整体性能提升约 10%

> 升级说明：

-----------------

1. 使用 HP-Socket v3.2.2 及以前版本的应用程序可以安全升级到 HP-Socket v3.2.3

---

*** v3.2.2 更新 ***

> 增加若干帮助方法：

-----------------

1. 批量发送方法 SendPackets()

   1) IClient/IServer/IAgent 增加方法 SendPackets(dwConnID, pBuffers[], iBufferCount)
   2) 对于 TCP 组件 - 顺序发送所有数据包
   3) 对于 UDP 组件 - 把所有数据包组合成一个数据包发送（总长度不能大于 UDP 包最大长度）

2. 小文件发送方法 SendSmallFile()

   1) ITcpClient/ITcpServer/ITcpAgent 增加方法 SendSmallFile(lpszFileName, pHead, pTail)
   2) 通过 pHead 和 pTail 参数，可以分别在文件数据的头部和尾部加入自定义数据
   3) SendSmallFile() 只能发送 4096 KB 以内大小的文件

3. HPSocket.dll 和 HPSocket4C.dll 增加以下导出方法

   1) SYS_WSAGetLastError()：调用系统的 WSAGetLastError()
   2) SYS_SetSocketOption()：调用系统的 setsockopt()
   3) SYS_GetSocketOption()：调用系统的 getsockopt()
   4) SYS_IoctlSocket()	：调用系统的 ioctlsocket()
   5) SYS_WSAIoctl()	：调用系统的 WSAIoctl()

> 升级说明：

-----------------

1. 使用 HP-Socket v3.2.1 及以前版本的应用程序可以安全升级到 HP-Socket v3.2.2

---

*** v3.2.1 更新 ***

> 增加 TcpAgent / TcpPullAgent 通信组件：

-----------------

1. 对于代理服务器或中转服务器等应用场景，服务器自身也作为客户端向其它服务器发起大规模连接
2. TcpClient / TcpPullClient 基于 Event Select 通信模型，每个组件对象管理一个 Socket，并开启一个线程，不适合上述应用场景
3. TcpAgent / TcpPullAgent 基于 IOCP 通信模型，一个组件对象管理多个 Socket，适合用作代理服务器或中转服务器的客户端通信组件
4. TcpAgent / TcpPullAgent 的使用方式依然简单，提供以下接口方法：

   /* 1) 通知接口方法 */
   OnPrepareConnect(CONNID dwConnID, SOCKET socket)
   OnConnect(CONNID dwConnID)
   OnSend(CONNID dwConnID, const BYTE* pData, int iLength)
   OnReceive(CONNID dwConnID, const BYTE* pData, int iLength)	//（Push 模型）
   OnReceive(CONNID dwConnID, int iLength)				//（Pull 模型）
   OnClose(CONNID dwConnID)
   OnError(CONNID dwConnID, EnSocketOperation enOperation, int iErrorCode)
   OnAgentShutdown()
   
   /* 2) 主要操作方法 */
   Start(LPCTSTR pszBindAddress = nullptr, BOOL bAsyncConnect = TRUE)
   Stop()
   Connect(LPCTSTR pszRemoteAddress, USHORT usPort, CONNID* pdwConnID = nullptr)
   Send(CONNID dwConnID, const BYTE* pBuffer, int iLength)
   Disconnect(CONNID dwConnID, BOOL bForce = TRUE)
   Fetch(CONNID dwConnID, BYTE* pData, int iLength)	//（Pull 模型）

5. 增加 TcpAgent / TcpPullAgent 使用示例：Agent-PFM / Agent-Pull / Agent-4C
   
6. 增加 TcpAgent + TcpServer 实现的 HTTP 代理服务器示例：HttpProxy
   

> 增加 HPSocket for Java SDK：

-----------------

1. 提供 Java 开发包：hpsocket-3.2.1.jar（通过 JNA 实现，目前只支持 Windows 平台）
2. 运行环境：JDK 1.6+，JVM 运行在 server 模式（"java -server"，在 client 模式下性能受影响）
3. MBCS 和 Unicode 版本分布位于包 org.jessma.hpsocket.mbcs 和 org.jessma.hpsocket.unicode
4. HPSocket for Java SDK 提供以下通信组件：

   1) TcpServer：TCP 通信服务端组件，支持 PUSH/PULL 模型
   2) TcpClient：TCP 通信客户端组件，支持 PUSH/PULL 模型
   3) TcpAgent ：TCP 通信 Agent 组件，支持 PUSH/PULL 模型
   4) UdpServer：UDP 通信服务端组件，支持 PUSH 模型
   5) UdpClient：UDP 通信客户端组件，支持 PUSH 模型

5. HPSocket4J 的使用方法（以 TcpAgent 为例）：

   /* 0: 应用程序加入 hpsocket-3.2.1.jar 和 jna-4.1.0.jar */
   
   /* 1: 创建通信组件对象 */
   TcpAgent agent = TcpAgent.create(Mode.PUSH);
   
   /* 2: 设置回调函数对象 */
   // （可选）
   agent.setCallBackOnPrepareConnect(new OnPrepareConnectImpl());
   // （可选）
   agent.setCallBackOnConnect(new OnConnectImpl());
   // （必须）PUSH 模型需要设置 OnReceive 回调函数对象
   agent.setCallBackOnReceive(new OnReceiveImpl());
   // （必须）PULL 模型需要设置 OnPullReceive 回调函数对象
   // agent.setCallBackOnPullReceive(new OnPullReceiveImpl());
   // （可选）
   agent.setCallBackOnSend(new OnSendImpl());
   // （必须）
   agent.setCallBackOnClose(new OnCloseImpl());
   // （必须）
   agent.setCallBackOnError(new OnErrorImpl());
   // （可选）
   agent.setCallBackOnAgentShutdown(new OnAgentShutdownImpl());
   
   /* 3：启动通信组件 */
   agent.start("127.0.0.1", false);
   
   /* 4：连接服务器 */
   agent.connect("localhost", (short)5555, pdwConnID);
   
   /* 5：处理通信数据 */
   // 响应 OnReceive / OnPullReceive 事件接收数据
   // 使用 agent.send(dwConnID, data, data.length) 发送数据
   
   /* 6：关闭通信组件 */
   agent.stop();
   
   /* 7：销毁通信组件 */
   TcpAgent.destroy(agent);

6. 增加示例工程 TestEcho-4J，展示 HPSocket4J 的使用方法（包括 PULL 模型示例和性能测试示例）
   

> 优化数据收发策略：

-----------------

1. Server 和 Agent 组件提供以下三种数据发送策略

   1）PACK - 打包模式（默认）：尽量把多个发送操作的数据组合在一起，增加传输效率
   2）SAFE - 安全模式	  ：尽量把多个发送操作的数据组合在一起，控制传输速度，避免缓冲区溢出
   3）DIRECT - 直接模式	  ：对每一个发送操作都直接投递，适用于负载不高但要求实时性较高的场合

2. Server 和 Agent 组件提供以下两种数据接收策略

   1）SERIAL - 串行模式（默认）：顺序触发同一连接的 OnReceive 和 OnClose/OnError 事件
   2）PARALLEL - 并行模式：在不同的通信线程中同时触发同一连接的 OnReceive 和 OnClose/OnError 事件

---

*** v3.1.3 更新 ***

> 增加其它语言 Demo：

-----------------

1. C#
2. Delphi
3. E 语言

> Bug Fix：

-----------------

1. 修复 IP 地址判断错误 Bug

   1) 客户端连接服务器时，如果服务器 IP 地址满位（12个数字：‘AAA.BBB.CCC.DDD’），IP 地址解析错误
   2) 影响组件：所有 TCP/UDP 客户端组件
   3) 影响版本：v3.1.2 及之前所有版本

2. 修复域名或主机名的 IP 地址解析错误 Bug

   1) 客户端组件通过域名或主机名连接服务器时，可能会解析到错误的 IP 地址
   2) 影响组件：所有 TCP/UDP 客户端组件
   3) 影响版本：v3.1.2 及之前所有版本

---

*** v3.1.2 更新 ***

 > 修改 Server 组件的 OnClose() / OnError() 事件的触发规则：

-----------------

1. 以前版本的 TCP/UDP Server 组件中，当关闭一个连接时可能会同时触发一个 OnClose() 事件和若干个 OnError() 事件
2. 由于存在上述可能性，所以应用程序需要对 OnClose() / OnError() 的处理事件代码段进行同步
3. 从 v3.1.2 开始，当多个 OnClose() / OnError() 事件同时发生时，组件只会向应用程序通知第一个事件，后续事件则忽略
4. 因此，应用程序在处理 OnClose() / OnError() 事件时不必处理同步，减少了出错的可能和编写同步及检测代码的负担
5. 示例代码

   /* 示例代码一：*/
   /*----------------------------------------------------------------------------*/
   ISocketListener::EnHandleResult CServerDlg::OnClose(CONNID dwConnID)
   {
   	// 以前版本：有可能存在并发的 OnClose()/OnError()，要把代码放在临界区中并检测返回值
   
   	CCriSecLock locallock(m_csPkgInfo);	// <-- 临界区
   
   	PVOID pInfo = nullptr;
   	// <-- 检测返回值
   	if(m_Server->GetConnectionExtra(dwConnID, &pInfo) && pInfo != nullptr)
   	{
   		m_Server->SetConnectionExtra(dwConnID, nullptr);
   		delete pInfo;
   	}
   }
   
   /* 示例代码二：*/
   /*----------------------------------------------------------------------------*/
   ISocketListener::EnHandleResult CServerDlg::OnClose(CONNID dwConnID)
   {
   	// v3.1.2 版本：只会接收到一个 OnClose()/OnError() 事件，能安全地移除临界区代码和检测代码
   
   	PVOID pInfo = nullptr;
   	m_Server->GetConnectionExtra(dwConnID, &pInfo);
   	ASSERT(pInfo != nullptr);
   
   	delete pInfo;
   }

---

*** v3.1.1 更新 ***

 > 增加导出纯 C 函数的动态链接库 HPSocket4C.dll：

-----------------

1. 增加代码文件 HPSocket4C.h 和 HPSocket4C.cpp，用于创建 HPSocket4C.dll
2. 导出纯 C 函数，让其它语言（如：C/C#/Delphi 等）能方便地使用 HPSocket
3. HPSocket4C.dll 使用方法

   方法一：
   ------------------------------------------------------------------------------
   (0) （C/C++ 程序）包含 HPSocket4C.h 头文件
   (1) 调用 ::Create_HP_XxxListener() 函数创建监听器对象
   (2) 调用 ::Create_HP_Xxx(pListener) 函数创建 HPSocket 对象
   (3) 调用 ::HP_Set_FN_Xxx_OnYyy(pListener, ...) 函数设置监听器的回调函数
   (4) 调用相关导出函数操作 HPSocket 对象
   (5) ...... ......
   (6) 调用 ::Destroy_HP_Xxx(pSocket) 函数销毁 HPSocket 对象
   (7) 调用 ::Destroy_HP_XxxListener(pListener) 函数销毁监听器对象
   
   方法二：
   ------------------------------------------------------------------------------
   (1) 应用程序把需要用到的导出函数封装到特定语言的包装类中
   (2) 通过包装类封装后，以面向对象的方式使用 HPSocket

4. 动态链接库发行版本

   (1) x86/HPSocket4C.dll		- (32位/MBCS/Release)
   (2) x86/HPSocket4C_D.dll	- (32位/MBCS/DeBug)
   (3) x86/HPSocket4C_U.dll	- (32位/UNICODE/Release)
   (4) x86/HPSocket4C_UD.dll	- (32位/UNICODE/DeBug)
   (5) x64/HPSocket4C.dll		- (64位/MBCS/Release)
   (6) x64/HPSocket4C_D.dll	- (64位/MBCS/DeBug)
   (7) x64/HPSocket4C_U.dll	- (64位/UNICODE/Release)
   (8) x64/HPSocket4C_UD.dll	- (64位/UNICODE/DeBug)

> 全面启用 Buffer Pool 缓存机制：

-----------------

1. Common/Src 增加代码文件 bufferpool.h 和 bufferpool.cpp，实现 Buffer Pool 缓存机制
2. 通过 Buffer Pool 缓存机制提升内存使用效率，减少动态内存分配和释放操作，避免内存空洞
3. ICTcpClient 用 CItemPool 和 TItemList 实现发送缓冲区
4. CUdpClient 用 CItemPool 和 TItemList 实现发送缓冲区
5. CTcpPullClient 用 CItemPool 和 TItemList 实现发送缓冲区和 PULL 缓冲区
6. CTcpPullServer 用 CBufferPool 和 TBuffer 实现 PULL 缓冲区

---

*** v3.0.2 更新 ***

> 把 HP-Socket 编译为动态链接库：

-----------------

1. 应用程序可以通过导入源代码或动态链接库方式使用 HP-Socket
2. 动态链接库使用方法

   方法一：
   ------------------------------------------------------------------------------
   (0) 应用程序包含 SocketInterface.h 和 HPSocket.h 头文件
   (1) 调用 HP_Create_Xxx() 函数创建 HPSocket 对象
   (2) 使用完毕后调用 HP_Destroy_Xxx() 函数销毁 HPSocket 对象
   
   方法二：
   ------------------------------------------------------------------------------
   (0) 应用程序包含 SocketInterface.h 和 HPSocket.h 头文件
   (1) 创建 CXxxWrapper 包装器，通过包装器智能指针使用 HPSocket 对象

3. 动态链接库发行版本

   (1) x86/HPSocket.dll      - (32位/MBCS/Release)
   (2) x86/HPSocket_D.dll    - (32位/MBCS/DeBug)
   (3) x86/HPSocket_U.dll    - (32位/UNICODE/Release)
   (4) x86/HPSocket_UD.dll   - (32位/UNICODE/DeBug)
   (5) x64/HPSocket.dll      - (64位/MBCS/Release)
   (6) x64/HPSocket_D.dll    - (64位/MBCS/DeBug)
   (7) x64/HPSocket_U.dll    - (64位/UNICODE/Release)
   (8) x64/HPSocket_UD.dll   - (64位/UNICODE/DeBug)

---

*** v3.0.1 更新 ***

> 新增 UDP 通信组件：

-----------------

1. 新增两个 UDP 通信组件：CUdpServer 为服务端组件，CUdpClient 为客户端组件
2. 服务端组件 CUdpServer 采用 IOCP 通信模型
3. 客户端组件 CUdpClient 采用 Event Select 通信模型
4. UDP 通信组件的接口与原 TCP 通信组件一致，简单实用
5. UDP 通信组件内置通信线路自动监测机制
6. 新增 UDP 通信组件示例工程 TestEcho-UDP

> 代码重构与优化：

-----------------

1. 规范所有接口、类以及代码文件的命名
2. 重构和优化了大量组件代码
3. 服务端组件加入读写锁机制，有效平衡处理性能与安全性
4. 服务端组件的 Socket 对象缓存列表设置了锁定时间，提高访问的安全性

---