蒲公英SDK文档

1. 概述
   PGYAPI 是上海贝锐股份有限公司开发的一套基于产品蒲公英的开发库，该库可以实现与蒲公英标准产品一致的组网服务功能。使用该开发库时，开发者无须关心组网细节以及通讯方式的具体实现。PGYAPI 会以 P2P 或服务器中转等方式为通讯提供可靠的数据传输服务。

2. 开发者账号
   使用 PGYAPI 之前，你需要先拥有一个 贝锐 帐户，可以通过https://www.oray.com的右上角的注册按钮进行注册。如图：

拥有帐户后，进入http://open.oray.com（开放平台的网址），进入开发者认证页面，填写必要资料并提交开发者申请。如图：

注册后，进入我的应用页面创建应用，创建成功后，在应用详情中看到自己的APP ID 和 APP KEY，有了这两个信息，就可以使用PGYAPI来开发自己的应用了。如图：

1. 支持平台
   目前 PGYAPI 支持 Window 系列平台，Linux 和其他系统平台也将会尽快推出。

2. 支持语言
   目前PGYAPI以纯C加二进制库实现方式提供接口，只要你的开发环境可以调用C函数即可。Win平台字符换使用Unicode编码

3. 使用规范

4. 目录结构
   在开发库下你可以看到以下目录include、lib、bin、doc、samples。

5. include目录：所有PGYAPI使用的API头文件，目前只有 pgysdk.h文件，用户只需要包含该文件即可使用PGYAPI所有功能

6. bin目录：放有 PGYAPI 运行时库，Windows 下为 pgyvpn.dll 文件，运行时请将它放到运行程序所在的目录。放有 PGYAPI 编译所需要的链接库，Windows 下为 pgyvpn.lib，编译时请链接该库

7. doc目录：所有PGYAPI的使用说明与相关文档

8. samples目录：所有PGYAPI应用实例

9. 驱动安装
   使用需要安装蒲公英虚拟网卡，进入 drivers 目录，使用管理员权限执行 driver_install.bat 脚本去安装蒲公英虚拟网卡；同样的在卸载应用时调用 driver_uninstall.bat 脚本去卸载蒲公英虚拟网卡

10. 具体使用
11. 配置开发者账号信息：使用PGY_SetConfig去配置开发者信息

{
PGY_SetConfig(PGY_CONDIG_APPID, appid);
PGY_SetConfig(PGY_CONDIG_APPSECRET, appsecret);

}

1. 注册回调监听：使用PGY_Register去设置事件的回调监听

{

PGY_Register(CALLBACK_EVENT_VNC_LOADIND, (void*)fnPgyVNCLoad);// 虚拟网卡加载
PGY_Register(CALLBACK_EVENT_CONNECT, (void*)fnPgyConnect);// 连接事件
PGY_Register(CALLBACK_EVENT_DISCONNECT, (void*)fnPgyDisconnect);// 断开连接事件
PGY_Register(CALLBACK_EVENT_LOGIN, (void*)fnPgyLogin);// 登录事件
PGY_Register(CALLBACK_EVENT_LOGOUT, (void*)fnPgyLogout);// 注销&退出事件
PGY_Register(CALLBACK_EVENT_MEMBER_JOIN, (void*)fnPgyMemberJoin);// 成员加入
PGY_Register(CALLBACK_EVENT_MEMBER_LEAVE, (void*)fnPgyMemberLeave);// 成员离开
PGY_Register(CALLBACK_EVENT_MEMBER_CHANGED, (void*)fnPgyMemberChanged);// 成员信息
发生更改
PGY_Register(CALLBACK_EVENT_MEMBER_CONNECT_CHANGED,
(void*)fnPgyConnectChanged);// 成员连接方式改变
PGY_Register(CALLBACK_EVENT_GROUP_LEAVE, (void*)fnPgyGroupLeave);// 离开组
PGY_Register(CALLBACK_EVENT_GROUP_CHANGED, (void*)fnPgyGroupChanged);// 组信息发生
更改

}

1. 开启日志存储：使用PGY_OpenLog开启日志存储功能

{
PGY_OpenLog(NULL, NULL);

}

1. 登录：使用PGY_Login去验证登录到服务器

{
PGY_Login(PGY_LOGIN_TYPE_ACCOUNT, username, password, NULL, NULL, NULL);

}

1. 操作：使用其他的PGYAPI去做具体的操作功能（PGY_Logout PGY_DumpTypeGet等）

2. API 详细说明
3. PGY_SetConfigBool
   原型：bool PGY_SetConfigBool(int option, bool bValue);

功能：设置布尔类型的全局配置信息

参数：option 配置项名称 (具体配置项查看 PGY_CONFIG_EM)
bValue 配置项的值

返回：是否设置成功

1. PGY_SetConfigInt
   原型：bool PGY_SetConfigInt(int option, int nValue);

功能：设置整型的全局配置信息

参数：option 配置项名称 (具体配置项查看 PGY_CONFIG_EM)
nValue 配置项的值

返回：是否设置成功

1. PGY_SetConfig
   原型：bool PGY_SetConfig(int option, const char* szValue);

功能：设置字符串类型的全局配置信息

参数：option 配置项名称 (具体配置项查看 PGY_CONFIG_EM) szValue 配置项的值

返回：是否设置成功

1. PGY_ShowConfig
   原型：void PGY_ShowConfig();

功能：显示全局的配置信息

参数：无

返回：无

1. PGY_Register
   原型：void PGY_Register(int event, void* fnCallback);

功能：通知事件注册函数 (通过该接口，来注册想要监听的通知事件)

参数：event 事件ID (具体事件ID查看 PGY_CALLBACK_ENVENT_EM )
fnCallback 回调函数的地址 ( 请查看 pgysdk.h 对应事件的函数定义 )

返回：无

1. PGY_OpenLog
   原型：void PGY_OpenLog(const char filepath, const char filename);

功能：根据配置信息，打开文件记录功能

参数：filepath 日志文件保存路径
filename 日志文件名

返回：无

1. PGY_Login
   原型：bool PGY_Login(PGY_LOGIN_TYPE login_type, char account, char password, char token, char
   device_token, char* package_key);

功能：蒲公英SDK登录接口，用于登录蒲公英组网服务

参数：type 登录类型(账号密码登录、VPNID登录、SN登录)
account 账号
password 密码
token device_token package_key 预留内部参数，默认为NULL即可

返回：登录过程调用是否成功

说明：真正的登录成功与否请监听 CALLBACK_EVENT_LOGIN 事件

1. PGY_Logout
   原型：void PGY_Logout();

功能：注销登录

参数：无

返回：无

说明：真正的注销登录成功与否请监听 CALLBACK_EVENT_LOGOUT 事件

1. PGY_GetMemberList
   原型：int PGY_GetMemberList(PGY_GTOUP_MEMBER* pstMembers, unsigned int nSize);

功能：获取组网成员列表

参数：pstMembers PGY_GTOUP_MEMBER* 接收组成员的缓存指针
nSize 缓存区大小

返回：操作成功返回PGY_ERR_OK; 否则返回其他值(如果缓存太小，则返回实际需要的缓存字节数)

1. PGY_GetGroup
   原型：int PGY_GetGroup(PGY_GROUP &stGroup);

功能：获取组网信息

参数：stGroup PGY_GROUP& 接收组信息

返回：操作成功返回PGY_ERR_OK; 否则返回其他值

1. PGY_SubscriberGetMessage
   原型：int PGY_SubscriberGetMessage(char* pszMessage, unsigned int nSize);

功能：读取订阅消息

参数：pszMessage char*数据缓存块(存放json字符串)
nSize 缓存区大小

返回：操作成功返回PGY_ERR_OK; 否则返回其他值

1. PGY_SubscriberGetPushMessage
   原型：int PGY_SubscriberGetPushMessage(PGY_PUSH_MSG* pstPgyPushMsg, unsigned int nSize);

功能：读取推送的消息

参数：pszMessage PGY_PUSH_MSG*数据缓存块
nSize 缓存区大小

返回：操作成功返回PGY_ERR_OK; 否则，返回应该申请的缓存区大小

1. PGY_SubscriberPushMessage
   原型：bool PGY_SubscriberPushMessage(char *msg);

功能：推送订阅消息

参数：msg char*推送的消息内容(存放json字符串)

返回：成功返回true；否则，返回false

1. PGY_SetForceForward
   原型：bool PGY_SetForceForward(unsigned int nMbrID, bool bEnabled);

功能：设置强制转发

参数：nMbrID 组成员的ID
bEnabled 是否强制转发 (true=设置强制转发，false=取消强制转发)

返回：成功返回true；否则，返回false

1. PGY_GetForceForward
   原型：int PGY_GetForceForward(PGY_GTOUP_MEMBER* pstFwdMember, unsigned int nSize);

功能：获取强制转发列表

参数：pstFwdMember 组成员的ID
nSize 缓冲区大小

返回：操作成功返回PGY_ERR_OK; 否则返回其他值(如果缓存太小，则返回实际需要的缓存字节数);

1. PGY_GetSession
   原型：int PGY_GetSession(PGY_SESSION &session);

功能：获取用户会话信息信息

参数：session PGY_SESSION&存放会话信息

返回：操作成功返回PGY_ERR_OK; 否则返回其他值

1. PGY_PringDebugInfo
   原型：void PGY_PringDebugInfo(char *pszDebug, unsigned int nSize);

功能：打印调试信息

参数：pszDebug 接收调试信息的缓存指针
nSize 缓冲区大小

返回：无

1. PGY_FaultDiagnosis
   原型：bool PGY_FaultDiagnosis(PGY_DUMP_TYPE eDumpType, PGY_DUMP_INFO& dumpResult);

功能：故障诊断

参数：eDumpType PGY_DUMP_TYPE 诊断类型
dumpResult PGY_DUMP_INFO&诊断信息

返回：操作成功返回true; 否则返回false

1. PGY_DumpTypeGet
   原型：int PGY_DumpTypeGet(PGY_DUMP_BASE* pDumpBases, unsigned nCount);

功能：查看支持的诊断类型

参数：pDumpBases PGY_DUMP_BASE*接收诊断类型的缓存
nCount 缓冲块数量

返回：返回支持的诊断类型的数量

1. 事件监听接口
2. FN_PGY_VirEthLoad（虚拟网卡加载事件）
   {
   typedef void(*FN_PGY_VirEthLoad)(int err_no);

}
事件ID：CALLBACK_EVENT_VNC_LOADIND

参数名称 参数类型 备注
err_no int 错误码

1. FN_PGY_Connect（组网连接成功事件）
   {
   typedef void(*FN_PGY_Connect)();

}
事件IDCALLBACK_EVENT_CONNECT

参数名称 参数类型 备注
无 无 无

1. FN_PGY_Disconnect（组网连接断开事件）
   {
   typedef void(*FN_PGY_Disconnect)(int err_no);
   }
   ????事件ID：CALLBACK_EVENT_DISCONNECT

参数名称 参数类型 备注
err_no int 错误码

1. FN_PGY_Login（登录事件）
   {
   typedef void(FN_PGY_Login)(int err_no, const char err_msg);

}
事件ID：CALLBACK_EVENT_LOGIN

参数名称 参数类型 备注
err_no int 错误码
err_msg const char* 错误信息

1. FN_PGY_Logout（注销登录事件）
   {
   typedef void(*FN_PGY_Logout)();

}
事件ID：CALLBACK_EVENT_LOGOUT

参数名称 参数类型 备注
无 无 无

1. FN_PGY_MemberJoin（新的成员加入组网事件）
   {
   typedef void(*FN_PGY_MemberJoin)(PGY_GTOUP_MEMBER &member);
   }
   事件ID：CALLBACK_EVENT_MEMBER_JOIN

参数名称 参数类型 备注
member PGY_GTOUP_MEMBER& 组网成员基本信息

1. FN_PGY_MemberLeave（组网成员离开组网事件）
   {
   typedef void(*FN_PGY_MemberLeave)(PGY_GTOUP_MEMBER &member);
   }
   事件ID：CALLBACK_EVENT_MEMBER_LEAVE

参数名称 参数类型 备注
member PGY_GTOUP_MEMBER& 组网成员基本信息

1. FN_PGY_MemberChanged（组网中某个成员信息发生改变事件）
   {
   typedef void(*FN_PGY_MemberChanged)(PGY_GTOUP_MEMBER &member);
   }
   事件ID：CALLBACK_EVENT_MEMBER_CHANGED

参数名称 参数类型 备注
member PGY_GTOUP_MEMBER& 组网成员基本信息

1. FN_PGY_MemberListUpdate（组网成员列表更新事件）
   {
   typedef void(*FN_PGY_MemberListUpdate)();
   }
   事件ID：CALLBACK_EVENT_MEMBER_CHANGED

参数名称 参数类型 备注
无 无 无

1. FN_PGY_ConnectChanged（组网成员连接类型发生改变事件）
   {
   typedef void(*FN_PGY_ConnectChanged)(int group_id, int member_id, int connect_type);
   }
   事件ID：CALLBACK_EVENT_MEMBER_CONNECT_CHANGED

参数名称 参数类型 备注
group_id int 组网ID
member_id int 组网中的成员ID
connect_type int 组网中成员的网络连接类型

1. FN_PGY_GroupLeave（组网断开事件）
   {
   typedef void(*FN_PGY_GroupLeave)(int group_id, int err_no);
   }
   事件ID：CALLBACK_EVENT_GROUP_LEAVE

参数名称 参数类型 备注
group_id int 组网ID
err_no int 错误码

1. FN_PGY_GroupChanged（组网信息发生变化事件）
   {
   typedef void(*FN_PGY_GroupChanged)(PGY_GROUP &group);
   }
   事件ID：CALLBACK_EVENT_GROUP_CHANGED

参数名称 参数类型 备注
group PGY_GROUP& 组网基本信息

1. FN_PGY_SubscriberUnbindMobile（解绑手机号事件）
   {
   typedef void (*FN_PGY_SubscriberUnbindMobile)(void);
   }
   事件ID：CALLBACK_EVENT_SUBSCRIBE_UNBIND_MOBILE

参数名称 参数类型 备注
无 无 无

1. FN_PGY_SubscriberRestartBroadband（重启宽带加速服务事件）
   {
   typedef void(*FN_PGY_SubscriberRestartBroadband)(void);
   }
   事件ID：CALLBACK_EVENT_SUBSCRIBE_RESTART_BROADBAND

参数名称 参数类型 备注
无 无 无

1. FN_PGY_SubscriberBindMobile（绑定手机号事件）
   {
   typedef void(FN_PGY_SubscriberBindMobile)(const char lpstrMobile);
   事件ID：CALLBACK_EVENT_SUBSCRIBE_BIND_MOBILE

参数名称 参数类型 备注
lpstrMobile const char* 手机号码

1. FN_PGY_SubscriberMemoChanged（更改当前登录账号备注事件）
   {
   typedef void(FN_PGY_SubscriberMemoChanged)(const char lpstrMemo);
   }
   事件ID：CALLBACK_EVENT_SUBSCRIBE_MEMO_CHANGED

参数名称 参数类型 备注
lpstrMemo const char* 备注

1. FN_PGY_SubscriberReset（重置UID事件）
   {
   typedef void(*FN_PGY_SubscriberReset)(void);
   }
   事件ID：CALLBACK_EVENT_SUBSCRIBE_RESET

参数名称 参数类型 备注
无 无 无

1. FN_PGY_SubscriberPwdChanged（更改密码事件）
   {
   typedef void(*FN_PGY_SubscriberPwdChanged)(void);
   }
   事件ID：CALLBACK_EVENT_SUBSCRIBE_PWD_CHANGED

参数名称 参数类型 备注
无 无 无

1. FN_PGY_SubscriberNetworkNameChanged（更改组网名称事件）
   {
   typedef void(FN_PGY_SubscriberNetworkNameChanged)(const char lpstrNetworkName);
   }
   事件ID：CALLBACK_EVENT_SUBSCRIBE_NET_NAME_CHANGED

参数名称 参数类型 备注
lpstrNetworkName const char* 组网名称

1. FN_PGY_SubscriberServiceChanged（组网服务发生变化事件）
   {
   typedef void(*FN_PGY_SubscriberServiceChanged)(void);
   }
   事件ID：CALLBACK_EVENT_SUBSCRIBE_SERVICE_CHANGED

参数名称 参数类型 备注
无 无 无

1. 错误码
   错误ID 错误码 错误描述
   -1 ERR_PGY_UNKNOWN 未知错误
   0 ERR_PGY_OK 成功
   1 ERR_PGY_VNC_INIT_FAILS 虚拟网卡初始化失败
   101 ERR_PGY_LOGIN_NOT_SUPPORT_PROXY 不支持代理方式上网
   102 ERR_PGY_LOGIN_ACCOUNT_OUT_OF_DATE 服务已过期
   103 ERR_PGY_LOGIN_CHECK_LEVEL_ERROR 检查服务等级失败
   104 ERR_PGY_LOGIN_PASSWORD 账号或密码错误
   105 ERR_PGY_LOGIN_NET 网络错误
   106 ERR_PGY_LOGIN_ENOUGH_MEMBER 成员数不足
   107 ERR_PGY_LOGIN_DISABLED 账号被禁用
   108 ERR_PGY_LOGIN_MOBILE_UNBIND_VPNID 未绑定手机号
   109 ERR_PGY_LOGIN_NOT_HAVE_VERIFY_CODE 未获取验证码
   110 ERR_PGY_LOGIN_PENDING 正在处理中
   111 ERR_PGY_LOGIN_GROUP_INFO 组信息错误
   112 ERR_PGY_LOGIN_GROUP_CALL 调用刷新组信息时失败
   113 ERR_PGY_LOGIN_PACKAGE_TOKEN 获取定制版Token失败
   114 ERR_PGY_LOGIN_ROUTER_UNBIND 未绑定路由器
   115 ERR_PGY_LOGIN_MAC_NOT_MATCH MAC地址不匹配
   123 ERR_PGY_DISCONNECT_REASON_REPEAT UID在其他地方登录
   124 ERR_PGY_DISCONNECT_REASON_VERSION 当前版本不兼容
   125 ERR_PGY_DISCONNECT_REASON_TIMEOUT 网络超时
   126 ERR_PGY_DISCONNECT_REASON_CHANGE_PASSWD 密码发生变化
   127 ERR_PGY_DISCONNECT_REASON_CHANGE_CIRCUIT 网络线路发生变化
   128 ERR_PGY_DISCONNECT_REASON_CHANGE_SERVICE_LEVEL 服务等级发生变化
   129 ERR_PGY_DISCONNECT_REASON_SERVICE_EXPRIEDATE 服务已到期
2. 配置信息
   配置项 是否必须 默认值 描述
   PGY_CONFIG_SN 是 SN（注：仅路由器是必须的）
   PGY_CONFIG_API_SERVER 否 sdkapi.sdwan.oray.com API服务器地址
   PGY_CONFIG_VPN_SERVER 否 VPN服务器地址
   PGY_CONFIG_HTTPS 否 true 是否启用HTTPS
   PGY_CONFIG_LOG_PATH 否 log 日志文件存放路径
   PGY_CONFIG_LOG_SIZE 否 16M 日志文件的大小
   PGY_CONFIG_LOG_LEVEL 否 错误、警告、信息(0x7) 日志文件等级
   PGY_CONFIG_VNC_NAME 否 orayboxvpn/oray_vnc 虚拟网卡的名称
   PGY_CONFIG_VNC_NETMASK 否 255.255.255.255 虚拟网卡的掩码地址
   PGY_CONFIG_VNC_MTU 否 1200/1300 虚拟网卡的MTU值
   PGY_CONFIG_RECONN 否 true 是否自动重连
   PGY_CONFIG_STATUS_FILE 否 orayboxvpn_status 状态文件
   PGY_CONFIG_P2P_BINDADDR 否 P2P的出口网卡地址
   PGY_CONFIG_P2P_TRANS_RSA 否 false P2P传输数据时是否启用RSA加密
   PGY_CONDIG_POWER_LOGIN 否 false 开机自动登录(有账号和密码的情况)
   PGY_CONDIG_APPID 是 开发者账号
   PGY_CONDIG_APPSECRET 是 开发者key