以下各節將說明如何使用硬體抽象層 (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 中為 tune、seek 或 scan，在 HIDL 中為 step) 非同步失敗時，由 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) |
|
| 說明：在更新節目清單時呼叫；每個區塊的大小應限制為 500 KB。 | ||
| 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 例項只有一個調諧器晶片)。ITunerSession 已從 AIDL 介面中移除，其介面已移至 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 中，由於繫結器交易緩衝區有硬性限制，因此圖片大小不得超過 1 MB。 | ||
| 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 2.0 | openSession(ITunerCallback callback) 產生 (Result result, ITunerSession session) |
|
| AIDL | void setTunerCallback(in ITunerCallback callback) |
|
說明：
|
||
| HIDL 2.0 | close() |
|
| AIDL | unsetTunerCallback() |
|
| 說明：收聽指定節目。 | ||
| HIDL 2.0 | tune(ProgramSelector program) generates (Result result) |
|
| AIDL | void tune(in ProgramSelector program) |
|
說明：搜尋air上下一個有效的節目。為避免 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 用戶端接收。
同樣地，如果 stopProgramListUpdates 是在 HAL 完成程式清單更新後，且在 onCurrentProgramInfoChanged 回呼完成前呼叫，則可以忽略 stopProgramListUpdates，回呼應會完成。
資料大小限制
由於繫結器交易緩衝區有嚴格限制，因此 AIDL HAL 會明確指出某些介面方法傳遞可能大型資料的資料限制。
getImage要求傳回的圖片大小不得超過 1 MB。onProgramListUpdate要求每個chunk的大小不得超過 500 KB。較大的節目清單必須由 HAL 實作項目分割為多個區塊，並透過多個回呼傳送。
AIDL HAL 資料結構的異動
除了介面變更之外，這些變更也已套用至在廣播電台 AIDL HAL 中定義的資料結構，以便充分利用 AIDL。
Constant列舉已從 AIDL 中移除，並在IBroadcastRadio中定義為 const int。同時，ANTENNA_DISCONNECTED_TIMEOUT_MS已重新命名為ANTENNA_STATE_CHANGE_TIMEOUT_MS。新增一個 const intTUNER_TIMEOUT_MS。所有調音、尋找和步驟操作都必須在這個時間內完成。- 列舉
RDS和Deemphasis已從 AIDL 中移除，並在AmFmRegionConfig中定義為 const int。相應地，ProgramInfo中的fmDeemphasis和fmRds都宣告為 int，也就是各標記位元計算結果。同時，D50和D75已分別重新命名為DEEMPHASIS_D50和DEEMPHASIS_D75。 - AIDL 已移除列舉
ProgramInfoFlags，並在ProgramInfo中定義為 const int，並加上前置字串FLAG_。相應地，ProgramInfo中的infoFlags會宣告為 int，也就是旗標的位元運算結果。TUNED也已重新命名為FLAG_TUNABLE，以便更準確地描述可收聽該電台的定義。 - 在
AmFmBandRange中，scan已在 AIDL 中重新命名為seek，因此scanSpacing會重新命名為seekSpacing。 - 由於 AIDL 中引入了聯集的概念，因此 HIDL HAL 中定義的
MetadataKey和Metadata已不再使用。AIDL HAL 中定義了 AIDL 聯集Metadata。先前在MetadataKey中的每個列舉值，現在都是Metadata中的欄位，其類型為字串或 int，視其定義而定。
支援 DAB 收音機
本節說明 DAB 收音機支援功能。
ID
AIDL Broadcast Radio HAL 中 DAB 和 DMB 廣播電台的主要 ID 類型為 DAB_SID_EXT。DAB_SID_EXT 使用 32 位元服務 ID (SID)，因此可同時代表 DAB 和 DMB 調頻廣播的 SID。
除了主要 ID 外，系統也支援 DAB_ENSEMBLE 和 DAB_FREQUENCY_KHZ 等次要 ID。這點很重要，因為多個 DAB 電台可以共用 DAB_SID_EXT，但擁有不同的 DAB_ENSEMBLE 或 DAB_FREQUENCY_KHZ 值。為確保節目清單更新正確，系統會使用 ITunerCallback#onProgramListUpdated 一起更新具有相同 DAB_SID_EXT 的電台。接著，這項更新會傳送至廣播電台服務和電台管理工具，最後透過 android.hardware.radio.ProgramList 傳送至電台應用程式。
中繼資料
下表列出 AIDL 廣播電台 HAL 中支援的 DAB 中繼資料：
| 中繼資料欄位 | 說明 |
|---|---|
dabEnsembleName (簡寫：dabEnsembleNameShort) |
DAB 電台的集合名稱 |
dabServiceName (由 dabServiceNameShort 縮寫而來) |
DAB 電台的服務名稱 |
dabComponentName (由 dabComponentNameShort 縮寫而來) |
DAB 電台的元件名稱 |
HD 電台支援
本節說明 HD 調頻廣播支援功能。
ID
HD_STATION_ID_EXT 是 HD 調頻電台的主要 ID。為進一步強化車站識別功能，我們也提供 HD_STATION_NAME 和 HD_STATION_LOCATION 等次要 ID。HD_STATION_LOCATION 可提供位置資訊，已在 Android 15 中推出。
啟用或停用數位廣播電台
從 Android 15 開始，您可以調整 ConfigFlag 來啟用或停用數位廣播電台 (例如 HD 廣播電台)。如要控制 FM 收音機的這項設定，請使用 FORCE_ANALOG_FM 標記；如要控制 AM 收音機，請使用 FORCE_ANALOG_AM 標記。將標記設為 false 可啟用 HD 無線電，將標記設為 true 則會強制使用類比 AM/FM 無線電。
提供 HD 高畫質頻道
自 Android 15 起，目前可供 HD 調頻電台使用的 HD 頻道，可在 ProgramInfo.metadata 中以 8 位元位元遮罩 Metadata#hdSubChannelsAvailable 表示。舉例來說，從左側開始的位元 1 的值代表 HD2 子頻道是否可供這個 HD 電台使用。
訊號擷取狀態
在 Android 15 以上版本中，收音機應用程式可向使用者顯示 HD 收音機電台的信號取得狀態。這很實用，因為取得強烈的 HD 訊號可能需要幾秒鐘的時間。
為提供這項資訊，系統會使用 ProgramInfo.infoFlags 追蹤狀態，並透過 ITunerCallback#onCurrentProgramInfoChanged. 更新收音機應用程式
以下是 ProgramInfo.infoFlags 中狀態的呈現方式：
- 位元 6：指出是否已取得 HD 調頻訊號。
- 位元 7：顯示是否有可用的車站資訊服務 (SIS) 資料。SIS 會提供電台和播放內容的額外資訊。
- 位元 8：指出是否提供 HD 數位音訊。
中繼資料
下表列出 Android 15 以上版本支援的 HD 調頻中繼資料。
| 中繼資料欄位 | 說明 |
|---|---|
commentShortDescription |
留言的簡短背景說明 |
commentActualText |
評論文字 |
commercial |
電台廣告 |
ufids |
與內容相關聯的專屬檔案 ID (UFID) |
hdStationNameShort |
HD 廣播電台的簡稱或通用簡稱 |
hdStationNameLong |
HD 廣播電台的完整名稱、標語或電台訊息。 |