3. libt2u C语言 API接口说明
3.1 概述
本节描述 libt2u C语言的接口函数，在Windows、IOS、MacOS 平台下，都使用C语言接口进行开发。
3.2 结构体说明
3.2.1 T2uCallBack
typedef struct _T2U_CALLBACK
{
void (*OnConnect)(unsigned short local_port, int usetime);
void (*OnDisconnect)(unsigned short local_port, int ret);
}T2uCallBack,*PT2uCallBack;
说明
回调函数指针结构体。成员说明
- OnConnect： P2P连接成功回调
- local_port： 本地映射端口号
- usetime： 建立 P2P 连接所用时间（毫秒）
- OnDisconnect：P2P连接失败或中断回调
- local_port： 本地映射端口号
- ret： 断开原因
- -2：连接失败
- -3：连接中断
- -4：对方离线
- -5：设备有P2P密码，密码认证失败
- OnConnect： P2P连接成功回调
3.2.2 T2uNetStat
typedef struct _T2U_NET_STAT
{
char ip[20];
int port;
int proxy;
float lost_rate;
int bandwidth;
int remote_nattype;
int local_nattype;
char ip6[40];
int remote_version;
}T2uNetStat,*PT2uNetStat;
说明
P2P 连接状态结构体。成员说明
- ip：对端在互联网上映射的 IP 地址
- port：对端在互联网上映射的端口号
- proxy：是否通过中继代理，0=否，1=是
- lost_rate：丢包率，百分比
- bandwidth：估算的上行带宽，非精确值，单位：KB/s
- remote_nattype：对端的NAT类型
- local_nattype：本地的NAT类型
- ip6：对端的ipv6地址（如果对端网络是IPV6的话才有）
- remote_version：对端的P2P开发库版本号
NAT类型含义
- -2：检测失败
- -1：正在检测
- 0：公网IP
- 1：Full Cone NAT
- 2：Restricted Cone NAT
- 3：Port Restricted Cone NAT
- 4：Symmetric NAT
3.3. 接口函数说明
3.3.1. t2u_init
void t2u_init(const char* svraddr, unsigned short svrport, const char* svrkey);
接口说明
初始化，整个应用程序在开启时调用一次本接口即可。参数说明
- svraddr：P2P 服务器地址，使用域名，开放平台域名为
nat.vveye.net - svrport：P2P 服务器端口，默认为 8000
- svrkey：P2P 服务器密钥，开放平台无密钥，传入""即可
- svraddr：P2P 服务器地址，使用域名，开放平台域名为
3.3.2. t2u_set_callback
void t2u_set_callback(PT2uCallBack callback);
接口说明
设置回调函数。参数说明
- callback： 回调函数结构体，参见T2uCallBack
3.3.3. t2u_set_port_range
void t2u_set_port_range(unsigned short min_port, unsigned short max_port);
接口说明
设置 P2P 端口范围。通常不需要调用此函数，如果客户端所在网络环境有 UDP 端口范围限制，则调用这个函数，以保证网络可以正常使用。参数说明
- min_port： 最小端口号
- max_port: 最大端口号
3.3.4. t2u_status
int t2u_status();
接口说明
查询客户端与服务器的连接状态。返回值
- 1: 与服务器连接，状态正常
- 0: 未连接服务器
- -1: SDK未初始化
- -2: 服务器密钥无效
3.3.5. t2u_query
int t2u_query(const char* uuid);
接口说明
查询指定设备的在线状态。参数说明
- uuid：设备序列号
返回值
- 1: 设备在线
- 0: 设备不在线
- -1: 查询失败
3.3.6. t2u_add_port / t2u_add_udp_port
int t2u_add_port(const char* uuid, unsigned short remote_port, unsigned short local_port);
int t2u_add_udp_port(const char* uuid, unsigned short remote_port, unsigned short local_port);
接口说明
这两个接口函数的作用是将远端设备的端口映射到本地，前者映射 TCP 服务端口，后者映射 UDP 服务端口，其工作原理和调用方法相同。参数说明
- uuid： 设备序列号
- remote_port：要映射的设备端服务端口
- local_port：映射到本地的端口，可传入 0 表示由接口函数随机分配端口（建议使用这种方式，以防止发生端口占用），随机分配的端口在返回值中返回。
返回值
- > 0：映射到本地的端口号
- -1：创建映射端口失败，本地端口被占用
3.3.7. t2u_add_port_v3 / t2u_add_udp_port_v3
int t2u_add_port_v3(const char* uuid, const char* passwd, const char* remote_ip, unsigned short remote_port, unsigned short local_port);
int t2u_add_udp_port_v3(const char* uuid, const char* passwd, const char* remote_ip, unsigned short remote_port, unsigned short local_port);
接口说明
这两个接口函数是 t2u_add_port/t2u_add_udp_port 的升级版，如果设备端没有 P2P 密码，使用 t2u_add_port/t2u_add_udp_port 即可。此接口用于将远端设备的端口映射到本地，前者映射 TCP 服务端口，后者映射 UDP 服务端口，其工作原理和调用方法相同。参数说明
- uuid： 设备序列号
- passwd： 设备端 P2P 密码
- remote_ip： 设备端 IP 地址，由于通常连接的是设备端本身，因此传入"127.0.0.1"即可，不需要指定实际的 IP 地址。
- remote_port： 要映射的设备端服务端口
- local_port： 映射到本地的端口，可传入 0 表示由接口函数随机分配端口（建议使用这种方式，以防止发生端口占用），随机分配的端口在返回值中返回。
返回值
- > 0：映射到本地的端口号
- -1：创建映射端口失败，本地端口被占用
3.3.8. t2u_port_status / t2u_udp_port_status
int t2u_port_status(unsigned short port,PT2uNetStat pStat);
int t2u_udp_port_status(unsigned short port,PT2uNetStat pStat);
接口说明
查询映射端口是否已经与远端设备连通。参数说明
- port：已映射的本地端口号，即 AddPort 系列函数的返回值
- pStat：保存P2P连接状态的结构体，参见结构体T2uNetStat
返回值
- 1: 已连通
- 0: 未连通
- -1: 设备uuid不存在
- -2: P2P连接失败，等待30秒后自动重连
- -3: P2P连接中断，等待30秒后自动重连
- -4: 对方离线，等待30秒后自动重连
- -5: 设备有密码，密码认证失败
3.3.9. t2u_del_port / t2u_del_udp_port
void t2u_del_port(unsigned short port);
void t2u_del_udp_port(unsigned short port);
接口说明
删除已创建的 P2P 连接，即删除已映射的本地端口。前者对应 t2u_add_port / t2u_add_port_v3 ，后者对应 t2u_add_udp_port / t2u_add_udp_port_v3参数说明
- port：已映射的本地端口号，即 t2u_add_port 系列函数的返回值
3.3.10. t2u_exit
void t2u_exit();
- 接口说明 退出并释放资源。在整个应用退出时调用一次即可。