网络使用指南

简介

网络模块提供 HTTP 客户端（GET/POST/高级请求/文件下载）与 TCP 客户端/服务端（事件驱动、支持分包协议）。
与远程调用的插件 RPC 不同，本模块是 通用网络原语，可直接对接 REST API、文件服务器或自定义 TCP 协议。

一、HTTP 典型流程

步骤	接口	说明
1	`HttpGet` / `HttpPost` / `HttpRequestEx`	发起请求，返回响应体字符串
2	`JsonParse` 等	解析 JSON 响应（可选）
3	`HttpDownloadFile` / `HttpDownloadFileEx`	大文件下载走专用接口

选型建议：

需求	推荐接口
简单 GET（参数拼 URL）	`HttpGet`
提交 JSON / 表单	`HttpPost`
自定义 Header、Cookie、Bearer Token、PUT/DELETE	`HttpRequestEx`
大文件 / 不稳定网络	`HttpDownloadFileEx`（断点续传 + 重试）

二、HTTP 完整示例

2.1 GET 请求（带查询参数）

查询参数直接拼在 URL 中，HttpGet 不支持自定义请求头。

cpp

#include "OLAPlugServer.h"

OLAPlugServer ola;
// 参数编码：中文或特殊字符需 URL 编码
string url = "https://httpbin.org/get?user=ola&page=1";
string body = ola.HttpGet(url);
if (!body.empty()) {
    // body 为 JSON 响应，可用 JsonParse 解析
}

2.2 POST JSON

cpp

OLAPlugServer ola;
string resp = ola.HttpPost(
    "https://httpbin.org/post",
    "{\"username\":\"ola\",\"level\":10}",
    "application/json"
);

2.3 POST 表单（application/x-www-form-urlencoded）

cpp

OLAPlugServer ola;
string resp = ola.HttpPost(
    "https://httpbin.org/post",
    "username=ola&password=123456",
    "application/x-www-form-urlencoded"
);

需要 Cookie、Authorization、User-Agent 或 PUT/DELETE 等方法时，使用 HttpRequestEx。

cpp

OLAPlugServer ola;
string headers =
    "Authorization: Bearer your_token_here\r\n"
    "User-Agent: OLAPlug/1.0\r\n"
    "Accept: application/json";
int status = 0;
string resp = ola.HttpRequestEx(
    "GET",
    "https://api.example.com/v1/user/profile",
    headers,
    "",
    "",
    status
);
// status 为 HTTP 状态码，如 200、401、404

POST JSON 并带 Header 示例：

cpp

string headers = "Authorization: Bearer your_token_here\r\n";
string body = "{\"name\":\"ola\"}";
int status = 0;
string resp = ola.HttpRequestEx(
    "POST",
    "https://api.example.com/v1/items",
    headers,
    body,
    "application/json",
    status
);

headers 格式：每行 Name: Value，行与行之间用 \r\n 分隔。

2.5 下载文件（带进度回调）

HttpDownloadFile / HttpDownloadFileEx 支持断点续传。回调在下载过程中多次触发。

cpp

// C++ 原生 DLL 回调示例
void OLA_CALL_TYPE OnDownloadProgress(int64_t current, int64_t total, int64_t speed, int64_t user_data) {
    if (total > 0) {
        double pct = (double)current / total * 100.0;
        // pct 为完成百分比，speed 为字节/秒
    }
}

long instance = CreateCOLAPlugInterFace();
int ret = HttpDownloadFileEx(
    instance,
    "https://example.com/large.zip",
    "D:\\downloads\\large.zip",
    OnDownloadProgress,
    0,   // user_data
    3,   // 断线最大重试 3 次
    10,  // 连接超时 10 秒
    60   // 读取超时 60 秒
);
// ret == 0 表示成功，< 0 为错误码（见 HttpDownloadFile 文档）

SDK 中若不需要进度，可传 nullptr / null / None 作为回调。

2.6 REST API + JSON 解析联动

cpp

OLAPlugServer ola;
string resp = ola.HttpGet("https://api.example.com/v1/status");
if (resp.empty()) return;

int err = 0;
long root = ola.JsonParse(resp, &err);
if (root != 0 && err == 0) {
    string code = ola.JsonGetString(root, "code", &err);
    ola.JsonFree(root);
}

三、TCP 典型流程

3.1 TCP 客户端生命周期

TcpClientCreate → TcpClientConnect → TcpClientSend → TcpClientDisconnect → TcpClientDestroy

步骤	接口	说明
创建	`TcpClientCreate`	注册事件回调，选择是否启用分包协议
连接	`TcpClientConnect`	异步，结果通过回调通知（event_type=0 成功，1 失败）
发送	`TcpClientSend`	异步，发送完成回调 event_type=4
断开	`TcpClientDisconnect`	可重连
销毁	`TcpClientDestroy`	释放资源，句柄失效

3.2 TCP 服务端生命周期

TcpServerCreate → (回调处理连接/收包) → TcpServerSend → TcpServerStop → TcpServerDestroy

步骤	接口	说明
创建	`TcpServerCreate`	绑定地址端口，注册回调
发送	`TcpServerSend`	向指定 conn_id 发数据
管理	`TcpServerGetAllConnectionIds` / `TcpServerGetClientAddress`	多连接管理
踢人	`TcpServerDisconnect`	断开指定连接
停止	`TcpServerStop`	停止监听并断开所有连接
销毁	`TcpServerDestroy`	释放资源

3.3 事件类型对照

客户端回调 TcpClientCallback：

event_type	事件	说明
0	连接成功	可开始 `TcpClientSend`
1	连接失败	检查地址/端口/网络
2	接收数据	`data`/`data_len` 有效，需在回调内拷贝
3	连接断开	对端关闭或网络中断
4	发送完成	上一包已写入内核缓冲区

服务端回调 TcpServerCallback：

event_type	事件	说明
0	新连接	`conn_id` 为新连接 ID
1	接收数据	从该 `conn_id` 收到数据
2	连接断开	客户端离开
3	发送完成	向该 `conn_id` 的发送完成

3.4 分包协议 vs 原始模式

enable_packet_protocol	行为	适用
`1`（推荐）	自动添加 4 字节小端长度前缀，解决粘包	OLA 客户端/服务端互通信
`0`	原始字节流，不添加协议头	对接第三方 TCP 服务

分包格式：[4 字节长度(小端)][消息体]

四、TCP 完整示例（C++ 原生）

4.1 客户端：连接并发消息

cpp

#include <cstring>

void OLA_CALL_TYPE OnClientEvent(int64_t client_handle, int32_t event_type,
                                   int64_t data, int32_t data_len, int64_t user_data) {
    switch (event_type) {
    case 0: // 连接成功
        {
            const char* msg = "hello server";
            TcpClientSend(user_data, client_handle, (int64_t)msg, (int32_t)strlen(msg));
        }
        break;
    case 2: // 收到数据
        if (data && data_len > 0) {
            // data 仅在回调期间有效，需立即拷贝
            char buf[4096] = {0};
            int copyLen = data_len < (int)sizeof(buf) - 1 ? data_len : (int)sizeof(buf) - 1;
            memcpy(buf, (void*)data, copyLen);
        }
        break;
    case 3: // 断开
        break;
    }
}

long instance = CreateCOLAPlugInterFace();
long client = TcpClientCreate(instance, OnClientEvent, instance, 1); // 1=启用分包
if (client != 0) {
    TcpClientConnect(instance, client, "127.0.0.1", 9000);
    // 连接结果在回调 event_type=0/1 中通知
    // ...
    TcpClientDestroy(instance, client);
}

4.2 服务端：Echo 回显

cpp

void OLA_CALL_TYPE OnServerEvent(int64_t server_handle, int64_t conn_id, int32_t event_type,
                                  int64_t data, int32_t data_len, int64_t user_data) {
    switch (event_type) {
    case 0: // 新连接
        {
            long addrPtr = TcpServerGetClientAddress(user_data, server_handle, conn_id);
            if (addrPtr != 0) {
                char addr[64] = {0};
                GetStringFromPtr(addrPtr, addr, sizeof(addr));
                FreeStringPtr(addrPtr);
                // addr 格式如 "192.168.1.100:54321"
            }
        }
        break;
    case 1: // 收到数据，原样回显
        if (data && data_len > 0) {
            TcpServerSend(user_data, server_handle, conn_id, data, data_len);
        }
        break;
    case 2: // 连接断开
        break;
    }
}

long instance = CreateCOLAPlugInterFace();
long server = TcpServerCreate(instance, "0.0.0.0", 9000, OnServerEvent, instance, 1);
// server != 0 表示监听成功
// 退出前：
TcpServerStop(instance, server);
TcpServerDestroy(instance, server);

4.3 广播：向所有连接发送

cpp

long idsPtr = TcpServerGetAllConnectionIds(instance, server);
if (idsPtr != 0) {
    char ids[256] = {0};
    GetStringFromPtr(idsPtr, ids, sizeof(ids));
    FreeStringPtr(idsPtr);
    // ids 格式 "1,2,3"，逐个 conn_id 调用 TcpServerSend
}

五、注意事项

项目	说明
字符串返回值	`HttpGet`/`HttpPost`/`HttpRequestEx` 等原生 DLL 返回字符串指针，需 `FreeStringPtr` 释放
HTTP 简单 vs 高级	仅需 body 时用 Get/Post；需 Header/Cookie/状态码时用 RequestEx
TCP 异步	`TcpClientConnect`/`TcpClientSend`/`TcpServerSend` 均为异步，结果靠回调
回调线程	TCP 回调在独立线程执行，注意线程安全，避免长时间阻塞
回调数据生命周期	event_type=2/1 的 `data` 指针仅在回调内有效，异步处理须先拷贝
资源释放	客户端/服务端使用完毕务必 Destroy；HTTP 字符串指针务必 FreeStringPtr

六、排障建议

现象	排查
HttpGet 返回空	检查 URL、网络、HTTPS 证书；需 Header 时改用 HttpRequestEx
status_code 401/403	检查 Authorization/Cookie 是否正确设置在 headers
下载失败 -4/-5	网络不通或超时，Ex 版可调大 connect/read_timeout 并增加 max_retries
TcpClientConnect 回调失败	确认服务端已监听、端口未被占用、防火墙放行
收不到完整消息	确认两端 enable_packet_protocol 一致；原始模式需自行处理粘包
服务端 Send 失败	conn_id 无效或连接已断开，检查回调中的 conn_id

网络使用指南 ​

简介 ​

一、HTTP 典型流程 ​

二、HTTP 完整示例 ​

2.1 GET 请求（带查询参数） ​

2.2 POST JSON ​

2.3 POST 表单（application/x-www-form-urlencoded） ​

2.4 高级请求：Bearer Token + 自定义 Header ​

2.5 下载文件（带进度回调） ​

2.6 REST API + JSON 解析联动 ​

三、TCP 典型流程 ​

3.1 TCP 客户端生命周期 ​

3.2 TCP 服务端生命周期 ​

3.3 事件类型对照 ​

3.4 分包协议 vs 原始模式 ​

四、TCP 完整示例（C++ 原生） ​

4.1 客户端：连接并发消息 ​

4.2 服务端：Echo 回显 ​

4.3 广播：向所有连接发送 ​

五、注意事项 ​

六、排障建议 ​