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

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

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

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

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

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

@AnnotationName AidlEntity

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

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

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

नोट: एआईडीएल कंपाइलर टिप्पणियों में @hide और @deprecated को पार्स करता है।

नल

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> std::optional<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>>> एंड्रॉइड 11 या उससे कम के सीपीपी बैकएंड के मामले में)।

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

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

utf8InCpp

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

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

CPP बैकएंड के लिए, @utf8InCpp String AIDL मैप्स में 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 प्रकार गैर-SDK इंटरफ़ेस का हिस्सा है जिसे लीगेसी ऐप्स के लिए एक्सेस किया जा सकता है। छिपे हुए एपीआई के बारे में अधिक जानकारी के लिए गैर-एसडीके इंटरफेस पर प्रतिबंध देखें।

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

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

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

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

समर्थन

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

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

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

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

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

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

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

JavaOnlyStableParcelable

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

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

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 आपको चेक को ओवरराइड करने देता है जब आपके द्वारा संदर्भित पार्सल योग्य Android SDK के हिस्से के रूप में पहले से ही सुरक्षित रूप से उपलब्ध हो।

@JavaOnlyStableParcelable
parcelable Data;

parcelable AnotherData {
    Data d; // OK
}

जावाडेरिव

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

@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 में जोड़ा गया है, यह नियंत्रित करता है कि क्या डिफ़ॉल्ट कार्यान्वयन संस्करण समर्थन उत्पन्न होता है ( setDefaultImpl के लिए)। स्थान बचाने के लिए यह समर्थन अब डिफ़ॉल्ट रूप से उत्पन्न नहीं होता है।

जावापासथ्रू

JavaPassthrough जेनरेट किए गए Java API को मनमाने ढंग से Java एनोटेशन के साथ एनोटेट करने देता है।

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

@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 को पहचानता है और इसे मेटलवा से पिकअप के लिए जावा आउटपुट में भेजता है। यह टिप्पणी सुनिश्चित करती है कि एंड्रॉइड बिल्ड सिस्टम जानता है कि एआईडीएल एपीआई एसडीके एपीआई नहीं हैं।

@टिप्पणियों में पदावनत

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

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

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