ブロードキャスト ラジオ 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 ラジオ ステーションの正式名、スローガン、またはステーションからのメッセージ。

緊急速報メール

Android 15 以降では、HD ラジオ ステーションで緊急速報メールがサポートされており、ラジオ ステーションから送信された緊急警報がラジオアプリのユーザーに通知されます。緊急速報メール（Alert）は Common Alerting Protocol（CAP）1.2 標準に準拠しており、以下の表に記載されているアラートに対応しています。

アラート情報	説明	利用可能な列挙値
AlertStatus	アラート メッセージのステータス	ACTUAL、EXERCISE、TEST
AlertMessageType	緊急速報メールのメッセージの種類	ALERT、UPDATE、CANCEL
AlertCategory	緊急速報メールのメッセージの対象イベントのカテゴリ	GEO、MET、SAFETY、SECURITY、RESCUE、FIRE、HEALTH、ENV、TRANSPORT、INFRA、CBRNE、OTHER
AlertUrgency	緊急速報メールのメッセージの対象イベントの緊急度	IMMEDIATE、EXPECTED、FUTURE、PAST、UNKNOWN
AlertSeverity	緊急速報メールのメッセージの対象イベントの重大度	EXTREME、SEVERE、MODERATE、MINOR、UNKNOWN
AlertCertainty	緊急速報メールのメッセージの対象イベントの確実性	OBSERVED、LIKELY、POSSIBLE、UNLIKELY、UNKNOWN

Alert（表内の情報を含む）、アラートのテキスト メッセージ、および AlertArea を使用して、現在のアラートに関する情報を表示できます。Alert は ProgramInfo のオプション フィールドであり、現在の番組情報や番組リストの更新情報を、チューナー コールバックを通じて Broadcast Radio HAL からラジオアプリに送信できるようにします。