Anotações em AIDL

AIDL suporta anotações que fornecem ao compilador AIDL informações extras sobre o elemento anotado, o que também afeta o código stub gerado.

A sintaxe é semelhante à do Java:

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

Aqui, AnnotationName é o nome da anotação e AidlEntity é uma entidade AIDL como interface Foo , void method() ou int arg . Uma anotação é anexada à entidade que a segue.

Algumas anotações podem ter argumentos definidos entre parênteses, como mostrado acima. Anotações que não têm um argumento não precisam de parênteses. Por exemplo:

@AnnotationName AidlEntity

Essas anotações não são iguais às anotações Java, embora pareçam muito semelhantes. Os usuários não podem definir anotações AIDL personalizadas; as anotações são todas pré-definidas. Algumas anotações afetam apenas um determinado back-end e são inoperantes em outros back-ends. Eles têm restrições diferentes onde podem ser anexados.

Abaixo está a lista de anotações AIDL pré-definidas:

anulável

nullable declara que o valor da entidade anotada não pode ser fornecido.

Esta anotação só pode ser anexada a tipos de retorno de método, parâmetros de método e campos parcelable.

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

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

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

As anotações não podem ser anexadas a tipos primitivos. O seguinte é um erro.

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

Esta anotação não é operacional para o back-end Java. Isso ocorre porque, em Java, todos os tipos não primitivos são passados ​​por referência, que pode ser null .

No back-end CPP, @nullable T mapeia para std::unique_ptr<T> no Android 11 ou inferior e para std::optional<T> no Android 12 ou superior.

No back-end do NDK, @nullable T sempre mapeia para std::optional<T> .

Para um tipo de lista L , como T[] ou List<T> , @nullable L mapeia para std::optional<std::vector<std::optional<T>>> (ou std::unique_ptr<std::vector<std::unique_ptr<T>>> no caso do back-end CPP para Android 11 ou inferior).

Há uma exceção a esse mapeamento. Quando T é IBinder ou uma interface AIDL, @nullable é no-op. Em outras palavras, @nullable IBinder e IBinder igualmente mapeiam para android::sp<IBinder> , que já é anulável porque é um ponteiro forte (leituras CPP ainda impõem a nulidade, mas o tipo ainda é android::sp<IBinder> ).

Começando com o Android T (AOSP experimental), @nullable(heap=true) pode ser usado para campos parcelables para modelar tipos recursivos. @nullable(heap=true) não pode ser usado com parâmetros de método ou tipos de retorno. Quando anotado com ele, o campo é mapeado para uma referência alocada por heap std::unique_ptr<T> nos back-ends CPP/NDK. @nullable(heap=true) não é operacional no back-end Java.

utf8InCpp

utf8InCpp declara que uma String é representada no formato UTF8 para o back-end CPP. Como o próprio nome indica, a anotação não é operacional para outros back-ends. Especificamente, String é sempre UTF16 no backend Java e UTF8 no backend NDK.

Esta anotação pode ser anexada em qualquer lugar onde o tipo String possa ser usado, incluindo valores de retorno, parâmetros, declarações constantes e campos parcelable.

Para o back-end CPP, @utf8InCpp String em AIDL mapeia para std::string , enquanto String sem a anotação mapeia para android::String16 onde UTF16 é usado.

Observe que a existência da anotação utf8InCpp não altera a maneira como as strings são transmitidas pelo fio. Strings são sempre transmitidas como UTF16 pelo fio. Uma string anotada utf8InCpp é convertida em UTF16 antes de ser transmitida. Quando uma string é recebida, ela é convertida de UTF16 para UTF8 se tiver sido anotada como utf8InCpp .

Estabilidade Vintf

VintfStability declara que um tipo definido pelo usuário (interface, parcelable e enum) pode ser usado nos domínios do sistema e do fornecedor. Consulte AIDL para HALs para obter mais informações sobre a interoperabilidade do sistema com o fornecedor.

A anotação não altera a assinatura do tipo, mas quando é definida, a instância do tipo é marcada como estável para que possa percorrer os processos do fornecedor e do sistema.

A anotação só pode ser anexada a declarações de tipo definidas pelo usuário, conforme mostrado abaixo:

@VintfStability
interface IFoo {
    ....
}

@VintfStability
parcelable Data {
    ....
}

@VintfStability
enum Type {
    ....
}

Quando um tipo é anotado com VintfStability , qualquer outro tipo referenciado no tipo também deve ser anotado como tal. No exemplo abaixo, Data e IBar devem ser anotados com 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 {...}

Além disso, os arquivos AIDL que definem os tipos anotados com VintfStability só podem ser construídos usando o tipo de módulo aidl_interface Soong, com a propriedade de stability definida como "vintf" .

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

Uso de aplicativo não suportado

A anotação UnsupportedAppUsage indica que o tipo AIDL anotado faz parte da interface não SDK que pode ser acessada por aplicativos herdados. Consulte Restrições em interfaces não SDK para obter mais informações sobre as APIs ocultas.

A anotação UnsupportedAppUsage não afeta o comportamento do código gerado. A anotação apenas anota a classe Java gerada com a anotação Java de mesmo nome.

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

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

Este é um não-op para back-ends não Java.

Apoio

A anotação de Backing especifica o tipo de armazenamento de um tipo de enumeração AIDL.

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

No back-end CPP, o código acima emite uma classe de enumeração C++ do tipo int32_t .

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

Se a anotação for omitida, o type será considerado byte , que é mapeado para int8_t para o back-end CPP.

O argumento type pode ser definido apenas para os seguintes tipos integrais:

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

JavaOnlyStableParcelable

JavaOnlyStableParcelable marca uma declaração parcelable (não definição) como estável para que possa ser referenciada de outros tipos AIDL estáveis.

O AIDL estável requer que todos os tipos definidos pelo usuário sejam estáveis. Para parcelables, ser estável requer que seus campos sejam explicitamente descritos no arquivo de origem 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
}

Se o parcelable não foi estruturado (ou apenas declarado), ele não pode ser referenciado.

parcelable Data; // Data is NOT a structured parcelable

parcelable AnotherData {
    Data d; // Error
}

JavaOnlyStableParcelable permite substituir a verificação quando o parcelable que você está referenciando já está disponível com segurança como parte do Android SDK.

@JavaOnlyStableParcelable
parcelable Data;

parcelable AnotherData {
    Data d; // OK
}

JavaDerive

JavaDerive gera automaticamente métodos para tipos parcelable no backend Java.

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

A anotação requer parâmetros adicionais para controlar o que gerar. Os parâmetros suportados são:

• equals=true gera métodos equals e hashCode .
• toString=true gera o método toString que imprime o nome do tipo e dos campos. Por exemplo: Data{number: 42, str: foo}

JavaDefault

JavaDefault , adicionado no Android T (AOSP experimental), controla se o suporte de versão de implementação padrão é gerado (para setDefaultImpl ). Este suporte não é mais gerado por padrão para economizar espaço.

JavaPassthrough

JavaPassthrough permite que a API Java gerada seja anotada com uma anotação Java arbitrária.

As seguintes anotações em AIDL

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

vir a ser

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

no código Java gerado.

O valor do parâmetro de annotation é emitido diretamente. O compilador AIDL não analisa o valor do parâmetro. Se houver algum erro de sintaxe no nível do Java, ele não será detectado pelo compilador AIDL, mas pelo compilador Java.

Esta anotação pode ser anexada a qualquer entidade AIDL. Esta anotação não é operacional para back-ends não Java.

Tamanho fixo

FixedSize marca um parcelal estruturado como tamanho fixo. Uma vez marcado, o parcelable não poderá ter novos campos adicionados a ele. Todos os campos do parcelable também devem ser tipos de tamanho fixo, incluindo tipos primitivos, enums, arrays de tamanho fixo e outros parcelables marcados com FixedSize .

Isso não oferece nenhuma garantia em diferentes bits e não deve ser usado para comunicação de bits mistos.

Descritor

Descriptor especifica forçosamente o descritor de interface de uma interface.

package android.foo;

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

O descritor da interface acima é android.bar.IWorld . Se a anotação do Descriptor estiver ausente, o descritor será android.foo.IHello .

Isso é útil para renomear uma interface já publicada. Tornar o descritor da interface renomeada igual ao descritor da interface antes da renomeação permite que as duas interfaces se comuniquem.

@esconder nos comentários

O compilador AIDL reconhece @hide nos comentários e o passa para a saída Java para o metalava coletar. Este comentário garante que o sistema de compilação do Android saiba que as APIs AIDL não são APIs do SDK.

@obsoleto nos comentários

O compilador AIDL reconhece @deprecated nos comentários como uma tag para identificar uma entidade AIDL que não deve mais ser usada.

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

Cada back-end marca entidades obsoletas com uma anotação/atributo específico de back-end para que o código do cliente seja avisado se ele se referir às entidades obsoletas. Por exemplo, a anotação @Deprecated e a tag @deprecated são anexadas ao código gerado em Java.