Se usó la API de Cloud Translation para traducir esta página.

Anotaciones en AIDL

AIDL admite anotaciones que brindan al compilador AIDL información adicional sobre el elemento anotado, lo que también afecta el código auxiliar generado.

La sintaxis es similar a la de Java:

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

Aquí, AnnotationName es el nombre de la anotación y AidlEntity es una entidad AIDL como interface Foo , void method() o int arg . Se adjunta una anotación a la entidad que le sigue.

Algunas anotaciones pueden tener argumentos dentro de los paréntesis, como se muestra arriba. Las anotaciones que no tienen un argumento no necesitan paréntesis. Por ejemplo:

@AnnotationName AidlEntity

Estas anotaciones no son las mismas que las anotaciones de Java, aunque se parecen mucho. Los usuarios no pueden definir anotaciones AIDL personalizadas; las anotaciones están todas predefinidas. Algunas anotaciones afectan solo a un determinado backend y no funcionan en otros backends. Tienen diferentes restricciones a las que se pueden adjuntar.

A continuación se muestra la lista de anotaciones AIDL predefinidas:

Anotaciones	Añadido en la versión de Android
`nullable`	7
`utf8InCpp`	7
`VintfStability`	11
`UnsupportedAppUsage`	10
`Hide`	11
`Backing`	11
`JavaOnlyStableParcelable`	11
`JavaDerive`	12
`JavaPassthrough`	12
`FixedSize`	12
`Descriptor`	12

anulable

nullable declara que no se puede proporcionar el valor de la entidad anotada.

Esta anotación solo se puede adjuntar a tipos de devolución de método, parámetros de método y campos parcelables.

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

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

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

Las anotaciones no se pueden adjuntar a tipos primitivos. Lo siguiente es un error.

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

Esta anotación no es operativa para el backend de Java. Esto se debe a que, en Java, todos los tipos no primitivos se pasan por referencia, que podría ser null .

En el backend de CPP, @nullable T asigna a std::unique_ptr<T> en Android 11 o versiones anteriores, y a std::optional<T> en Android 12 o versiones posteriores.

En el backend del NDK, @nullable T siempre se asigna a std::optional<T> .

Para un tipo L similar a una lista, como T[] o List<T> , @nullable L asigna a std::optional<std::vector<std::optional<T>>> (o std::unique_ptr<std::vector<std::unique_ptr<T>>> en el caso del backend CPP para Android 11 o inferior).

Hay una excepción a esta asignación. Cuando T es IBinder o una interfaz AIDL, @nullable no funciona. En otras palabras, tanto @nullable IBinder como IBinder se asignan por igual a android::sp<IBinder> , que ya es anulable porque es un puntero fuerte (las lecturas de CPP aún aplican la anulabilidad, pero el tipo sigue siendo android::sp<IBinder> ).

A partir de Android T (AOSP experimental), @nullable(heap=true) se puede usar para campos parcelables para modelar tipos recursivos. @nullable(heap=true) no se puede usar con parámetros de método o tipos de devolución. Cuando se anota con él, el campo se asigna a una referencia asignada en montón std::unique_ptr<T> en los backends de CPP/NDK. @nullable(heap=true) no funciona en el backend de Java.

utf8InCpp

utf8InCpp declara que una String se representa en formato UTF8 para el backend de CPP. Como su nombre lo indica, la anotación no es operativa para otros backends. Específicamente, String siempre es UTF16 en el backend de Java y UTF8 en el backend de NDK.

Esta anotación se puede adjuntar en cualquier lugar donde se pueda usar el tipo String , incluidos los valores devueltos, los parámetros, las declaraciones constantes y los campos parcelables.

Para el backend de CPP, @utf8InCpp String en AIDL se asigna a std::string , mientras que String sin la anotación se asigna a android::String16 donde se usa UTF16.

Tenga en cuenta que la existencia de la anotación utf8InCpp no cambia la forma en que se transmiten las cadenas a través del cable. Las cadenas siempre se transmiten como UTF16 a través del cable. Una cadena anotada utf8InCpp se convierte a UTF16 antes de transmitirse. Cuando se recibe una cadena, se convierte de UTF16 a UTF8 si se anotó como utf8InCpp .

VintfEstabilidad

VintfStability declara que un tipo definido por el usuario (interfaz, parcelable y enumeración) se puede usar en los dominios del sistema y del proveedor. Consulte AIDL para HAL para obtener más información sobre la interoperabilidad entre sistemas y proveedores.

La anotación no cambia la firma del tipo, pero cuando se establece, la instancia del tipo se marca como estable para que pueda viajar a través de los procesos del proveedor y del sistema.

La anotación solo se puede adjuntar a declaraciones de tipo definidas por el usuario como se muestra a continuación:

@VintfStability
interface IFoo {
    ....
}

@VintfStability
parcelable Data {
    ....
}

@VintfStability
enum Type {
    ....
}

Cuando un tipo se anota con VintfStability , cualquier otro tipo al que se haga referencia en el tipo también se debe anotar como tal. En el siguiente ejemplo, tanto Data como IBar deben anotarse con 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 {...}

Además, los archivos AIDL que definen los tipos anotados con VintfStability solo se pueden crear utilizando el tipo de módulo aidl_interface Soong, con la propiedad de stability establecida en "vintf" .

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

Uso de aplicación no compatible

La anotación UnsupportedAppUsage indica que el tipo de AIDL anotado es parte de la interfaz que no es del SDK a la que se ha podido acceder para las aplicaciones heredadas. Consulte Restricciones en las interfaces que no pertenecen al SDK para obtener más información sobre las API ocultas.

La anotación UnsupportedAppUsage no afecta el comportamiento del código generado. La anotación solo anota la clase Java generada con la anotación Java del mismo nombre.

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

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

Esto no es operativo para los backends que no son de Java.

Apoyo

La anotación de Backing especifica el tipo de almacenamiento de un tipo de enumeración AIDL.

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

En el backend de CPP, lo anterior emite una clase de enumeración de C++ de tipo int32_t .

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

Si se omite la anotación, se supone que el type es byte , que se asigna a int8_t para el backend de CPP.

El argumento de type solo se puede establecer en los siguientes tipos integrales:

byte (8 bits de ancho)
int (32 bits de ancho)
long (ancho de 64 bits)

JavaOnlyStableParcelable

JavaOnlyStableParcelable marca una declaración parcelable (no una definición) como estable para que se pueda hacer referencia a ella desde otros tipos de AIDL estables.

AIDL estable requiere que todos los tipos definidos por el usuario sean estables. Para parcelables, ser estable requiere que sus campos se describan explícitamente en el archivo fuente 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 el paquete no estaba estructurado (o simplemente se declaró), no se puede hacer referencia a él.

parcelable Data; // Data is NOT a structured parcelable

parcelable AnotherData {
    Data d; // Error
}

JavaOnlyStableParcelable le permite anular la verificación cuando el paquete al que hace referencia ya está disponible de forma segura como parte del SDK de Android.

@JavaOnlyStableParcelable
parcelable Data;

parcelable AnotherData {
    Data d; // OK
}

JavaDerive

JavaDerive genera automáticamente métodos para tipos parcelables en el backend de Java.

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

La anotación requiere parámetros adicionales para controlar qué generar. Los parámetros soportados son:

equals=true genera métodos equals y hashCode .
toString=true genera el método toString que imprime el nombre del tipo y los campos. Por ejemplo: Data{number: 42, str: foo}

JavaPredeterminado

JavaDefault , agregado en Android T (AOSP experimental), controla si se genera la compatibilidad con el control de versiones de la implementación predeterminada (para setDefaultImpl ). Este soporte ya no se genera por defecto para ahorrar espacio.

Transferencia de Java

JavaPassthrough permite que la API de Java generada se anote con una anotación de Java arbitraria.

Las siguientes anotaciones en AIDL

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

volverse

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

en el código Java generado.

El valor del parámetro de annotation se emite directamente. El compilador AIDL no analiza el valor del parámetro. Si hay algún error de sintaxis a nivel de Java, no será detectado por el compilador AIDL sino por el compilador de Java.

Esta anotación se puede adjuntar a cualquier entidad AIDL. Esta anotación no es operativa para los backends que no son de Java.

Tamaño fijo

FixedSize marca un paquete estructurado como de tamaño fijo. Una vez marcado, no se permitirá que se agreguen nuevos campos al parcelable. Todos los campos de la parcelable también deben ser tipos de tamaño fijo, incluidos tipos primitivos, enumeraciones, matrices de tamaño fijo y otras parcelables marcadas con FixedSize .

Esto no proporciona ninguna garantía en diferentes bits y no debe confiarse en él para la comunicación de bits mixtos.

descriptor

Descriptor especifica a la fuerza el descriptor de interfaz de una interfaz.

package android.foo;

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

El descriptor de la interfaz anterior es android.bar.IWorld . Si falta la anotación Descriptor , el descriptor sería android.foo.IHello .

Esto es útil para cambiar el nombre de una interfaz ya publicada. Hacer que el descriptor de la interfaz renombrada sea el mismo que el descriptor de la interfaz antes del cambio de nombre permite que las dos interfaces se comuniquen entre sí.

@ocultar en los comentarios

El compilador AIDL reconoce @hide en los comentarios y lo pasa a la salida de Java para que metalava lo recoja. Este comentario garantiza que el sistema de compilación de Android sepa que las API de AIDL no son API de SDK.

@deprecated en comentarios

El compilador AIDL reconoce @deprecated en los comentarios como una etiqueta para identificar una entidad AIDL que ya no debe usarse.

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

Cada backend marca las entidades obsoletas con una anotación/atributo específico del backend para que se advierta al código del cliente si hace referencia a las entidades obsoletas. Por ejemplo, la anotación @Deprecated y la etiqueta @deprecated se adjuntan al código generado por Java.