P2P 隧道模块SDK编程手册 v1.22

1. SDK压缩包的目录：

目录	说明	备注
Bin	Android版的JNI封装库 Windows版的pgTunnelStatic可执行程序 Ubuntu版的pgTunnelStatic可执行程序
Demo	P2P隧道模块SDK的演示程序的源代码
DemoApp	演示程序的可执行文件。	演示程序登录到穿透科技的服务器，地址：connect.peergine.com:7885
Depend	第三方依赖库文件
Doc	文档目录
Include	P2P隧道模块SDK的API头文件
Lib	P2P隧道模块SDK的库文件
Src	Windows版的pgTunnelStatic代码工程 Ubuntu版的pgTunnelStatic代码工程

2. 各种OS平台下的库文件名称：

OS系统	库文件名	依赖库	说明
Android	Lib\libtunnel_and.a	Depend\Lib\Android\lib\libcrypto.a libpthread (系统自带)	可以直接使用Bin\Android\pgJniTunnel目录中编译好的JNI动态库工程
IOS	Lib\libtunnel_ios.a	Depend\Lib\IOS\lib\libcrypto.a libpthread (系统自带) libiconv (系统自带) libresolv (系统自带)	真机和模拟器共用一个库文件
Windows	Lib\pgLibTunnel.lib Lib\pgLibTunnel_d.lib	Depend\Lib\Windows\lib\libcrypto.lib Depend\Lib\Windows\lib\libcrypto_d.lib Depend\Lib\Windows\lib\zlib.lib Depend\Lib\Windows\lib\zlibd.lib ws2_32.lib (系统自带) winmm.lib (系统自带) wininet.lib (系统自带) Imm32.lib (系统自带)	Release和Debug两个版本
Ubuntu	Lib\libtunnel_ubt.a	Depend\Lib\Linux\lib\libcrypto.a libpthread (系统自带)
MacOSX	Lib\libtunnel_mac.a	Depend\Lib\MacOSX\lib\libcrypto.a libpthread (系统自带) libiconv (系统自带)

注：嵌入式Linux平台的库，需要提供toolchain给穿透科技进行编译。

3. API接口：

1）常量：

错误码定义

typedef enum tagPG_TUNNEL_ERROR_E {

PG_TUNNEL_ERROR_OK = 0, // 成功

PG_TUNNEL_ERROR_SYSTEM = -1, // 系统错误。

PG_TUNNEL_ERROR_BADPARAM = -2, // 传递的参数错误。

PG_TUNNEL_ERROR_BADSTATUS = -6, // 状态不正确。

PG_TUNNEL_ERROR_BADUSER = -8, // 用户不存在。

PG_TUNNEL_ERROR_NETWORK = -11, // 网络故障

PG_TUNNEL_ERROR_TIMEOUT = -12, // 操作超时

PG_TUNNEL_ERROR_REJECT = -13, // 拒绝操作

PG_TUNNEL_ERROR_BUSY = -14, // 系统正忙

PG_TUNNEL_ERROR_NOEXIST = -18, // 资源不存在

PG_TUNNEL_ERROR_NOIMP = -127, // 该功能没有实现。

} PG_TUNNEL_ERROR_E;

P2P通道的连接类型

typedef enum tagPG_TUNNEL_CNNT_E {

PG_TUNNEL_CNNT_Unknown = 0, // 未知，还没有检测到连接类型

PG_TUNNEL_CNNT_IPV4_Pub = 4, // 公网IPv4地址

PG_TUNNEL_CNNT_IPV4_NATConeFull = 5, // 完全锥形NAT

PG_TUNNEL_CNNT_IPV4_NATConeHost = 6, // 主机限制锥形NAT

PG_TUNNEL_CNNT_IPV4_NATConePort = 7, // 端口限制锥形NAT

PG_TUNNEL_CNNT_IPV4_NATSymmet = 8, // 对称NAT

PG_TUNNEL_CNNT_IPV4_Private = 12, // 私网直连

PG_TUNNEL_CNNT_IPV4_NATLoop = 13, // 私网NAT环回

PG_TUNNEL_CNNT_IPV4_TunnelTCP = 16, // TCPv4转发

PG_TUNNEL_CNNT_IPV4_TunnelHTTP = 17, // HTTPv4转发

PG_TUNNEL_CNNT_IPV4_PeerFwd = 24, // 借助P2P节点转发

PG_TUNNEL_CNNT_IPV6_Pub = 32, // 公网IPv6地址

PG_TUNNEL_CNNT_IPV6_TunnelTCP = 40, // TCPv6转发

PG_TUNNEL_CNNT_IPV6_TunnelHTTP 41, // HTTPv6转发

PG_TUNNEL_CNNT_Offline = 65535, // 对端不在线

} PG_TUNNEL_CNNT_E;

查询状态的选项

typedef enum tagPG_TUNNEL_GET_STA_E {

PG_TUNNEL_GET_STA_LOGIN = 0, // 查询登录状态

} PG_TUNNEL_GET_STA_E;

登录状态定义

typedef enum tagPG_TUNNEL_STA_LOGIN_E {

PG_TUNNEL_STA_LOGIN_SUCCESS = 0, // 登录成功

PG_TUNNEL_STA_LOGIN_CONFIG = 4, // 加载配置文件失败

PG_TUNNEL_STA_LOGIN_SYSINFO = 5, // 系统信息参数错误

PG_TUNNEL_STA_LOGIN_RESOLUTION = 6, // 域名解析失败

PG_TUNNEL_STA_LOGIN_BUILDACCOUNT = 7, // 生成账号信息失败

PG_TUNNEL_STA_LOGIN_INITNODE = 8, // 初始化Node失败

PG_TUNNEL_STA_LOGIN_INITFAILED = 9, // 其他初始化失败

PG_TUNNEL_STA_LOGIN_LOGINFAILED = 10, // 发送登录请求失败

PG_TUNNEL_STA_LOGIN_LOGOUTED = 11, // 已经注销（稍后重试登录请求）

PG_TUNNEL_STA_LOGIN_REQUESTING = 16, // 正在请求登录

PG_TUNNEL_STA_LOGIN_TIMEOUT = 17, // 登录错误（请求超时）

PG_TUNNEL_STA_LOGIN_NETWORK = 18, // 登录错误（网络错误）

PG_TUNNEL_STA_LOGIN_BADUSER = 19, // 登录错误（用户名错误）

PG_TUNNEL_STA_LOGIN_BADPASS = 20, // 登录错误（密码错误）

PG_TUNNEL_STA_LOGIN_REJECT = 21, // 登录错误（拒绝访问）

PG_TUNNEL_STA_LOGIN_BUSY = 22, // 登录错误（服务器正忙）

PG_TUNNEL_STA_LOGIN_FAILED = 23, // 登录错误（其他登录失败）

PG_TUNNEL_STA_LOGIN_KICKOUT = 32, // 用户名冲突被服务器踢下线

PG_TUNNEL_STA_LOGIN_UNKNOWN = 255, // 未知状态

PG_TUNNEL_STA_LOGIN_EXTEND = 256, // 用户自定义错误码的开始编号

} PG_TUNNEL_STA_LOGIN_E;

2）结构体：

版本信息结构体

typedef struct tagPG_TUNNEL_VERSION_S {

char szVersion[64]; // 版本信息

} PG_TUNNEL_VERSION_S;

状态信息结构体

typedef struct tagPG_TUNNEL_STATUS_S {

unsigned int uStatus; // 状态信息，见’PG_TUNNEL_STA_LOGIN_E’枚举定义

} PG_TUNNEL_STATUS_S;

域名称结构体

typedef struct tagPG_TUNNEL_DOMAIN_S {

char szDomain[128]; // 域名称

} PG_TUNNEL_DOMAIN_S;

客户端说明结构体

typedef struct tagPG_TUNNEL_COMMENT_S {

char szComment[256]; // 客户端说明信息

} PG_TUNNEL_COMMENT_S;

P2P通道信息结构体

typedef struct tagPG_TUNNEL_PEER_INFO_S {

char szPeerID[128]; // 对端的用户ID

unsigned int uType; // P2P通道类型，见枚举‘PG_TUNNEL_CNNT_E’定义。

char szAddrLocal[64]; // 本端的登录地址端口

char szAddrRemote[64]; // 对端的登录地址端口

char szTunnelLocal[64]; // 本端的通道地址端口（P2P连接没有建立时通道地址为空）

char szTunnelRemote[64]; // 对端的通道地址端口（P2P连接没有建立时通道地址为空）

char szPrivateRemote[64]; // 对端的私网地址端口

} PG_TUNNEL_PEER_INFO_S;

客户端连接地址端口结构体

typedef struct tagPG_TUNNEL_CLIENT_ADDR_S {

char szClientAddr[64]; // 本端的客户端连接地址端口

} PG_TUNNEL_CLIENT_ADDR_S;

隧道连接信息结构体

typedef struct tagPG_TUNNEL_CONNECT_INFO_S {

char szPeerID[128]; // 对端的用户ID

unsigned int uType; // 隧道连接的类型，见“PG_TUNNEL_CNNT_E”定义

unsigned int uEncrypt; // 是否加密：0为不加密，1为加密

char szListenAddr[64]; // 对端的侦听地址端口

char szClientAddr[64]; // 本端的客户端地址端口

} PG_TUNNEL_CONNECT_INFO_S;

自定义数据结构体

typedef struct tagPG_TUNNEL_DATA_S {

unsigned int uSize; // 指明 ‘szData’ 缓冲区的长度（字节）

char szData[4]; // 接收数据的缓冲区

} PG_TUNNEL_DATA_S;

本端的用户P2P ID结构体

typedef struct tagPG_TUNNEL_SELF_S {

char szSelf[128]; // 本端的用户P2P ID

} PG_TUNNEL_SELF_S;

3）API函数声明：

TfnTunnelLogOut日志输出回调函数

/**

* 日志输出回调函数

* uLevel：[IN] 日志级别

* lpszOut：[IN] 日志输出内容

*/

typedef void (*TfnTunnelLogOut)(unsigned int uLevel, const char* lpszOut);

pgTunnelStart: 启动P2P隧道客户端模块

/**

* 描述：启动P2P隧道客户端模块

* 阻塞方式：非阻塞，立即返回。

* lpszCfgFile：[IN] 配置文件的路径

* lpszSysInfo：[IN] 设备的系统信息。可以用pgTunnelSysInfo()辅助函数获取。

* 格式：”(DevID){1234}(MacAddr){}(CpuMHz){1}(MemSize){1}(BrwVer){}(OSVer){}(OSSpk){}(OSType){}”

* 在花括号中填入参数的值，其中“DevID”是必选的，其他参数是可选的。

* DevID：设备ID（必填）

* MacAddr：MAC地址（可选）

* CpuMHz：CPU主频（单位M赫兹）（可选）

* MemSize：内存大小(单位MB)（可选）

* BrwVer：浏览器版本（可选）

* OSVer：操作系统版本（可选）

* OSSpk：操作系统补丁版本（可选）

* OSType：操作系统类型（可选）

* lpvParam：[IN] 自定义参数，保留。

* pfnLogOut：[IN] 日志输出回调函数的指针。回调函数原型见‘TfnLogOut’定义。

* 返回值：见枚举‘PG_ERROR_E’的定义

*/

int pgTunnelStart(const char* lpszCfgFile, const char* lpszSysInfo, void* lpvParam, TfnTunnelLogOut pfnLogOut);

pgTunnelStop: 停止P2P隧道客户端模块

/**

* 描述：停止P2P隧道客户端模块。

* 阻塞方式：非阻塞，立即返回。

*/

void pgTunnelStop();

pgTunnelSetCfgParam: 直接设置配置文件参数内容

/**

* 描述：直接设置配置文件参数内容

* 注意：必须在pgTunnelStart()之前调用。

* 因为配置文件里有一些敏感的明文信息，所以有些场景下不希望用户看到配置文件的内容。

* 这种场景下，可以调用此函数直接把配置文件的内容设置保存到SDK的内部变量中，

* 而不需要再提供一个配置文件。

*

* 阻塞方式：非阻塞，立即返回。

* lpszCfgParam：[IN] 配置参数内容(格式和内容参考配置文件参数说明)

* 返回值：见枚举‘PG_TUNNEL_ERROR_E’的定义

*/

int pgTunnelSetCfgParam(const char* lpszCfgParam);

pgTunnelSysInfo: 辅助获取系统信息

/**

* 描述：获取当前设备的系统信息。(辅助函数，有些设备或操作系统上没有实现)

* 阻塞方式：非阻塞，立即返回。

* lpszCfgPath：[IN] 配置文件路径。(从配置文件获取指定的沙盒目录)

* lpszInfo：[OUT] 接受系统信息的缓冲区。

* 格式：”(DevID){1234}(MacAddr){}(CpuMHz){1}(MemSize){1}(BrwVer){}(OSVer){}(OSSpk){}(OSType){}”

* 在花括号中填入参数的值，其中“DevID”是必选的，其他参数是可选的。

* DevID：设备ID（必填）

* MacAddr：MAC地址（可选）

* CpuMHz：CPU主频（单位M赫兹）（可选）

* MemSize：内存大小(单位MB)（可选）

* BrwVer：浏览器版本（可选）

* OSVer：操作系统版本（可选）

* OSSpk：操作系统补丁版本（可选）

* OSType：操作系统类型（可选）

* uSize：[IN] “lpszInfo”缓冲区的长度。

* 返回值：见枚举‘PG_ERROR_E’的定义

*/

int pgTunnelSysInfo(const char* lpszCfgPath, char* lpszInfo, unsigned int uSize);

pgTunnelSetNetCard: 指定使用的网卡

/**

* 描述：指定使用的网卡。(辅助函数，在LINUX系统有实现。)

* 注意：必须在pgTunnelStart()之前调用。

* 阻塞方式：非阻塞，立即返回。

* lpszNetCard：[IN] 指定的网卡接口名称，例如：eth0, eth1, …

* 返回值：见枚举‘PG_TUNNEL_ERROR_E’的定义

*/

int pgTunnelSetNetCard(const char* lpszNetCard);

pgTunnelVersionGet：获取pgLibTunnel SDK的版本号

/**

* 描述：获取pgLibTunnel SDK的版本号

* 阻塞方式：非阻塞，立即返回。

* lpstVersion：[OUT] 版本号信息，见’PG_TUNNEL_VERSION_S’定义。

* 返回值：见枚举‘PG_TUNNEL_ERROR_E’的定义

*/

int pgTunnelVersionGet(PG_TUNNEL_VERSION_S* lpstVersion);

pgTunnelStatusGet：获取登录到P2P服务器的状态

/**

* 描述：获取登录到P2P服务器的状态

* 阻塞方式：非阻塞，立即返回。

* uOption：[IN] 选项，见’PG_TUNNEL_GET_STA_E’定义。

* lpstStatus：[OUT] 状态信息，见’PG_TUNNEL_STATUS_S’定义。

* 返回值：见枚举‘PG_TUNNEL_ERROR_E’的定义

*/

int pgTunnelStatusGet(unsigned int uOption, PG_TUNNEL_STATUS_S* lpstStatus);

pgTunnelDomainSet: 设置域识别码，把本客户端加入到该识别码对应的用户域里

/**

* 描述：设置域识别码，把本客户端加入到该识别码对应的用户域里。

* 阻塞方式：阻塞，等待服务器执行操作。

* lpszPasscode：[IN] 域的识别码。

* 返回值：见枚举‘PG_TUNNEL_ERROR_E’的定义

*/

int pgTunnelDomainSet(const char* lpszPasscode);

pgTunnelDomainGet: 获取客户端当前的域名称

/**

* 描述：获取客户端当前的域名称。

* 阻塞方式：阻塞，等待服务器执行操作。

* lpstDomain：[OUT] 域的名称，见’PG_TUNNEL_DOMAIN_S’定义。

* 返回值：见枚举‘PG_TUNNEL_ERROR_E’的定义

*/

int pgTunnelDomainGet(PG_TUNNEL_DOMAIN_S* lpstDomain);

pgTunnelCommentSet: 设置客户端的说明

/**

* 描述：设置客户端的说明。

* 阻塞方式：阻塞，等待服务器执行操作。

* lpszComment：[IN] 客户端的说明。

* 返回值：见枚举‘PG_TUNNEL_ERROR_E’的定义

*/

int pgTunnelCommentSet(const char* lpszComment);

pgTunnelCommentGet: 获取客户端的说明

/**

* 描述：获取客户端的说明。

* 阻塞方式：阻塞，等待服务器执行操作。

* lpstComment：[OUT] 客户端的说明信息，见’PG_TUNNEL_COMMENT_S’定义。

* 返回值：见枚举‘PG_TUNNEL_ERROR_E’的定义

*/

int pgTunnelCommentGet(PG_TUNNEL_COMMENT_S* lpstComment);

pgTunnelTunnelSet: 设置客户端的域识别码和说明

/**

* 描述：设置客户端的域识别码和说明。

* 阻塞方式：阻塞，等待服务器执行操作。

* lpszPasscode：[IN] 客户端的域识别码。

* lpszComment：[IN] 客户端的说明信息。

* 返回值：见枚举‘PG_TUNNEL_ERROR_E’的定义

*/

int pgTunnelTunnelSet(const char* lpszPasscode, const char* lpszComment);

pgTunnelPeerInfoGet: 获取本客户端和指定用户ID的远程客户端之间的P2P通道信息

/**

* 描述：获取本客户端和指定用户ID的远程客户端之间的P2P通道信息。

* 阻塞方式：阻塞，等待服务器执行操作。

* lpszPeerID：[IN] 对端客户端的用户ID。

* lpstPeerInfo：[OUT] P2P通道的信息，见’PG_TUNNEL_PEER_INFO_S’定义。

* 输出的‘PG_TUNNEL_PEER_INFO_S’数据结构中的‘szTunnelLocal’

* 和‘szTunnelRemote’属性为空字符串时，表示P2P通道连接还没有成功建立。

*

* 返回值：见枚举‘PG_TUNNEL_ERROR_E’的定义

*/

int pgTunnelPeerInfoGet(const char* lpszPeerID, PG_TUNNEL_PEER_INFO_S* lpstPeerInfo);

pgTunnelConnectAdd: 本客户端和指定用户ID的远程客户端之间添加一条隧道连接

/**

* 描述：本客户端和指定用户ID的远程客户端之间添加一条隧道连接。

* 如果添加成功，返回本端映射的客户端连接地址端口信息。

* 阻塞方式：阻塞，等待服务器执行操作。

* lpszSession：[IN] 登录会话ID。

* （可选，传空字符串，只有在P2P服务器端开启登录会话验证的时候需要传入有效值）

* lpszPeerID：[IN] 对端客户端的用户ID。

* uType：[IN] 隧道连接的类型，0:为TCP连接，1为HTTP代理连接

* uEncrypt：[IN] 隧道连接是否加密，0为不加密，1为加密。

* lpszListenAddr：[IN] 对端TCP服务器的侦听地址端口。

* lpszClientAddr：[IN] 本端映射的客户端连接地址端口。

* 如果传空字符串，则由P2P服务器自动分配地址端口。

* lpstClientAddr：[OUT] 客户端连接地址端口信息，见’PG_TUNNEL_CLIENT_ADDR_S’定义。

* 返回值：见枚举‘PG_TUNNEL_ERROR_E’的定义

*/

int pgTunnelConnectAdd(const char* lpszSession, const char* lpszPeerID,

unsigned int uType, unsigned int uEncrypt, const char* lpszListenAddr,

const char* lpszClientAddr, PG_TUNNEL_CLIENT_ADDR_S* lpstClientAddr);

pgTunnelConnectDelete: 删除一条隧道连接

/**

* 描述：删除一条隧道连接。

* 阻塞方式：阻塞，等待服务器执行操作。

* lpszSession：[IN] 登录会话ID。

* （可选，传空字符串，只有在P2P服务器端开启登录会话验证的时候需要传入有效值）

* lpszPeerID：[IN] 对端客户端的用户ID。

* uType：[IN] 隧道连接的类型，0:为TCP连接，1为HTTP代理连接

* uEncrypt：[IN] 隧道连接是否加密，0为不加密，1为加密。

* lpszListenAddr：[IN] 对端TCP服务器的侦听地址端口。

* lpszClientAddr：[IN] 本端映射的客户端连接地址端口。

* 如果传空字符串，则删除由“lpszPeerID、uType、uEncrypt、lpszListenAddr”

* 这4个参数匹配的隧道连接。

*

* 返回值：见枚举‘PG_TUNNEL_ERROR_E’的定义

*/

int pgTunnelConnectDelete(const char* lpszSession, const char* lpszPeerID,

unsigned int uType, unsigned int uEncrypt, const char* lpszListenAddr,

const char* lpszClientAddr);

pgTunnelConnectQuery: 获取一条隧道连接的本端映射的客户端连接地址端口

/**

* 描述：获取一条隧道连接的本端映射的客户端连接地址端口。

* 阻塞方式：阻塞，等待服务器执行操作。

* lpszPeerID：[IN] 对端客户端的用户ID。

* uType：[IN] 隧道连接的类型，0:为TCP连接，1为HTTP代理连接

* uEncrypt：[IN] 隧道连接是否加密，0为不加密，1为加密。

* lpszListenAddr：[IN] 对端TCP服务器的侦听地址端口。

* lpstClientAddr：[OUT] 本端映射的客户端连接地址端口信息，见’PG_TUNNEL_CLIENT_ADDR_S’定义。

* 返回值：见枚举‘PG_TUNNEL_ERROR_E’的定义

*/

int pgTunnelConnectQuery(const char* lpszPeerID, unsigned int uType, unsigned int uEncrypt,

const char* lpszListenAddr, PG_TUNNEL_CLIENT_ADDR_S* lpstClientAddr);

pgTunnelConnectLocalDelete: 根据本端映射的客户端连接地址端口信息删除一条隧道连接

/**

* 描述：根据本端映射的客户端连接地址端口信息删除一条隧道连接。

* 阻塞方式：阻塞，等待服务器执行操作。

* lpszSession：[IN] 登录会话ID。

* （可选，传空字符串，只有在P2P服务器端开启登录会话验证的时候需要传入有效值）

* lpszClientAddr：[IN] 本端映射的客户端连接地址端口。

* 返回值：见枚举‘PG_TUNNEL_ERROR_E’的定义

*/

int pgTunnelConnectLocalDelete(const char* lpszSession, const char* lpszClientAddr);

pgTunnelConnectLocalQuery: 根据本端映射的客户端连接地址端口信息获取一条隧道连接的全部信息

/**

* 描述：根据本端映射的客户端连接地址端口信息获取一条隧道连接的全部信息。

* 阻塞方式：阻塞，等待服务器执行操作。

* lpszClientAddr：[IN] 本端映射的客户端连接地址端口。

* lpstConnectInfo：[OUT] 隧道连接的全部信息，见’PG_TUNNEL_CONNECT_INFO_S’定义。

* 返回值：见枚举‘PG_TUNNEL_ERROR_E’的定义

*/

int pgTunnelConnectLocalQuery(const char* lpszClientAddr, PG_TUNNEL_CONNECT_INFO_S* lpstConnectInfo);

pgTunnelUserExtend: 发送自定义请求给P2P服务器，并接收服务器的应答

/**

* 描述：发送自定义请求给P2P服务器，并接收服务器的应答。

* 阻塞方式：阻塞，等待服务器执行操作。

* lpszRequestData：[IN] 发送给服务器的请求数据。

* lpstReplyData：[OUT] 接收到服务器的返回数据。

* uTimeout：[IN] 等待超时时间（毫秒）。（传0则使用默认的超时时间，默认为10000毫秒）

* 返回值：见枚举‘PG_TUNNEL_ERROR_E’的定义

*/

int pgTunnelUserExtend(const char* lpszRequestData, PG_TUNNEL_DATA_S* lpstReplyData, unsigned int uTimeout);

pgTunnelPushGet: 接收P2P服务器下发的推送消息:

/**

* 描述：接收P2P服务器下发的推送消息。

* 阻塞方式：如果客户端的缓冲区中已经有下推的消息数据，则立即返回缓冲区里的消息数据。

* 如果客户端的缓冲区中还没有下推的消息数据，则等待P2P服务器下推消息数据。

* lpstPushData：[OUT] 接收到服务器的推送消息数据。

* uTimeout：[IN] 等待超时时间（毫秒）。

* 返回值：见枚举‘PG_TUNNEL_ERROR_E’的定义

*/

int pgTunnelPushGet(PG_TUNNEL_DATA_S* lpstPushData, unsigned int uTimeout);

pgTunnelSelfGet 获取本端的用户ID

/**

* 描述：获取本端的用户ID。

* 阻塞方式：阻塞，等待服务器执行操作。

* lpstSelf [OUT] 接收到本端的用户ID。

* 返回值：见枚举‘PG_TUNNEL_ERROR_E’的定义

*/

int pgTunnelSelfGet(PG_TUNNEL_SELF_S* lpstSelf);

pgTunnelConnectEnum 根据索引逐条获取隧道连接的全部信息

/**

* 描述：根据索引逐条获取隧道连接的全部信息。

* 阻塞方式：阻塞，等待服务器执行操作。

* uIndex [IN] 隧道的索引号：0, 1, 2, 3, 4, …

* lpstConnectInfo：[OUT] 隧道连接的全部信息，见’PG_TUNNEL_CONNECT_INFO_S’定义。

* 返回值：见枚举‘PG_TUNNEL_ERROR_E’的定义

*/

int pgTunnelConnectEnum(unsigned int uIndex, PG_TUNNEL_CONNECT_INFO_S* lpstConnectInfo);

4. HTTP控制接口：

1）设置用户域：

描述:

设置P2P隧道客户端帐号的用户域。

请求操作：

样例：http://127.0.0.1:17881/domainset?passcode=12345678

action: domainset

参数：

passcode：识别码

响应操作：

样例：domainset:{“result”:”0″}

action: domainset

参数：

result: 错误码（参考“HTTP控制接口错误码”章节）

2）获取用户域：

描述:

获取P2P隧道客户端帐号的用户域。

请求操作：

样例：http://127.0.0.1:17881/domainget

action: domainget

参数：

无

响应操作：

样例：domainget:{”domain”:”pptun.com”}

action: domainget

参数：

domain: 用户域名称

3）设置客户端说明：

描述:

设置P2P隧道客户端说明。

请求操作：

样例：http://127.0.0.1:17881/commentset?comment=pptun%20client

action: commentset

参数：

comment: 客户端说明内容

响应操作：

样例：commentset:{”result”:”0”}

action: commentset

参数：

result: 错误码（参考“HTTP控制接口错误码”章节）

4）获取客户端说明：

描述:

获取P2P隧道客户端说明。

请求操作：

样例：http://127.0.0.1:17881/commentget

action: commentget

参数：

无

响应操作：

样例：commentget:{”comment”:”pptun client”}

action: commentget

参数：

comment: 客户端说明

5）设置客户端参数：

描述:

设置识别码和P2P隧道客户端说明。

请求操作：

样例：http://127.0.0.1:17881/tunnelset?passcode=12345678&comment=pptun%20client

action: tunnelset

参数：

passcode: 识别码

comment: 客户端说明

响应操作：

样例：tunnelset:{”result”:”0”}

action: tunnelset

参数：

result: 错误码（参考“HTTP控制接口错误码”章节）

6）获取客户端版本：

描述:

获取当前P2P隧道客户端的版本号。

请求操作：

样例：http://127.0.0.1:17881/versionget

action: versionget

参数：

无

响应操作：

样例：versionget:{”version”:”1.0.0.1”}

action: versionget

参数：

version: 版本号

7）获取登录到P2P服务器的状态：

描述:

获取登录到P2P服务器的状态。

请求操作：

样例：http://127.0.0.1:17881/statusget?option=0

action: statusget

参数：

option: 选项，见‘PG_TUNNEL_GET_STA_E’定义

响应操作：

样例：statusget:{”result”:”0”,”status”:”0”}

action: statusget

参数：

result: 错误码（参考“HTTP控制接口错误码”章节）

status: 状态码，见‘PG_TUNNEL_STA_LOGIN_E’定义

8）获取与对端节点的P2P通道信息：

描述:

查询一条本端与对端之间的P2P连接。

请求操作：

样例：http://127.0.0.1:17881/peerinfoget?peerid=_DEV_123456@pptun.com

action: peerinfoget

参数：

peerid: 对端的P2P节点名

响应操作：

样例：peerinfoget:{”result”:”0”,”peerid”:”_DEV_123456@pptun.com”,“type”:”4”, “addrlocal”:”x.x.x.x:port”,“addrremote”:”x.x.x.x:port”,“tunnellocal”:”x.x.x.x:port”, “tunnelremote”:”x.x.x.x:port”,“privremote”:”x.x.x.x:port”}

action: peerinfoget

参数：

result: 错误码（参考“HTTP控制接口错误码”章节）

peerid：对端的P2P节点名

type：连接的通道类型，数值如下：

0：未识别

4：公网IP地址

5：完全锥形NAT

6：主机限制锥形NAT

7：端口限制锥形NAT

8：对称NAT

12：私网直连

13：NAT环回

16：TCP转发

17：HTTP转发

24：节点转发

65535：对端不在线

addrlocal：本端的登录地址端口

addrremote：对端的登录地址端口

tunnellocal：本端的通道地址端口

tunnelremote：对端的通道地址端口

privremote：对端的内网地址端口

9）添加一条与对端P2P节点的隧道：

描述:

添加一条本端与对端之间的P2P隧道。

请求操作：

样例：http://127.0.0.1:17881/cnntadd?session=654321&peerid=_DEV_123456@pptun.com&type=0&encrypt=1&listenaddr=127.0.0.1:8000&clientaddr=127.0.0.1:8001

action: cnntadd

参数：

session: 会话ID（可选）

peerid: 对端的P2P节点名

type: 连接类型。0为TCP隧道，1为HTTP代理隧道

encrypt: 是否加密。1为加密，0为不加密

listenaddr：对端TCP服务器的侦听地址端口

clientaddr: 本端TCP客户端的连接地址端口（可选，如果不指定则自动分配）

响应操作：

样例：cnntadd:{”result”:”0”,”clientaddr”:”127.0.0.1:8001”}

action: cnntadd

参数：

result: 错误码（参考“HTTP控制接口错误码”章节）

clientaddr: 本端TCP客户端的连接地址端口

10）删除一条与对端P2P节点的隧道：

描述:

删除一条本端与对端之间的P2P隧道。

请求操作：

样例：http://127.0.0.1:17881/cnntdelete? session=654321&peerid=_DEV_123456@pptun.com&type=0&encrypt=1&listenaddr=127.0.0.1:8000&clientaddr=127.0.0.1:8001

action: cnntdelete

参数：

session: 会话ID（可选）

peerid: 对端的P2P节点名

type: 连接类型。0为TCP隧道，1为HTTP代理隧道

encrypt: 是否加密。1为加密，0为不加密

listenaddr：对端TCP服务器的侦听地址端口

clientaddr: 本端TCP客户端的连接地址端口（可选，如果不指定则不匹配）

响应操作：

样例：cnntdelete:{”result”:”0”}

action: cnntdelete

参数：

result: 错误码（参考“HTTP控制接口错误码”章节）

11）查询一条与对端P2P节点的隧道：

描述:

查询一条本端与对端之间的P2P隧道。

请求操作：

样例：http://127.0.0.1:17881/cnntquery?peerid=_DEV_123456@pptun.com&type=0&listenaddr=127.0.0.1:8080

action: cnntquery

参数：

peerid: 对端的P2P节点名

type: 连接类型。0为TCP隧道，1为HTTP代理隧道

listenaddr：对端TCP服务器的侦听地址端口

响应操作：

样例：cnntquery:{“result”:”0”,”clientaddr”:”127.0.0.1:8001”}

action: cnntquery

参数：

result: 错误码（参考“HTTP控制接口错误码”章节）

clientaddr: 本端TCP客户端的连接地址端口

12）删除一条与对端P2P节点的隧道(根据本地地址)：

描述:

根据本地地址删除一条本端与对端之间的P2P隧道。

请求操作：

样例：http://127.0.0.1:17881/cnntlcldelete?session=654321&clientaddr=127.0.0.1:8001

action: cnntlcldelete

参数：

session: 会话ID（可选）

clientaddr: 本端TCP客户端的连接地址端口

响应操作：

样例：cnntlcldelete:{“result”:”0”}

action: cnntlcldelete

参数：

result: 错误码（参考“HTTP控制接口错误码”章节）

13）查询一条与对端P2P节点的隧道(根据本地地址)：

描述:

根据本地地址查询一条本端与对端之间的P2P隧道。

请求操作：

样例：http://127.0.0.1:17881/cnntlclquery?clientaddr=127.0.0.1:8001

action: cnntlclquery

参数：

clientaddr: 本端TCP客户端的连接地址端口

响应操作：

样例：cnntlclquery:{“result“:“0“, “peerid“:“_DEV_123456@pptun.com“, “type“:“0“, “encrypt“: “1“, “listenaddr“:“127.0.0.1:8000“, “clientaddr“:“127.0.0.1:8001“}

action: cnntlclquery

参数：

result: 错误码（参考“HTTP控制接口错误码”章节）

peerid: 对端的P2P节点名

type: 连接类型。0为TCP连接，1为HTTP代理

encrypt: 是否加密。1为加密，0为不加密

listenaddr：对端TCP服务器的侦听地址端口

clientaddr: 本端TCP客户端的连接地址端口

14）客户端与P2P服务器之间的透传通信

描述:

P2P隧道客户端与P2P服务器之间的透明传输数据的方式。

请求操作：

样例：http://127.0.0.1:17881/userextend?xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

action: userextend

参数：

发送给服务器的字符串数据。用户自定义内容和格式

响应操作：

样例：userextend:{”result”:”0”,”data”:”yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy”}

action: userextend

参数：

result: 错误码（参考“HTTP控制接口错误码”章节）

data: 服务器返回的字符串数据。用户自定义内容和格式

15）接收服务器推送消息：

描述:

接收P2P服务器下发的推送消息。本接口使用HTTP长连接的方式访问P2P隧道客户端。如果P2P隧道客户端的队列里有下发的推送消息，则立即返回该推送消息。如果P2P隧道客户端的队列里没有推送消息，则一直等待，直到接收到下一次P2P服务器下发的推送消息时，返回该推送消息。

请求操作：

样例：http://127.0.0.1:17881/pushget

action: pushget

参数：

无

响应操作：

样例：pushget:{“result”:”0″, ”data”:”xxxxxxxxxxxxx”}

action: pushget

参数：

result: 错误码。0为成功，非0为错误码。（参考“HTTP控制接口错误码”章节）

data: 推送的消息，用户自定义内容和格式。

16）获取本端的用户ID：

描述:

获取本端的用户ID

请求操作：

样例：http://127.0.0.1:17881/selfget

action: selfget

参数：

无

响应操作：

样例：selfget:{“self”:”_DEV_654321@pptun.com”}

action: selfget

参数：

self: 本端的用户P2P ID

17）根据索引逐条获取隧道连接的全部信息：

描述:

根据索引逐条获取隧道连接的全部信息。

请求操作：

样例：http://127.0.0.1:17881/connectenum?index=0

action: connectenum

参数：

index: 隧道的索引号：0, 1, 2, 3, 4, …

响应操作：

样例：connectenum:{“result“:“0“, “peerid“:“_DEV_123456@pptun.com“, “type“:“0“, “encrypt“: “1“, “listenaddr“:“127.0.0.1:8000“, “clientaddr“:“127.0.0.1:8001“}

action: connectenum

参数：

result: 错误码（参考“HTTP控制接口错误码”章节）

peerid: 对端的P2P节点名

type: 连接类型。0为TCP连接，1为HTTP代理

encrypt: 是否加密。1为加密，0为不加密

listenaddr：对端TCP服务器的侦听地址端口

clientaddr: 本端TCP客户端的连接地址端口

5. HTTP控制接口错误码

PG_ERR_Normal = 0 // 成功

PG_ERR_System = 1 // 系统错误

PG_ERR_BadParam = 2 // 参数错误

PG_ERR_BadClass = 3 // 无效的功能类

PG_ERR_BadMethod = 4 // 无效的方法

PG_ERR_BadObject = 5 // 无效的对象

PG_ERR_BadStatus = 6 // 错误的状态

PG_ERR_BadFile = 7 // 无效的文件

PG_ERR_BadUser = 8 // 无效的用户

PG_ERR_BadPass = 9 // 密码错误

PG_ERR_NoLogin = 10 // 未登录

PG_ERR_Network = 11 // 网络错误

PG_ERR_Timeout = 12 // 操作超时

PG_ERR_Reject = 13 // 拒绝访问

PG_ERR_Busy = 14 // 系统正忙

PG_ERR_Opened = 15 // 资源已经打开

PG_ERR_Closed = 16 // 资源已经关闭

PG_ERR_Exist = 17 // 资源已经存在

PG_ERR_NoExist = 18 // 资源不存在

PG_ERR_NoSpace = 19 // 空间或容量限制

PG_ERR_BadType = 20 // 无效的类型

PG_ERR_CheckErr = 21 // 校验错误

PG_ERR_BadServer = 22 // 无效的服务器

PG_ERR_BadDomain = 23 // 无效的域

PG_ERR_NoData = 24 // 没有数据

PG_ERR_Unknown = 255 // 未知错误

PG_ERR_Extend = 256 // 用户自定义错误码开始编号

6. 配置文件：

P2P隧道的配置文件的内容：

// 指定沙盒目录。（不指定此参数，则使用缺省的沙盒目录）

// 重要：在嵌入式设备上，必须指定沙盒目录，沙盒目录分配在FLASH里，可写，且重新上电后数据不能丢失。

(Home){/home/xxxx} // 目录路径中不能包含 ( ) { } { } & 等字符，且该目录必须所有用户都可写。

// P2P中继服务器列表（可配置多个中继服务器）：

(RelayList){

(Relay0){

(Type){0} // 中继类型：0: TCP、1: HTTP

(Addr){connect.peergine.com:443} // 中继转发服务器地址端口

}

(Relay1){

(Type){1} // 中继类型：0: TCP、1: HTTP

(Addr){connect.peergine.com:8000} // 中继转发服务器地址端口

}

}

// 客户端模式设置：

(ModeClient){

(Base){

(MaxSess){256} // 最大并发的TCP连接数

(MaxHttp){8} // 最大并发的HTTP控制连接数（设置为0时，关闭HTTP控制接口）

(MaxTunnel){16} // 最大隧道数

(ConnectTimeout){60} // 建立TCP连接超时时间（秒）

(SessBufSize){256} // P2P会话缓冲区大小（K Bytes）

(P2PTryTime){15} // P2P尝试穿透超时时间（秒）

(AcceptSpeed){0} // 接受(Accept)TCP连接的速度限制（次/秒），0为不限制

(MaxParallel){0} // 每个隧道并发的最大TCP连接数限制，0为不限制

(AddrHttpListen){127.0.0.1:17881} // HTTP控制的侦听端口，默认为127.0.0.1:17881

(LoginDelayInterval){10} // 尝试重新登录的退避时间的增长步进（秒）。有效范围1 ~ 300，默认10

(LoginDelayMax){300} // 尝试重新登录的退避时间的最大值（秒）。有效范围30 ~ 300，默认300

}

(Node){

(SvrAddr){connect.peergine.com:7885} // P2P服务器地址

(CltAddr){0:0:0:127.0.0.1:0:0} // P2P客户端地址（建议使用缺省值，让系统自动选择地址）

(SvrName){pgTunnelSvr0} // P2P服务器节点名（必须与P2P服务器端配置一致）

(Digest){1} // 传递密码的方式：0为明文传递密码，1为传递密码摘要。本参数为空则使用摘要方式。

(ClientOnly){0} // 只作为TCP客户端（不能作为TCP被连接端）。1为启用，0为禁用。默认为0

// 启用此选项时，本端的P2P ID不计入P2P服务器授权ID的数量。

// 建议手机APP端等不需要被动接受TCP连接的应用场景启用此选项。

}

(AccountCode){ // 用DevID生成的帐号登录P2P服务器

(Prefix){_DEV_} // 用来生成用户名的前缀（必须与P2P服务器端配置一致）

(Domain){pptun.com} // 用来生成P2P用户名的域名称。

(Comment){pptun客户端} // P2P隧道客户端说明信息

}

// AccountCode 和 AccountPass 只能二选一，不使用的方式应该注释或删除。

(AccountPass){ // 用服务器端配置好的帐号登录P2P服务器

(User){_DEV_abcd@pptun.com} // P2P隧道客户端登录用户名

(Pass){1234} // P2P隧道客户端登录密码

(Comment){pptun客户端} // P2P隧道客户端说明信息

}

(Log){

(Level0){1} // Major级日志开关

(Level1){1} // General级日志开关

(Level2){0} // Suggestive级日志开关

(Level3){0} // Info级日志开关

(FileNum){8} // 日志文件的最大数量

(FileSize){65536} // 每个日志文件最大长度(字节)

(Debug){1} // 开启/关闭调试信息打印，默认为开启

}

(Utilize){

(ForwardSpeed){327680} // 允许本节点作为转发节点。非0：允许转发的带宽(字节/秒)，0：禁用转发。

(ForwardUse){1} // 本节点是否使用其他节点作为转发节点。非0：是，0：否。

(TunnelKillPort){1} // 是否杀掉占用隧道入口TCP端口的其他进程（Windows系统有效）

(TunnelIdlePort){1} // 是否在TCP端口已占用时自动分配其他空闲的TCP端口。默认为1

(DirectTunnelAccept){1} // 是否接受客户端之间直接隧道连接请求。默认为1

(DirectTunnelEnable){0} // 是否启用客户端之间直接隧道连接。默认为0

}

}

7. 沙盒目录

Peergine系列软件（P2P隧道是Peergine系列软件的一员）使用一个文件夹目录集中保存软件运行过程输出的数据，包括日志信息、生成的验证信息等。这个集中保存软件运行过程输出的数据的文件夹目录称为“沙盒目录”。Peergine软件对这个“沙盒目录”必须具有可写权限，所以默认情况下，Peergine软件会根据当前的操作系统类型、当前的用户名，选择一个最有可能具备可写权限的目录作为“沙盒目录”。

在Windows系统上，一般选择运行该Peergine软件的用户的“文档”目录作为沙盒目录。例如，当前运行Peergine软件的用户为Administrator那么“沙盒目录”为C:\Users\Administrator\Documents。如果Peergine软件运行为在后台服务程序，那么“沙盒目录”为以下的目录之一（不同版本的Windows操作系统“沙盒目录”的路径略微不同）：

“C:\Users\Default\Documents”

“C:\Windows\System32\config\systemprofile\Documents”

“C:\Windows\SysWOW64\config\systemprofile\Documents”

“C:\Documents and Settings\Default User\My Documents”

这些目录往往是隐藏的，要把文件夹选项改成显示隐藏文件才看得到。

在Linux操作上，一般选择运行该Peergine软件的用户的“HOME”目录作为沙盒目录。假设，当前运行Peergine软件的用户为root，那么“沙盒目录”为 /root。假设，当前运行Peergine软件的用户为一个普通用户user，那么“沙盒目录”为 /home/user。如果当前用户的“HOME”目录也没有可写权限，那么Peergine软件尝试把 /var目录作为沙盒目录。

除了Peergine软件默认选择一个可写的文件夹作为“沙盒目录”，还可以通过配置参数指定一个文件夹目录作为“沙盒目录”。例如，P2P隧道SDK可以在配置文件的 (Home){} 配置参数指定一个文件夹目录作为“沙盒目录”。

8. 修改记录：

序号	修改说明	版本号
1	补充完善HTTP控制接口	1.9
2	补充完善配置文件说明	1.9
3	增加“删除一条与对端P2P节点的隧道(根据本地地址)”和“查询一条与对端P2P节点的隧道(根据本地地址)”2个HTTP控制API。	1.10
4	增加“HTTP控制接口错误码”章节	1.10
5	配置文件增加ForwardUse参数	1.11
6	增加配置文件中的沙盒目录描述，增加嵌入式设备上的沙盒目录配置要求。	1.12
7	增加C语言的隧道控制接口	1.13
8	增加pgTunnelStatusGet()的API函数，用来查询P2P隧道客户端登录到P2P服务器的状态。	1.15
9	HTTP控制API，增加“获取登录到P2P服务器的状态”，用来查询P2P隧道客户端登录到P2P服务器的状态。	1.15
10	在“6. 配置文件”章节，配置文件的Node小节，增加Digest参数，用来指定传递给P2P服务器的登录密码方式	1.15
11	“登录状态定义”枚举增加自定义错误码	1.16
12	“HTTP控制接口错误码”枚举增加自定义错误码	1.16
13	在“6. 配置文件”章节，配置参数MaxHttp增加当配置为0时，关闭“HTTP控制接口”功能。	1.16
14	增加“沙盒目录”章节	1.16
15	增加pgTunnelSetCfgParam()函数，直接设置配置文件的内容到pgLibTunnel中。	1.17
16	增加pgTunnelSelfGet()和pgTunnelConnectEnum()函数	1.18
17	配置文件增加Utilize.TunnelIdlePort选项	1.19
18	配置文件增加Utilize.DirectTunnelAccept和 Utilize.DirectTunnelEnable选项	1.20
19	配置文件增加Log.Debug选项	1.21
20	配置文件增加Base.LoginDelayInterval和Base.LoginDelayMax选项 配置文件增加Node.ClientOnly选项	1.22