इंटरफ़ेस और पैकेज

HIDL को इंटरफ़ेस पर बनाया गया है, जो ऑब्जेक्ट-ओरिएंटेड में इस्तेमाल किया जाने वाला एक ऐब्स्ट्रैक्ट टाइप है भाषाओं का इस्तेमाल करें. हर इंटरफ़ेस किसी पैकेज का हिस्सा होता है.

पैकेज

पैकेज के नाम में सबलेवल के हो सकते हैं, जैसे कि package.subpackage. कॉन्टेंट बनाने पब्लिश किए गए HIDL पैकेज की रूट डायरेक्ट्री hardware/interfaces है या vendor/vendorName (उदाहरण के लिए, Pixel के लिए vendor/google डिवाइसों के हिसाब से). पैकेज का नाम रूट के तहत एक या उससे ज़्यादा सबडायरेक्ट्री बनाता है directory; पैकेज तय करने वाली सभी फ़ाइलें एक ही डायरेक्ट्री में होती हैं. उदाहरण के लिए, package android.hardware.example.extension.light@2.0 मिल सकता है hardware/interfaces/example/extension/light/2.0 से कम.

इस टेबल में पैकेज प्रीफ़िक्स और जगहों की जानकारी दी गई है:

पैकेज का प्रीफ़िक्स	जगह की जानकारी	इंटरफ़ेस के टाइप
android.hardware.*	hardware/interfaces/*	HAL
android.frameworks.*	frameworks/hardware/interfaces/*	फ़्रेमवर्क/ संबंधित
android.system.*	system/hardware/interfaces/*	सिस्टम/ संबंधित
android.hidl.*	system/libhidl/transport/*	कोर

पैकेज डायरेक्ट्री में .hal एक्सटेंशन वाली फ़ाइलें शामिल हैं. कई फ़ाइल में पैकेज का नाम वाला package स्टेटमेंट होना चाहिए और का एक हिस्सा है. types.hal फ़ाइल मौजूद होने पर, यह काम करती है इंटरफ़ेस को परिभाषित नहीं करता है, बल्कि प्रत्येक इंटरफ़ेस पर दिखाई गई है.

इंटरफ़ेस की परिभाषा

types.hal के अलावा, हर दूसरी .hal फ़ाइल एक इंटरफ़ेस. आम तौर पर, इंटरफ़ेस इस तरह परिभाषित किया जाता है:

interface IBar extends IFoo { // IFoo is another interface
    // embedded types
    struct MyStruct {/*...*/};

    // interface methods
    create(int32_t id) generates (MyStruct s);
    close();
};

ऐसा इंटरफ़ेस जिसमें साफ़ तौर पर extends की जानकारी नहीं दी गई है android.hidl.base@1.0::IBase से बढ़ता है (इससे मिलता-जुलता जावा में java.lang.Object.) ज़ाहिर तौर पर, IBase इंटरफ़ेस इंपोर्ट की गई है, जो कई रिज़र्व की गई विधियों की जानकारी देती है. उपयोगकर्ता के हिसाब से बनाए गए इंटरफ़ेस में फिर से एलान किया गया हो या किसी और तरीके से इस्तेमाल किया गया हो. ये तरीके शामिल करें:

• ping
• interfaceChain
• interfaceDescriptor
• notifySyspropsChanged
• linkToDeath
• unlinkToDeath
• setHALInstrumentation
• getDebugInfo
• debug
• getHashChain

इंपोर्ट की प्रोसेस

import स्टेटमेंट, पैकेज को ऐक्सेस करने के लिए HIDL तकनीक है इंटरफ़ेस और किसी अन्य पैकेज में टाइप करता है. import का स्टेटमेंट दो इकाइयों से संबंधित है:

• इंपोर्टिंग इकाई, जो कोई पैकेज या कोई इंटरफ़ेस
• इंपोर्टकी गई इकाई, जो कोई पैकेज या इंटरफ़ेस

इंपोर्ट करने वाली इकाई, इसकी लोकेशन पर निर्भर करती है import स्टेटमेंट. जब स्टेटमेंट किसी पैकेज के अंदर होता है types.hal, जो इंपोर्ट किया जा रहा है वह पूरे पैकेज में दिखता है; यह पैकेज-लेवल इंपोर्ट है. जब स्टेटमेंट इंटरफ़ेस फ़ाइल है, तो इंपोर्ट करने वाली इकाई खुद इंटरफ़ेस होती है; यह एक इंटरफ़ेस-लेवल इंपोर्ट करें.

इंपोर्ट की गई इकाई की वैल्यू, import के बाद की वैल्यू से तय की जाती है कीवर्ड. यह ज़रूरी नहीं है कि वैल्यू पूरी तरह क्वालिफ़ाइड नाम हो; अगर कोई कॉम्पोनेंट शामिल न करने पर, उसमें मौजूदा पैकेज से जुड़ी जानकारी अपने-आप भर जाती है. पूरी तरह क्वालिफ़ाइड वैल्यू के लिए, इंपोर्ट के इन उदाहरणों का इस्तेमाल किया जा सकता है:

• पूरे पैकेज को इंपोर्ट करना. अगर वैल्यू, पैकेज का नाम और वर्शन (नीचे बताया गया सिंटैक्स) का इस्तेमाल करता है, तो पूरा पैकेज आयात करने वाली इकाई.
• कुछ हद तक इंपोर्ट. अगर वैल्यू यह है:
  • एक इंटरफ़ेस, पैकेज का types.hal, और वह इंटरफ़ेस इंपोर्ट करने वाली इकाई में इंपोर्ट किया गया हो.
  • types.hal में तय किया गया UDT है. इसके बाद, सिर्फ़ उसी UDT को इंपोर्ट करने वाली इकाई (types.hal में दूसरी तरह की इकाइयां इंपोर्ट नहीं की जाती हैं).
• टाइप-ओनली इंपोर्ट. अगर मान ऊपर बताया गया आंशिक आयात, लेकिन इसके बजाय types कीवर्ड से इंटरफ़ेस नाम का है, सिर्फ़ types.hal में मौजूद यूडीटी. पैकेज इंपोर्ट किए गए.

इंपोर्ट करने वाली इकाई को इनके कॉम्बिनेशन का ऐक्सेस मिलता है:

• इंपोर्ट किए गए पैकेज के सामान्य यूडीटी, जिनके बारे में types.hal में बताया गया है;
• इंपोर्ट किए गए पैकेज के इंटरफ़ेस (पूरे पैकेज को इंपोर्ट करने के लिए) या इंटरफ़ेस (आंशिक इंपोर्ट के लिए) का इस्तेमाल करता है, ताकि उन्हें शुरू किया जा सके. उन्हें हैंडल करती है और/या उनसे इनहेरिट करती है.

आयात विवरण इंपोर्ट किए जा रहे पैकेज या इंटरफ़ेस का नाम और वर्शन:

import android.hardware.nfc@1.0;            // import a whole package
import android.hardware.example@1.0::IQuux; // import an interface and types.hal
import android.hardware.example@1.0::types; // import just types.hal

इंटरफ़ेस इनहेरिटेंस

इंटरफ़ेस, पहले से तय इंटरफ़ेस का एक्सटेंशन हो सकता है. एक्सटेंशन इन तीन तरह के हो सकते हैं:

• इंटरफ़ेस के एपीआई के साथ ही, इंटरफ़ेस किसी दूसरे फ़ंक्शन में काम कर सकता है कोई बदलाव नहीं.
• पैकेज अपने एपीआई को शामिल करके, दूसरे में फ़ंक्शन जोड़ सकता है कोई बदलाव नहीं.
• इंटरफ़ेस किसी पैकेज या किसी खास इंटरफ़ेस से कई तरह के डेटा इंपोर्ट कर सकता है.

एक इंटरफ़ेस सिर्फ़ एक अन्य इंटरफ़ेस (एक से ज़्यादा इनहेरिटेंस नहीं) को एक्सटेंड कर सकता है. माइनर वर्शन नंबर के अलावा किसी पैकेज में शामिल हर इंटरफ़ेस के लिए इंटरफ़ेस पर पेस्ट किया गया है. उदाहरण के लिए, अगर कोई इंटरफ़ेस derivative पैकेज के वर्शन 4.0 में IBar इस पर आधारित है पैकेज के वर्शन 1.2 में, इंटरफ़ेस IFoo को (एक्सेप्ट करता है) original, और पैकेज original का वर्शन 1.3 है बनाया गया, IBar वर्शन 4.1 इसके वर्शन 1.3 को आगे नहीं बढ़ा सकता IFoo. इसके बजाय, IBar के वर्शन 4.1 के लिए इस सुविधा का इस्तेमाल करना ज़रूरी है IBar वर्शन 4.0, जो IFoo के वर्शन 1.2 से जुड़ा है. IBar वर्शन 5.0, IFoo के वर्शन 1.3 को बढ़ा सकता है, अगर चाहते हैं.

इंटरफ़ेस एक्सटेंशन, लाइब्रेरी डिपेंडेंसी या क्रॉस-एचएएल शामिल करने की अनुमति नहीं देते में बदल दिया जाता है—वे सिर्फ़ डेटा स्ट्रक्चर और तरीके को इंपोर्ट करते हैं HIDL लेवल पर परिभाषाएं. एचएएल में शामिल सभी तरीकों को हैल.

वेंडर एक्सटेंशन

कुछ मामलों में, वेंडर एक्सटेंशन बेस ऑब्जेक्ट जो उस मुख्य इंटरफ़ेस को दिखाता है जिसे वे एक्सपैंड करते हैं. वही ऑब्जेक्ट है को बेस एचएएल नाम और वर्शन के तहत और एक्सटेंशन के तहत रजिस्टर किया जाता है (वेंडर) एचएएल का नाम और उसका वर्शन.

वर्शन

पैकेज के अलग-अलग वर्शन होते हैं और इंटरफ़ेस में उनके पैकेज का वर्शन होता है. वर्शन को दो पूर्णांकों में दिखाया जाता है, major.माइनर.

• मेजर वर्शन, पुराने सिस्टम के साथ काम नहीं करते. बढ़ोतरी हो रही है मेजर वर्शन नंबर, माइनर वर्शन नंबर को 0 पर रीसेट कर देता है.
• माइनर वर्शन, पुराने सिस्टम के साथ काम करता है. बढ़ाना माइनर नंबर का मतलब है कि नया वर्शन, पिछला वर्शन. नए डेटा स्ट्रक्चर और तरीके जोड़े जा सकते हैं, लेकिन कोई मौजूदा डेटा स्ट्रक्चर या मेथड के सिग्नेचर को बदला जा सकता है.

किसी डिवाइस पर एचएएल के कई बड़े या छोटे वर्शन मौजूद हो सकते हैं साथ-साथ हालांकि, मेजर वर्शन की तुलना में माइनर वर्शन को प्राथमिकता दी जानी चाहिए क्योंकि क्लाइंट कोड पिछले माइनर वर्शन इंटरफ़ेस के साथ काम करता है भी उसी इंटरफ़ेस के नए छोटे वर्शन के साथ काम करता है. ज़्यादा के लिए वर्शन और वेंडर एक्सटेंशन की जानकारी देखें, तो HIDL वर्शन.

इंटरफ़ेस के लेआउट की खास जानकारी

इस सेक्शन में, HIDL इंटरफ़ेस पैकेज को मैनेज करने के तरीके के बारे में खास जानकारी दी गई है (जैसे hardware/interfaces) और इसमें दी गई जानकारी को इकट्ठा करता है HIDL सेक्शन में. पढ़ने से पहले, पक्का करें कि आपको HIDL वर्शन, के साथ हैश करना hidl-gen सिद्धांतों, के साथ काम करने की जानकारी सामान्य तौर पर HIDL और ये परिभाषाएं:

शब्द	परिभाषा
ऐप्लिकेशन बाइनरी इंटरफ़ेस (एबीआई)	ऐप्लिकेशन प्रोग्रामिंग इंटरफ़ेस के साथ-साथ बाइनरी लिंकेज होना ज़रूरी है.
पूरी तरह क्वालिफ़ाइड नाम (fqName)	hidl के टाइप में अंतर करने के लिए, उसे नाम दें. उदाहरणः android.hardware.foo@1.0::IFoo.
पैकेज	पैकेज में एक HIDL इंटरफ़ेस और टाइप हैं. उदाहरणः android.hardware.foo@1.0.
पैकेज रूट	HIDL इंटरफ़ेस वाला रूट पैकेज. उदाहरण: HIDL इंटरफ़ेस android.hardware, पैकेज रूट में है android.hardware.foo@1.0.
पैकेज रूट पाथ	Android सोर्स ट्री में वह जगह जहां पैकेज रूट मैप होता है.

ज़्यादा परिभाषाओं के लिए, HIDL देखें शब्दावली.

पैकेज रूट मैपिंग से हर फ़ाइल मिल सकती है और इसका पूरी तरह क्वालिफ़ाइड नाम

पैकेज रूट को तर्क के तौर पर hidl-gen में बताया गया है -r android.hardware:hardware/interfaces. उदाहरण के लिए, अगर पैकेज vendor.awesome.foo@1.0::IFoo और hidl-gen है -r vendor.awesome:some/device/independent/path/interfaces को भेजा गया, तो इंटरफ़ेस फ़ाइल में $ANDROID_BUILD_TOP/some/device/independent/path/interfaces/foo/1.0/IFoo.hal.

हमारा सुझाव है कि awesome नाम वाले वेंडर या OEM को यह सुझाव दिया जाता है में अपने स्टैंडर्ड इंटरफ़ेस शामिल करने के लिए vendor.awesome. पैकेज के बाद पथ चुना गया है, तो इसे बदला नहीं जाना चाहिए, क्योंकि यह इसके एबीआई में बेक किया गया है डालें.

पैकेज पाथ की मैपिंग यूनीक होनी चाहिए

उदाहरण के लिए, अगर आपके पास -rsome.package:$PATH_A और -rsome.package:$PATH_B, $PATH_A इसके बराबर होना चाहिए $PATH_B एक समान इंटरफ़ेस निर्देशिका के लिए (यह भी कई वर्शन वाले इंटरफ़ेस और आसान).

पैकेज रूट में वर्शन वाली फ़ाइल होनी चाहिए

अगर पैकेज पाथ बनाया जाता है, जैसे कि -r vendor.awesome:vendor/awesome/interfaces, आपको भी करना चाहिए फ़ाइल बनाएं $ANDROID_BUILD_TOP/vendor/awesome/interfaces/current.txt, जो इसमें -Lhash विकल्प का इस्तेमाल करके बनाए गए इंटरफ़ेस के हैश होने चाहिए hidl-gen (इस पर विस्तृत रूप से चर्चा की गई है इसके साथ हैशिंग hidl-gen).

चेतावनी: सभी बदलावों को ध्यान से मैनेज करें! विक्रेता टेस्ट सुइट (वीटीएस) तब काम नहीं करता, जब कोई इंटरफ़ेस फ़्रीज़ नहीं किया गया है और इंटरफ़ेस में एबीआई के साथ काम न करने वाले बदलावों की वजह से सिर्फ़ फ़्रेमवर्क-ओनली ओटीए काम नहीं करेंगे.

इंटरफ़ेस डिवाइस-इंडिपेंडेंट में काम करते हैं जगहें

हमारा सुझाव है कि आप अलग-अलग ब्रांच के बीच इंटरफ़ेस शेयर करें. यह अलग-अलग वर्शन में कोड का ज़्यादा से ज़्यादा दोबारा इस्तेमाल और ज़्यादा से ज़्यादा टेस्ट करने की अनुमति देता है और उनके इस्तेमाल के उदाहरण.