本頁面由 Cloud Translation API 翻譯而成。

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

可為空值

nullable 會宣告系統可能不會提供已加註實體的值。

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

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 中的 std::unique_ptr<T> 11 以下版本，以及 Android 中的 std::optional<T> 12 以上版本。

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

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

這個對應有例外狀況。時間：T 為 IBinder 或 AIDL 介面，@nullable 為免人工管理。也就是說 @nullable IBinder 和 IBinder 等於 android::sp<IBinder>，已經是可為空值，因為這是強的指標 (CPP 讀取仍強制執行是否可為空值，但類型仍為 android::sp<IBinder>)。

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

utf8InCpp

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

此註解可附加在 String 類型可以使用的任何位置。包括回傳值、參數、常數宣告和 parcelable 只要使用來自這些領域的小型資料集訓練即可

在 CPP 後端中，AIDL 中的 @utf8InCpp String 對應至 std::string，不含註解的 String 對應至使用 UTF16 的 android::String16。

請注意，utf8InCpp 註解的存在並不會改變這些字串會經由線路傳輸。字串一律會以 UTF16 傳送 utf8InCpp 註解字串會先轉換為 UTF16，然後才是傳送。收到字串後，如果有，會由 UTF16 轉換為 UTF8 加註為 utf8InCpp。

陷阱

VintfStability 會宣告使用者定義的類型 (interface、parcelable、和列舉) 可以在系統和供應商網域中使用。詳情請見 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 {...}

此外，AIDL 檔案會定義使用 VintfStability 註解的類型只能透過 aidl_interface Soong 模組類型建構，且 stability 屬性已設為 "vintf"。

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

不支援的應用程式使用方式

UnsupportedAppUsage 註解表示註解的 AIDL 類型為。請參閱「非 SDK 的相關限制介面。

UnsupportedAppUsage 註解不會影響產生的程式碼註解只會使用同名的 Java 註解。

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

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

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

備份中

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 會標記 parcelable 宣告 (非定義) 保持穩定，以便從其他穩定的 AIDL 類型參照。這個就像 JavaOnlyStableParcelable，但 NdkOnlyStableParcelable 會將 parcelable 宣告標示為 NDK 的穩定版而非 Java 應用程式

如何使用這個 parcelable：

您必須指定 ndk_header。
您必須使用指定 parcelable 的 NDK 程式庫，而且程式庫必須編譯到程式庫中比方說，在 cc_* 模組，使用 static_libs 或 shared_libs。對於 aidl_interface，請新增「Android.bp」中 additional_shared_libraries 下的程式庫

JavaOnlyStableParcelable

JavaOnlyStableParcelable 會標記 parcelable 宣告 (非定義) 保持穩定，以便從其他穩定的 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
}

JavaOnlyStableParcelable 可讓您覆寫 Parcelable 的檢查所參照的元件都已安全提供給 Android SDK 中

@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)

JavaDefault 新增於 Android 13 中，可控制產生預設的實作版本管理支援 (針對 setDefaultImpl)。為節省空間。

Java 直通式

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 會將結構化 Parcel 標示為固定大小。標示完成後 parcelable 將禁止新增欄位。下列所有欄位： parcelable 也必須是固定大小的類型，包括原始類型列舉、固定大小陣列，以及其他標有 FixedSize 的 parcelable。

無法保證不同位元的值，不一定仰賴混合型通訊

描述元

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

package android.foo;

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

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

如要重新命名已經發布的介面，這項功能就能派上用場。透過重新命名後的介面描述元可讓兩個介面彼此通訊。

在留言中使用 @隱藏

AIDL 編譯器會在註解中辨識 @hide，並傳遞給該編譯器將 Metalava 到取貨的 Java 輸出內容此註解可確保 Android 建構系統知道 AIDL API 並非 SDK API。

@已在註解中淘汰

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

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

每個後端都會使用後端專屬註解標示已淘汰的實體，或是屬性，如果用戶端程式碼參照已淘汰的實體。例如 @Deprecated 註解和 @deprecated 標記附加至 Java 產生的程式碼