Anotaciones en el AIDL

AIDL admite anotaciones que le proporcionan al compilador de AIDL información adicional sobre el elemento anotado, lo que también afecta el código de stub 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 del AIDL, como interface Foo, void method() o int arg. Una anotación se adjunta a la entidad que la sigue.

Algunas anotaciones pueden tener argumentos establecidos 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 iguales que las de Java, aunque se ven muy similares. Los usuarios no pueden definir anotaciones AIDL personalizadas, ya que todas están predefinidas. Algunas anotaciones solo afectan a un backend determinado y no tienen efecto en otros. Tienen diferentes restricciones a las que se pueden adjuntar.

Esta es la lista de anotaciones de AIDL predefinidas:

nullable

nullable declara que es posible que no se proporcione el valor de la entidad con anotaciones.

Esta anotación solo se puede adjuntar a tipos de datos que se devuelven, parámetros de métodos 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. El siguiente es un error.

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

Esta anotación no realiza ninguna acción en 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 se 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>.

En el backend de Rust, @nullable T siempre se asigna a Option<T>.

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

Hay una excepción a esta asignación. Cuando T es IBinder o una interfaz de AIDL, @nullable es no-op para todos los backends, excepto Rust. En otras palabras, @nullable IBinder y IBinder se asignan de la misma manera a android::sp<IBinder>, que ya es nulo porque es un puntero fuerte (las lecturas de CPP aún aplican la nulidad, pero el tipo sigue siendo android::sp<IBinder>). En Rust, estos tipos son nullable solo si se anotan con @nullable. Se asignan a Option<T> si se anotan.

A partir de Android 13, se puede usar @nullable(heap=true) para campos parcelables para modelar tipos recursivos. @nullable(heap=true) no se puede usar con parámetros de método ni tipos de datos que se muestran. Cuando se lo anota, el campo se asigna a una referencia std::unique_ptr<T> asignada por el montón en los backends de CPP/NDK. @nullable(heap=true) no realiza ninguna acción en el backend de Java.

utf8InCpp

utf8InCpp declara que un String se representa en formato UTF8 para el backend de CPP. Como su nombre lo indica, la anotación es una no-op 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 siempre que se pueda usar el tipo String, incluidos los valores que se muestran, los parámetros, las declaraciones de 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.

Ten en cuenta que la existencia de la anotación utf8InCpp no cambia la forma en que se transmiten las strings por cable. Las cadenas siempre se transmiten como UTF16 por el cable. Una cadena con anotaciones utf8InCpp se convierte a UTF16 antes de transmitirse. Cuando se recibe una cadena, se convierte de UTF16 a UTF8 si se anotó como utf8InCpp.

VintfStability

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

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, Data y 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 tipos con anotaciones VintfStability solo se pueden compilar con el tipo de módulo Soong aidl_interface, con la propiedad stability establecida en "vintf".

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

Uso de la aplicación no admitido

La anotación UnsupportedAppUsage indica que el tipo de AIDL anotado forma parte de la interfaz que no pertenece al SDK a la que se puede acceder desde las apps heredadas. Consulta Restricciones en interfaces que no pertenecen al SDK para obtener más información sobre las APIs 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 {...}

Esta es una operación no válida para backends que no sean de Java.

Copia de seguridad

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

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

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

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

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

El argumento type solo se puede establecer en los siguientes tipos de números enteros:

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

NdkOnlyStableParcelable

NdkOnlyStableParcelable marca una declaración parcelable (no definición) como estable para que se pueda hacer referencia a ella desde otros tipos de AIDL estables. Esto es similar a JavaOnlyStableParcelable, pero NdkOnlyStableParcelable marca una declaración parcelable como estable para el backend de NDK en lugar de Java.

Para usar este objeto parcelable, haz lo siguiente:

• Debes especificar ndk_header.
• Debes tener una biblioteca de NDK que especifique el elemento parcelable, y la biblioteca debe compilarse en la biblioteca. Por ejemplo, en el sistema de compilación principal de un módulo cc_*, usa static_libs o shared_libs. Para aidl_interface, agrega la biblioteca en additional_shared_libraries en Android.bp.

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.

El AIDL estable requiere que todos los tipos definidos por el usuario sean estables. En el caso de los objetos parcelables, ser estables requiere que sus campos se describan de forma explícita en el archivo fuente del 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 elemento parcelable no estaba estructurado (o solo se declaró), no se puede hacer referencia a él.

parcelable Data; // Data is NOT a structured parcelable

parcelable AnotherData {
    Data d; // Error
}

JavaOnlyStableParcelable te permite anular la verificación cuando el objeto parcelable al que haces 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 admitidos son los siguientes:

• 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}

JavaDefault

JavaDefault, que se agregó en Android 13, controla si se genera la compatibilidad predeterminada con el control de versiones de implementación (para setDefaultImpl). Esta compatibilidad ya no se genera de forma predeterminada para ahorrar espacio.

JavaPassthrough

JavaPassthrough permite que la API de Java generada se annote 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)")

convertirse

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

en el código Java generado.

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

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

FixedSize

FixedSize marca un elemento parcelable estructurado como de tamaño fijo. Una vez marcado, no se le podrán agregar campos nuevos al elemento parcelable. Todos los campos del elemento parcelable también deben ser de tipos de tamaño fijo, incluidos los tipos primitivos, las enumeraciones, los arrays de tamaño fijo y otros elementos parcelables marcados con FixedSize.

Esto no proporciona ninguna garantía en diferentes tamaños de bits y no se debe confiar en él para la comunicación de bits mixtos.

Descriptor

Descriptor especifica de forma forzosa el descriptor de interfaz de una interfaz.

package android.foo;

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

El descriptor de esta interfaz 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 con el nombre cambiado sea el mismo que el descriptor de la interfaz anterior al cambio de nombre permite que las dos interfaces se comuniquen entre sí.

@hide in comments

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

@obsoleto en los comentarios

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

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

Cada backend marca las entidades obsoletas con una anotación o un atributo específicos del backend para que se le 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.