3. HIDL 接口定义实战：定义 .hal 文件、package 声明、数据类型、方法定义

在 Treble 架构中，HIDL（HAL Interface Definition Language）是连接 Framework 与 Vendor HAL 的核心契约语言。本章通过实战方式，系统讲解如何编写一个完整的 .hal 接口文件，涵盖包声明、数据类型选择与方法定义规范。掌握这些基础，是后续进行接口测试验证的前提。

3.1 .hal 文件结构与包声明

每个 HIDL 接口文件以 .hal 为后缀，文件路径必须与包名严格对应。包名遵循反向域名风格，并包含版本号。

包声明规则：

• 格式：package <vendor>.<subsystem>.<module>@<major>.<minor>;
• 版本号必须与文件所在目录的版本子目录一致。
• 一个包可以包含多个 .hal 文件，但每个文件只能声明一个包。

示例：IHealth.hal 文件结构

// 文件路径：hardware/interfaces/health/2.0/IHealth.hal
package android.hardware.health@2.0;

import android.hardware.health@2.0::types;

interface IHealth {
    // 方法定义将在后续小节展开
};

3.2 数据类型定义与使用

HIDL 支持多种数据类型，包括基础类型、枚举、结构体、联合体以及集合类型。合理选择数据类型直接影响接口的跨进程传输效率与可测试性。

常用数据类型一览表：

实战：在 types.hal 中定义健康状态枚举与结构体

// 文件路径：hardware/interfaces/health/2.0/types.hal
package android.hardware.health@2.0;

enum HealthStatus : int32_t {
    GOOD = 0,
    OVERHEAT = 1,
    COLD = 2,
    CRITICAL = 3,
    UNKNOWN = 4
};

struct HealthInfo {
    float batteryTemperature;       // 电池温度，单位摄氏度
    int32_t batteryLevel;           // 电池电量百分比 0-100
    HealthStatus currentStatus;     // 当前健康状态
    bool isCharging;                // 是否正在充电
};

3.3 方法定义与回调机制

HIDL 接口方法支持同步调用与单向调用（oneway），同时可以通过回调接口（callback）实现异步通知。方法定义需要明确参数方向（in / out / inout）以及返回值类型。

方法定义语法：

interface IHealth {
    // 同步方法：返回 HealthInfo 结构体
    getHealthInfo() generates (HealthInfo info);

    // 单向方法：设置阈值，不等待返回
    oneway setTemperatureThreshold(float threshold);

    // 回调注册：客户端传入回调接口，服务端在状态变化时调用
    registerCallback(IHealthCallback callback) generates (bool success);
};

// 回调接口定义
interface IHealthCallback {
    oneway onHealthStatusChanged(HealthStatus newStatus);
};

参数方向说明：

3.4 完整 IHealth 接口实战

综合以上知识点，下面给出完整的 IHealth 接口定义，包含类型导入、方法声明与回调接口。该定义将作为后续测试验证的基准接口。

// ============================================
// 文件：hardware/interfaces/health/2.0/types.hal
// ============================================
package android.hardware.health@2.0;

enum HealthStatus : int32_t {
    GOOD = 0,
    OVERHEAT = 1,
    COLD = 2,
    CRITICAL = 3,
    UNKNOWN = 4
};

struct HealthInfo {
    float batteryTemperature;
    int32_t batteryLevel;
    HealthStatus currentStatus;
    bool isCharging;
};

// ============================================
// 文件：hardware/interfaces/health/2.0/IHealthCallback.hal
// ============================================
package android.hardware.health@2.0;

interface IHealthCallback {
    oneway onHealthStatusChanged(HealthStatus newStatus);
    oneway onTemperatureAlert(float temperature);
};

// ============================================
// 文件：hardware/interfaces/health/2.0/IHealth.hal
// ============================================
package android.hardware.health@2.0;

import android.hardware.health@2.0::types;
import android.hardware.health@2.0::IHealthCallback;

interface IHealth {
    // 获取当前健康信息
    getHealthInfo() generates (HealthInfo info);

    // 设置温度告警阈值
    oneway setTemperatureThreshold(float threshold);

    // 注册回调，返回是否成功
    registerCallback(IHealthCallback callback) generates (bool success);

    // 注销回调
    unregisterCallback(IHealthCallback callback) generates (bool success);
};

3.5 接口定义常见错误与避坑

在实际开发中，接口定义阶段的错误往往在测试阶段才暴露。以下列出高频问题及解决方案：