Annotationen in AIDL

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 Sie static_libs oder shared_libs. Für aidl_interface hinzufügen der Bibliothek unter additional_shared_libraries in Android.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 Methoden equals und hashCode.
• toString=true generiert die toString-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.