ブロードキャストラジオ HAL

次のセクションでは、ブロードキャストラジオを実装するために、Hardware Abstraction Layer（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)`
説明: 番組リストが更新されたときに呼び出されます。各チャンクのサイズは 500 KiB に制限する必要があります。
	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 インターフェースを使用してオペレーションを呼び出します。ただし、一度に有効にできるチューナーは 1 つだけです（各ブロードキャストラジオ HAL インスタンスにチューナーチップが 1 つしかない場合）。 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 HAL: 新しいチューナーセッションを開始したときに、古いセッションを終了する必要があります。 AIDL HAL: 利用できるチューナーセッションがないため、チューナーコールバックのみを設定する必要があります。セッションがある場合は、古いコールバックの設定を解除する必要があります。
	HIDL 2.0	`openSession(ITunerCallback callback)` が `(Result result, ITunerSession session)` を生成します。
	AIDL	`void setTunerCallback(in ITunerCallback callback)`
説明: HIDL HAL: チューナーセッションの終了は失敗してはならず、1 回のみ行う必要があります。 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 でのシーク、ステップ）は時間がかかる可能性があり、スレッドが長時間ブロックされないようにするため、時間のかかるオペレーションを後で実行してステータスや結果をすばやく返すように、スケジュールされます。具体的には、各オペレーションで以下を行う必要があります。

保留中のすべての選局オペレーションをキャンセルします。
メソッド入力とチューナーのステータスに基づいてオペレーションが処理できるかどうかをチェックします。
選局タスクをスケジュールしたら、すぐに HIDL での Result、または AIDL での status を返します。 Result または status が OK の場合、タイムアウトなどが理由で選局タスクが失敗または完了したときには、チューナーコールバック tuneFailed または currentProgramInfoChanged を呼び出す必要があります。

同様に startProgramListUpdates は、番組リストの更新という時間のかかるタスクを後で実行して、ステータスまたは結果をすばやく返すようにスケジュールします。このメソッドでは、まず保留中の更新リクエストをキャンセルしてから、更新タスクをスケジュールし、結果をすばやく返します。

競合状態

選局オペレーション（選局、HIDL でのスキャン、AIDL でのシーク、ステップ）の非同期動作のため、オペレーションのキャンセルと選局オペレーションの間に競合状態が生じます。HAL が選局オペレーションを完了してコールバックが完了する前に cancel が呼び出された場合、キャンセルを無視して、コールバックが完了して HAL クライアントによって受信されるようにする必要があります。

同様に、HAL が番組リストの更新を完了し、onCurrentProgramInfoChanged コールバックが完了する前に stopProgramListUpdates が呼び出された場合、stopProgramListUpdates を無視し、コールバックが完了されるようにする必要があります。

データサイズの上限

バインダトランザクションバッファにはハードリミットがあるため、AIDL HAL では、インターフェースメソッドで渡されるデータサイズが大きい場合について、明確なデータ制限が定められています。

getImage では、返される画像が 1 MB 未満である必要があります。
onProgramListUpdate では、各 chunk が 500 KiB 未満である必要があります。これよりも大きい番組リストは、HAL 実装によって複数のチャンクに分割され、複数のコールバックを介して送信されなければなりません。

AIDL HAL データ構造の変更

AIDL を利用するブロードキャストラジオ AIDL HAL で定義されたデータ構造には、インターフェースの変更に加え、次の変更が適用されています。

Constant 列挙型が AIDL では削除され、IBroadcastRadio で定数 int として定義されました。同時に、ANTENNA_DISCONNECTED_TIMEOUT_MS の名前が ANTENNA_STATE_CHANGE_TIMEOUT_MS に変更されました。新しい定数 int TUNER_TIMEOUT_MS が追加されました。選局、シーク、ステップの各オペレーションはすべて、この時間内に完了する必要があります。
列挙型 RDS と Deemphasis が AIDL で削除され、AmFmRegionConfig で定数 int として定義されました。それに応じて、ProgramInfo の fmDeemphasis と fmRds はどちらも、それぞれのフラグのビット演算結果である int として宣言されます。同時に、D50 と D75 の名前がそれぞれ DEEMPHASIS_D50 と DEEMPHASIS_D75 に変更されました。
列挙型 ProgramInfoFlags が AIDL で削除され、ProgramInfo で int として定義されました。また、接頭辞 FLAG_ が追加されました。これに応じて、ProgramInfo の infoFlags が、フラグのビット演算結果である int として宣言されます。また、TUNED の名前も FLAG_TUNABLE に変更され、その定義、つまりラジオ局を選局できる範囲の説明がわかりやすくなりました。
AIDL で scan の名前が seek に変更されたため、AmFmBandRange で scanSpacing の名前が seekSpacing に変更されました。
union のコンセプトが AIDL で導入されたため、HIDL HAL で定義された MetadataKey と Metadata は使用されなくなりました。AIDL union Metadata は、AIDL HAL で定義されます。以前は MetadataKey にあった各列挙値は、定義に応じて、文字列型または int 型の Metadata フィールドになります。

DAB ラジオのサポート

このセクションでは、DAB ラジオのサポートについて説明します。

識別子

AIDL ブロードキャストラジオ HAL の DAB ラジオおよび DMB ラジオのプライマリ識別子タイプは DAB_SID_EXT です。DAB_SID_EXT では、DAB ラジオと DMB ラジオの両方のサービス識別子（SID）を表せるように 32 ビットの SID が使用されます。

プライマリ識別子に加えて、DAB_ENSEMBLE や DAB_FREQUENCY_KHZ などのセカンダリ識別子もサポートされています。複数の DAB ステーションで DAB_SID_EXT を共有しつつ異なる DAB_ENSEMBLE 値や DAB_FREQUENCY_KHZ 値を持つことができるため、これは重要です。番組リストの更新が正確に行われるように、DAB_SID_EXT が同じステーションは ITunerCallback#onProgramListUpdated で一緒に更新されます。その後、この更新はブロードキャストラジオサービスとラジオマネージャーにリレーされ、最終的には android.hardware.radio.ProgramList を通じてラジオアプリに送られます。

メタデータ

次の表に、AIDL ブロードキャストラジオ HAL でサポートされている DAB 固有のメタデータを示します。

メタデータフィールド	説明
`dabEnsembleName`（省略形: `dabEnsembleNameShort`）	DAB ステーションのアンサンブル名
`dabServiceName`（省略形 `dabServiceNameShort`）	DAB ステーションのサービス名
`dabComponentName`（省略形 `dabComponentNameShort`）	DAB ステーションのコンポーネント名

HD ラジオのサポート

このセクションでは、HD ラジオのサポートについて説明します。

識別子

HD_STATION_ID_EXT は HD ラジオステーションのプライマリ識別子として機能します。ステーションを確実に識別できるよう、HD_STATION_NAME や HD_STATION_LOCATION などのセカンダリ識別子も用意されています。位置情報を指定する 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 の Metadata#hdSubChannelsAvailable という 8 ビットのビットマスクで表されます。たとえば、左のビット 1 の値は、HD2 サブチャンネルがこの HD ステーションで利用可能かどうかを表します。

信号取得ステータス

Android 15 以降のバージョンでは、ラジオアプリは HD ラジオステーションの信号取得ステータスをユーザーに表示できます。強い HD 信号の取得には時間がかかることがあるため、これは便利です。

この情報を提供するために、ProgramInfo.infoFlags でステータスが追跡され、ITunerCallback#onCurrentProgramInfoChanged. でラジオアプリが更新されます。

ProgramInfo.infoFlags 内でのステータスの表示は以下のとおりです。

ビット 6: HD ラジオ信号が取得されたかどうかを示します。
ビット 7: Station Information Service（SIS）データが利用可能かどうかを示します。SIS ではステーションと再生中のコンテンツに関する追加情報が提供されます。
ビット 8: HD デジタルオーディオが利用可能かどうかを示します。

メタデータ

次の表に、Android 15 以降のバージョンでサポートされている HD ラジオのメタデータを示します。

メタデータフィールド	説明
`commentShortDescription`	コメントのコンテキストに関する簡単な説明
`commentActualText`	コメントのテキスト
`commercial`	ラジオコマーシャル
`ufids`	コンテンツに関連付けられた固有のファイル識別子（UFID）
`hdStationNameShort`	HD ラジオステーションの省略名または一般的な略称
`hdStationNameLong`	HD ラジオステーションの正式名、スローガン、またはステーションからのメッセージ。

ブロードキャスト ラジオ HAL