Annotations dans AIDL

AIDL prend en charge les annotations qui donnent au compilateur AIDL des informations supplémentaires sur l'élément annoté, ce qui affecte également le code du bouchon généré.

La syntaxe est semblable à celle de Java:

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

Ici, AnnotationName est le nom de l'annotation, et AidlEntity correspond à une entité AIDL telle que interface Foo, void method() ou int arg. Une est attachée à l'entité qui la suit.

Certaines annotations peuvent avoir des arguments définis entre parenthèses, comme indiqué ci-dessus. Les parenthèses sans argument ne sont pas nécessaires pour les annotations qui n'ont pas d'argument. Exemple :

@AnnotationName AidlEntity

Ces annotations ne sont pas les mêmes que les annotations des annotations, bien qu'elles semblent très similaires. Les utilisateurs ne peuvent pas définir d'AIDL personnalisé les annotations ; les annotations sont toutes prédéfinies. Certaines annotations concernent uniquement un backend donné et qu'aucune opération n'est effectuée dans d'autres backends. Ils ont différentes et des restrictions auxquelles elles peuvent être associées.

Voici la liste des annotations AIDL prédéfinies:

Annotations	Ajouté à la version 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

pouvant avoir une valeur nulle

nullable déclare que la valeur de l'entité annotée ne peut pas être fournie.

Cette annotation ne peut être associée qu'aux types renvoyés, paramètres de méthode et parcelables.

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

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

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

Les annotations ne peuvent pas être associées à des types primitifs. Voici une erreur.

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

Cette annotation est no-op pour le backend Java. En effet, en Java, toutes Les types non primitifs sont transmis par référence, qui peut être null.

Dans le backend CPP, @nullable T correspond à std::unique_ptr<T> dans Android 11 ou version antérieure, et vers std::optional<T> sous Android 12 ou ultérieure.

Dans le backend du NDK, @nullable T est toujours mappé sur std::optional<T>.

Pour un type L de type liste tel que T[] ou List<T>, @nullable L correspond à std::optional<std::vector<std::optional<T>>> (ou std::unique_ptr<std::vector<std::unique_ptr<T>>> dans le cas du backend CPP pour Android 11 ou version antérieure).

Il existe une exception à ce mappage. Lorsque T est IBinder ou une interface AIDL, @nullable est une interface no-op. En d'autres termes, les deux @nullable IBinder et IBinder sont également mappés à android::sp<IBinder>, ce qui peut déjà avoir une valeur nulle, car il s'agit d'un pointeur fort (c'est-à-dire appliquer la possibilité de valeur nulle, mais le type est toujours android::sp<IBinder>).

À partir d'Android 13, @nullable(heap=true) peut être utilisé pour champs parcelables pour modéliser les types récursifs. Impossible d'utiliser @nullable(heap=true) avec des paramètres de méthode ou des types renvoyés. Lorsqu'il est annoté avec lui, le champ est mappée à une référence allouée par un tas de mémoire std::unique_ptr<T> dans le CPP/NDK ; backends. @nullable(heap=true) est no-op dans le backend Java.

utf8InCpp

utf8InCpp déclare qu'un élément String est représenté au format UTF8 pour la CPP. backend. Comme son nom l'indique, l'annotation est une opération no-op pour les autres backends. Plus précisément, String est toujours UTF16 dans le backend Java et UTF8 dans le NDK. backend.

Cette annotation peut être associée partout où le type String peut être utilisé, y compris les valeurs renvoyées, les paramètres, les déclarations de constantes et les paramètres .

Pour le backend CPP, @utf8InCpp String dans AIDL correspond à std::string, tandis que String sans l'annotation correspond à android::String16 où UTF16 est utilisé.

Notez que l'existence de l'annotation utf8InCpp ne modifie pas la façon dont les chaînes sont transmises sur le fil. Les chaînes sont toujours transmises au format UTF16. sur le fil. Une chaîne annotée utf8InCpp est convertie au format UTF16 avant d'être transmis. Lorsqu'une chaîne est reçue, elle est convertie de UTF16 en UTF8 si elle a été annotée en tant que utf8InCpp.

VintfStability

VintfStability déclare qu'un type défini par l'utilisateur (interface, parcelable, et enum) peuvent être utilisées dans les domaines du système et des fournisseurs. Voir AIDL pour les HAL pour en savoir plus l'interopérabilité système-fournisseur.

L'annotation ne modifie pas la signature du type, mais lorsqu'elle est définie, l'instance du type est marquée comme stable pour pouvoir traverser les processus du fournisseur et du système.

L'annotation ne peut être associée qu'à des déclarations de type définies par l'utilisateur, comme illustré ici:

@VintfStability
interface IFoo {
    ....
}

@VintfStability
parcelable Data {
    ....
}

@VintfStability
enum Type {
    ....
}

Lorsqu'un type est annoté avec VintfStability, tout autre type référencées dans le type doivent également être annotées comme telles. Dans les Par exemple, Data et IBar doivent tous deux être annotés avec 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 {...}

De plus, les fichiers AIDL définissant les types annotés avec VintfStability ne peuvent être compilés qu'à l'aide du type de module Soong aidl_interface, avec le Propriété stability définie sur "vintf".

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

Utilisation de l'application non compatible

L'annotation UnsupportedAppUsage indique que le type AIDL annoté est partie de l'interface non SDK qui a été accessible aux anciennes applications. Voir Restrictions sur les produits non SDK de commande pour en savoir plus sur les API masquées.

L'annotation UnsupportedAppUsage n'affecte pas le comportement de du code généré. L'annotation n'annote que la classe Java générée avec le paramètre Annotation Java du même nom.

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

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

Il s'agit d'une opération no-op pour les backends non Java.

Support

L'annotation Backing spécifie le type de stockage d'un type d'énumération AIDL.

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

Dans le backend CPP, cela émet une classe d'énumération C++ de type int32_t.

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

Si l'annotation est omise, type est considéré comme byte, ce qui correspond à int8_t pour le backend CPP.

L'argument type ne peut être défini que sur les types entiers suivants:

• byte (largeur 8 bits)
• int (largeur 32 bits)
• long (largeur 64 bits)

NdkOnlyStableParcelable (NdkOnlyStableParcelable)

NdkOnlyStableParcelable marque une déclaration de parcel (pas de définition) afin qu'il puisse être référencé à partir d'autres types AIDL stables. Ce est semblable à JavaOnlyStableParcelable, mais NdkOnlyStableParcelable marque une déclaration parcelable comme stable pour le NDK. pour le backend plutôt que pour Java.

Pour utiliser cet élément parcelable:

• Vous devez spécifier ndk_header.
• Vous devez disposer d'une bibliothèque NDK spécifiant le parcelable, et la bibliothèque doit être compilées dans la bibliothèque. Par exemple, dans le système de compilation module cc_*, utilisez static_libs ou shared_libs. Pour aidl_interface, ajoutez la bibliothèque sous additional_shared_libraries dans Android.bp.

JavaOnlyStableParcelable

JavaOnlyStableParcelable marque une déclaration de parcel (pas de définition) afin qu'il puisse être référencé à partir d'autres types AIDL stables.

La version stable d'AIDL nécessite que tous les types définis par l'utilisateur soient stables. Pour parcelables, la stabilité exige que ses champs soient explicitement décrits le fichier source 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
}

Si le parcelable n'était pas structuré (ou s'il a simplement été déclaré), il ne peut pas être référencées.

parcelable Data; // Data is NOT a structured parcelable

parcelable AnotherData {
    Data d; // Error
}

JavaOnlyStableParcelable vous permet d'ignorer le chèque lorsque le parcelable que vous référencez est déjà disponible en toute sécurité dans le SDK Android.

@JavaOnlyStableParcelable
parcelable Data;

parcelable AnotherData {
    Data d; // OK
}

JavaDerive

JavaDerive génère automatiquement des méthodes pour les types parcelables dans backend Java.

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

L'annotation nécessite des paramètres supplémentaires pour contrôler générer. Les paramètres acceptés sont les suivants:

• equals=true génère les méthodes equals et hashCode.
• toString=true génère la méthode toString qui affiche le nom du type. et champs. Exemple : Data{number: 42, str: foo}

JavaDefault

JavaDefault, ajoutée dans Android 13, contrôle si la prise en charge de la gestion des versions d'implémentation par défaut est générée (pour setDefaultImpl). Cette prise en charge n'est plus générée par défaut d'économiser de l'espace.

JavaPassthrough

JavaPassthrough permet à l'API Java générée d'être annotée avec une valeur Annotation Java.

Les annotations suivantes dans AIDL :

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

devenir

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

dans le code Java généré.

La valeur du paramètre annotation est émise directement. AIDL le compilateur ne prend pas en compte la valeur du paramètre. S'il y a des Erreur de syntaxe au niveau de Java, elle ne sera pas détectée par le compilateur AIDL, mais par Compilateur Java.

Cette annotation peut être associée à n'importe quelle entité AIDL. Cette annotation est une opération no-op pour les backends autres que Java.

Taille fixe

FixedSize marque une parcelle structurée comme une taille fixe. Une fois les éléments sélectionnés, parcelable ne pourra pas être ajouté à de nouveaux champs. Tous les champs de le parcelable doit aussi être de taille fixe, y compris les types primitifs, énumérations, tableaux de taille fixe et autres éléments parcelables marqués FixedSize.

Cela n'offre aucune garantie sur les différentes bits et ne doit pas être pour la communication de données mixtes.

Titre

Descriptor spécifie de force le descripteur d'une interface.

package android.foo;

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

Le descripteur de cette interface est android.bar.IWorld. Si le L'annotation Descriptor est manquante, le descripteur serait android.foo.IHello

Cela s'avère utile pour renommer une interface déjà publiée. Rendre descripteur de l'interface renommée identique au descripteur de l'interface avant le changement de nom permet aux deux interfaces de communiquer entre elles.

@masquer dans les commentaires

Le compilateur AIDL reconnaît @hide dans les commentaires et le transmet à la sortie Java pour le retrait de metalava. Ce commentaire garantit que l'Android votre système de compilation sait que les API AIDL ne sont pas des API SDK.

@obsolète dans les commentaires

Le compilateur AIDL reconnaît @deprecated dans les commentaires comme une balise pour identifier un Entité AIDL qui ne doit plus être utilisée.

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

Chaque backend marque les entités obsolètes par une annotation ou afin que le code client soit averti s'il fait référence aux entités. Par exemple, l'annotation @Deprecated et @deprecated sont associés au code généré par Java.