支援的 FIDL 屬性如下:
@available
@deprecated
@discoverable
@doc
@generated_name
@no_doc
@selector
@transitional
@transport
@unknown
範圍
FIDL 元素前面的屬性,例如:
@doc(" MyType summary\n")
type MyType = struct {
用於修改元素特性或提供說明文件。
語法
屬性可能包含值,多個屬性可能會堆疊,例如:
@discoverable
@transport("Channel")
同時說明以下兩個層面:
- 有兩個屬性:
@discoverable
和@transport
,以及 @transport
屬性會從下方列舉的清單取得值。
@available
USAGE:@available(platform="
string", added=
版本,
deprecated=
版本, removed=
版本, removed=
版本,
note="
字串", legacy=
舊版)
MEANING:所有引數都是選用引數,但必須提供至少一個引數。
platform
:只有在屬性出現在library
宣告中時才能使用。必須是有效的程式庫名稱元素。如果省略,則會預設為程式庫名稱的第一個元素。added
、deprecated
、removed
、replaced
:必須是介於 1 到 2^63-1 之間的整數,或是特殊常數HEAD
。不得為LEGACY
。removed
和replaced
互斥,無法共同存在。- 必須遵循
added <= deprecated < removed
或added <= deprecated < replaced
。
note
:只有在提供deprecated
的情況下才允許。提供簡短的說明,指示您改用哪些功能,適合包含在編譯器錯誤訊息中。legacy
:只有在提供或沿用removed
的情況下才允許。預設值為 False。如為 true,該元素會包含LEGACY
版本。
詳情請參閱 FIDL 版本管理。
@deprecated
USAGE:@deprecated
MEANING:請參閱 RFC-0058。
@discoverable
USAGE:@discoverable(
name)
MEANING:指派用於服務探索的名稱。也就是說,@discoverable
通訊協定可以使用指定的名稱提供,而連線至該通訊協定的用戶端則可使用相同名稱搜尋該通訊協定。如此便可在用戶端搜尋正確的名稱,而不需手動確保查詢名稱與伺服器端傳遞的名稱相符。
如果省略 name,系統會根據程式庫和通訊協定名稱 (例如 some.library.SomeProtocol
) 產生名稱。如果提供「name」,則必須採用相同格式。請注意,這「不是」完整名稱,而是使用斜線 (例如 some.library/SomeProtocol
)。
@doc
USAGE:@doc("
string")
MEANING:在 FIDL 中,註解的開頭可以有兩個 (「//
」) 或三個斜線 (「///
」),也可以在 @doc
屬性中納入這些項目。雙斜線變化版本不會將註解傳播至產生的目標,而三斜線和 @doc
變體則會同時套用。
如下所示:
/// Foo
type WithThreeSlashes = struct {
和
@doc("Foo")
type WithAttribute = struct {
達到相同效果,其中一個 (「///
」) 是彼此的語法糖。註解文字會發送到產生的程式碼,運作方式與譯文語言的語法相容。
@generated_name
USAGE:@generated_name("Foo")
MEANING:這個屬性用來覆寫 fidlc
為所有內嵌版面配置保留的名稱。當您偏好使用其他名稱時,這項功能就很實用 (例如避免與其他類型名稱衝突)。
舉例來說,以下程式碼會導致名稱衝突,因為這兩個內嵌版面配置都會保留相同的 Options
名稱:
table StartupConfig {
1: options table {
...
};
...
};
table TeardownConfig {
2: options table {
...
};
};
要區分兩者之間的一種方法,是手動指定不同的產生名稱:
table StartupConfig {
1: options
@generated_name("StartupOptions") table {
...
};
...
};
table TeardownConfig {
1: options
@generated_name("TeardownOptions") table {
...
};
...
};
@no_doc
USAGE:@no_doc
MEANING:這個屬性是用來標示文件產生工具應略過的程式庫。舉例來說,這個屬性由產生的 FIDL 程式庫 (例如驅動程式繫結編譯器) 使用。
@selector
USAGE:@selector("
選取器")
MEANING:可讓您變更方法序數的雜湊基礎,請參閱 RFC-0020。selector 可以是原始方法的名稱 (例如 SomeMethod
) 或完整名稱。
可用於在不影響 ABI 相容性的情況下重新命名方法。舉例來說,如果想在 Science
介面中將 Investigate
方法重新命名為 Experiment
,我們可以編寫:
protocol Science {
@selector("Investigate")
Experiment();
};
這項屬性也可用來處理從某個通訊協定移至另一個通訊協定,或移至另一個程式庫的方法,或兩者並用。舉例來說,假設在 purple.examples.docs
程式庫的 fuchsia.examples.docs
程式庫中,Org
通訊協定上的 Org
通訊協定原本在 Area120
通訊協定上命名為 Discover
:Productionize
protocol Org {
@selector("purple.examples.docs/Area120.Discover")
Productionize();
};
@transitional
USAGE:@transitional("
description")
MEANING:指示繫結產生可成功建構的程式碼,無論是否實作方法都一樣。RFC-0021 包含更多詳細資料。
@transport
USAGE:@transport("
tranportList")
MEANING:可讓您選取傳輸。請提供以逗號分隔的值清單,選項如下:
Channel
— 使用 Zircon 頻道。Syscall
:用來指定通訊協定用於定義 Zircon syscall (而非一般 IPC) 的傳輸機制。
如未指定,則預設值為 Channel
。如果指定值或值,則系統只會使用這些值 (例如指定 @transport("Foo")
會停用 Channel
,且只使用 Foo
)。
@unknown
USAGE:@unknown
MEANING:您可以將 @unknown
置於列舉成員中,表示此成員代表特定的未知預留位置。其用意是將以「未知」成員手動實作的嚴格行為,轉換為手動實作的嚴格列舉,轉換為彈性列舉:在轉換為彈性前,使用 @unknown
屬性將代表未知的成員加上註解,確保 @unknown
成員會視為不明資料,而不是當做已知成員。移除 @unknown
成員的使用後,就不再需要該成員。