Oray开放平台开发指引

1. 概述

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

2. 开发者帐号

    使用 PGYAPI 之前,你需要先拥有一个 Oray 帐户,可以通过https://www.oray.com的右上角的注册按钮进行注册。如图:

image

    拥有帐户后,进入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