fuchsia.component

新增：7

通訊協定

繫結機制

定義於 fuchsia.component/binder.fidl

架構提供的通訊協定，允許使用該架構的元件繫結至 可以新增可用元件的元件連線至這個通訊協定的行為 觸發繫結。因此，這個通訊協定不含任何方法。瞭解詳情 有關繫結，請參閱 https://fuchsia.dev/fuchsia-src/concepts/components/v2/lifecycle#binding.

當元件連上通訊協定時，元件就會公開這項能力 就會啟動 (如果尚未執行的話)若無法啟動， 元件架構會用 zx.Status 八分音符。

ChildIterator

在 fuchsia.component/realm.fidl 定義

一種通訊協定，可疊代領域中的子項清單。

繼續

推動疊代器並傳回下一批次的子項。

傳回 ChildRef 的向量。如果有空白向量 也不要再小孩

要求

<空白>

回應

名稱類型
children vector<fuchsia.component.decl/ChildRef>[128]

控制器

在 fuchsia.component/controller.fidl 定義

用於元件上作業的通訊協定。

使用Controller Realm.CreateChild 方法。您或許也能Controller 運用 Realm.OpenController 方法處理現有子項元件

新增：14

刪除

刪除這個元件。當這個方法傳回時，系統會傳回以下兩者之一：

  • 傳回結果，表示刪除已開始。
  • 系統傳回錯誤，系統不會嘗試刪除。

如果傳回 Ok 訊息，刪除作業會在背景繼續進行，但刪除作業會在背景執行 可能尚未完成完成後，架構就會 關閉此 [控制器] 管道。

錯誤：

  • ACCESS_DENIED：不允許刪除這個元件。 目前如果元件是其靜態子項，就可能發生這種情況 父項。
新增時間：HEAD

要求

<空白>

回應

名稱類型
payload Controller_Destroy_Result

GetExposedDictionary

傳回包含元件公開功能的字典。

新增時間：HEAD

要求

<空白>

回應

名稱類型
payload Controller_GetExposedDictionary_Result

IsStarted

如果這個執行個體正在執行，則傳回 true。

要求

<空白>

回應

名稱類型
payload Controller_IsStarted_Result

開始

啟動元件，並視需要提供其他控點 加入元件如果執行個體是 目前運作中的 Pod

要求

名稱類型
args StartChildArgs
execution_controller server_end<ExecutionController>

回應

名稱類型
payload Controller_Start_Result

EventStream

在 fuchsia.component/events.fidl 中定義的

元件階層事件的接聽程式。 無法在平台外部使用。

新增日期：11

GetNext

要求

<空白>

回應

名稱類型
events vector<Event>

WaitForReady

立即傳回。用於表示 FIDL 連線 已完成非靜態串流必須這麼做才能進行驗證 訂閱者必須先完成訂閱，才算是元件

要求

<空白>

回應

<空白>

ExecutionController

在 fuchsia.component/controller.fidl 定義

新增：14

OnStop

當子項因呼叫 Stop 而停止時，子項就會退出 或基於任何其他理由，呼叫 OnStop，然後 就會關閉管道

回應

名稱類型
stopped_payload StoppedPayload

停止

針對這個元件啟動停止動作。完成後，OnStop 就會 呼叫停止的酬載，且這個管道已關閉。

請注意，元件隨時可能自行停止執行，因此 可能在呼叫 Stop 前接收 OnStop

要求

<空白>

自我介紹人

定義於 fuchsia.component/introspector.fidl

元件執行個體用來取得相關資訊的通訊協定 和專屬領域中的元件

這個通訊協定目前只支援取得路徑名稱，但 會展開至其他特殊權限資訊，例如元件的網址。

元件架構為採用 fuchsia.component.Introspector 來自架構。

新增時間：HEAD

GetMoniker

取得相對於元件的這個領域來獲取的路徑名稱 對應於提供的權杖執行器可透過以下方法取得權杖： fuchsia.component.runner/ComponentStartInfo.component_instance。

如果權杖無效，則傳回 Error.INSTANCE_NOT_FOUND；或 未對應至這個領域底下的元件。

要求

名稱類型
component_instance handle<event>

回應

名稱類型
payload Introspector_GetMoniker_Result

命名空間

在 fuchsia.component/namespace.fidl 定義

執行命名空間作業的通訊協定。

新增：20

建立

要求

名稱類型
entries vector<NamespaceInputEntry>

回應

名稱類型
payload Namespace_Create_Result

領域

在 fuchsia.component/realm.fidl 定義

元件執行個體用來管理自身領域的通訊協定，例如 繫結至其子項

我們會按照接收順序處理傳送至這個通訊協定的要求， 想要同時傳送要求的用戶端，應開啟多個 連線狀態。

元件架構可提供此服務給使用 fuchsia.component.Realm。

CreateChild

動態建立子項元件執行個體。當這個函式 會傳回成功，但執行個體可能存在，但可能並未執行。

子項執行個體的環境取決於環境 集合。decl不得設定「environment」。

如果 decl.startup == EAGER 或 collection.durability == SINGLE_RUN， [CreateChild] 會啟動元件，並在元件 已開始。否則 [CreateChild] 會在建立後立即傳回 無法啟動或解析該元件

錯誤：

  • INVALID_ARGUMENTS：collection 不是有效的參照或 child 不是有效的宣告。
  • COLLECTION_NOT_FOUND：collection不存在。
  • INSTANCE_ALREADY_EXISTS：collection中已有「decl.name」。
  • INSTANCE_CANNOT_RESOLVE：child 的元件宣告無法解析 「SingleRun」集合中。
  • NO_SPACE：無法為新的執行個體分配儲存空間。
  • INSTANCE_DIED：這個領域已不存在。

要求

名稱類型
collection fuchsia.component.decl/CollectionRef
decl fuchsia.component.decl/Child
args CreateChildArgs

回應

名稱類型
payload Realm_CreateChild_Result

DestroyChild

刪除動態建立的元件執行個體。當這個函式 就會刪除，執行個體也已遭到刪除並停止執行。不過 並清除元件資源 (例如獨立儲存空間) 的 會在這個函式傳回後於背景執行

錯誤：

  • INVALID_ARGUMENTS：child 不是有效參考資料或未參照 複製到動態執行個體
  • INSTANCE_NOT_FOUND：child不存在。
  • COLLECTION_NOT_FOUND：collection不存在。
  • INSTANCE_DIED：這個領域已不存在。

要求

名稱類型
child fuchsia.component.decl/ChildRef

回應

名稱類型
payload Realm_DestroyChild_Result

ListChildren

傳回列出集合中所有執行個體的疊代器。

注意：結果不保證一致。執行個體 疊代器上線期間建立或刪除的檔案 此方法傳回。

錯誤：

  • INVALID_ARGUMENTS：collection 不是有效的參照或 iter 不含 ZX_RIGHT_WAIT。
  • COLLECTION_NOT_FOUND：collection不存在。
  • INSTANCE_DIED：這個領域已不存在。
  • 如果「iter」不具備一般管道權限，這項功能可能會 傳回 ACCESS_DENIED 或元件管理員可關閉 iter。

要求

名稱類型
collection fuchsia.component.decl/CollectionRef
iter server_end<ChildIterator>

回應

名稱類型
payload Realm_ListChildren_Result

OpenController

對子項元件執行操作。請參閱「控制器」的說明文件。

錯誤：

  • INVALID_ARGUMENTS：child 不是有效的子參照。
  • INSTANCE_NOT_FOUND：child不存在。
  • INSTANCE_DIED：這個領域已不存在。
新增時間：HEAD

要求

名稱類型
child fuchsia.component.decl/ChildRef
controller server_end<Controller>

回應

名稱類型
payload Realm_OpenController_Result

OpenExposedDir

開啟公開的子項元件執行個體目錄。當此情況 函式成功傳回，exposed_dir 繫結至目錄 其中包含子機構向其領域公開的功能 透過 ComponentDecl.exposes (透過 元件的資訊清單)。子項元件並非以 結果。而是會在父項繫結的情況下開始 而是 exposed_dir 中的其中一項功能。

只要 child 存在，「exposed_dir」就會營業。

錯誤：

  • INVALID_ARGUMENTS：child 不是有效的子參照。
  • INSTANCE_NOT_FOUND：child不存在。
  • INSTANCE_CANNOT_RESOLVE：無法解析 child 的元件宣告。
  • INSTANCE_DIED：這個領域已不存在。

要求

名稱類型
child fuchsia.component.decl/ChildRef
exposed_dir server_end<fuchsia.io/Directory>

回應

名稱類型
payload Realm_OpenExposedDir_Result

結構

Controller_Destroy_Response

在 fuchsia.component/controller.fidl 定義

<空白>

Controller_GetExposedDictionary_Response 資源

在 fuchsia.component/controller.fidl 定義

欄位類型說明預設
dictionary fuchsia.component.sandbox/DictionaryRef 無預設

Controller_IsStarted_Response 資源

在 fuchsia.component/controller.fidl 定義

欄位類型說明預設
is_started bool 無預設

Controller_Start_Response

在 fuchsia.component/controller.fidl 定義

<空白>

Introspector_GetMoniker_Response

定義於 fuchsia.component/introspector.fidl

欄位類型說明預設
moniker string[4096] 無預設

NamespaceInputEntry 資源

在 fuchsia.component/namespace.fidl 定義

新增：20

欄位類型說明預設
path string[4095] 無預設
dictionary fuchsia.component.sandbox/Dictionary 無預設

Namespace_Create_Response 資源

在 fuchsia.component/namespace.fidl 定義

欄位類型說明預設
entries vector<NamespaceEntry> 無預設

Realm_CreateChild_Response

在 fuchsia.component/realm.fidl 定義

<空白>

Realm_DestroyChild_Response

在 fuchsia.component/realm.fidl 定義

<空白>

Realm_ListChildren_Response

在 fuchsia.component/realm.fidl 定義

<空白>

Realm_OpenController_Response

在 fuchsia.component/realm.fidl 定義

<空白>

Realm_OpenExposedDir_Response

在 fuchsia.component/realm.fidl 定義

<空白>

ENUMS

錯誤彈性

類型：uint32

定義於 fuchsia.component/error.fidl

元件架構通訊協定的標準錯誤代碼。

名稱值說明
1

元件管理員發生其他不明錯誤 執行作業。
2

至少有一個引數的格式無效。
3

尚未支援此功能。
4

呼叫端沒有執行指定作業的權限。 或提供的其中一個帳號代碼沒有足夠的權限。
5

找不到元件執行個體。
6

元件執行個體已存在。
7

無法啟動元件執行個體。
8

無法解析元件的宣告。
9

找不到元件集合。
10

資源不足，無法執行這項作業。
11

元件執行個體意外停止運作。
12

要求的資源不存在。
13

無法取消解析元件。
14

元件執行個體已啟動。

新增：14

EventType 嚴格

類型：uint32

在 fuchsia.component/events.fidl 中定義的

這些 EventType 是用於 EventStream 通訊協定。 這些是 hooks.rs 中的 EventType 列舉 FIDL 版本， 這兩個概念

新增日期：11

名稱值說明
1

這個元件已要求一項能力。事件 酬載則會承載要求管道。
2

可使用一個元件公開對架構的目錄。

移除時間：20
3

找到元件執行個體。這是生命週期的第一個階段 元件在建立動態子項時分派給靜態元素 子項資源，且在元件管理員時，用於根層級 就可以開始
4

執行個體遭刪除且已不存在。
5

第一次成功解決執行個體的宣告。
6

這個執行個體已根據元件管理員啟動。不過，如果是 可執行檔元件，執行元件還有進一步的工作來啟動元件。
7

已成功停止執行個體。
8

與 STARTED 類似，但酬載會保留訂閱者所發出的事件配對 可以延遲元件啟動的時間舉例來說，偵錯工具 在建立任何程序之前 先執行一些設定
9

成功未解析執行個體。

NamespaceError 彈性

類型：uint32

在 fuchsia.component/namespace.fidl 定義

Namespace 中的方法傳回錯誤。

新增：20

名稱值說明
1

父項父項與其他命名空間項目共用前置字串
2

兩個項目具有相同的命名空間路徑。
3

無法將命名空間字典轉換為目錄。

BAD_ENTRY

 4

命名空間項目無效。
5

讀取其中一個字典時發生錯誤，

資料表

CapabilityRequestedPayload 資源

在 fuchsia.component/events.fidl 中定義的

CapabilityRequested 事件的酬載

新增日期：11

Ordinal欄位類型說明
name name

能力的名稱。
capability handle<channel>

要託管的管道伺服器端的控制代碼 技術。

CreateChildArgs 資源

在 fuchsia.component/realm.fidl 定義

Ordinal欄位類型說明
numbered_handles vector<fuchsia.process/HandleInfo>[128]

要傳遞至元件執行個體的編號控點。

如果元件的執行元件不支援編號控點， 會關閉控點
dynamic_offers vector<fuchsia.component.decl/Offer>[128]

這會指定元件執行個體的動態優惠。

在這個向量中加入 OfferDecl 會造成額外功能 提供給新建立的孩子 (除了 OfferDecl秒) 指定集合的父項 ComponentDecl。

任何種類的優惠 (例如通訊協定、目錄) 都可以當做動態使用 方案。適用於靜態優惠的任何來源也都有效 定義動態優惠此外，動態優惠與靜態優惠不同 可以使用「同層」將動態子項元件設為來源 來源為設定 collection 欄位的 ChildRef。

動態優惠一律會指定新建立的子元件。身為 結果，dynamic_offers 中的 OfferDecl 不得設定 target 欄位，因為其值在隱含。

如果來源是其中之一 (也就是 source 欄位中命名的元件)， OfferDecl) 或動態優惠的目標遭到刪除， 優惠本身就會被銷毀

如要將這個欄位設為非空白值， 正在建立的子項元件 ComponentDecl.allowed_offers = STATIC_AND_DYNAMIC。
controller server_end<Controller>

此元件的控制器，可能會用來影響 整個元件的生命週期

新增：14
dictionary fuchsia.component.sandbox/DictionaryRef

字典，包含元件執行個體的額外功能。

新增時間：HEAD

DebugStartedPayload 資源

在 fuchsia.component/events.fidl 中定義的

DebugStarted 事件的酬載。

新增日期：11

Ordinal欄位類型說明
runtime_dir fuchsia.io/Directory

執行元件提供的目錄，用於顯示執行階段和執行元件專屬資訊 關於元件另一端則傳送到 ComponentStartInfo 中的執行元件。 舉例來說，您可以透過查詢瞭解元件是否為 ELF 元件 支援下方的斷路_on_start 通訊協定
break_on_start handle<eventpair>

可讓偵錯工具用來延後元件啟動的事件配對。 例如：ELF 偵錯管道可在您按住 然後放置事件配對，通知執行元件程序可能 另一端則傳送到 ComponentStartInfo 中的執行元件。

DestroyedPayload

在 fuchsia.component/events.fidl 中定義的

已刪除事件的酬載。

新增日期：11

Ordinal欄位類型說明

DirectoryReadyPayload 資源

在 fuchsia.component/events.fidl 中定義的

DirectoryReady 事件酬載

已移除：20 已淘汰：19 新增：11

Ordinal欄位類型說明
name name

能力的名稱。
node fuchsia.io/Node

連結至目錄能力。

DiscoveredPayload

在 fuchsia.component/events.fidl 中定義的

探索事件的酬載。

新增日期：11

Ordinal欄位類型說明

事件資源

在 fuchsia.component/events.fidl 中定義的

包含單一事件的所有相關資訊

新增日期：11

Ordinal欄位類型說明
header EventHeader

產生此事件的元件相關資訊。
payload EventPayload

部分事件類型的選用酬載

EventHeader

在 fuchsia.component/events.fidl 中定義的

提供目標元件執行個體中繼資料的標頭。

新增日期：11

Ordinal欄位類型說明
event_type EventType

與事件對應的事件類型
moniker string[4096]

用於識別元件執行個體的相對路徑名稱。相對於事件範圍。
component_url fuchsia.url/Url

用來解析元件的網址。
timestamp zx/Time

事件發生的時間。

NamespaceEntry 資源

在 fuchsia.component/controller.fidl 定義

單一元件命名空間項目，用於說明命名空間掛接點 (path) 和支援該資料的目錄 (directory)。這個類型通常 組成詳情請參閱 ComponentStartInfo.ns。

新增：14

Ordinal欄位類型說明
path string[4095]

目錄的掛接點，包括 開頭加上斜線例如：「/pkg」、「/svc」或「/config/data」。
directory fuchsia.io/Directory

掛接在上述 path 的目錄。

PurgedPayload

在 fuchsia.component/events.fidl 中定義的

清除事件的酬載。

新增：11

Ordinal欄位類型說明

ResolvedPayload

在 fuchsia.component/events.fidl 中定義的

已解析事件的酬載。

新增：11

Ordinal欄位類型說明

StartChildArgs 資源

在 fuchsia.component/controller.fidl 定義

新增：14

Ordinal欄位類型說明
numbered_handles vector<fuchsia.process/HandleInfo>[128]

要傳遞至元件執行個體的編號控點。

如果元件的執行元件不支援編號處理， 應關閉控點

設定後，此處指定的值將會覆寫 CreateChildArgs.
namespace_entries vector<NamespaceEntry>[32]

元件管理員產生的命名空間將擴大納入 尚未提供給元件的 執行元件

如果項目有任何衝突，啟動時就會發生錯誤 這個元件
dictionary fuchsia.component.sandbox/DictionaryRef

字典，包含元件執行個體的額外功能。

新增時間：HEAD

StartedPayload

在 fuchsia.component/events.fidl 中定義的

啟動事件的酬載。

新增日期：11

Ordinal欄位類型說明

StoppedPayload

在 fuchsia.component/events.fidl 中定義的

已停止事件的酬載。

新增：11

Ordinal欄位類型說明
status zx/Status

設定在 fuchsia.component.runner/ComponentController 上的 Epitaph 通訊協定管道這是元件的結束狀態。 如要瞭解可能的狀態值及其意義，請參閱 元件控制器
exit_code int64

元件執行個體的結束代碼。請注意，並非所有元件 停止傳送容器

許多程式執行階段都有結束程式碼的概念。跑者可以繪製地圖 填入這個欄位例如：ELF 執行元件 會在此處發布 Zircon 程序的傳回碼。

新增日期：23

UnresolvedPayload

在 fuchsia.component/events.fidl 中定義的

未解析事件的酬載。

新增日期：11

Ordinal欄位類型說明

聯合國

Controller_Destroy_Result 嚴格

在 fuchsia.component/controller.fidl 定義

OrdinalVariant類型說明
response Controller_Destroy_Response
err Error
framework_err internal

Controller_GetExposedDictionary_Result 嚴格 資源

在 fuchsia.component/controller.fidl 定義

OrdinalVariant類型說明
response Controller_GetExposedDictionary_Response
err Error
framework_err internal

Controller_IsStarted_Result 嚴格 資源

在 fuchsia.component/controller.fidl 定義

OrdinalVariant類型說明
response Controller_IsStarted_Response
err Error
framework_err internal

Controller_Start_Result 嚴格

在 fuchsia.component/controller.fidl 定義

OrdinalVariant類型說明
response Controller_Start_Response
err Error
framework_err internal

EventPayload 彈性 資源

在 fuchsia.component/events.fidl 中定義的

封裝某些事件類型的其他資料/通訊協定。

新增：11
OrdinalVariant類型說明
capability_requested CapabilityRequestedPayload

CapabilityRequested 事件的酬載
purged PurgedPayload

清除事件的酬載。
directory_ready DirectoryReadyPayload

DirectoryReady 事件酬載

已移除：20 已淘汰：19
discovered DiscoveredPayload

探索事件的酬載。

已淘汰：22
destroyed DestroyedPayload

已刪除事件的酬載。
resolved ResolvedPayload

已解析事件的酬載
started StartedPayload

啟動事件的酬載
stopped StoppedPayload

已停止事件的酬載
debug_started DebugStartedPayload

DebugStarted 事件酬載
unresolved UnresolvedPayload

未解析事件的酬載

Introspector_GetMoniker_Result 嚴格

定義於 fuchsia.component/introspector.fidl

OrdinalVariant類型說明
response Introspector_GetMoniker_Response
err Error
framework_err internal

Namespace_Create_Result 嚴格 資源

在 fuchsia.component/namespace.fidl 定義

OrdinalVariant類型說明
response Namespace_Create_Response
err NamespaceError
framework_err internal

Realm_CreateChild_Result 嚴格

在 fuchsia.component/realm.fidl 定義

OrdinalVariant類型說明
response Realm_CreateChild_Response
err Error

Realm_DestroyChild_Result 嚴格

在 fuchsia.component/realm.fidl 定義

OrdinalVariant類型說明
response Realm_DestroyChild_Response
err Error

Realm_ListChildren_Result 嚴格

在 fuchsia.component/realm.fidl 定義

OrdinalVariant類型說明
response Realm_ListChildren_Response
err Error

Realm_OpenController_Result 嚴格

在 fuchsia.component/realm.fidl 定義

OrdinalVariant類型說明
response Realm_OpenController_Response
err Error

Realm_OpenExposedDir_Result 嚴格

在 fuchsia.component/realm.fidl 定義

OrdinalVariant類型說明
response Realm_OpenExposedDir_Response
err Error

觀測站

名稱值類型說明
MAX_CAPABILITY_ID_LENGTH 50 uint64

能力 ID 的字串長度上限。 這個值目前採任意設定。

新增日期：11
MAX_CHILD_COUNT 128 uint32

呼叫 ChildIterator.Next 的子項數量上限 傳回。 請注意，這並非可新增的兒童人數限制 新增至元件這個限制只是 Next 方法。
MAX_CHILD_NAME_LENGTH 1024 uint32
MAX_DYNAMIC_OFFER_COUNT 128 uint32

可指定已建立元件的動態優惠數量上限。
MAX_ERROR_DESCRIPTION_LENGTH 100 uint64

錯誤說明的字串長度上限。

新增日期：11
MAX_HANDLE_COUNT 128 uint32

可傳遞至所建立元件的帳號代碼數量上限。
MAX_MONIKER_LENGTH 4096 uint32
MAX_NAMESPACE_COUNT 32 uint32
新增：14
MAX_NAME_LENGTH fuchsia.io/MAX_NAME_LENGTH uint64
新增日期：19
MAX_NUM_EVENTS_RECEIVED 100 uint64

接收器可監聽的事件數量上限。
MAX_PATH_LENGTH fuchsia.io/MAX_PATH_LENGTH uint64
新增：15
MAX_SUBSCRIPTION_REQUESTS 2 uint32

每個事件訂閱項目的要求數量上限。
MAX_URL_SCHEME_LENGTH MAX_NAME_LENGTH uint64
新增日期：19

ALIASES

名稱值說明
child_name string[MAX_CHILD_NAME_LENGTH]
名稱 string[MAX_NAME_LENGTH]
url_scheme string[MAX_URL_SCHEME_LENGTH]