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. 使用规范

1. 目录结构

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

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

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

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

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

2. 驱动安装

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

3. 具体使用

    1. 配置开发者帐号信息：使用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 详细说明

---

1. 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. 事件监听接口

1. 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