एआईडीएल एनोटेशन का समर्थन करता है जो एडीएल कंपाइलर को एनोटेटेड तत्व के बारे में अतिरिक्त जानकारी देता है, जो जेनरेट किए गए स्टब कोड को भी प्रभावित करता है।
वाक्यविन्यास जावा के समान है:
@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
टैग जावा जनरेट किए गए कोड से जुड़े हुए हैं।