Google se compromete a impulsar la igualdad racial para las comunidades afrodescendientes. Obtén información al respecto.

Anotaciones en AIDL

AIDL admite anotaciones que brindan al compilador AIDL información adicional sobre el elemento anotado, lo que también afecta al 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 la sigue.

Algunas anotaciones pueden tener argumentos entre 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 son muy similares. Los usuarios no pueden definir anotaciones AIDL personalizadas; todas las anotaciones están predefinidas. Algunas anotaciones afectan solo a un determinado backend y no son operativas en otros backend. Tienen diferentes restricciones a las que pueden unirse.

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

Anotaciones Agregado 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 el valor de la entidad anotada no puede proporcionar.

Esta anotación solo se puede adjuntar a tipos de retorno 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;
}

No se pueden adjuntar anotaciones 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 back-end CPP, @nullable T asigna a std::unique_ptr<T> en Android 11 o inferior, y para std::optional<T> en Android 12 o superior.

En el back-end NDK, @nullable T siempre se asigna a std::optional<T> .

Para obtener una lista similar de tipo L 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 CPP para Android 11 o inferior).

Hay una excepción a este mapeo. Cuando T es IBinder o una interfaz AIDL, @nullable es no-op. En otras palabras, tanto @nullable IBinder y IBinder igualmente se asignan a android::sp<IBinder> , que ya es anulable - porque es un puntero fuerte.

Comenzando con Android T (experimental AOSP), @nullable(heap=true) se puede utilizar para campos parcelable para modelar tipos recursivos. @nullable(heap=true) no se puede utilizar con los parámetros del método o tipos de retorno. Cuando anotado con ella, el campo se asigna a una referencia heap-asignado std::unique_ptr<T> en los backends CPP / NDK. @nullable(heap=true) es no-op en el backend Java.

utf8InCpp

utf8InCpp declara que una String está representado en formato UTF-8 para el backend CPP. Como su nombre lo indica, la anotación no es operativa para otros backends. En concreto, String es siempre UTF16 Java en el back-end y back-end UTF8 en el NDK.

Esta anotación se puede unir en cualquier lugar de la String tipo se puede utilizar, incluyendo valores de retorno, parámetros, declaraciones de constantes, y los campos parcelable.

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

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

VintfEstabilidad

VintfStability declara que un tipo definido por el usuario (interfaz, parcelable, y enum) se puede utilizar en todos los dominios del sistema y de los proveedores. Ver AIDL de HAL para más información sobre el sistema de interoperabilidad entre 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 que se hace referencia en el tipo también debe ser anotado como tal. En el siguiente ejemplo, Data y IBar tanto deben ser anotados 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 que definen tipos AIDL con anotada VintfStability sólo pueden construirse utilizando la aidl_interface Soong tipo de módulo, con la stability propiedad establecida en "vintf" .

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

UnsupportedAppUsage

Los UnsupportedAppUsage denota el tipo de anotación que AIDL anotada es parte de la interfaz no SDK que ha sido accesible para aplicaciones de legado. Ver Restricciones de interfaces no SDK para obtener más información acerca de las API ocultos.

El UnsupportedAppUsage anotación no afecta al 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 operativa para backends que no son de Java.

Esconder

El Hide anotación es similar a UnsupportedAppUsage . Se asigna directamente a la anotación de Java android.annotation.Hide que indica que una API no es parte de la API de Android.

El android.annotation.Hide anotación es otra manera de ocultar un API, que normalmente se realiza mediante la adición de la @hide alguna parte literal de cadena en el comentario para que el API.

Esta es una operación no operativa para backends que no son de Java.

Apoyo

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

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

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

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

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

El type argumento sólo puede ajustarse a los siguientes tipos integrales:

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

JavaOnlyStableParcelable

JavaOnlyStableParcelable marcas una declaración parcelable (no la definición) como estable para que se pueda hacer referencia a otros tipos AIDL estable.

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

parcelable Data; // Data is NOT a structured parcelable

parcelable AnotherData {
    Data d; // Error
}

JavaOnlyStableParcelable le permite anular el cheque cuando el parcelable se hace referencia a que ya es segura disponible como parte del SDK de Android.

@JavaOnlyStableParcelable
parcelable Data;

parcelable AnotherData {
    Data d; // OK
}

JavaDerive

JavaDerive genera automáticamente métodos para tipos parcelable en el back-end 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:

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

JavaPassthrough

JavaPassthrough permite la API Java generado se anota con una anotación arbitraria Java.

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 de la annotation parámetro 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 una operación para los backends que no son de Java.

Tamaño fijo

FixedSize marca un parcelable estructurado como tamaño fijo. Una vez marcado, no se permitirá que se le agreguen nuevos campos al parcelable. Todos los campos de la parcelable también deben fijarse los tipos de tamaño, incluyendo los tipos primitivos, enumeraciones y otros parcelables marcados con FixedSize .

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

Descriptor

Descriptor especifica por 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 el Descriptor anotación no está presente, 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í.

@deprecated en comentarios

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

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

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