广播电台 HAL

下面几部分将介绍如何使用硬件抽象层 (HAL) 来实现广播电台。

广播电台 HAL 接口

广播电台 HAL 在硬件级别提供数据结构和接口，以实现 AM/FM 和 DAB 电台等广播电台功能。

HIDL 2.0 和 AIDL 接口

广播电台 HAL 使用下面几部分中介绍的接口。

IAnnouncementListener

IAnnouncementListener 是通知监听器的回调接口，可以在广播电台 HAL 上注册此监听器，以便接收通知。该接口使用以下方法：

IAnnouncementListener
说明：每当通知列表发生变化时会被调用。
	HIDL 2.0	`oneway onListUpdated(vec<Announcement> announcements)`
	AIDL	`oneway void onListUpdated(in Announcement[] announcements)`

ICloseHandle

ICloseHandle 是通用关闭句柄，可移除不需要活跃接口的回调。

ICloseHandle
说明：关闭手柄。
	HIDL 2.0	`close()`
	AIDL	`void close()`

ITunerCallback

ITunerCallback 是广播电台 HAL 调用的回调接口，用于向 HAL 客户端服务发送更新。

ITunerCallback
说明：当调谐操作（调谐、搜寻 [使用 AIDL]/扫描 [使用 HIDL] 以及步进成功时）异步失败时，由 HAL 调用。
	HIDL 2.0	`oneway onCurrentProgramInfoChanged(ProgramInfo info)`
	AIDL	`void onCurrentProgramInfoChanged(in ProgramInfo info)`
说明：会在调谐、搜寻（使用 AIDL）/扫描（使用 HIDL）或步进成功时调用。
	HIDL 2.0	`oneway onTuneFailed(Result result, ProgramSelector selector)`
	AIDL	`void onTuneFailed(in Result result, in ProgramSelector selector)`
说明：会在调谐、搜寻（使用 AIDL）/扫描（使用 HIDL）或步进成功时调用。
	HIDL 2.0	`oneway onCurrentProgramInfoChanged(ProgramInfo info)`
	AIDL	`void onCurrentProgramInfoChanged(in ProgramInfo info)`
说明：会在节目列表更新时调用；每个分块的大小不得超过 500kiB。
	HIDL 2.0	`oneway onProgramListUpdated(ProgramListChunk chunk)`
	AIDL	`oneway onProgramListUpdated(ProgramListChunk chunk)`
说明：会在天线连接或断开连接时调用。
	HIDL 2.0	`oneway onAntennaStateChange(bool connected)`
	AIDL	`void onCurrentProgramInfoChanged(in ProgramInfo info)`
说明：会在 HAL 内部更新供应商特定参数值时调用（不应在 HAL 客户端调用 `setParameters` 之后再调用）。
	HIDL 2.0	`oneway onParametersUpdated(vec<VendorKeyValue> parameters)`
	AIDL	`void onParametersUpdated(in VendorKeyValue[] parameters)`
说明：AIDL 中的新功能。会在 HAL 内部更新配置标志时调用（不应在 HAL 客户端调用 `setConfigFlag` 之后再调用）。
	HIDL 2.0	不适用。
	AIDL	`void onConfigFlagUpdated(in ConfigFlag flag, in boolean value)`

IBroadcastRadio

IBroadcastRadio 是广播电台 HAL 的主要接口。在 HIDL 2.0 HAL 中，使用调谐器的 ITunerSession 接口来调用操作。不过，一次最多只有一个调谐器处于活跃状态（前提是每个广播电台 HAL 实例只有一个调谐器芯片）。系统从 AIDL 接口中移除了 ITunerSession，并将其接口移到了 IBroadcastRadio。

IBroadcastRadio
说明：获取模块及其功能的说明。
	HIDL 2.0	`getProperties() generates (Properties properties)`
	AIDL	`Properties getProperties()`
说明：提取当前或可能的 AM/FM 区域配置。
	HIDL 2.0	`getAmFmRegionConfig(bool full) generates (Result result, AmFmRegionConfig config)`
	AIDL	`AmFmRegionConfig getAmFmRegionConfig(bool full)`
说明：提取当前的 DAB 区域配置。
	HIDL 2.0	`getDabRegionConfig() generates (Result result, vec<DabTableEntry> config)`
	AIDL	`DabTableEntry[] getDabRegionConfig()`
说明：从电台模块缓存中获取图片。在 AIDL 中，由于 binder 事务缓冲区存在硬性上限，因此图片大小必须小于 1MB。
	HIDL 2.0	`getImage(uint32_t id) generates (vec<uint8_t> image)`
	AIDL	`byte[] getImage(in int id)`
说明：注册通知监听器。
	HIDL 2.0	`registerAnnouncementListener(vec<AnnouncementType> enabled,IAnnouncementListener listener) generates (Result result, ICloseHandle closeHandle)`
	AIDL	`ICloseHandle registerAnnouncementListener(in IAnnouncementListener listener, in AnnouncementType[] enabled)`
说明： HIDL HAL：打开新的调谐器会话时，必须终止旧的会话。 AIDL HAL：由于没有可用的调谐器会话，因此只需设置调谐器回调。如果调谐器回调已存在，则应取消设置旧回调。
	HIDL 2.0	`openSession(ITunerCallback callback)` 生成 `(Result result, ITunerSession session)`
	AIDL	`void setTunerCallback(in ITunerCallback callback)`
说明： HIDL HAL：关闭调谐器会话不得失败，并且只能发出一次该命令。 AIDL HAL：没有调谐器，只需要取消设置调谐器回调。
	HIDL 2.0	`close()`
	AIDL	`unsetTunerCallback()`
说明：调谐到指定的节目。
	HIDL 2.0	`tune(ProgramSelector program) generates (Result result)`
	AIDL	`void tune(in ProgramSelector program)`
说明：寻找下一个在播送中的有效节目。为避免在 AIDL 中产生混淆，`scan` 已重命名为 `seek`。
	HIDL 2.0	`scan(bool directionUp, bool skipSubChannel) generates (Result result)`
	AIDL	`void seek(in boolean directionUp, in boolean skipSubChannel)`
说明：步进到相邻的频道，此频道可能未被任何节目占用。
	HIDL 2.0	`step(bool directionUp) generates (Result result)`
	AIDL	`void step(in boolean directionUp)`
说明：取消待处理的调谐、扫描（使用 HIDL）/搜寻（使用 AIDL）或步进操作。
	HIDL 2.0	`cancel()`
	AIDL	`void cancel()`
说明：对节目列表应用过滤条件，并开始通过 `onProgramListUpdated` 回调发送节目列表更新。
	HIDL 2.0	`startProgramListUpdates(ProgramFilter filter) generates (Result result)`
	AIDL	`void startProgramListUpdates(in ProgramFilter filter)`
说明：停止发送节目列表更新。
	HIDL 2.0	`stopProgramListUpdates()`
	AIDL	`void stopProgramListUpdates()`
说明：提取给定配置标志的当前设置。
	HIDL 2.0	`isConfigFlagSet(ConfigFlag flag) generates (Result result, bool value)`
	AIDL	`boolean isConfigFlagSet(in ConfigFlag flag)`
说明：设置给定配置标志。
	HIDL 2.0	`setConfigFlag(ConfigFlag flag, bool value) generates (Result result)`
	AIDL	`void setConfigFlag(in ConfigFlag flag, boolean value)`
说明：设置供应商特定的参数值。
	HIDL 2.0	`setParameters(vec<VendorKeyValue> parameters)` 生成， `(vec<VendorKeyValue> results)`
	AIDL	`VendorKeyValue[] setParameters(in VendorKeyValue[] parameters)`
说明：检索供应商特定的参数值。
	HIDL 2.0	`getParameters(vec<string> keys) generates (vec<VendorKeyValue> parameters)`
	AIDL	`VendorKeyValue[] getParameters(in String[] keys)`

接口说明

异步行为

由于每个调谐操作（例如调谐、扫描 [使用 HIDL]/搜寻 [使用 AIDL] 或步进）都可能非常耗时，并且不应长时间阻塞线程，因此操作流程应将耗时的操作安排在稍后执行，并快速返回状态或结果。详细来说，每个操作应该：

取消所有待处理的调谐操作。
检查是否可以根据方法输入和调谐器状态处理操作。
安排调谐任务，然后立即返回 Result（使用 HIDL）或 status（使用 AIDL）。如果 Result 或 status 为 OK，则在调谐任务失败（例如由于超时）或完成时必须调用调谐器回调 tuneFailed 或 currentProgramInfoChanged。

同样，startProgramListUpdates 还会安排更新节目列表这项比较耗时的任务在稍后完成，并快速返回状态或结果。该方法会先取消待处理的更新请求，然后安排更新任务并快速返回结果。

竞态条件

由于调谐操作（例如调谐、扫描 [使用 HIDL]/搜寻 [使用 AIDL] 和步进）的异步行为，取消操作和调谐操作之间存在竞态条件。如果在 HAL 完成调谐操作之后、回调完成之前调用 cancel，则可以忽略取消操作，且相应回调应完成并由 HAL 客户端接收。

同样，如果在 HAL 完成节目列表更新后、onCurrentProgramInfoChanged 回调完成之前调用 stopProgramListUpdates，则可以忽略 stopProgramListUpdates，且相应回调应完成。

数据大小限制

由于 binder 事务缓冲区存在硬性限制，因此 AIDL HAL 中会说明传递可能较大的数据时某些接口方法的数据限制。

getImage 要求返回的图片小于 1MB。
onProgramListUpdate 要求每个 chunk 小于 500kiB。较大的节目列表必须由 HAL 实现拆分为多个分块，并通过多个回调发送。

AIDL HAL 数据结构的变更

除了接口的变更之外，这些变更已被应用于广播电台 AIDL HAL 中定义的数据结构，该数据结构利用了 AIDL。

Constant 枚举已从 AIDL 中移除，并已在 IBroadcastRadio 中定义为常量整数。同时，ANTENNA_DISCONNECTED_TIMEOUT_MS 已重命名为 ANTENNA_STATE_CHANGE_TIMEOUT_MS。系统新增了一个常量整数 TUNER_TIMEOUT_MS。所有调谐、搜寻和步进操作都必须在这段时间内完成。
枚举 RDS 和 Deemphasis 已从 AIDL 中移除，并已在 AmFmRegionConfig 中定义为常量整数。相应地，ProgramInfo 中的 fmDeemphasis 和 fmRds 会声明为整数，这是相应标志的位计算结果。同时，D50 和 D75 已分别重命名为 DEEMPHASIS_D50 和 DEEMPHASIS_D75。
枚举 ProgramInfoFlags 已从 AIDL 中移除，并已在 ProgramInfo 中定义为常量整数，同时添加了前缀 FLAG_。相应地，ProgramInfo 中的 infoFlags 会声明为整数，这是标志的位计算结果。TUNED 也已重命名为 FLAG_TUNABLE，以更好地描述其定义，即电台可调谐的范围。
因为在 AIDL 中，scan 已重命名为 seek，所以在 AmFmBandRange 中，scanSpacing 已重命名为 seekSpacing。
由于 AIDL 中引入了并集的概念，因此系统不再使用 HIDL HAL 中定义的 MetadataKey 和 Metadata。AIDL HAL 中定义了 AIDL 并集 Metadata。之前在 MetadataKey 中的每个枚举值现在都是 Metadata 中的字段，其类型为字符串或整数，具体取决于其定义。