AIDL 中的註解

AIDL 支援註解，可為 AIDL 編譯器提供註解元素的額外資訊，這也會影響產生的輔助程式碼。

語法與 Java 的語法相似：

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

此處的 AnnotationName 是註解名稱，AidlEntity 是 interface Foo、void method() 或 int arg 等 AIDL 實體。註解會附加至其後方的實體。

部分註解可在括號內設定引數，如上方所示。沒有引數的註解不需要使用括號。例如：

@AnnotationName AidlEntity

雖然這些註解看起來很相似，但與 Java 註解不同。使用者無法定義自訂 AIDL 註解；註解皆會預先定義。部分註解只會影響特定後端，在其他後端中不會執行。這些檔案的附加位置有不同的限制。

以下是預先定義的 AIDL 註解清單：

註解	已在 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

注意： AIDL 編譯器會剖析註解中的 @hide 和 @deprecated。

可為空值

nullable 宣告註解實體的值可能未提供。

這個註解只能附加至方法傳回類型、方法參數和可分割欄位。

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

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

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

註解無法附加至基本類型。以下是錯誤訊息。

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

這個註解對 Java 後端而言是無操作。這是因為在 Java 中，所有非基本類型都是透過參照傳遞，而參照可能為 null。

在 CPP 後端中，@nullable T 會對應至 Android 11 以下版本的 std::unique_ptr<T>，以及 Android 12 以上版本的 std::optional<T>。

在 NDK 後端中，@nullable T 一律會對應至 std::optional<T>。

在 Rust 後端中，@nullable T 一律會對應至 Option<T>。

對於列表類型 L (例如 T[] 或 List<T>)，@nullable L 會對應至 std::optional<std::vector<std::optional<T>>> (如果是 Android 11 以下版本的 CPP 後端，則會對應至 std::unique_ptr<std::vector<std::unique_ptr<T>>>)。

這個對應有例外狀況。如果 T 是 IBinder 或 AIDL 介面，@nullable 對所有後端都是無操作，但 Rust 除外。換句話說，@nullable IBinder 和 IBinder 都會對應至 android::sp<IBinder>，而 android::sp<IBinder> 是強烈的 指標，因此已可為空值 (CPP 讀取仍會強制執行是否可為空值，但類型仍為 android::sp<IBinder>)。在 Rust 中，只有在註解為 @nullable 時，這些類型才是 nullable。如果已標註，則會對應至 Option<T>。

從 Android 13 開始，@nullable(heap=true) 可用於可分割的欄位，以模擬遞迴類型。@nullable(heap=true) 無法與方法參數或傳回類型搭配使用。使用此註解時，這個欄位會對應至 CPP/NDK 後端中的堆積分配參照 std::unique_ptr<T>。@nullable(heap=true) 是 Java 後端中的免人工管理。

utf8InCpp

utf8InCpp 宣告 String 以 UTF8 格式表示 CPP 後端。顧名思義，註解為其他後端的免人工管理。具體來說，String 在 Java 後端中一律為 UTF16，在 NDK 後端中則為 UTF8。

這個註解可附加至可使用 String 類型的任何位置，包括回傳值、參數、常數宣告和可分割的欄位。

針對 CPP 後端，AIDL 中的 @utf8InCpp String 會對應至 std::string，而沒有註解的 String 會對應至使用 UTF16 的 android::String16。

請注意，utf8InCpp 註解的存在並不會改變字串透過線路傳輸的方式。字串一律會以 UTF16 格式透過網路傳輸。utf8InCpp 註解字串會在傳輸之前先轉換為 UTF16。收到字串時，如果該字串已標註為 utf8InCpp，系統會將其從 UTF16 轉換為 UTF8。

VintfStability

VintfStability 宣告使用者定義的類型 (介面、parcelable 和 enum) 可在系統和供應商網域中使用。如要進一步瞭解系統供應商的互通性，請參閱「HAL 專用 AIDL」。

註解不會變更類型的簽名，但設定後，該類型的執行個體會標示為穩定，以便在供應商和系統程序之間傳輸。

註解只能附加至使用者定義的類型宣告，如下所示：

@VintfStability
interface IFoo {
    ....
}

@VintfStability
parcelable Data {
    ....
}

@VintfStability
enum Type {
    ....
}

使用 VintfStability 註解類型時，也應該為該類型中參照的任何其他類型加上註解，在以下範例中，Data 和 IBar 都應加上 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 {...}

此外，定義以 VintfStability 加註的類型的 AIDL 檔案，只能使用 aidl_interface Soong 模組類型建構，且 stability 屬性必須設為 "vintf"。

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

UnsupportedAppUsage

UnsupportedAppUsage 註解表示註解 AIDL 類型是舊版應用程式可存取的非 SDK 介面。如要進一步瞭解隱藏 API，請參閱「非 SDK 介面的限制」。

UnsupportedAppUsage 註解不會影響所產生程式碼的行為。註解只會使用同名 Java 註解為產生的 Java 類別加上註解。

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

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

這是非 Java 後端的免人工管理。

Backing

Backing 註解會指定 AIDL 列舉類型的儲存空間類型。

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

在 CPP 後端中，這會產生類型為 int32_t 的 C++ 列舉類別。

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

如果未使用註解，系統會假設 type 為 byte，並將其對應至 CPP 後端的 int8_t。

type 引數只能設為下列整數型別：

• byte (寬度為 8 位元)
• int (32 位元寬度)
• long (64 位元寬度)

NdkOnlyStableParcelable

NdkOnlyStableParcelable 會將可分割的宣告 (非定義) 標示為穩定，以便從其他穩定的 AIDL 類型參照。這與 JavaOnlyStableParcelable 類似，但 NdkOnlyStableParcelable 會將 parcelable 宣告標示為 NDK 後端的穩定版本，而非 Java 的穩定版本。

如何使用這個可分割的項目：

• 您必須指定 ndk_header。
• 您必須擁有指定可分割的 NDK 程式庫，且該程式庫必須編譯至程式庫。舉例來說，在 cc_* 模組的核心建構系統中，請使用 static_libs 或 shared_libs。若是 aidl_interface，請在 Android.bp 的 additional_shared_libraries 底下新增程式庫。

JavaOnlyStableParcelable

JavaOnlyStableParcelable 會將可分割聲明 (非定義) 標示為穩定，以便從其他穩定的 AIDL 類型參照。

穩定版 AIDL 中的所有使用者定義類型都必須保持穩定。為了保持穩定，以 parcelable 來說，需要在 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
}

如果 parcelable 是非結構化 (或剛宣告)，便無法參照。

parcelable Data; // Data is NOT a structured parcelable

parcelable AnotherData {
    Data d; // Error
}

當您參照的 parcelable 已安全地提供為 Android SDK 的一部分時，JavaOnlyStableParcelable 可讓您覆寫檢查作業。

@JavaOnlyStableParcelable
parcelable Data;

parcelable AnotherData {
    Data d; // OK
}

JavaDerive

JavaDerive 會自動在 Java 後端中產生可剖析類型的方法。

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

註解需要額外參數來控制要產生的內容。支援的參數如下：

• equals=true 會產生 equals 和 hashCode 方法。
• toString=true 會產生 toString 方法，用於列印類型和欄位的名稱。例如：Data{number: 42, str: foo}

JavaDefault

JavaDefault 是在 Android 13 中新增的功能，用於控制是否要產生預設實作版本支援 (適用於 setDefaultImpl)。為了節省空間，系統不再預設產生這項支援。

JavaPassthrough

JavaPassthrough 可讓產生的 Java API 加上任意 Java 註解。

AIDL 中的以下註解

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

成為

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

在產生的 Java 程式碼中。

annotation 參數的值會直接發出。AIDL 編譯器不會查看參數的值。如果有任何 Java 層級語法錯誤，AIDL 編譯器不會偵測到，而是由 Java 編譯器偵測到。

這個註解可附加至任何 AIDL 實體。這個註解是非 Java 後端的免人工管理元件。

FixedSize

FixedSize 會將結構化 parcelable 標示為固定大小。標記後，Parcelable 就無法新增欄位。parcelable 的所有欄位也必須設為固定大小的類型，包括原始類型、列舉、固定大小陣列，以及其他加上 FixedSize 的 parcelable。

這不會為不同位元數提供任何保證，也不應用於混合位元數的通訊。

描述元

Descriptor 會強制指定介面的介面描述元。

package android.foo;

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

這個介面的描述元是 android.bar.IWorld。如果缺少 Descriptor 註解，描述元為 android.foo.IHello。

這項功能可用於重新命名已發布的介面。讓重新命名的介面描述符與重新命名前的介面描述符相同，即可讓兩個介面互相通訊。

@hide in comments

AIDL 編譯器會辨識註解中的 @hide，並將其傳遞至 Java 輸出內容，供 metalava 擷取。這項註解可確保 Android 建構系統知道 AIDL API 並非 SDK API。

註解中的 @deprecated

AIDL 編譯器會將註解中的 @deprecated 視為標記，用於識別應不再使用的 AIDL 實體。

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

每個後端都會使用後端專屬的註解或屬性標示已淘汰的實體，以便在用戶端程式碼參照已淘汰的實體時發出警告。舉例來說，@Deprecated 註解和 @deprecated 標記會附加至產生的 Java 程式碼。