एआईडीएल में टिप्पणियां

एआईडीएल एनोटेशन का समर्थन करता है जो एडीएल कंपाइलर को एनोटेटेड तत्व के बारे में अतिरिक्त जानकारी देता है, जो जेनरेट किए गए स्टब कोड को भी प्रभावित करता है।

वाक्यविन्यास जावा के समान है:

@AnnotationName(argument1=value, argument2=value) AidlEntity

यहां, AnnotationName एनोटेशन का नाम है, और AidlEntity एक AIDL इकाई है जैसे interface Foo , void method() , या int arg । इसका अनुसरण करने वाली इकाई से एक एनोटेशन जुड़ा हुआ है।

जैसा कि ऊपर दिखाया गया है, कुछ एनोटेशन में कोष्ठक के अंदर तर्क सेट किए जा सकते हैं। जिन टिप्पणियों में कोई तर्क नहीं है उन्हें कोष्ठक की आवश्यकता नहीं है। उदाहरण के लिए:

@AnnotationName AidlEntity

ये एनोटेशन जावा एनोटेशन के समान नहीं हैं, हालाँकि ये बहुत समान दिखते हैं। उपयोगकर्ता कस्टम एआईडीएल एनोटेशन को परिभाषित नहीं कर सकते; एनोटेशन सभी पूर्व-परिभाषित हैं। कुछ एनोटेशन केवल एक निश्चित बैकएंड को प्रभावित करते हैं और अन्य बैकएंड में नो-ऑप होते हैं। उनके पास अलग-अलग प्रतिबंध हैं जहां उन्हें संलग्न किया जा सकता है।

पूर्व-परिभाषित एआईडीएल एनोटेशन की सूची नीचे दी गई है:

एनोटेशन Android संस्करण में जोड़ा गया
nullable 7
utf8InCpp 7
VintfStability 11
UnsupportedAppUsage 10
Hide 11
Backing 11
NdkOnlyStableParcelable 14
JavaOnlyStableParcelable 11
JavaDerive 12
JavaPassthrough 12
FixedSize 12
Descriptor 12

नल

nullable घोषणा करता है कि एनोटेटेड इकाई का मूल्य प्रदान नहीं किया जा सकता है।

यह एनोटेशन केवल विधि रिटर्न प्रकार, विधि पैरामीटर और पार्सल करने योग्य फ़ील्ड से जुड़ा जा सकता है।

interface IFoo {
    // method return types
    @nullable Data method();

    // method parameters
    void method2(in @nullable Data d);
}

parcelable Data {
    // parcelable fields
    @nullable Data d;
}

एनोटेशन को आदिम प्रकारों से नहीं जोड़ा जा सकता. निम्नलिखित एक त्रुटि है.

void method(in @nullable int a); // int is a primitive type

यह एनोटेशन जावा बैकएंड के लिए नो-ऑप है। ऐसा इसलिए है, क्योंकि जावा में, सभी गैर-आदिम प्रकारों को संदर्भ द्वारा पारित किया जाता है, जो null हो सकता है।

सीपीपी बैकएंड में, @nullable T एंड्रॉइड 11 या उससे नीचे के संस्करण में std::unique_ptr<T> और एंड्रॉइड 12 या उससे ऊपर के संस्करण में std::optional<T> को मैप करता है।

एनडीके बैकएंड में, @nullable T हमेशा std::optional<T> पर मैप होता है।

सूची-जैसे प्रकार L जैसे T[] या List<T> के लिए, @nullable L std::optional<std::vector<std::optional<T>>> (या std::unique_ptr<std::vector<std::unique_ptr<T>>> पर मैप करता है std::unique_ptr<std::vector<std::unique_ptr<T>>> एंड्रॉइड 11 या उससे पहले के सीपीपी बैकएंड के मामले में)।

इस मैपिंग का एक अपवाद है. जब T IBinder या AIDL इंटरफ़ेस है, तो @nullable नो-ऑप है। दूसरे शब्दों में, @nullable IBinder और IBinder दोनों समान रूप से android::sp<IBinder> पर मैप करते हैं, जो पहले से ही अशक्त है क्योंकि यह एक मजबूत सूचक है (CPP पढ़ता है अभी भी अशक्तता को लागू करता है, लेकिन प्रकार अभी भी android::sp<IBinder> है) ).

एंड्रॉइड 13 से शुरुआत करते हुए, पुनरावर्ती प्रकारों को मॉडल करने के लिए पार्सल करने योग्य फ़ील्ड के लिए @nullable(heap=true) उपयोग किया जा सकता है। @nullable(heap=true) उपयोग विधि पैरामीटर या रिटर्न प्रकारों के साथ नहीं किया जा सकता है। जब इसके साथ एनोटेट किया जाता है, तो फ़ील्ड को CPP/NDK बैकएंड में ढेर-आवंटित संदर्भ std::unique_ptr<T> पर मैप किया जाता है। @nullable(heap=true) जावा बैकएंड में नो-ऑप है।

utf8InCpp

utf8InCpp घोषणा करता है कि CPP बैकएंड के लिए एक String UTF8 प्रारूप में दर्शाया गया है। जैसा कि इसके नाम से संकेत मिलता है, एनोटेशन अन्य बैकएंड के लिए नो-ऑप है। विशेष रूप से, String हमेशा जावा बैकएंड में UTF16 और NDK बैकएंड में UTF8 होती है।

इस एनोटेशन को कहीं भी संलग्न किया जा सकता है जहां String प्रकार का उपयोग किया जा सकता है, जिसमें रिटर्न मान, पैरामीटर, निरंतर घोषणाएं और पार्सल करने योग्य फ़ील्ड शामिल हैं।

CPP बैकएंड के लिए, AIDL में @utf8InCpp String std::string पर मैप होती है, जबकि एनोटेशन के बिना String android::String16 पर मैप होती है जहां UTF16 का उपयोग किया जाता है।

ध्यान दें कि utf8InCpp एनोटेशन का अस्तित्व तार पर तारों के संचारित होने के तरीके को नहीं बदलता है। स्ट्रिंग्स को हमेशा तार पर UTF16 के रूप में प्रसारित किया जाता है। एक utf8InCpp एनोटेटेड स्ट्रिंग को प्रसारित होने से पहले UTF16 में बदल दिया जाता है। जब एक स्ट्रिंग प्राप्त होती है, तो इसे UTF16 से UTF8 में परिवर्तित कर दिया जाता है यदि इसे utf8InCpp के रूप में एनोटेट किया गया हो।

विन्टफ़स्टेबिलिटी

VintfStability घोषित करती है कि उपयोगकर्ता-परिभाषित प्रकार (इंटरफ़ेस, पार्सलेबल और एनम) का उपयोग सिस्टम और विक्रेता डोमेन में किया जा सकता है। सिस्टम-विक्रेता इंटरऑपरेबिलिटी के बारे में अधिक जानकारी के लिए एचएएल के लिए एआईडीएल देखें।

एनोटेशन प्रकार के हस्ताक्षर को नहीं बदलता है, लेकिन जब इसे सेट किया जाता है, तो प्रकार के उदाहरण को स्थिर के रूप में चिह्नित किया जाता है ताकि यह विक्रेता और सिस्टम प्रक्रियाओं में यात्रा कर सके।

एनोटेशन को केवल उपयोगकर्ता-परिभाषित प्रकार की घोषणाओं से जोड़ा जा सकता है जैसा कि नीचे दिखाया गया है:

@VintfStability
interface IFoo {
    ....
}

@VintfStability
parcelable Data {
    ....
}

@VintfStability
enum Type {
    ....
}

जब किसी प्रकार को VintfStability के साथ एनोटेट किया जाता है, तो उस प्रकार में संदर्भित किसी अन्य प्रकार को भी उसी रूप में एनोटेट किया जाना चाहिए। नीचे दिए गए उदाहरण में, Data और IBar दोनों को VintfStability के साथ एनोटेट किया जाना चाहिए।

@VintfStability
interface IFoo {
    void doSomething(in IBar b); // references IBar
    void doAnother(in Data d); // references Data
}

@VintfStability // required
interface IBar {...}

@VintfStability // required
parcelable Data {...}

इसके अलावा, VintfStability के साथ एनोटेट किए गए प्रकारों को परिभाषित करने वाली एआईडीएल फाइलें केवल aidl_interface सूंग मॉड्यूल प्रकार का उपयोग करके बनाई जा सकती हैं, जिसमें stability संपत्ति "vintf" पर सेट होती है।

aidl_interface {
    name: "my_interface",
    srcs: [...],
    stability: "vintf",
}

असमर्थित ऐप उपयोग

UnsupportedAppUsage एनोटेशन दर्शाता है कि एनोटेटेड AIDL प्रकार गैर-एसडीके इंटरफ़ेस का हिस्सा है जो लीगेसी ऐप्स के लिए पहुंच योग्य है। छिपे हुए एपीआई के बारे में अधिक जानकारी के लिए गैर-एसडीके इंटरफेस पर प्रतिबंध देखें।

UnsupportedAppUsage एनोटेशन जनरेट किए गए कोड के व्यवहार को प्रभावित नहीं करता है। एनोटेशन केवल उसी नाम के जावा एनोटेशन के साथ उत्पन्न जावा क्लास को एनोटेट करता है।

// in AIDL
@UnsupportedAppUsage
interface IFoo {...}

// in Java
@android.compat.annotation.UnsupportedAppUsage
public interface IFoo {...}

यह गैर-जावा बैकएंड के लिए नो-ऑप है।

समर्थन

Backing एनोटेशन एआईडीएल एनम प्रकार के भंडारण प्रकार को निर्दिष्ट करता है।

@Backing(type="int")
enum Color { RED, BLUE, }

सीपीपी बैकएंड में, उपरोक्त int32_t प्रकार का C++ एनम वर्ग उत्सर्जित करता है।

enum class Color : int32_t {
    RED = 0,
    BLUE = 1,
}

यदि एनोटेशन छोड़ दिया जाता है, type को byte माना जाता है, जो सीपीपी बैकएंड के लिए int8_t पर मैप होता है।

type तर्क केवल निम्नलिखित अभिन्न प्रकारों पर सेट किया जा सकता है:

  • byte (8-बिट चौड़ा)
  • int (32-बिट चौड़ा)
  • long (64-बिट चौड़ा)

एनडीकेओनलीस्टेबलपार्सलेबल

NdkOnlyStableParcelable एक पार्सल योग्य घोषणा (परिभाषा नहीं) को स्थिर के रूप में चिह्नित करता है ताकि इसे अन्य स्थिर AIDL प्रकारों से संदर्भित किया जा सके। यह JavaOnlyStableParcelable की तरह है, लेकिन NdkOnlyStableParcelable जावा के बजाय NDK बैकएंड के लिए पार्सल योग्य घोषणा को स्थिर के रूप में चिह्नित करता है।

इस पार्सलेबल का उपयोग करने के लिए: * आपको ndk_header निर्दिष्ट करना होगा। * आपके पास पार्सल योग्य निर्दिष्ट करने वाली एक एनडीके लाइब्रेरी होनी चाहिए और लाइब्रेरी को लाइब्रेरी में संकलित किया जाना चाहिए। उदाहरण के लिए, cc_* मॉड्यूल पर कोर बिल्ड सिस्टम में, static_libs या shared_libs उपयोग करें। aidl_interface के लिए, Android.bp में additional_shared_libraries के अंतर्गत लाइब्रेरी जोड़ें।

JavaOnlyStableParcelable

JavaOnlyStableParcelable एक पार्सल योग्य घोषणा (परिभाषा नहीं) को स्थिर के रूप में चिह्नित करता है ताकि इसे अन्य स्थिर AIDL प्रकारों से संदर्भित किया जा सके।

स्थिर एआईडीएल के लिए आवश्यक है कि सभी उपयोगकर्ता-परिभाषित प्रकार स्थिर हों। पार्सलेबल्स के लिए, स्थिर होने के लिए आवश्यक है कि इसके फ़ील्ड एआईडीएल स्रोत फ़ाइल में स्पष्ट रूप से वर्णित हों।

parcelable Data { // Data is a structured parcelable.
    int x;
    int y;
}

parcelable AnotherData { // AnotherData is also a structured parcelable
    Data d; // OK, because Data is a structured parcelable
}

यदि पार्सल योग्य असंरचित था (या बस घोषित किया गया था), तो इसे संदर्भित नहीं किया जा सकता है।

parcelable Data; // Data is NOT a structured parcelable

parcelable AnotherData {
    Data d; // Error
}

JavaOnlyStableParcelable आपको चेक को ओवरराइड करने की सुविधा देता है जब आप जिस पार्सलेबल का संदर्भ ले रहे हैं वह एंड्रॉइड एसडीके के हिस्से के रूप में पहले से ही सुरक्षित रूप से उपलब्ध है।

@JavaOnlyStableParcelable
parcelable Data;

parcelable AnotherData {
    Data d; // OK
}

JavaDeriv

JavaDerive स्वचालित रूप से जावा बैकएंड में पार्सल योग्य प्रकारों के लिए तरीके उत्पन्न करता है।

@JavaDerive(equals = true, toString = true)
parcelable Data {
  int number;
  String str;
}

क्या उत्पन्न करना है इसे नियंत्रित करने के लिए एनोटेशन को अतिरिक्त पैरामीटर की आवश्यकता होती है। समर्थित पैरामीटर हैं:

  • equals=true equals और hashCode विधियाँ उत्पन्न करता है।
  • toString=true toString विधि उत्पन्न करता है जो प्रकार और फ़ील्ड का नाम प्रिंट करता है। उदाहरण के लिए: Data{number: 42, str: foo}

JavaDefault

Android 13 में जोड़ा गया JavaDefault यह नियंत्रित करता है कि डिफ़ॉल्ट कार्यान्वयन संस्करण समर्थन उत्पन्न होता है या नहीं ( setDefaultImpl के लिए)। स्थान बचाने के लिए यह समर्थन अब डिफ़ॉल्ट रूप से उत्पन्न नहीं होता है।

जावापासथ्रू

JavaPassthrough उत्पन्न जावा एपीआई को एक मनमाने जावा एनोटेशन के साथ एनोटेट करने की सुविधा देता है।

एआईडीएल में निम्नलिखित एनोटेशन

@JavaPassthrough(annotation="@android.annotation.Alice")
@JavaPassthrough(annotation="@com.android.Alice(arg=com.android.Alice.Value.A)")

बनना

@android.annotation.Alice
@com.android.Alice(arg=com.android.Alice.Value.A)

उत्पन्न जावा कोड में।

annotation पैरामीटर का मान सीधे उत्सर्जित होता है। एआईडीएल कंपाइलर पैरामीटर के मान पर ध्यान नहीं देता है। यदि कोई जावा-स्तरीय सिंटैक्स त्रुटि है, तो इसे एआईडीएल कंपाइलर द्वारा नहीं बल्कि जावा कंपाइलर द्वारा पकड़ा जाएगा।

यह एनोटेशन किसी भी एआईडीएल इकाई से जोड़ा जा सकता है। यह एनोटेशन गैर-जावा बैकएंड के लिए नो-ऑप है।

निर्धारित माप

FixedSize एक संरचित पार्सल योग्य को निश्चित आकार के रूप में चिह्नित करता है। एक बार चिह्नित होने के बाद, पार्सलेबल को इसमें नए फ़ील्ड जोड़ने की अनुमति नहीं दी जाएगी। पार्सल करने योग्य के सभी फ़ील्ड भी निश्चित आकार के प्रकार के होने चाहिए, जिनमें आदिम प्रकार, एनम, निश्चित आकार के सरणियाँ और FixedSize के साथ चिह्नित अन्य पार्सल योग्य चीजें शामिल हैं।

यह विभिन्न बिटनेस पर कोई गारंटी नहीं देता है और मिश्रित-बिटनेस संचार के लिए इस पर भरोसा नहीं किया जाना चाहिए।

डिस्क्रिप्टर

Descriptor किसी इंटरफ़ेस के इंटरफ़ेस डिस्क्रिप्टर को जबरन निर्दिष्ट करता है।

package android.foo;

@Descriptor(value="android.bar.IWorld")
interface IHello {...}

उपरोक्त इंटरफ़ेस का डिस्क्रिप्टर android.bar.IWorld है। यदि Descriptor एनोटेशन गायब है, तो डिस्क्रिप्टर android.foo.IHello होगा।

यह पहले से प्रकाशित इंटरफ़ेस का नाम बदलने के लिए उपयोगी है। पुनर्नामित इंटरफ़ेस के डिस्क्रिप्टर को नाम बदलने से पहले इंटरफ़ेस के डिस्क्रिप्टर के समान बनाने से दोनों इंटरफ़ेस एक-दूसरे से बात कर सकते हैं।

@टिप्पणियों में छिपाएँ

एआईडीएल कंपाइलर टिप्पणियों में @hide पहचानता है और मेटालावा को पिकअप के लिए जावा आउटपुट के माध्यम से भेजता है। यह टिप्पणी सुनिश्चित करती है कि एंड्रॉइड बिल्ड सिस्टम जानता है कि एआईडीएल एपीआई एसडीके एपीआई नहीं हैं।

@टिप्पणियों में निंदा की गई

एआईडीएल कंपाइलर एआईडीएल इकाई की पहचान करने के लिए टिप्पणियों में @deprecated एक टैग के रूप में पहचानता है जिसका अब उपयोग नहीं किया जाना चाहिए।

interface IFoo {
  /** @deprecated use bar() instead */
  void foo();
  void bar();
}

प्रत्येक बैकएंड एक बैकएंड-विशिष्ट एनोटेशन/विशेषता के साथ अप्रचलित इकाइयों को चिह्नित करता है ताकि क्लाइंट कोड को चेतावनी दी जा सके यदि वह अप्रचलित इकाइयों को संदर्भित करता है। उदाहरण के लिए, @Deprecated एनोटेशन और @deprecated टैग जावा जनरेट किए गए कोड से जुड़े हुए हैं।