隧道模块使用流程和常用API报错分析
隧道模块使用流程和常用API报错分析
1. 调用API流程
(1) pgTunnelSysInfo
辅助获取系统信息
(2) pgTunnelStart
启动P2P隧道客户端模块
注意：此时隧道模块只是启动成功，不意味着账号已经成功登录到服务器了。
因为登录操作必须是异步的，所以不能通过pgTunnelStart的返回值来判断登录结果。
登录结果可以通过pgTunnelStatusGet来判断。
（3）等待登录成功
循环检测调用pgTunnelStatusGet直至获取到正确状态。可参考下面的代码等待客户端登录成功，推荐等待时间为15秒以上：
int waitLogin(int maxWaitSecond) {
int statusgetNum = 0;
int maxNum = maxWaitSecond * 1000 / 300;
int iStatus = -1;
while (1) {
PG_TUNNEL_STATUS_S stStatus;
memset(&stStatus, 0, sizeof(stStatus));
int iErr = pgTunnelStatusGet(PG_TUNNEL_GET_STA_LOGIN, &stStatus);
iStatus = -1;
if (iErr == PG_TUNNEL_ERROR_OK) {
iStatus = (int)(stStatus.uStatus);
printf(” Status: %u \n”, stStatus.uStatus);
}
else {
printf(” Get status failed, Error: %d\n”, iErr);
}
if (iStatus == 0) {
break;
}
statusgetNum++;
if (statusgetNum > maxNum)
{
break;
}
Sleep(300);
}
return iStatus;
}
(4) pgTunnelConnectAdd
本客户端和指定用户ID的远程客户端之间添加一条隧道连接。
注意:
此时隧道连接可以选择保 存在三个地方：客户端内存，服务器内存，服务器数据库。默认是保存在服务器内存，我们推荐保存在客户端内存，可防止服务器负担太大和其他异常问题。三种保存隧道连接具体区别请看： http://blog.peergine.com/?p=359
(5) pgTunnelPeerInfoGet
确认访问端和被访问端之间是有之前创建的隧道连接的，就能开始使用这条连接。
(6) pgTunnelConnectDelete
删除一条隧道。
(7) pgTunnelStop
停止隧道模块
注意：程序退出务必要调用此函数，否则多次重复会导致服务器退避该客户端的登录，客户端登录时间就会过久
具体API使用请看SDK里面的《P2P 隧道模块SDK编程手册 vx》
2. 几个常用API的错误分析。
(1) pgTunnelStart的错误码分析:
错误码1（系统错误）：
可能原因：
1.未正确加载隧道模块的库文件
2.尤其是嵌入式设备，如果系统的toolchain和拿到的隧道SDK不配套就会导致这个错误。
3.android设备未配置联网权限。
(2) pgTunnelDomainSet的错误码分析:
错误码1（系统错误）;
可能原因：
1.未加载隧道模块的库文件
错误码12（超时退出）;
可能原因：
1.有多个相同账号同时在线了，如果服务器配置了(KickOutEnable){1} 时，多个相同账号同时家在线就会报错 。这个错误可能是登录成功后，过一段时间后再报，也可能是一调用API就报。
2. 网络信号差。
当网络出现故障或网络时断时续不稳定时，就会出现这错误。
3. 还未登录成功。在pgTunnelStart后就马上去domainset了。解决方法：pgTunnelStart后，通过pgTunnelStatusget获取到登录状态，如果登录状态是0，才去domainset。
(3) pgTunnelConnectAdd 的错误分析:
错误码13（拒绝操作）可能原因：
1）对端客户端的隧道数量达到上限（隧道数量上限请看配置文件的 MaxTunnel参数的值）
2）本端客户端的隧道数量达到上限（隧道数量上限请看配置文件的 MaxTunnel参数的值）
3）本端的入口端口占用（被已经添加的隧道占用或者被其他程序占用）
4）对端和本端的客户端不在同一个用户域里面。
5）隧道的入口地址使用局域网地址的时候，如果这个地址对应的设备是Android或IOS系统的，此时创建隧道会被系统拒绝。遇到这种情况请在本机上集成或安装隧道客户端。注意:作为隧道入口时，IOS的回环地址必须使用127.0.0.1，Android的端口号最小为1024。
6) 隧道客户端是集成中嵌入式linux或android设备中的时候，如果删除掉隧道连接就立即创建隧道连接就会报一个13错误码。
因为嵌入式linux和android设备上的端口关闭需要一定的时间，隧道服务器上的隧道连接数据已经删除了，但是实际设备上的端口还未关闭，所以创建不了。
建议在删除隧道连接延时个5到10秒再去创建隧道。
错误码6（状态错误）可能原因：
1. 本端未成功登录到服务器上。解决方法：调用本方法之前或出错时，要通过pgTunnelStatus
获取到登录状态，登录成功时才做这个操作。
引申：
本端未成功登录到服务器上可能原因：
（1）.有多个相同账号同时在线了，如果服务器配置了(KickOutEnable){1} 时，多个相同账号同时家在线就会报错 。这个错误可能是登录成功后，过一段时间后再报，也可能是一调用API就报。
（2）. 网络信号差。
当网络出现故障或网络时断时续不稳定时，就会出现这错误。
（3）. 还未登录成功。
以前创建过的隧道一段时间后就不见了的可能原因：
1. 隧道连接是客户端的API创建的，默认是保存在了服务器的内存中了，而服务器重启P2P服务或重启服务器主机后内存就清空了，所以隧道连接信息就不存在了。
2 客户端配置开启了这个 (ClientOnly){1} 后，通过客户端API所创建的隧道就会保存在创建连接客户端的内存中，所以客户端程序重启后隧道连接信息就不存在，说明一下，这种情况下pgTunnelStop停止隧道模块和pgTunnelStart启动隧道隧道是不会影响保存在程序内存中的隧道连接。
引申：
隧道生存周期的3种模式：
1) 从管理页面添加的隧道，或者调用服务器管理接口添加的隧道，保存的在MYSQL里
2) 从客户端调用API接口添加的隧道保存在服务器的内存CACHE里，重启服务器将清除。
3) 客户端的配置文件启用了”直接隧道(DirectTunnelEnable)”模式，那么从客户端调用API添加的隧道，只存在于客户端之间，不再保存在服务器的CACHE里面。客户端退出就清除。（较新版的客户端SDK才能支持）
注：隧道保存服务器端，不管是保存在MYSQL还是保存在CACHE里，都对于那些只要临时隧道的客户带来较多的烦恼，所以，我们增加“直接隧道”模式。
3. 本端ID和对端发生了变化。
（1）如果您的隧道客户端ID是随机生成的，很可能本端ID和对端ID会发生变化，如果ID变化了之后，隧道连接是对应不上的，所以才会提示没有这条隧道。解决方法;开启客户端下线时自动删除掉所绑定的隧道，配置方法是修改P2P服务器配置项(LogoutDetachTunnel){1}
