AIDL hỗ trợ các chú giải cung cấp thêm thông tin cho trình biên dịch AIDL về phần tử được chú thích, điều này cũng ảnh hưởng đến mã mã giả lập được tạo.
Cú pháp tương tự như cú pháp của Java:
@AnnotationName(argument1=value, argument2=value) AidlEntity
Ở đây, AnnotationName
là tên chú thích, còn AidlEntity
là
một thực thể AIDL như interface Foo
, void method()
hoặc int arg
. Một
chú thích sẽ được đính kèm với thực thể theo sau nó.
Một số chú giải có thể có đối số được đặt bên trong dấu ngoặc đơn, như được hiển thị ở trên. Chú thích không có đối số không cần dấu ngoặc đơn. Ví dụ:
@AnnotationName AidlEntity
Các chú giải này không giống với Java của mình, mặc dù chúng trông rất giống nhau. Người dùng không thể xác định AIDL tuỳ chỉnh chú thích; các chú thích đều được xác định trước. Một số chú thích chỉ ảnh hưởng đến một chương trình phụ trợ nhất định và không hoạt động trong các chương trình phụ trợ khác. Chúng có các đặc điểm khác nhau có thể đính kèm vào các hạn chế đó.
Dưới đây là danh sách các chú thích AIDL được xác định trước:
Chú thích | Đã thêm vào phiên bản 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 |
rỗng
nullable
khai báo rằng có thể không cung cấp giá trị của thực thể được chú giải.
Bạn chỉ có thể đính kèm chú thích này vào loại phương thức trả về, tham số của phương thức và các trường theo gói.
interface IFoo {
// method return types
@nullable Data method();
// method parameters
void method2(in @nullable Data d);
}
parcelable Data {
// parcelable fields
@nullable Data d;
}
Không thể đính kèm chú thích vào các loại dữ liệu nguyên gốc. Sau đây là một lỗi.
void method(in @nullable int a); // int is a primitive type
Chú thích này không hoạt động đối với phần phụ trợ Java. Điều này là do trong Java, tất cả
các loại không phải nguyên gốc được truyền qua tham chiếu, đó có thể là null
.
Trong phần phụ trợ CPP, @nullable T
ánh xạ tới std::unique_ptr<T>
trong Android
11 trở xuống và lên std::optional<T>
trong Android
12 trở lên.
Trong phần phụ trợ của NDK, @nullable T
luôn ánh xạ với std::optional<T>
.
Đối với loại danh sách L
, chẳng hạn như T[]
hoặc List<T>
, @nullable L
sẽ ánh xạ tới
std::optional<std::vector<std::optional<T>>>
(hoặc
std::unique_ptr<std::vector<std::unique_ptr<T>>>
trong trường hợp phần phụ trợ CPP
dành cho Android 11 trở xuống).
Có một ngoại lệ đối với việc liên kết này. Khi T
là IBinder
hoặc giao diện AIDL, @nullable
không hoạt động. Nói cách khác, cả hai
@nullable IBinder
và IBinder
ánh xạ như nhau đến android::sp<IBinder>
.
vốn có thể rỗng vì đây là một con trỏ mạnh (CPP vẫn đọc
thực thi tính chất rỗng nhưng kiểu này vẫn là android::sp<IBinder>
).
Kể từ Android 13, bạn có thể dùng @nullable(heap=true)
để
các trường theo gói để lập mô hình các loại đệ quy. Không dùng được @nullable(heap=true)
có tham số phương thức hoặc kiểu dữ liệu trả về. Khi được chú thích, trường này sẽ
liên kết với một tệp đối chiếu được phân bổ vùng nhớ khối xếp std::unique_ptr<T>
trong CPP/NDK
chương trình phụ trợ. @nullable(heap=true)
không hoạt động trong phần phụ trợ Java.
utf8InCpp
utf8InCpp
khai báo rằng String
được biểu thị dưới định dạng UTF8 cho CPP
phần phụ trợ. Đúng như tên gọi, chú thích này không hoạt động đối với các phần phụ trợ khác.
Cụ thể, String
luôn là UTF16 trong phần phụ trợ Java và UTF8 trong NDK
phần phụ trợ.
Bạn có thể đính kèm chú thích này ở bất kỳ nơi nào có thể sử dụng loại String
,
bao gồm cả giá trị trả về, tham số, khai báo hằng số và có thể đóng gói
mới.
Đối với phần phụ trợ CPP, @utf8InCpp String
trong AIDL liên kết với std::string
, trong khi đó
String
không có chú giải sẽ liên kết với android::String16
có sử dụng UTF16.
Xin lưu ý rằng sự tồn tại của chú giải utf8InCpp
sẽ không làm thay đổi cách thức
chuỗi được truyền trên dây. Chuỗi luôn được truyền dưới dạng UTF16
trên dây. Chuỗi có chú thích utf8InCpp
sẽ được chuyển đổi thành UTF16 trước khi được
được truyền. Khi nhận được một chuỗi, chuỗi đó sẽ được chuyển đổi từ UTF16 thành UTF8 nếu giá trị đó
đã được chú thích là utf8InCpp
.
Độ ổn định của Vintf
VintfStability
khai báo rằng một loại do người dùng xác định (giao diện, có thể đóng gói,
và enum) trên miền hệ thống và miền của nhà cung cấp. Xem
AIDL cho HAL để biết thêm thông tin về
khả năng tương tác của nhà cung cấp hệ thống.
Chú thích sẽ không thay đổi chữ ký của loại, nhưng khi chú thích được đặt, thực thể của loại này được đánh dấu là ổn định để có thể di chuyển qua các quy trình của nhà cung cấp và hệ thống.
Bạn chỉ có thể đính kèm chú thích vào phần khai báo loại do người dùng xác định như minh hoạ tại đây:
@VintfStability
interface IFoo {
....
}
@VintfStability
parcelable Data {
....
}
@VintfStability
enum Type {
....
}
Khi một kiểu được chú thích bằng VintfStability
, mọi kiểu khác được chú thích
tham chiếu đến loại dữ liệu nào cũng phải được chú thích như vậy. Trong phần sau
ví dụ: cả Data
và IBar
đều phải được chú thích bằng 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 {...}
Ngoài ra, các tệp AIDL xác định các loại được chú thích bằng VintfStability
chỉ có thể được tạo bằng loại mô-đun Soong aidl_interface
, với
Đã đặt thuộc tính stability
thành "vintf"
.
aidl_interface {
name: "my_interface",
srcs: [...],
stability: "vintf",
}
Sử dụng ứng dụng không được hỗ trợ
Chú thích UnsupportedAppUsage
biểu thị rằng loại AIDL được chú giải là
một phần của giao diện không phải SDK mà ứng dụng cũ có thể truy cập được.
Xem Hạn chế đối với sản phẩm không phải SDK
giao diện
để biết thêm thông tin về các API ẩn.
Chú giải UnsupportedAppUsage
không ảnh hưởng đến hành vi của
tạo. Chú thích này chỉ chú thích lớp Java được tạo bằng
Chú giải Java cùng tên.
// in AIDL
@UnsupportedAppUsage
interface IFoo {...}
// in Java
@android.compat.annotation.UnsupportedAppUsage
public interface IFoo {...}
Tính năng này không hoạt động đối với các phần phụ trợ không phải là Java.
Dự phòng
Chú giải Backing
chỉ định loại hình lưu trữ của một loại enum AIDL.
@Backing(type="int")
enum Color { RED, BLUE, }
Trong phần phụ trợ CPP, thao tác này sẽ tạo ra một lớp enum C++ thuộc loại int32_t
.
enum class Color : int32_t {
RED = 0,
BLUE = 1,
}
Nếu chú thích bị bỏ qua, type
được giả định là byte
, liên kết
tới int8_t
cho phần phụ trợ CPP.
Bạn chỉ có thể đặt đối số type
thành các loại tích phân sau:
byte
(rộng 8 bit)int
(rộng 32 bit)long
(rộng 64 bit)
NdkOnlyStableParcelable (Có thể đóng gói)
NdkOnlyStableParcelable
đánh dấu một nội dung khai báo theo gói (không phải định nghĩa)
ổn định để có thể tham chiếu từ các kiểu AIDL ổn định khác. Chiến dịch này
giống như JavaOnlyStableParcelable
, nhưng
NdkOnlyStableParcelable
đánh dấu một nội dung khai báo theo gói là ổn định cho NDK
phụ trợ thay vì cho Java.
Cách sử dụng thuộc tính theo gói này:
- Bạn phải chỉ định
ndk_header
. - Bạn phải có một thư viện NDK chỉ định gói có thể đóng gói và thư viện phải
sẽ được biên dịch vào thư viện. Ví dụ: trong hệ thống xây dựng cốt lõi trên
Mô-đun
cc_*
, sử dụngstatic_libs
hoặcshared_libs
. Đối vớiaidl_interface
, hãy thêm thư viện thuộcadditional_shared_libraries
trongAndroid.bp
.
Gói JavaOnlyStableParcelable
JavaOnlyStableParcelable
đánh dấu một nội dung khai báo theo gói (không phải định nghĩa)
ổn định để có thể tham chiếu từ các kiểu AIDL ổn định khác.
AIDL ổn định yêu cầu tất cả các kiểu do người dùng xác định đều phải ổn định. Cho Parcables, để ổn định, các trường của nó phải được mô tả rõ ràng trong tệp nguồn 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
}
Nếu bưu kiện không có cấu trúc (hoặc vừa được khai báo), thì nó không được tham chiếu.
parcelable Data; // Data is NOT a structured parcelable
parcelable AnotherData {
Data d; // Error
}
JavaOnlyStableParcelable
cho phép bạn ghi đè dấu kiểm khi gói hàng
mà bạn đang tham chiếu đã được cung cấp một cách an toàn trong SDK Android.
@JavaOnlyStableParcelable
parcelable Data;
parcelable AnotherData {
Data d; // OK
}
JavaDerive
JavaDerive
tự động tạo phương thức cho các loại theo gói trong
Phần phụ trợ Java.
@JavaDerive(equals = true, toString = true)
parcelable Data {
int number;
String str;
}
Chú thích yêu cầu tham số bổ sung để kiểm soát những gì cần tạo. Các tham số được hỗ trợ bao gồm:
equals=true
tạo các phương thứcequals
vàhashCode
.toString=true
tạo phương thứctoString
để in tên của kiểu và trường. Ví dụ:Data{number: 42, str: foo}
Mặc định Java
JavaDefault
, được thêm vào Android 13, kiểm soát việc
hỗ trợ tạo phiên bản triển khai mặc định được tạo (cho
setDefaultImpl
). Chức năng hỗ trợ này không còn được tạo theo mặc định để
để tiết kiệm không gian.
Thông qua Java
JavaPassthrough
cho phép chú thích API Java đã tạo bằng
Chú giải Java.
Các chú thích sau trong AIDL
@JavaPassthrough(annotation="@android.annotation.Alice")
@JavaPassthrough(annotation="@com.android.Alice(arg=com.android.Alice.Value.A)")
trở thành
@android.annotation.Alice
@com.android.Alice(arg=com.android.Alice.Value.A)
trong mã Java đã tạo.
Giá trị của tham số annotation
được phát trực tiếp. AIDL
trình biên dịch không xem xét giá trị của tham số. Nếu có
Lỗi cú pháp cấp Java, trình biên dịch AIDL sẽ không phát hiện lỗi này mà
Trình biên dịch Java.
Bạn có thể đính kèm chú thích này vào bất kỳ thực thể AIDL nào. Chú thích này không hoạt động đối với các chương trình phụ trợ không phải là Java.
Kích thước cố định
FixedSize
đánh dấu kích thước cố định cho gói có cấu trúc. Sau khi được đánh dấu,
theo gói sẽ không được phép thêm trường mới vào gói đó. Tất cả các trường của
gói cũng phải là loại có kích thước cố định, bao gồm cả loại nguyên gốc,
enum, mảng có kích thước cố định và các bưu kiện khác được đánh dấu bằng FixedSize
.
Điều này không cung cấp bất kỳ sự đảm bảo nào cho các bit khác nhau và không nên dựa vào giao tiếp bit hỗn hợp.
Nội dung mô tả
Descriptor
buộc chỉ định mã mô tả giao diện của một giao diện.
package android.foo;
@Descriptor(value="android.bar.IWorld")
interface IHello {...}
Phần mô tả của giao diện này là android.bar.IWorld
. Nếu
Thiếu chú thích Descriptor
, phần mô tả sẽ là
android.foo.IHello
Điều này rất hữu ích khi đổi tên giao diện đã được xuất bản. Làm cho thông tin mô tả của giao diện được đổi tên giống như mô tả của giao diện trước khi đổi tên cho phép hai giao diện giao tiếp với nhau.
@ẩn trong nhận xét
Trình biên dịch AIDL nhận ra @hide
trong các nhận xét và truyền mã này qua
sang đầu ra Java để metalava đến lấy hàng. Nhận xét này đảm bảo rằng Android
hệ thống xây dựng biết rằng API AIDL không phải là API SDK.
@đã ngừng hoạt động trong nhận xét
Trình biên dịch AIDL nhận ra @deprecated
trong các nhận xét dưới dạng một thẻ để xác định một
Thực thể AIDL không được dùng nữa.
interface IFoo {
/** @deprecated use bar() instead */
void foo();
void bar();
}
Mỗi phần phụ trợ đánh dấu các thực thể không dùng nữa bằng chú thích dành riêng cho phần phụ trợ hoặc
để mã ứng dụng khách được cảnh báo nếu nó tham chiếu đến thuộc tính
thực thể. Ví dụ: chú giải @Deprecated
và @deprecated
được đính kèm vào mã do Java tạo.