واجهة VHAL

يتم تحديد واجهة برمجة التطبيقات لنظام التشغيل Android (AIDL) لواجهة برمجة التطبيقات لنظام التشغيل Android (VHAL) في ملف android.hardware.automotive.vehicle namespace. تم تحديد واجهة 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) لا يتم استخدامها ويمكن تنفيذها كإجراء لا يؤدي إلى أيّ تأثير.

يتمّ تحديد وظائف الاستدعاء في 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، يحدث حدث خاصية عند تغيير قيمة أو حالة السمة. قيمة SharedMemoryFileCount دائمًا 0.
oneway void onPropertySetError(in VehiclePropErrors errors) رد الاتصال لإعداد تقارير عن أخطاء مجموعة المواقع غير المتزامنة التي لا تحتوي على طلب مجموعة مطابق. إذا عرفنا طلب المجموعة الذي حدث فيه الخطأ، يجب استخدام onSetValues مع نتيجة خطأ بدلاً من ذلك.

لمزيد من المعلومات، يُرجى الاطّلاع علىملف IVehicle.aidl وملف IVehicleCallback.aidl.

يتم التحقّق من صحة تنفيذ VHAL من خلال أداة التحقّق من VHAL VTS فيملف VtsHalAutomotiveVehicle_TargetTest.cpp. يُجري الاختبار التحقّق من تنفيذ الطرق الأساسية بشكل صحيح وصحة إعدادات الموقع المتوافق.

قيمة ممتلكات المركبة

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

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

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

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

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

الشكل 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, 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.
}