بث HAL على الراديو

توضّح الأقسام التالية كيفية العمل مع طبقة HAL لتطبيق ميزة البث الإذاعي.

واجهة HAL للبث الإذاعي

يوفّر Broadcast radio HAL هياكل البيانات وواجهات على مستوى الأجهزة لتطبيق بث الراديو، مثل AM/FM وDAB radio.

واجهات 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
الوصف: يتم استدعاء هذه الوظيفة من خلال HAL عند تعذُّر إجراء عملية ضبط (ضبط أو التقديم أو الإيقاف (في AIDL) أو المسح (في HIDL) ونجاح الخطوة) بشكل غير متزامن.
	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 كيلوبايت.
	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 (لا تستدعي هذه الوظيفة بعد استدعاء setParameters بواسطة برنامج HAL).
	HIDL 2.0	oneway onParametersUpdated(vec<VendorKeyValue> parameters)
	لغة تعريف الهوية (AIDL)	void onParametersUpdated(in VendorKeyValue[] parameters)
الوصف: جديد في AIDL يتمّ استدعاؤه عند تعديل علامة الضبط داخليًا في HAL (يجب عدم استدعائه بعد استدعاء setConfigFlag بواسطة عميل HAL).
	HIDL 2.0	غير منطبق.
	لغة تعريف الهوية (AIDL)	void onConfigFlagUpdated(in ConfigFlag flag, in boolean value)

IBroadcastRadio

IBroadcastRadio هي الواجهة الأساسية لواجهة برمجة التطبيقات لبثّ الراديو. في 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 ميغابايت بسبب الحدّ الأقصى الثابت لمساحة التخزين المؤقت لمعاملات الربط.
	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 callback.
	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، يجب استدعاء دالة callback tuneFailed أو currentProgramInfoChanged لتطبيق الضبط عند تعذُّر إكمال مهمة الضبط (على سبيل المثال، بسبب انتهاء مهلة) أو اكتمالها.

وبالمثل، يحدّد startProgramListUpdates أيضًا موعدًا لمهمّة تعديل قائمة البرامج التي تستغرق وقتًا طويلاً، وذلك لكي يتم عرض حالة أو نتيجة بسرعة. تلغي الطريقة أولاً طلبات التعديل التي في انتظار المراجعة، ثم تحدّد موعدًا لمهمة التعديل وتُظهر النتيجة بسرعة.

حالة السباق

بسبب السلوك غير المتزامن لعمليات الضبط (مثل الضبط والفحص (في HIDL) أو التقديم/الترجيع (في AIDL) والخطوة)، يتوفّر شرط تسابق بين إلغاء العملية وعمليات الضبط. في حال تمّ استدعاء cancel بعد أن يُكمِل HAL عملية ضبط وقبل اكتمال callback، يمكن تجاهل الإلغاء ومن المفترض أن يكتمل callback ويتلقّاه العميل HAL.

وبالمثل، إذا تمّ استدعاء stopProgramListUpdates بعد أن يُكمل HAL تعديلًا في قائمة البرامج وقبل اكتمال عملية استدعاء onCurrentProgramInfoChanged، يمكن تجاهل stopProgramListUpdates ومن المفترض أن تكتمل عملية الاستدعاء.

الحد الأقصى لحجم البيانات

بما أنّ هناك حدًا صارمًا على وحدة تخزين المعاملات في أداة الربط، يتم توضيح حد البيانات لبعض طُرق واجهة التي تنقل بيانات قد تكون كبيرة الحجم في AIDL HAL.

• تتطلّب getImage أن يكون حجم الصورة المعروضة أقل من 1 ميغابايت.
• تتطلّب onProgramListUpdate أن يكون حجم كل chunk أقل من 500 كيلوبايت. يجب تقسيم قوائم البرامج الأكبر حجمًا من خلال تنفيذ HAL إلى أجزاء متعددة وإرسالها من خلال callbacks متعددة.

التغييرات في هياكل بيانات HAL لواجهة برمجة التطبيقات الذكية (AIDL)

بالإضافة إلى التغييرات في الواجهات، تم تطبيق هذه التغييرات على هياكل البيانات المحدّدة في حزمة HAL لبروتوكول AIDL للبث الإذاعي، والتي تستفيد من حزمة AIDL.

• تمّت إزالة Constant enum في AIDL وتمّ تعريفها على أنّها const int في IBroadcastRadio. في هذه الأثناء، تمت إعادة تسمية ANTENNA_DISCONNECTED_TIMEOUT_MS إلى ANTENNA_STATE_CHANGE_TIMEOUT_MS. تمت إضافة TUNER_TIMEOUT_MS ثابت جديد. يجب إكمال جميع عمليات الضبط والتقديم والترجيع خلال هذا الوقت.
• تتم إزالة العنصرَين التعريفيين RDS وDeemphasis في AIDL ويتم تعريفهما على أنّهما const int في AmFmRegionConfig. وبالمثل، تمّ الإعلان عن كلّ من fmDeemphasis و fmRds في ProgramInfo على أنّهما int، وهي نتيجة حسابية ثنائية للعلامات المعنية. وفي الوقت نفسه، تمت إعادة تسمية D50 وD75 إلى DEEMPHASIS_D50 وDEEMPHASIS_D75، على التوالي.
• تتم إزالة العنصر ProgramInfoFlags في AIDL ويتم تعريفه على أنّه const int في ProgramInfo مع إضافة بادئة FLAG_. وفقًا لذلك، تمّ الإعلان عن infoFlags في ProgramInfo على أنّه int، وهو نتيجة معالجة ثنائية للأعلام. تمت أيضًا إعادة تسمية TUNED إلى FLAG_TUNABLE لوصف التعريف الذي يمكن ضبط المحطة عليه بشكل أفضل.
• في AmFmBandRange، تمت إعادة تسمية scanSpacing إلى seekSpacing، لأنّه تمت إعادة تسمية scan إلى seek في لغة تعريف واجهة نظام Android ‏(AIDL).
• بما أنّ مفهوم الاتحاد تم تقديمه في AIDL، لم يعُد يتم استخدام MetadataKey و Metadata المحدَّدين في HIDL HAL. يتم تعريف بنية ائتلاف AIDL Metadata في HAL AIDL. كل قيمة من القيم المحدَّدة مسبقًا في MetadataKey أصبحت الآن حقلًا في Metadata بنوع سلسلة أو int، استنادًا إلى تعريفاتها.

توافق مع راديو البث الرقمي

يوضّح هذا القسم مدى توافق الجهاز مع راديو DAB.

المعرفات

نوع المعرّف الأساسي لراديو DAB وDMB في واجهة HAL لبثّ الراديو في AIDL هو DAB_SID_EXT. يستخدم DAB_SID_EXT معرّفات الخدمة (SID) بسعة 32 بت حتى يتمكّن من تمثيل معرّف SID لكل من راديو DAB وDMB.

بالإضافة إلى المعرّفات الأساسية، يمكن استخدام المعرّفات الثانوية، مثل DAB_ENSEMBLE و DAB_FREQUENCY_KHZ. هذا مهم لأنّه يمكن لعدة محطات DAB استخدام DAB_SID_EXT مع اختلاف قيم DAB_ENSEMBLE أو DAB_FREQUENCY_KHZ. لضمان دقة تعديلات قائمة البرامج، يتم تعديل المحطات التي تستخدم DAB_SID_EXT نفسه معًا باستخدام ITunerCallback#onProgramListUpdated. ويتم بعد ذلك نقل هذا التعديل إلى "خدمة البث " للراديو و"مدير الراديو"، ثم إلى تطبيق الراديو من خلال android.hardware.radio.ProgramList.

البيانات الوصفية

يوضِّح الجدول التالي البيانات الوصفية المتوافقة الخاصة بتقنية DAB في واجهة HAL لبث الإذاعة في AIDL:

حقل البيانات الوصفية	الوصف
dabEnsembleName (الشكل المختصر: dabEnsembleNameShort)	اسم مجموعة محطات DAB
dabServiceName (اختصار dabServiceNameShort)	اسم خدمة محطة DAB
dabComponentName (اختصار dabComponentNameShort)	اسم مكوّن محطة DAB

إتاحة الراديو الرقمي المختلط

يوضّح هذا القسم مدى توفّر ميزة "الراديو عالي الدقة".

المعرفات

يُستخدَم HD_STATION_ID_EXT كمعرّف أساسي لمحطات الراديو عالية الدقة. لتحسين عملية تحديد المحطة، يتم أيضًا توفير معرّفات ثانوية مثل HD_STATION_NAME و HD_STATION_LOCATION. HD_STATION_LOCATION، الذي يقدّم معلومات عن الموقع الجغرافي، تم طرحه في Android 15.

تفعيل الراديو الرقمي أو إيقافه

بدءًا من الإصدار 15 من Android، يمكنك تفعيل الراديو الرقمي (مثل الراديو عالي الدقة) أو إيقافه من خلال تعديل ConfigFlag. للتحكّم في هذا الإعداد لراديو FM، استخدِم العلامة FORCE_ANALOG_FM، ولراديو AM، استخدِم العلامة FORCE_ANALOG_AM. يؤدي ضبط العلامة على false إلى تفعيل الراديو بدقة عالية، بينما يؤدي ضبطها على true إلى فرض استخدام الراديو التناظري AM/FM.

قنوات بدقة عالية متاحة

بدءًا من الإصدار 15 من Android، يمكن تمثيل القنوات العالية الدقة المتاحة حاليًا لمحطة راديو عالية الدقة باستخدام قناع بتات مكوّن من 8 بتات، Metadata#hdSubChannelsAvailable، في ProgramInfo.metadata. على سبيل المثال، تمثل قيمة النقطة الأولى من اليسار ما إذا كان القناة الفرعية HD2 متاحة لمحطة HD هذه.

حالة اكتساب الإشارة

في الإصدار 15 من Android والإصدارات الأحدث، يمكن لتطبيقات الراديو أن تعرض للمستخدمين حالة اكتساب إشارة محطات الراديو بدقة عالية. ويُعدّ ذلك مفيدًا لأنّ الحصول على إشارة عالية الدقة قوية قد يستغرق أحيانًا بضع لحظات.

لتقديم هذه المعلومات، يستخدم النظام ProgramInfo.infoFlags لتتبُّع حالة التطبيق وتعديله من خلال ITunerCallback#onCurrentProgramInfoChanged..

في ما يلي كيفية تمثيل الحالة في ProgramInfo.infoFlags:

• النقطة 6: تشير إلى ما إذا تم الحصول على إشارة الراديو عالي الدقة.
• البتّ 7: يعرض ما إذا كانت بيانات خدمة معلومات المحطة (SIS) متاحة. يوفّر نظام SIS معلومات إضافية عن المحطة والمحتوى الذي يتم تشغيله.
• النقطة الثمانية: تشير إلى ما إذا كان الصوت الرقمي عالي الدقة متاحًا.

البيانات الوصفية

يعرض الجدول التالي البيانات الوصفية المتاحة لأجهزة Android 15 والإصدارات الأحدث التي تتضمّن بثّ راديو بدقة عالية.

حقل البيانات الوصفية	الوصف
commentShortDescription	وصف موجز للسياق الخاص بالتعليق
commentActualText	نص التعليق
commercial	إعلان تلفزيوني
ufids	معرّفات الملفات الفريدة (UFID) المرتبطة بالمحتوى
hdStationNameShort	الاسم المختصر للمحطة الإذاعية بدقة عالية أو الاسم المختصر العالمي
hdStationNameLong	الاسم الكامل للمحطة الإذاعية بدقة عالية أو شعارها أو رسالة من المحطة