6.5 事件监听

上面提到的都是同步接口，而事件监听接口将为您提供一种异步的状态监控方式。

事件监听接口包括两个，分别是注册事件监听器以及注销事件监听器。在使用事件监听之前，请确保您已正确调用初始化接口。

6.5.1 注册事件监听器

接口定义

typedef void (*atrust_event_listener)(atrust_event_type event, atrust_event_data data);

atrust_event_listener ATRUST_API atrust_regist_listener(atrust_event_listener listener);

参数和返回值说明

事件监听器通过atrust_event_listener回调函数进行事件通知。请确保您的listener回调函数正确，并在调用后面的atrust_clear_listener接口之前一直可用，否则在事件回调时可能导致崩溃。

在您的回调函数被执行时，您收到的atrust_event_type可能会有如下事件类型：

1. 用户被注销
2. 隧道状态变化
3. 升级相关
4. 资源诊断相关

根据不同的事件类型，atrust_event_data对应的实际数据类型也不一样。其中，用户被注销事件USER_LOGOUT（10001）以及隧道状态变化事件TUNNEL_STATUS（10002）关系到aTrust客户端的核心业务可用性。

1. 用户被注销

当您收到注销事件时，意味着当前已经登录的用户被执行了一次注销流程。该注销行为可能来自客户端，也有可能来自服务器，您可以根据注销类型来进行判断，还可以获取注销前的用户名和服务器地址。

这里需要特别注意的是，当您执行登录流程，并且选择了强制登录模式时，也有可能会收到注销事件，以及后续关联的【隧道状态变化事件】。因为强制登录流程中会注销调之前已经登录的用户，并触发相关动作。因此，建议您在执行强制登录流程之后，忽略掉该相关事件。

为了保险起见，这里不建议您在收到注销事件之后，就将您的用户状态直接设为注销。建议您在收到该类型事件后，调用【状态查询】接口atrust_sync_query_status查询状态，以最终确认。该建议对下面的【隧道状态变化事件】同样有效。

2. 隧道状态变化 隧道状态分为以下三种：

1. 隧道不可用
2. 隧道启动中
3. 隧道可用

当您的用户处于未登录状态时，隧道状态正常情况下会一直处于不可用状态。当您的用户登录之后，如果您的用户拥有隧道资源，则隧道状态会变为【隧道启动中】以及【隧道可用】。因为【隧道启动中】的状态可能很短暂，因此您的事件监听器可能收不到【隧道启动种】的状态变化通知。

另外，您可能会连续收到相同内容的隧道状态变化事件，比如连续收到两个【隧道不可用】事件。

3. 升级相关 在您登录之后，或在程序运行期间，aTrust客户端会检测您登录的服务器上是否有新的客户端版本下载，并通知您在SDK种注册的事件监听回调函数。您可以调用后续的【版本与升级】接口，或许直接忽略该事件。

在您执行升级指令，或您的客户端以其他方式升级的过程中，您还会收到其他的升级相关事件。

4. 资源诊断相关 资源诊断事件用来返回后续【资源诊断】接口的调用结果。该事件内容是JSON格式字符串的资源诊断递增结果，请在您确保了解相关信息的情况下关注并消费该事件。

示例代码

void event_handler(atrust_event_type event, atrust_event_data data) {
    // 事件监听器收到事件! 事件类型: event

    // 注意回调函数所在的线程

    switch (event) {
    case atrust_event_type::USER_LOGOUT:
        // 用户 data.data.logout.username 
        // 已从服务器 data.data.logout.sdpc 注销！
        // 注销类型：data.data.logout.type 
        // 描述: data.data.logout.typeDescribe

        // 注意，这里可能是强制登录时产生的注销事件，且收到注销事件的时间可能在强制登录成功之后。
        // 因此，如果希望利用该事件设置用户状态，请在收到该事件之后调用一次atrust_sync_query_status接口确保用户已经离线
        break;
    case atrust_event_type::TUNNEL_STATUS: 
        // 新的隧道状态：data.data.tunnel_status.tunnelStatus 
        // 描述 data.data.tunnel_status.tunnelStatusDescribe
        break;
    case atrust_event_type::SELECT_UPDATE_MODEL:
        // 检测到升级版本!升级类型：data.data.update_info.type
        // 版本：data.data.update_info.version
        // 定制码：data.data.update_info.custom_code
        // 定制版本号：data.data.update_info.custom_version
        break;
    case atrust_event_type::UPDATE_SUCCESS: 
        // 客户端升级成功！
        break;
    case atrust_event_type::UPDATE_FAIL: 
        // 客户端升级失败！
        break;
    case atrust_event_type::BEGIN_DOWNLOAD: 
        // 正在下载升级包...
        break;
    case atrust_event_type::END_DOWNLOAD: 
        // 升级包下载完毕！
        break;
    case atrust_event_type::BEGIN_INSTALL:
        // 正在安装客户端升级包...
        break;
    case atrust_event_type::END_INSTALL: 
        // 客户端升级包安装完成！
        break;
    case atrust_event_type::DIAGNOSIS_RESULT: {
        // 收到资源诊断结果！诊断任务ID：data.data.diagnosis_result.trace_id

        //是当前程序开始的资源诊断任务
        if (data.data.diagnosis_result.trace_id == m_LatestTraceId) {
            // 诊断进度及结果，注意编码方式以防乱码
            // std::string contentTranslate = Utf8ToGbk(data.data.diagnosis_result.content);
        }
        else {
            // 当前诊断任务ID非本程序最新启动的诊断任务ID！
        }
        break;
    }                         
    default:
        // 未知的事件类型！
    }
}

// ...

atrust_regist_listener(event_handler);

6.5.2 注销事件监听器

调用该接口后，您之前注册的事件监听回调函数将不再收到新的事件通知。 请确保在您的atrust_event_listener回调函数失效/析构之前，调用atrust_clear_listener接口，否则可能引发崩溃。

接口定义

atrust_event_listener ATRUST_API atrust_clear_listener();

参数和返回值说明

示例代码

atrust_clear_listener();