الدوال

يتم ربط الدوال في واجهة HIDL بالطرق في واجهة برمجة التطبيقات التي يتم إنشاؤها تلقائيًا. بيان واحد (IFoo) من فئة C++ يظل اسم كل دالة هو نفسه في C++؛ تصف الأقسام التالية كيفية عرض وسيطات HIDL تتم ترجمة القيم إلى C++.

معلمات الدالة

يتم ربط الوسيطات المدرَجة في ملف .hal بأنواع بيانات C++. يتم تمرير الوسيطات التي لا يتم تعيينها إلى نوع C++ أساسي من خلال الثابت المرجع.

لكل دالة HIDL التي لها قيمة معروضة (تحتوي على generates )، تحتوي قائمة المعلمات C++ لهذه الدالة على وسيطة إضافية: دالة استدعاء يتم استدعاؤها بالقيم المعروضة لدالة HIDL. هناك استثناء واحد: إذا كانت عبارة generates يحتوي على معلمة واحدة يتم تعيينها مباشرةً إلى أساسي C++، استدعاء يتم استخدام الحذف (تتم إزالة الاستدعاء وتكون القيمة المعروضة يتم إرجاعه من الدالة من خلال عبارة return عادية).

القيم التي تعرضها الدالة

الدوال التالية لها قيم إرجاع.

أخطاء النقل ونوع الإرجاع

يمكن أن تؤدي عبارة generates إلى ثلاثة أنواع من الدوال التوقيعات:

• للحصول على قيمة معروضة واحدة فقط تمثل أحد مبادئ C++ الأساسية، يتم عرض generates القيمة المعروضة من خلال القيمة من الدالة في كائن Return<T>.
• في الحالات الأكثر تعقيدًا، تكون القيم المعروضة generates هي من خلال معلمة معاودة الاتصال المتوفرة مع استدعاء الدالة نفسها، وتُرجع الدالة Return<void>.
• في حال عدم وجود عبارة generates، تعرض الدالة Return<void>

قد تواجه استدعاءات استدعاء إجراء عن بُعد (RPC) أحيانًا أخطاء في النقل، على سبيل المثال: عندما يبدأ الخادم أو الوفاة، أو عندما تكون موارد النقل غير كافية لإكمال الاتصال، أو عندما المعلمات التي تم تمريرها لا تسمح بإكمال الاتصال (مثل عدم وجود دالة معاودة الاتصال المطلوبة). حدث خطأ في نقل عنصرَين (Return) إلى المتجر. بالإضافة إلى قيمة T (باستثناء Return<void>).

نظرًا لأن الدوال من جانب العميل والدالّة من جانب الخادم لهما التوقيع نفسه، يجب أن تعرض الدالة جانب الخادم النوع Return على الرغم من التنفيذ لا يشير إلى أخطاء النقل. Return<T> يتم إنشاء الكائنات باستخدام Return(myTValue) (أو يمكن أن تكون ضمنيًا تم إنشاؤها من mTValue، مثل return العبارات) وReturn<void> يتم إنشاء العناصر باستخدام Void()

يحتوي Return<T> عنصر على إحالة ناجحة ضمنية من وإلى قيمتها T. يمكن التحقّق من الكائن Return أخطاء النقل من خلال استدعاء طريقة isOk(). عملية التحقّق هذه ليست مطلوبة؛ ومع ذلك، إذا حدث خطأ ولم يتم التحقق منه بحلول الوقت تلف عنصر واحد (Return) أو تم تحويل قيمة T تمت محاولة إجرائها، فسيتم إنهاء عملية العميل وسيتم تسجيل خطأ. في حال حذف تشير القيمة isOk() إلى خطأ في النقل أو تعذُّر الاتصال بسبب أحد الأسباب. خطأ في رمز المطوّر (مثل تمرير nullptr كرمز متزامن معاودة الاتصال)، فيمكن استدعاء description() في كائن Return إلى لإرجاع سلسلة مناسبة للتسجيل. في مثل هذه الحالات، لا توجد طريقة تحديد مقدار التعليمات البرمجية التي يمكن تنفيذها على الخادم نتيجة تعذّر الاتصال. يتم توفير الطريقة isDeadObject() أيضًا. هذا النمط إلى أن !isOk() يرجع إلى أن الكائن البعيد أو تعطلت أو لم تعد موجودة. يشير isDeadObject() دائمًا إلى !isOk()

العرض حسب القيمة

إذا كانت عبارة generates مرتبطة بأساسي C++ واحد، لا في قائمة المَعلمات. بدلاً من ذلك، يوفر التنفيذ القيمة المعروضة T في الكائن Return<T>، والتي يمكن إنشاؤها ضمنيًا من النوع الأساسي T. بالنسبة مثال:

Return<uint32_t> someMethod() {
    uint32_t return_data = ...; // Compute return_data
    return return_data;
};

يتم توفير الطريقة Return<*>::withDefault أيضًا. هذا النمط قيمة في الحالات التي تكون فيها القيمة المعروضة هي !isOk(). تضع هذه الطريقة أيضًا علامة تلقائية على الكائن الإرجاع على أنه "موافق" حتى يتمكن العميل لن يتم إنهاء العملية.

الإرجاع باستخدام مَعلمة معاودة الاتصال

يمكن أن يمرّر معاودة الاتصال قيمة إرجاع دالة HIDL إلى المتصل. النموذج الأولي لرد الاتصال هو كائن std::function ذو المعلمات (المأخوذة من عبارة generates) التي تم ربطها بـ C++ الأنواع. قيمتها المعروضة باطلة - ولن تكون معاودة الاتصال نفسها تُرجع قيمة.

تكون القيمة المعروضة لدالة C++ مع معلَمة استدعاء من نوع Return<void> يكون تنفيذ الخادم مسؤولاً فقط عن تقديم القيمة المعروضة بما أنّه سبق أن تم نقل القيم المعروضة باستخدام طلب الاستدعاء، تكون معلمة النموذج T هي void:

Return<void> someMethod(someMethod_cb _cb);

من تطبيق C++ الخاص بهم، يجب أن تعرض عمليات تنفيذ الخادم Void()، وهي دالة ثابتة مضمَّنة تعرض كائن Return<void>. مثال على طريقة نموذجية للخادم التنفيذ باستخدام معلَمة معاودة الاتصال:

Return<void> someMethod(someMethod_cb _cb) {
    // Do some processing, then call callback with return data
    hidl_vec<uint32_t> vec = ...
    _cb(vec);
    return Void();
};

دوال بدون قيم إرجاع

توقيع C++ لدالة بدون عبارة generates على مَعلمة رد اتصال في قائمة المَعلمات. سيبدأ نوع الإرجاع سيكون Return<void>.

الدوال الأحادية

الدوال التي تم وضع علامة عليها مع الكلمة الرئيسية oneway غير متزامنة. الدوال (لن يحظر العملاء عند تنفيذها) ولا يكون لديهم القيم. لن يكون توقيع C++ لدالة oneway على في قائمة المعلَمات، وستكون قيمة إرجاع C++ لها Return<void>