统信uos开发登录认证锁屏插件api详解

环境配置

安装开发包 dde-session-shell-dev，安装完成后在 /usr/include/dde-session-shell/ 路径会有四个插件相关的头文件：

• base_module_interface.h
• login_module_interface.h
• login_module_interface_v2.h
• tray_module_interface.h

开发时使用 login_module_interface_v2.h 即可，有更完备的接口和功能。

认证插件需要使用 Qt 框架，根据实际需求搭建 Qt 开发环境即可，这里不再赘述。

数据结构说明

下面是开发认证插件时可能会用到的数据结构，可以在开发时作为工具文档使用。

enum ModuleType

说明： 插件类型

枚举值	字段	说明	备注
0	LoginType	认证插件	认证插件默认使用此字段
1	TrayType	托盘插件	展示在登录器右下方控制区域的插件（例如网络，认证插件不用关注这个类型）

---

struct AuthCallbackData

说明： 认证插件需要传回的数据

字段	数据类型	说明	必填	备注
result	int	认证结果	是	1 成功，其他失败
account	string	账户	否	用户账号
token	string	通行令牌	否	用户密码等
message	string	提示消息	否
json	string	冗余字段	否	暂时没有使用

---

struct LoginCallBack

说明： 回调函数以及登录器的回传指针

字段	类型	说明	备注
app_data	void*	登录器的回传指针	插件无需关注，只需在回调函数中传入即可
authCallbackFun	AuthCallbackFun	认证回调函数	用于认证完成后通知登录器
messageCallbackFunc 2.0.0以后	MessageCallbackFun	消息回调函数	用于主动与登录器交互

---

enum AppType

说明： 发起认证的应用类型

枚举值	字段	说明	备注
0	None	异常值	如果为 None 则说明出现异常
1	Login	登录	二进制文件为：/usr/bin/lightdm-deepin-greeter
2	Lock	锁屏	二进制文件为：/usr/bin/dde-lock

---

enum LoadType

说明： 模块加载的类型

枚举值	字段	说明
0	Load	加载插件
1	NotLoad	不加载插件

---

enum AuthObjectType

说明： 模块加载的类型

枚举值	字段	说明
0	LightDM	显示管理器
1	DeepinAuthenticate	不加载插件

---

enum AuthType

说明： 认证类型

枚举值	字段	说明
0	AT_None	默认
1 << 0	AT_Password	密码
1 << 1	AT_Fingerprint	指纹
1 << 2	AT_Face	人脸
1 << 3	AT_ActiveDirectory	AD 域
1 << 4	AT_Ukey	UKey
1 << 5	AT_FingerVein	指静脉
1 << 6	AT_Iris	虹膜
1 << 7	AT_PIN	PIN
1 << 29	AT_PAM	PAM
1 << 30	AT_Custom	自定义
-1	AT_All	ALL

---

enum AuthState

说明： 认证状态

枚举值	字段	说明	备注
-1	AS_None	默认
0	AS_Success	成功	此次认证的最终结果
1	AS_Failure	失败	此次认证的最终结果
2	AS_Cancel	取消	当认证没有给出最终结果时，调用 End 会出发 Cancel 信号
3	AS_Timeout	超时	一些认证设备会有超时状态的设定
4	AS_Error	错误
5	AS_Verify	验证中
6	AS_Exception	设备异常	当前认证会被 End
7	AS_Prompt	设备提示
8	AS_Started	认证已启动	调用 Start 之后，每种成功开启都会发送此信号
9	AS_Ended	认证已结束	调用 End 之后，每种成功关闭的都会发送此信号，当某种认证类型被锁定时，也会触发此信号
10	AS_Locked	认证已锁定	认证类型已锁定，表示认证类型不可用（从安全角度考虑，失败次数过多时会导致这种情况）
11	AS_Recover	设备恢复	需要调用 Start 重新开启认证，对应 AS_Exception
12	AS_Unlocked	认证解锁	认证类型解除锁定，表示可以继续继续使用此认证类型开始认证了

接口说明

在开发认证插件时需要以 public 方式继承LoginModuleInterfaceV2，并实现以下接口。

BaseModuleInterface

---

virtual ModuleType type() const = 0

说明： 插件的类型。

返回值：

类型	说明	备注
ModuleType	插件的类型	认证插件必须返回 LoginType

注意: LoginModuleInterface 已经实现了这个函数，默认返回 LoginType

---

virtual void init() = 0  必须实现 

说明： 界面相关的初始化，插件在非主线程加载，故界面相关的初始化需要放在这个方法里，由主程序调用并初始化。

---

virtual QString key() const = 0  必须实现 

说明： 唯一值，用于与其它模块区分。

返回值：

类型	说明	备注
string	唯一编码	传入与项目相关的命名即可

---

virtual QString icon() const

说明：
当认证因子不止一种时，登录器会显示认证类型切换组件，它是由一个按钮组（Button Group）组成的，此函数返回的图标会展示在“认证插件切换按钮”上面。

返回值：

类型	说明	备注
string	认证插件的图标	可以返回图标的绝对路径（加载方式为 QIcon(“absolute path”)），也可以返回系统图标的名称(加载方式为 QIcon::fromTheme(“system icon name”))。

---

virtual QWidget* content() const = 0  必须实现 

说明：
登录器会将返回的 QWidget* 内容展示出来，可以展示提示信息或者二维码等，具体内容插件可以自由设计。需要注意的是，登录器的展示的版面有限，高度最好不要超过 500 像素，宽度不超过 900 像素。

返回值：

类型	说明	备注
QWidget*	插件想要显示的窗口指针	由登录器托管，插件不要释放这个指针

---

`virtual LoadType loadPluginType() const  必须实现 ， 1.1.0新增 

说明：
登录器在加载插件的时候会调用这个接口，如果返回 Load，那么登录会加载插件，返回其它则不会加载插件。 非全平台或全架构的插件需要重新实现这个接口，根据实际情况处理。

返回值：

类型	说明
LoadType	见 LoadType的说明

---

virtual LoadType setAppdata(void*) const  2.0.0新增 

说明：
设置登录器的回调指针，插件需要保存指针，在使用回调函数的时候回传给登录器。如果要使用回调函数，则必须实现此函数。
函数可能会被重复调用，插件只需要保证回传的时候是最后一次设置的即可。

类型	说明
void*	-

---

virtual void setMessageCallback(MessageCallbackFunc *) = 0

说明： 设置回调函数，会在 init 函数之前调用。

参数：

类型	说明
MessageCallbackFunc*	详见 MessageCallbackFunc类型说明

---

QString (*)(const QString &, void *)

说明：
消息回调函数，用于向登录器发起通讯的场景

参数：

类型	说明	备注
string	发送给登录器的 json 格式数据	json 数据的具体内容详见下面数据协议部分
void*	即 LoginCallBack 的 app_data 字段

返回值：

类型	说明
string	发送给登录器的 json 格式数据

数据协议：

默认返回的数据:

字段	类型	说明
Code	int	0 成功，其他失败
Message	string	提示消息

例：

{
  "Code": 0,
  "Message": "Success"
}

1. 获取属性

请求：

字段	类型	值	说明
CmdType	string	"GetProperties"
Data	array	["AppType","CurrentUser"]	[值]列中展示的是目前支持的值,传入其它值无效。<br>根据 api 版本号来判断支持哪些字段：<br>since api-2.0.0 ("AppType", "CurrentUser")

例：

{
  "CmdType": "GetProperties",
  "Data": ["AppType", "CurrentUser"]
}

返回值：

字段	类型	说明
Code	int	0 成功，其他失败
Message	string	提示消息
Data	object	-
Data.AppType	int	详见 AppType 枚举说明
Data.CurrentUser	object	当前用户信息
Data.CurrentUser.Name	string	当前用户的用户名

例：

{
  "Code": 0,
  "Message": "Success",
  "Data": {
    "AppType": 2,
    "CurrentUser": {
      "Name": "uos"
    }
  }
}

---

virtual QString message(const QString &)  2.0.0新增 

说明：
登录器主动向认证插件发起通讯，一般用于获取插件信息或者给插件提供信息，入参和返回值都是 json 格式的字符串。

参数：

类型	说明
QString	json 格式字符串

返回值：

类型	说明
QString	json 格式字符串

数据协议：

默认返回的数据:

字段	类型	说明
Code	int	0 成功，其他失败
Message	string	提示消息

例：

{
  "Code": 0,
  "Message": "Success"
}

1. 用户发生变化 (CurrentUserChanged)
   说明：程序启动或者切换用户的时候登录器会主动发送此消息，告知认证插件当前正在认证的用户是谁。

请求：

字段	类型	值	说明
CmdType	string	CurrentUserChanged
Data	object	-
Data.Name	string	-	当前用户的用户名

示例：

{
  "CmdType": "CurrentUserChanged",
  "Data": {
    "Name": "uos"
  }
}

返回值：默认数据。

2. 获取配置 (GetConfigs)
   支持认证插件来控制登录器其它的 UI 控件。

请求：

字段	类型	值
CmdType	string	“GetConfigs”

示例：

{
  "CmdType": "GetConfigs"
}

返回值：

字段	类型	必填项	说明
Code	int	否	0 成功，其他失败
Message	string	否	提示消息
Data	object	是
Data.ShowAvatar	bool	否	是否显示用户头像
Data.ShowUserName	bool	否	是否显示用户名
Data.ShowSwitchButton	bool	否	是否显示认证类型切换按钮
Data.ShowLockButton	bool	否	是否显示解锁按钮
Data.DefaultAuthLevel	int	否	0：如果获取到上次认证成功的类型，则默认使用上次登录成功的类型，否则根据系统默认的顺序来选择。<br>1：如果获取到上次认证成功的类型，则默认使用上次登录成功的类型，否则使用插件认证。<br>2：无论是否可以获取到上次认证成功的类型，都默认选择插件验证。<br>默认为 1
Data.SupportDefaultUser	bool	否	插件是否支持默认用户的登录。默认用户：即当前没有指定用户，默认用户为"..."，一般在域管和服务器环境下会出现。<br>支持的场景：用户在登录界面扫描二维码，认证成功后插件得知是扫码人员的身份，与系统中的人员进行比对，将人员身份和认证结果返回给登录器，登录器可以登录此用户。<br>不支持的场景：必须先知道当前验证人员的身份，才能进行验证。<br>插件不处理此接口，则默认为支持。

示例：

{
  "Code": 0,
  "Message": "Success",
  "Data": {
    "ShowAvatar": true,
    "ShowUserName": true,
    "ShowSwitchButton": true,
    "ShowLockButton": false,
    "DefaultAuthLevel": 1
  }
}

3. 认证开始（StartAuth）
   登陆界面会有两次开启验证，一次是 deepin-authenticate 服务，还有一次是 lightdm，插件需要等到这两个验证都开启后再发送验证结果。
   锁屏界面只有 deepin-authenticate 会发起一次验证，插件需要等 deepin-authenticate 开启验证后再发送验证结果。
   这两种验证类型都会在插件加载后的很短的一段时间后开启验证（1s 以内），主要是处理指纹一键登录的需求。如果插件发送验证结果的时间较晚（比如扫码、输入验证码等）则无需关心此消息。

请求：

字段	类型	值	说明
CmdType	string	StartAuth
Data	object
Data.AuthObjectType	int		见 AuthObjectType的说明

示例：

{
  "CmdType": "StartAuth",
  "Data": {
    "AuthObjectType": 1
  }
}

返回值：默认数据。

4. 认证状态（AuthState）
   当前登录器的认证状态

请求：

字段	类型	值	说明
CmdType	string	"AuthState"
Data	object
Data.AuthType	int		见 AuthType的说明
Data.AuthState	int		见 AuthState的说明

示例：

{
    "CmdType": "AuthState",
    "Data": {
       "AuthType": 1，
       "AuthState": 0

    }
}

返回值：默认数据。

5. 限制信息（LimitsInfo）
   所有认证类型的限制信息

请求：

字段	类型	值	说明
CmdType	string	"LimitsInfo"
Data	array
Object.Flag	int		认证类型，见 AuthType
Object.Locked	bool		是否锁定
Object.MaxTries	int		可尝试的次数
Object.NumFailures	int		已错误次数
Object.UnlockSecs	int		还剩多久解锁
Object.UnlockTime	string		解锁时间

示例：

{
  "CmdType": "LimitsInfo",
  "Data": [
    {
      "Flag": 1,
      "Locked": false,
      "MaxTries": 5,
      "NumFailures": 0,
      "UnlockSecs": 0,
      "UnlockTime": "0001-01-01T00:00:00Z"
    },
    {
      "Flag": 2,
      "Locked": false,
      "MaxTries": 3,
      "NumFailures": 0,
      "UnlockSecs": -1,
      "UnlockTime": "0001-01-01T00:00:00Z"
    }
  ]
}

返回值：默认数据。

6. 是否启用插件
   登录器在开始验证的时候会向插件发起此请求，插件自行决定现在是否要启用插件，登录器默认插件是启用的。

请求：

字段	类型	值
CmdType	string	"IsPluginEnabled"

示例：

{
  "CmdType": "IsPluginEnabled"
}

返回值：

字段	类型	必填项	说明
Code	int	否	0 成功，其他失败
Message	string	否	提示消息
Data	bool	是	默认为 true

示例：

{
  "Code": 0,
  "Message": "Success",
  "Data": {
    "IsPluginEnabled": true
  }
}

LoginModuleInterfaceV2

---

virtual void setAuthCallback(AuthCallbackFunc *) = 0  必须实现 ,  2.0.0新增 

说明： 设置回调函数，会在init函数之前调用。

参数：

类型	说明
AuthCallbackFunc*	详见 AuthCallbackFunc类型说明

---

void (*)(const AuthCallbackData *, void *)

说明： 认证回调函数，用于插件返回认证的状态、结果等

参数：

类型	说明
AuthCallbackData*	认证相关信息
void*	即 LoginCallBack 的 app_data 字段

---

virtual void reset() = 0  必须实现 ,  2.0.0新增 

说明：
插件需要在这个方法中重置UI和验证状态，通常验证开始之前登录器会调用这个方法，但是不保证每次验证前都会调用。插件必须实现这个函数，并在函数内重置之前的验证结果，避免将以前的结果应用在当前认证中。

初始化接口调用

认证插件初始化时接口调用顺序如下：