Broadcast radio 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
الوصف: يتم استدعاء هذه الطريقة من خلال طبقة 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 void 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 هي الواجهة الأساسية لطبقة تجريد الأجهزة (HAL) الخاصة بالبث العام على الراديو. في طبقة تجريد الأجهزة (HAL) 2.0 الخاصة بلغة وصف واجهة HIDL، استخدِم واجهة 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 ميغابايت بسبب الحدّ الأقصى الثابت لمخزن مؤقت لمعاملات Binder.
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)
الوصف:
  • طبقة تجريد الأجهزة (HAL) في HIDL: عند فتح جلسة موالف جديدة، يجب إنهاء الجلسة القديمة.
  • 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) أو التنقّل خطوة بخطوة)، يحدث تعارض بين إلغاء العملية وعمليات الضبط. إذا تم استدعاء cancel بعد أن يكمل HAL عملية ضبط وقبل اكتمال معاودة الاتصال، يمكن تجاهل الإلغاء ويجب أن يكتمل معاودة الاتصال وأن يتلقّاها عميل HAL.

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

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

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

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

التغييرات في هياكل بيانات AIDL HAL

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

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

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

يوضّح هذا القسم إمكانية استخدام راديو DAB.

المعرّفات

نوع المعرّف الأساسي لراديو DAB وDMB في AIDL Broadcast Radio HAL هو DAB_SID_EXT. يستخدم DAB_SID_EXT معرّفات خدمة (SIDs) تبلغ 32 بت، ما يتيح له تمثيل معرّف الخدمة لكل من راديو DAB وDMB.

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

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

يعرض الجدول التالي البيانات الوصفية المتوافقة مع DAB في AIDL Broadcast Radio HAL:

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

HD radio rupport

يوضّح هذا القسم إمكانية استخدام الراديو عالي الدقة.

المعرّفات

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

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

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

تتوفّر قنوات بدقة عالية

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

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

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

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

في ما يلي طريقة عرض الحالة ضمن ProgramInfo.infoFlags:

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

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

يوضِّح الجدول التالي البيانات الوصفية المتوافقة مع راديو HD في الإصدار 15 من نظام التشغيل Android والإصدارات الأحدث.

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

تنبيهات الطوارئ

في نظام التشغيل Android 15 والإصدارات الأحدث، تتوافق تنبيهات الطوارئ مع محطات الراديو عالية الدقة لإعلام مستخدمي تطبيقات الراديو بتنبيهات الطوارئ التي ترسلها محطات الراديو. يتّبع تنبيه الطوارئ (Alert) معيار بروتوكول التنبيه الشائع (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 إلى تطبيقات الراديو من خلال عمليات رد الاتصال الخاصة بجهاز الاستقبال للحصول على معلومات البرنامج الحالي وتعديلات قائمة البرامج.