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

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

واجهة VHAL

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

الإصدارات

إصدار Android	أحدث إصدار من VHAL	أحدث إصدار من سمة VHAL	الحد الأدنى لإصدار VHAL المتوافق
Android 16	الإصدار 4	الإصدار 4	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` property، يحدث حدث الموقع استنادًا إلى معدّل أخذ العينات للاشتراك بالهرتز أو معدّل تكرار رسائل ناقل بيانات المركبة. قد يحدث حدث موقع أيضًا في حال تغيّرت حالة الموقع. على سبيل المثال، من غير متوفّر إلى متوفّر. بالنسبة إلى السمة `ON_CHANGE`، يحدث حدث خاصية عند تغيير قيمة أو حالة السمة. يجب أيضًا استخدام هذا الإجراء لإرسال أحداث تغيير حالة الموقع، على سبيل المثال، عندما يصبح الموقع غير متاح أو يحدث خطأ في القراءة، يجب إرسال `VehiclePropValue` بحالة غير متاح أو خطأ وقيمة فارغة. `SharedMemoryFileCount` يكون دائمًا `0`.
`oneway void onPropertySetError(in VehiclePropErrors errors)` إجراء استدعاء لإعداد تقارير عن أخطاء مجموعة المواقع غير المتزامنة التي لا تتضمّن طلبًا مقابلًا لتحديد مجموعة. إذا عرفنا طلب المجموعة الذي حدث فيه الخطأ، يجب استخدام `onSetValues` مع نتيجة خطأ بدلاً من ذلك.
`oneway void onSupportedValueChange(in List propIdAreaIds)` إجراء استدعاء لإعداد تقارير عن الحد الأدنى والحد الأقصى للقيمة المسموح بها أو تغييرات قائمة القيم المسموح بها من المفترض أن يتصل المتصل بالرقم `getMinMaxSupportedValue` أو `getSupportedValuesLists` للحصول على القيم المعدّلة.

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

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

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

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

عناصر parcelable كبيرة

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

إرشادات	الوصف
`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 لتسلسل حزمة.

بصفتها برنامج 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.
}