اعتبارًا من 27 آذار (مارس) 2025، ننصحك باستخدام android-latest-release بدلاً من aosp-main لإنشاء AOSP والمساهمة فيه. لمزيد من المعلومات، يُرجى الاطّلاع على التغييرات في AOSP.

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

واجهة VHAL

يتم تحديد AIDL VHAL في android.hardware.automotive.vehicle namespace. يتم تحديد واجهة VHAL في IVehicle.aidl. ما لم يُحدّد خلاف ذلك، يجب تنفيذ جميع الطرق لإصدار معيّن من VHAL.

الإصدارات

إصدار Android	أحدث إصدار من VHAL	أحدث إصدار من سمة VHAL	الحد الأدنى لإصدار VHAL المتوافق
Android 16	V4	V4	V1
Android 15	V3	V3	V1
Android 14	V2	V2	V1
Android 13	V1	(لم يتم تقسيم واجهة VHAL)	V1

يُنصح بتنفيذ أحدث إصدار من VHAL لإصدار معيّن من Android.

الدوال وعمليات رد الاتصال

يمكن الاطّلاع على تعريفات دوال VHAL على الرابط IVehicle.aidl.

الطريقة
`VehiclePropConfigs getAllPropConfigs()` تعرض هذه الطريقة قائمة بجميع إعدادات الأجهزة المتوافقة مع طبقة HAL الخاصة بالمركبة.
`VehiclePropConfigs getPropConfigs(in int[] props)` تعرض هذه الطريقة قائمة بإعدادات المواقع لأرقام تعريف المواقع المحدّدة.
`void getValues(IVehicleCallback callback, in GetValueRequests requests)` الحصول على قيم سمات المركبة بشكل غير متزامن تعالج هذه السمة مجموعة من `GetValueRequest` بشكل غير متزامن. يتم عرض النتيجة من خلال طريقة رد الاتصال `onGetValues`.
`void setValues(IVehicleCallback callback, in SetValueRequests requests)` اضبط قيم خصائص المركبة بشكل غير متزامن. تعالج مجموعة من `SetValueRequest` بشكل غير متزامن. يتم عرض النتيجة من خلال طريقة رد الاتصال `onSetValues`.
`void subscribe(in IVehicleCallback callback, in SubscribeOptions[] options, int maxSharedMemoryFileCount)` يتم الاشتراك في أحداث الموقع باستخدام الخيارات المحدّدة. تتضمّن خيارات الاشتراك رقم تعريف الموقع ورقم تعريف منطقة الموقع ومعدّل أخذ العيّنات بالهرتز (لموقع مستمر). لم يتم استخدام `maxSharedMemoryFileCount`.
`void unsubscribe(in IVehicleCallback callback, in int[] propIds)` إلغاء الاشتراك في أحداث الموقع التي تم الاشتراك فيها سابقًا لمواقع محدّدة
`returnSharedMemory(in IVehicleCallback callback, long sharedMemoryId)` لا يتم استخدامها ويمكن تنفيذها كعملية غير نشطة.
(ميزة جديدة في Android 16) `SupportedValuesListResults getSupportedValuesLists(in List propIdAreaIds)` تعرض هذه الطريقة قوائم القيم المتوافقة مع أزواج معرّفات المواقع الجغرافية ومعرّفات الخصائص المحدّدة. تمت إضافة هذه السمة في الإصدار 4 من VHAL.
(ميزة جديدة في Android 16) `MinMaxSupportedValueResults getMinMaxSupportedValue(in List propIdAreaIds)` تعرض هذه الطريقة الحدّين الأدنى والأقصى للقيم المتوافقة مع أزواج أرقام تعريف المواقع وأرقام تعريف المناطق المحدّدة. تمت إضافة هذه السمة في الإصدار 4 من VHAL.
`void registerSupportedValueChangeCallback(in IVehicleCallback callback, in List propIdAreaIds)` تسجّل هذه السمة دالة معاودة الاتصال ليتم استدعاؤها عند تغيير القيم المتوافقة. تمت إضافة هذه السمة في الإصدار 4 من VHAL.
`void unregisterSupportedValueChangeCallback(in IVehicleCallback callback, in List propIdAreaIds)` لإلغاء تسجيل معاودة الاتصال لتغيير القيمة المتوافقة تمت إضافة هذه السمة في الإصدار 4 من VHAL.

يتم تحديد عمليات الاسترجاع في IVehicleCallback.aidl وتتضمّن هذه الطرق.

الطريقة
`oneway void onGetValues(in GetValueResults responses)` دالة ردّ الاتصال للدالة `getValues` من أجل عرض نتائج الحصول على القيمة. يتم استدعاء هذه الطريقة عندما تكون بعض القيم المطلوب جلبها جاهزة.
`oneway void onSetValues(in SetValueResults responses)` دالة ردّ الاتصال للدالة `setValues` من أجل عرض نتائج القيمة المحدّدة. يتم استدعاؤها عندما ينتهي VHAL من معالجة بعض طلبات ضبط السمات.
`oneway void onPropertyEvent(in VehiclePropValues propValues, int sharedMemoryFileCount)` دالة ردّ الاتصال لإعداد تقارير عن أحداث تعديل السمة. في الموقع `CONTINUOUS`، يحدث حدث الموقع استنادًا إلى معدّل أخذ العيّنات من الاشتراك بالهرتز أو معدّل تكرار رسائل ناقل بيانات المركبة. قد يحدث حدث خاص بموقع أيضًا إذا تغيّرت حالة الموقع. على سبيل المثال، من غير متوفّر إلى متوفّر. بالنسبة إلى السمة `ON_CHANGE`، يحدث حدث خاص بالسمة عند تغيير قيمة السمة أو حالة السمة. يجب استخدام هذا الحقل أيضًا لعرض أحداث تغيير حالة العقار، مثلاً، عندما يصبح العقار غير متاح أو تظهر فيه أخطاء عند القراءة، يجب عرض `VehiclePropValue` بحالة غير متاحة أو حالة خطأ وقيمة فارغة. `SharedMemoryFileCount` يساوي دائمًا `0`.
`oneway void onPropertySetError(in VehiclePropErrors errors)` دالة ردّ لإعداد تقارير عن أخطاء غير متزامنة في ضبط الموقع لا تتضمّن طلب ضبط مطابقًا. إذا عرفنا مجموعة الطلبات التي حدث الخطأ فيها، يجب استخدام `onSetValues` مع نتيجة خطأ بدلاً من ذلك.
`oneway void onSupportedValueChange(in List propIdAreaIds)` دالة رد الاتصال لإعداد تقارير عن الحدّ الأدنى والأقصى للقيمة المسموح بها أو تغييرات قائمة القيم المسموح بها. من المفترض أن يتصل المتصل بالرقم `getMinMaxSupportedValue` أو `getSupportedValuesLists` للحصول على القيم المعدَّلة.

يتم التحقّق من صحة تنفيذ VHAL من خلال VTS الخاص بـ VHAL على VtsHalAutomotiveVehicle_TargetTest.cpp.

يتحقّق الاختبار من تنفيذ الطرق الأساسية بشكل صحيح ومن صحة إعدادات المواقع المتوافقة. يتم إجراء الاختبار على جميع مثيلات VHAL على الجهاز، ولكن لا يستخدم نظام التشغيل Android Automotive إلا المثيل التلقائي (android.hardware.automotive.vehicle.IVehicle/default).

قيمة خاصية المركبة

استخدِم بنية VehiclePropValue لوصف قيمة كل سمة، والتي تتضمّن الحقول التالية:

الحقل	الوصف
`timestamp`	الطابع الزمني الذي يمثّل الوقت الذي وقع فيه الحدث وتمت مزامنته مع ساعة `SystemClock.elapsedRealtimeNano()`.
`prop`	تمثّل هذه السمة معرّف الموقع لهذه القيمة.
`areaid`	تمثّل هذه السمة رقم تعريف المنطقة لهذه القيمة. يجب أن تكون المنطقة إحدى المناطق المتوافقة والمدرَجة في إعدادات رقم تعريف المنطقة، أو `0` للمواقع العالمية.
`value`	بنية بيانات تحتوي على قيمة السمة الفعلية استنادًا إلى نوع السمة، يتم استخدام حقل واحد أو أكثر ضمن هذا الحقل لتخزين القيمة الفعلية. على سبيل المثال، يتم استخدام العنصر الأول في `value.int32Values` للسمات من النوع Int32. لمزيد من التفاصيل، يُرجى الاطّلاع على إعدادات الموقع.
`status`	تمثّل هذه السمة حالة الموقع الإلكتروني للقراءة. بالنسبة إلى سمة القراءة/الكتابة، قد ينطبق ذلك أيضًا على الكتابة ولكن ليس مضمونًا، على سبيل المثال، قد تكون السمة متاحة للقراءة ولكن ليس للكتابة. في هذه الحالة، تكون الحالة `AVAILABLE` ويحتوي حقل القيمة على معلومات صالحة. ملاحظة: لا تتوفّر حاليًا طريقة تتيح للعميل تتبُّع حالة الكتابة الخاصة بقراءة/كتابة أو كتابة سمة. لا يعرف العميل ما إذا كانت السمة متاحة للكتابة إلا عندما يحاول ضبط قيمة. ملاحظة مهمة: إذا لم تكن الحالة `AVAILABLE`، يجب تجاهل حقل القيمة. للاطّلاع على الحالات المحتملة، راجِع `VehiclePropertyStatus`.

الدالتان غير المتزامنتان getValues وsetValues

يتم تنفيذ العمليتَين getValues وsetValues بشكل غير متزامن، ما يعني أنّ الدالة قد تعرض قيمة قبل اكتمال عملية الحصول على البيانات أو ضبطها. يتم عرض نتائج العملية (على سبيل المثال، قيمة السمة الخاصة بـ getValues وحالة النجاح أو الخطأ الخاصة بـ setValues) من خلال عمليات الرجوع التي يتم تمريرها كوسيطات.

يجب ألا يتم الحظر على النتيجة في سلسلة ربط البيانات التي تعالج الطلب. بدلاً من ذلك، ننصحك بتخزين الطلب في قائمة انتظار الطلبات واستخدام سلسلة معالجة منفصلة للتعامل مع الطلبات بشكل غير متزامن. يمكنك الاطّلاع على التنفيذ المرجعي للحصول على التفاصيل.

الشكل 1. عملية غير متزامنة

عناصر كبيرة قابلة للتسلسل

تُسمى جميع البِنى التي تحمل الاسم XXXs، مثل VehiclePropConfigs وSetValueRequests وVehiclePropValues، باسم LargeParcelable (أو StableLargeParcelable). ويمثّل كل منها قائمة بالقيم المستخدَمة لنقل البيانات الكبيرة التي قد تتجاوز حدود Binder (4 كيلوبايت في تنفيذ مكتبة LargeParcelable) عبر حدود Binder. يتضمّن كلّ منهما تعريفًا مشابهًا للبنية يحتوي على الحقول التالية.

إرشادات	الوصف
`payloads`	قائمة بالقيم عندما يكون حجم القيمة مناسبًا لحدود ذاكرة الرابط، أو قائمة فارغة
`sharedMemoryFd`	واصف ملف قابل للتصغير يشير إلى ملف ذاكرة مشتركة يخزّن الحِزم المتسلسلة إذا كانت قائمة القيم كبيرة جدًا.

على سبيل المثال، يتم تعريف VehiclePropConfigs على النحو التالي:

parcelable VehiclePropConfigs {
    // The list of vehicle property configs if they fit the binder memory
    // limitation.
    VehiclePropConfig[] payloads;
    // Shared memory file to store configs if they exceed binder memory
    // limitation. Created by VHAL, readable only at client. Client could keep
    // the fd opened or keep the FD mapped to access configs.
    @nullable ParcelFileDescriptor sharedMemoryFd;
}

يجب أن تحتوي VehiclePropConfigs على حمولات غير فارغة أو على sharedMemoryFd غير فارغ.

إذا لم يكن payloads فارغًا، سيخزّن قائمة بالبيانات الفعلية، وهي إعدادات السمة.
إذا لم يكن sharedMemoryFd فارغًا، سيحتوي على ملف ذاكرة مشتركة يخزّن البنية المتسلسلة لـ VehiclePropConfigs. يستخدم البنية الدالة writeToParcel لتسلسل Parcel.

بصفتها برنامج Java للعميل في VHAL، تتولّى خدمة Car Service عملية التسلسل وإلغاء التسلسل لـ LargeParcelable. بالنسبة إلى عمليات تنفيذ VHAL والبرامج الأصلية، يجب تسلسل LargeParcelable وإلغاء تسلسله باستخدام مكتبة LargeParcelable أو فئة تضمين مفيدة للمكتبة في ParcelableUtils.h.

على سبيل المثال، يكون عميل أصلي يحلّل الطلبات الخاصة بـ getValues التي تم تلقّيها من رابط على النحو التالي:

// 'requests' are from the binder.
GetValueRequests requests;
expected<LargeParcelableBase::BorrowedOwnedObject, ScopedAStatus> deserializedResults = fromStableLargeParcelable(requests);
if (deserializedResults.ok()) {
    const std::vector& getValueRequests = deserializedResults.value().getObject()->payloads;
    // Use the getValueRequests.
  } else {
    // handle error.
}

في ما يلي نموذج لتنفيذ VHAL يرسل نتائج getValues من خلال الرابط:

std::vector results = getResults();
GetValueResults parcelableResults;
ScopedAStatus status = vectorToStableLargeParcelable(std::move(results), &parcelableResults);
if (status.isOk()) {
    // Send parcelableResults through callback.
} else {
    // Handle error.
}