AIDL unterstützt Annotationen, die dem AIDL-Compiler zusätzliche Informationen liefern über das annotierte Element, was sich auch auf den generierten Stub-Code auswirkt.
Die Syntax ähnelt der von Java:
@AnnotationName(argument1=value, argument2=value) AidlEntity
Hier ist AnnotationName
der Name der Anmerkung und AidlEntity
ist
Eine AIDL-Entität wie interface Foo
, void method()
oder int arg
. Eine
-Anmerkung an die folgende Entität angehängt.
Bei einigen Anmerkungen können Argumente in Klammern gesetzt werden, wie oben gezeigt. Anmerkungen, die kein Argument enthalten, benötigen keine Klammer. Beispiel:
@AnnotationName AidlEntity
Diese Annotationen sind nicht mit der Java- -Anmerkungen, obwohl sie sehr ähnlich aussehen. Nutzer können keine benutzerdefinierte AIDL definieren Anmerkungen; Alle Anmerkungen sind vordefiniert. Einige Anmerkungen betreffen nur einem bestimmten Back-End und sind bei anderen Back-Ends fehlerfrei. Sie haben unterschiedliche Einschränkungen hinzugefügt werden können.
Hier ist die Liste der vordefinierten AIDL-Annotationen:
Anmerkungen | In Android-Version hinzugefügt |
---|---|
nullable |
7 |
utf8InCpp |
7 |
VintfStability |
11 |
UnsupportedAppUsage |
10 |
Hide |
11 |
Backing |
11 |
NdkOnlyStableParcelable |
14 |
JavaOnlyStableParcelable |
11 |
JavaDerive |
12 |
JavaPassthrough |
12 |
FixedSize |
12 |
Descriptor |
12 |
Nullwerte zulässig
nullable
gibt an, dass der Wert der annotierten Entität nicht angegeben werden darf.
Diese Annotation kann nur an Methodenrückgabetypen, Methodenparameter, und Parcelable-Felder.
interface IFoo {
// method return types
@nullable Data method();
// method parameters
void method2(in @nullable Data d);
}
parcelable Data {
// parcelable fields
@nullable Data d;
}
An primitive Typen können keine Anmerkungen angehängt werden. Folgendes ist ein Fehler.
void method(in @nullable int a); // int is a primitive type
Diese Annotation ist für das Java-Back-End managementfrei. Das liegt daran, dass in Java
nicht-primitive Typen werden durch einen Verweis übergeben, der null
sein kann.
Im CPP-Back-End wird @nullable T
der std::unique_ptr<T>
in Android zugeordnet.
11 oder niedriger und unter Android auf std::optional<T>
12 oder höher.
Im NDK-Back-End wird @nullable T
immer std::optional<T>
zugeordnet.
Für einen listenähnlichen Typ L
wie T[]
oder List<T>
wird @nullable L
std::optional<std::vector<std::optional<T>>>
(oder
std::unique_ptr<std::vector<std::unique_ptr<T>>>
für das CPP-Backend
für Android 11 oder niedriger).
Für diese Zuordnung gibt es eine Ausnahme. Wenn T
IBinder
oder eine AIDL-Schnittstelle ist, ist @nullable
ein Nullbetrieb. Mit anderen Worten: Beide
@nullable IBinder
und IBinder
sind gleichermaßen android::sp<IBinder>
zugeordnet, was
ist bereits für Nullwerte zulässig, da es ein starker Zeiger ist (CPP-Lesevorgänge
Erzwingen der Null-Zulässigkeit, aber der Typ ist immer noch android::sp<IBinder>
).
Ab Android 13 kann @nullable(heap=true)
verwendet werden für
parzellierbare Felder zur Modellierung rekursiver Typen. @nullable(heap=true)
kann nicht verwendet werden
mit Methodenparametern
oder Rückgabetypen. Wenn das Feld damit annotiert ist,
einer Heap-zugewiesenen Referenz std::unique_ptr<T>
in der CPP/NDK zugeordnet
Back-Ends. @nullable(heap=true)
ist im Java-Back-End managementfrei.
utf8InCpp
utf8InCpp
deklariert, dass ein String
für die CPP im UTF8-Format dargestellt wird.
Back-End. Wie der Name schon sagt, ist die Annotation eine Nulloperation für andere Back-Ends.
Insbesondere ist String
im Java-Back-End immer UTF16 und im NDK UTF8.
Back-End.
Diese Anmerkung kann überall dort hinzugefügt werden, wo der Typ String
verwendet werden kann,
einschließlich Rückgabewerten, Parametern, Konstantendeklarationen und
.
Für das CPP-Back-End wird @utf8InCpp String
in AIDL std::string
zugeordnet.
String
ohne Annotation wird android::String16
zugeordnet, wobei UTF16 verwendet wird.
Hinweis: Das Vorhandensein der Anmerkung utf8InCpp
ändert nichts an der Art und Weise,
werden über das Kabel übertragen. Strings werden immer als UTF16 übertragen
über das Kabel. Ein mit utf8InCpp
annotierter String wird vor der Übernahme in UTF16 konvertiert.
übertragen werden. Wenn ein String empfangen wird, wird er von UTF16 in UTF8 konvertiert, sofern
wurde als utf8InCpp
gekennzeichnet.
vintfStabilität
VintfStability
deklariert, dass ein benutzerdefinierter Typ (Schnittstelle, Paket,
und enum) können in allen System- und Anbieterdomains verwendet werden. Weitere Informationen finden Sie unter
AIDL für HALs
System-Anbieter-Interoperabilität.
Die Annotation ändert nicht die Signatur des Typs, aber wenn sie festgelegt ist, wird die Instanz des Typs als stabil markiert, damit sie Zulieferunternehmen und Systemprozesse.
Die Anmerkung kann nur an benutzerdefinierte Typdeklarationen angehängt werden, wie hier gezeigt. hier:
@VintfStability
interface IFoo {
....
}
@VintfStability
parcelable Data {
....
}
@VintfStability
enum Type {
....
}
Wenn ein Typ mit VintfStability
annotiert ist, kann jeder andere Typ, der
auf die im Typ verwiesen wird, sollten auch als solche annotiert werden. Im Folgenden
Beispiel: Data
und IBar
sollten beide mit VintfStability
annotiert werden.
@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 {...}
Außerdem werden die AIDL-Dateien, die mit VintfStability
annotierte Typen definiert sind,
kann nur mit dem aidl_interface
-Soong-Modultyp erstellt werden, wobei die
Die Eigenschaft stability
wurde auf "vintf"
festgelegt.
aidl_interface {
name: "my_interface",
srcs: [...],
stability: "vintf",
}
Nicht unterstützte App-Nutzung
Die Annotation UnsupportedAppUsage
gibt an, dass der annotierte AIDL-Typ
Teil der Nicht-SDK-Oberfläche, auf den auch ältere Apps zugreifen können.
Siehe Einschränkungen für Nicht-SDKs
Benutzeroberflächen
finden Sie weitere Informationen zu den verborgenen APIs.
Die Anmerkung UnsupportedAppUsage
wirkt sich nicht auf das Verhalten des
generiertem Code. Die Annotation annotiert nur die generierte Java-Klasse mit dem
Java-Annotation mit demselben Namen.
// in AIDL
@UnsupportedAppUsage
interface IFoo {...}
// in Java
@android.compat.annotation.UnsupportedAppUsage
public interface IFoo {...}
Dies ist ein No-Op für Nicht-Java-Back-Ends.
Rückenlehnen
Die Annotation Backing
gibt den Speichertyp eines AIDL-Enum-Typs an.
@Backing(type="int")
enum Color { RED, BLUE, }
Im CPP-Back-End gibt dies eine C++-Enum-Klasse vom Typ int32_t
aus.
enum class Color : int32_t {
RED = 0,
BLUE = 1,
}
Wenn die Anmerkung weggelassen wird, wird für type
angenommen, dass es sich um byte
handelt, was die Zuordnung
int8_t
für das CPP-Back-End.
Das Argument type
kann nur auf die folgenden ganzzahligen Typen festgelegt werden:
byte
(8-Bit-Breite)int
(32-Bit-Breite)long
(64-Bit-Breite)
NdkOnlyStableParcelable
NdkOnlyStableParcelable
kennzeichnet eine Parzellendeklaration (keine Definition)
als stabil, damit von anderen stabilen AIDL-Typen darauf verwiesen werden kann. Dieses
entspricht JavaOnlyStableParcelable
, aber
NdkOnlyStableParcelable
kennzeichnet eine Deklaration für Pakete als stabil für das NDK.
Back-End anstelle von Java.
So verwenden Sie dieses Paket:
- Sie müssen
ndk_header
angeben. - Sie benötigen eine NDK-Bibliothek, die das Paket angibt, und die Bibliothek muss
in die Bibliothek kompiliert werden. Im Core-Build-System auf einer
Modul
cc_*
, verwenden Siestatic_libs
odershared_libs
. Füraidl_interface
hinzufügen der Bibliothek unteradditional_shared_libraries
inAndroid.bp
.
JavaOnlyStableParcelable
JavaOnlyStableParcelable
kennzeichnet eine Parzellendeklaration (keine Definition)
als stabil, damit von anderen stabilen AIDL-Typen darauf verwiesen werden kann.
Für den stabilen AIDL müssen alle benutzerdefinierten Typen stabil sein. Für parcelables sind, erfordert die Stabilität, dass die Felder explizit in Die AIDL-Quelldatei
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
}
Wenn das Paket unstrukturiert (oder gerade deklariert) war, kann es nicht auf die verwiesen wird.
parcelable Data; // Data is NOT a structured parcelable
parcelable AnotherData {
Data d; // Error
}
Mit JavaOnlyStableParcelable
können Sie die Prüfung überschreiben, wenn das Paket
Sie verweisen, ist bereits im Android SDK sicher verfügbar.
@JavaOnlyStableParcelable
parcelable Data;
parcelable AnotherData {
Data d; // OK
}
JavaDerive
JavaDerive
generiert automatisch Methoden für Parcelable-Typen im
Java-Back-End.
@JavaDerive(equals = true, toString = true)
parcelable Data {
int number;
String str;
}
Die Anmerkung erfordert zusätzliche Parameter, um zu steuern, was generieren. Folgende Parameter werden unterstützt:
equals=true
generiert die Methodenequals
undhashCode
.toString=true
generiert dietoString
-Methode, die den Namen des Typs ausgibt. und Felder. Beispiel:Data{number: 42, str: foo}
JavaStandard
JavaDefault
, in Android 13 hinzugefügt, steuert,
wird die standardmäßige Implementierungsversionierung generiert (für
setDefaultImpl
). Diese Unterstützung wird nicht mehr standardmäßig generiert, um
um Platz zu sparen.
JavaPassthrough
Mit JavaPassthrough
kann die generierte Java API mit einer beliebigen
Java-Annotation.
Die folgenden Annotationen in AIDL
@JavaPassthrough(annotation="@android.annotation.Alice")
@JavaPassthrough(annotation="@com.android.Alice(arg=com.android.Alice.Value.A)")
werden
@android.annotation.Alice
@com.android.Alice(arg=com.android.Alice.Value.A)
im generierten Java-Code ein.
Der Wert des Parameters annotation
wird direkt ausgegeben. AIDL
prüft den Wert des Parameters nicht. Falls es welche gibt,
Syntaxfehler auf Java-Ebene, wird nicht vom AIDL-Compiler, sondern vom
Java-Compiler.
Diese Annotation kann an jede AIDL-Entität angehängt werden. Diese Anmerkung ist eine Nulloperation für Nicht-Java-Back-Ends.
Feste Größe
FixedSize
kennzeichnet ein strukturiertes Flurstück als feste Größe. Nach der Markierung
dem Attribut „parcelable“ keine neuen Felder hinzugefügt werden. Alle Felder von
muss das Paket auch
feste Größe haben, u. a. primitive Typen,
Enums, Arrays mit fester Größe und andere Parcelables, die mit FixedSize
gekennzeichnet sind.
Das ist keine Garantie für verschiedene Bits und sollte auf die Kommunikation mit unterschiedlichen Bits anwenden.
Beschreibung
Descriptor
gibt zwangsweise den Schnittstellendeskriptor einer Schnittstelle an.
package android.foo;
@Descriptor(value="android.bar.IWorld")
interface IHello {...}
Der Deskriptor dieser Schnittstelle ist android.bar.IWorld
. Wenn die
Descriptor
-Anmerkung fehlt, wäre der Deskriptor
android.foo.IHello
.
Dies ist hilfreich, wenn Sie eine bereits veröffentlichte Schnittstelle umbenennen möchten. Die Beschreibung der umbenannten Schnittstelle ist mit der Beschreibung der Schnittstelle identisch bevor die Umbenennung erfolgt, können die beiden Schnittstellen miteinander kommunizieren.
In Kommentaren @ausblenden
Der AIDL-Compiler erkennt @hide
in Kommentaren und übergibt ihn
in die Java-Ausgabe, damit Metalava Abholung möglich ist. Durch diesen Kommentar wird sichergestellt,
dass AIDL APIs keine SDK-APIs sind.
@eingestellt in Kommentaren
Der AIDL-Compiler erkennt @deprecated
in Kommentaren als Tag zur Identifizierung eines
AIDL-Entität, die nicht mehr verwendet werden sollte.
interface IFoo {
/** @deprecated use bar() instead */
void foo();
void bar();
}
Jedes Backend markiert verworfene Entitäten mit einer Backend-spezifischen Annotation oder
, sodass der Clientcode gewarnt wird, wenn er auf die eingestellte
Entitäten. Zum Beispiel die Annotation @Deprecated
und die @deprecated
-Tags an den Java-generierten Code angehängt werden.