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

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

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

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

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

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

5. 使用规范

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

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

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

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

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

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

12. 具体使用

13. 配置开发者账号信息：使用PGY_SetConfig去配置开发者信息

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

} 2. 注册回调监听：使用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);// 组信息发生
更改

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

{ PGY_OpenLog(NULL, NULL);

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

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

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

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

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

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

返回：是否设置成功

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

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

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

返回：是否设置成功

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

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

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

返回：是否设置成功

4. PGY_ShowConfig 原型：void PGY_ShowConfig();

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

参数：无

返回：无

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

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

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

返回：无

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

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

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

返回：无

7. 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 事件

8. PGY_Logout 原型：void PGY_Logout();

功能：注销登录

参数：无

返回：无

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

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

功能：获取组网成员列表

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

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

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

功能：获取组网信息

参数：stGroup PGY_GROUP& 接收组信息

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

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

功能：读取订阅消息

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

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

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

功能：读取推送的消息

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

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

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

功能：推送订阅消息

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

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

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

功能：设置强制转发

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

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

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

功能：获取强制转发列表

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

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

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

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

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

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

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

功能：打印调试信息

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

返回：无

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

功能：故障诊断

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

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

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

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

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

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

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

} 事件ID：CALLBACK_EVENT_VNC_LOADIND

参数名称 参数类型 备注 err_no int 错误码 2. FN_PGY_Connect（组网连接成功事件） { typedef void(*FN_PGY_Connect)();

} 事件IDCALLBACK_EVENT_CONNECT

参数名称 参数类型 备注 无 无 无 3. FN_PGY_Disconnect（组网连接断开事件） { typedef void(*FN_PGY_Disconnect)(int err_no); } ????事件ID：CALLBACK_EVENT_DISCONNECT

参数名称 参数类型 备注 err_no int 错误码 4. 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* 错误信息 5. FN_PGY_Logout（注销登录事件） { typedef void(*FN_PGY_Logout)();

} 事件ID：CALLBACK_EVENT_LOGOUT

参数名称 参数类型 备注 无 无 无 6. FN_PGY_MemberJoin（新的成员加入组网事件） { typedef void(*FN_PGY_MemberJoin)(PGY_GTOUP_MEMBER &member); } 事件ID：CALLBACK_EVENT_MEMBER_JOIN

参数名称 参数类型 备注 member PGY_GTOUP_MEMBER& 组网成员基本信息 7. FN_PGY_MemberLeave（组网成员离开组网事件） { typedef void(*FN_PGY_MemberLeave)(PGY_GTOUP_MEMBER &member); } 事件ID：CALLBACK_EVENT_MEMBER_LEAVE

参数名称 参数类型 备注 member PGY_GTOUP_MEMBER& 组网成员基本信息 8. FN_PGY_MemberChanged（组网中某个成员信息发生改变事件） { typedef void(*FN_PGY_MemberChanged)(PGY_GTOUP_MEMBER &member); } 事件ID：CALLBACK_EVENT_MEMBER_CHANGED

参数名称 参数类型 备注 member PGY_GTOUP_MEMBER& 组网成员基本信息 9. FN_PGY_MemberListUpdate（组网成员列表更新事件） { typedef void(*FN_PGY_MemberListUpdate)(); } 事件ID：CALLBACK_EVENT_MEMBER_CHANGED

参数名称 参数类型 备注 无 无 无 10. 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 组网中成员的网络连接类型 11. 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 错误码 12. FN_PGY_GroupChanged（组网信息发生变化事件） { typedef void(*FN_PGY_GroupChanged)(PGY_GROUP &group); } 事件ID：CALLBACK_EVENT_GROUP_CHANGED

参数名称 参数类型 备注 group PGY_GROUP& 组网基本信息 13. FN_PGY_SubscriberUnbindMobile（解绑手机号事件） { typedef void (*FN_PGY_SubscriberUnbindMobile)(void); } 事件ID：CALLBACK_EVENT_SUBSCRIBE_UNBIND_MOBILE

参数名称 参数类型 备注 无 无 无 14. FN_PGY_SubscriberRestartBroadband（重启宽带加速服务事件） { typedef void(*FN_PGY_SubscriberRestartBroadband)(void); } 事件ID：CALLBACK_EVENT_SUBSCRIBE_RESTART_BROADBAND

参数名称 参数类型 备注 无 无 无 15. FN_PGY_SubscriberBindMobile（绑定手机号事件） { typedef void(FN_PGY_SubscriberBindMobile)(const char lpstrMobile); 事件ID：CALLBACK_EVENT_SUBSCRIBE_BIND_MOBILE

参数名称 参数类型 备注 lpstrMobile const char* 手机号码 16. FN_PGY_SubscriberMemoChanged（更改当前登录账号备注事件） { typedef void(FN_PGY_SubscriberMemoChanged)(const char lpstrMemo); } 事件ID：CALLBACK_EVENT_SUBSCRIBE_MEMO_CHANGED

参数名称 参数类型 备注 lpstrMemo const char* 备注 17. FN_PGY_SubscriberReset（重置UID事件） { typedef void(*FN_PGY_SubscriberReset)(void); } 事件ID：CALLBACK_EVENT_SUBSCRIBE_RESET

参数名称 参数类型 备注 无 无 无 18. FN_PGY_SubscriberPwdChanged（更改密码事件） { typedef void(*FN_PGY_SubscriberPwdChanged)(void); } 事件ID：CALLBACK_EVENT_SUBSCRIBE_PWD_CHANGED

参数名称 参数类型 备注 无 无 无 19. FN_PGY_SubscriberNetworkNameChanged（更改组网名称事件） { typedef void(FN_PGY_SubscriberNetworkNameChanged)(const char lpstrNetworkName); } 事件ID：CALLBACK_EVENT_SUBSCRIBE_NET_NAME_CHANGED

参数名称 参数类型 备注 lpstrNetworkName const char* 组网名称 20. FN_PGY_SubscriberServiceChanged（组网服务发生变化事件） { typedef void(*FN_PGY_SubscriberServiceChanged)(void); } 事件ID：CALLBACK_EVENT_SUBSCRIBE_SERVICE_CHANGED

参数名称 参数类型 备注 无 无 无 8. 错误码 错误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 服务已到期 9. 配置信息 配置项 是否必须 默认值 描述 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