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 的向量。只要沒有其他子項，就會傳回空白向量。

要求

<EMPTY>

回應

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

控制器

定義於 fuchsia.component/controller.fidl

新增時間：18 歲

GetExposedDictionary

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

已新增：HEAD

要求

名稱類型
dictionary server_end<fuchsia.component.sandbox/Dictionary>

回應

名稱類型
payload Controller_GetExposedDictionary_Result

IsStarted

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

要求

<EMPTY>

回應

名稱類型
payload Controller_IsStarted_Result

開始

啟動元件，並視需要提供其他要給元件的控點。如果執行個體目前正在執行，則傳回 INSTANCE_ALREADY_RUNNING。

要求

名稱類型
args StartChildArgs
execution_controller server_end<ExecutionController>

回應

名稱類型
payload Controller_Start_Result

EventStream

在 fuchsia.component/events.fidl 中定義

元件階層事件的事件監聽器。

新增時間：11 張

GetNext

要求

<EMPTY>

回應

名稱類型
events vector<Event>

WaitForReady

立即傳回。用來表示 FIDL 連線已完成。非靜態串流需要執行此操作，才能在元件開始之前驗證訂閱是否已完成。

要求

<EMPTY>

回應

<EMPTY>

ExecutionController

定義於 fuchsia.component/controller.fidl

新增時間：18 歲

OnStop

當子項因呼叫 Stop 而停止時，子項會自行結束或其他原因，系統會呼叫 OnStop 並關閉這個管道。

回應

名稱類型
stopped_payload StoppedPayload

停止

啟動此元件的停止動作。完成後，系統就會使用已停止的酬載呼叫 OnStop。

請注意，元件隨時都有可能會停止運作，因此在呼叫 Stop 之前，也可能收到 OnStop。

要求

<EMPTY>

引言

定義於 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：無法在 SingleRun 集合中解析 child 的元件宣告。
  • 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

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_GetExposedDictionary_Response

定義於 fuchsia.component/controller.fidl

<EMPTY>

Controller_IsStarted_Response 資源

定義於 fuchsia.component/controller.fidl

廣闊類型說明預設
is_started bool 無預設

Controller_Start_Response

定義於 fuchsia.component/controller.fidl

<EMPTY>

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

<EMPTY>

Realm_DestroyChild_Response

定義於 fuchsia.component/realm.fidl

<EMPTY>

Realm_ListChildren_Response

定義於 fuchsia.component/realm.fidl

<EMPTY>

Realm_OpenExposedDir_Response

定義於 fuchsia.component/realm.fidl

<EMPTY>

ENUMS

錯誤：strict

類型：uint32

定義於 fuchsia.component/error.fidl

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

名稱值說明
1

元件管理員在執行作業時遇到其他未指定的錯誤。
2

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

系統尚未支援這項功能。
4

呼叫端沒有執行指定作業的權限，或提供給該通話的其中一個控制代碼沒有充分權限。
5

找不到元件執行個體。
6

元件執行個體已存在。
7

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

無法解析元件的宣告。
9

找不到元件集合。
10

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

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

要求的資源不存在。
13

無法取消解析元件。
14

元件執行個體已啟動。

新增日期：14 天

EventType strict

類型：uint32

在 fuchsia.component/events.fidl 中定義

這些 EventTypes 用於 EventStream 通訊協定。它們是 hooks.rs 中屬於 EventType 列舉的 FIDL 版本，意義相同。

新增時間：11 張

名稱值說明
1

已要求這個元件提供的功能。事件酬載會產生要求管道。
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 張

序數廣闊類型說明
name name

能力的名稱。
capability handle<channel>

管道端伺服器主機的代管能力控制代碼。

CreateChildArgs 資源

定義於 fuchsia.component/realm.fidl

序數廣闊類型說明
numbered_handles vector<fuchsia.process/HandleInfo>[128]

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

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

用於指定元件執行個體的動態優惠。

如果在這個向量中加入 OfferDecl，系統就會向新建的子項提供額外功能，而非提供指定集合的父項 ComponentDecl 中的 OfferDecl。

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

動態優惠一律會指定新建立的子元件。因此，dynamic_offers 中的 OfferDecl 不得設定 target 欄位，因為該欄位的值以隱含方式表示。

如果來源 (也就是 OfferDecl 中 source 欄位指定的元件) 或動態優惠的目標遭到刪除，優惠本身會同時遭到刪除。

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

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

新增日期：14 天
config_capabilities vector<fuchsia.component.decl/Configuration>[128]

用於指定元件執行個體的設定功能。

在這個清單中納入設定，就會在目前領域中將設定功能新增為動態能力。這樣做也會為子項建立這項能力的動態優惠。

動態優惠是從 self 建立到新建立的子項。

如果刪除新建立的子項，設定能力和產生的動態優惠都會遭到刪除。

如要將這個欄位設為非空白值，建立子項元件的集合必須指定 ComponentDecl.allowed_offers = STATIC_AND_DYNAMIC。

已新增：HEAD
dictionary fuchsia.component.sandbox/Dictionary

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

已新增：HEAD

DebugStartedPayload 資源

在 fuchsia.component/events.fidl 中定義

DebugStarted 事件酬載。

新增時間：11 張

序數廣闊類型說明
runtime_dir fuchsia.io/Directory

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

偵錯工具使用的事件組合，可延遲元件的啟動作業，例如ELF 偵錯工具可以在保留事件組合時，在工作上設定例外狀況管道，然後捨棄事件組合來通知執行元件可以建立程序。另一端傳送到 ComponentStartInfo 中的執行元件。

DestroyedPayload

在 fuchsia.component/events.fidl 中定義

已刪除事件的酬載。

新增時間：11 張

序數廣闊類型說明

DiscoveredPayload

在 fuchsia.component/events.fidl 中定義

探索事件的酬載。

新增時間：11 張

序數廣闊類型說明

事件資源

在 fuchsia.component/events.fidl 中定義

包含單一事件的所有資訊

新增時間：11 張

序數廣闊類型說明
header EventHeader

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

部分事件類型的選用酬載

EventHeader

在 fuchsia.component/events.fidl 中定義

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

新增時間：11 張

序數廣闊類型說明
event_type EventType

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

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

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

事件發生的時間。

NamespaceEntry 資源

定義於 fuchsia.component/controller.fidl

單一元件命名空間項目，描述一個命名空間掛接點 (path) 及其背後的目錄 (directory)。此類型通常在向量內組成。詳情請參閱 ComponentStartInfo.ns。

新增日期：14 天

序數廣闊類型說明
path string[4095]

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

掛接在上述 path 的目錄。

PurgedPayload

在 fuchsia.component/events.fidl 中定義

已清除事件的酬載。

新增時間：11 張

序數廣闊類型說明

ResolvedPayload

在 fuchsia.component/events.fidl 中定義

已解決事件的酬載。

新增時間：11 張

序數廣闊類型說明

StartChildArgs 資源

定義於 fuchsia.component/controller.fidl

新增日期：14 天

序數廣闊類型說明
numbered_handles vector<fuchsia.process/HandleInfo>[128]

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

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

設定後，此處提供的值將會覆寫 CreateChildArgs 中指定的控點。
namespace_entries vector<NamespaceEntry>[32]

元件管理員產生的命名空間將經過擴充，納入這裡列出的任何命名空間項目，再將其提供給元件的執行元件。

如有任何衝突的項目，啟動元件時就會發生錯誤。
dictionary fuchsia.component.sandbox/Dictionary

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

已新增：HEAD

StartedPayload

在 fuchsia.component/events.fidl 中定義

已開始事件的酬載。

新增時間：11 張

序數廣闊類型說明

StoppedPayload

在 fuchsia.component/events.fidl 中定義

已停止事件的酬載。

新增時間：11 張

序數廣闊類型說明
status zx/Status

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

UnresolvedPayload

在 fuchsia.component/events.fidl 中定義

未解析事件的酬載。

新增時間：11 張

序數廣闊類型說明

聯合國

Controller_GetExposedDictionary_Result 嚴格

定義於 fuchsia.component/controller.fidl

序數Variant類型說明
response Controller_GetExposedDictionary_Response
err Error
framework_err internal

Controller_IsStarted_Result 嚴格 資源

定義於 fuchsia.component/controller.fidl

序數Variant類型說明
response Controller_IsStarted_Response
err Error
framework_err internal

Controller_Start_Result 嚴格

定義於 fuchsia.component/controller.fidl

序數Variant類型說明
response Controller_Start_Response
err Error
framework_err internal

EventPayload 彈性 資源

在 fuchsia.component/events.fidl 中定義

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

新增時間：11 張
序數Variant類型說明
capability_requested CapabilityRequestedPayload

CapabilityRequested 事件的酬載
purged PurgedPayload

已清除事件的酬載。
discovered DiscoveredPayload

探索事件的酬載。
destroyed DestroyedPayload

已刪除事件的酬載。
resolved ResolvedPayload

已解決事件的酬載
started StartedPayload

已開始事件酬載
stopped StoppedPayload

已停止事件的酬載
debug_started DebugStartedPayload

DebugStarted 事件酬載
unresolved UnresolvedPayload

未解析事件的酬載

Introspector_GetMoniker_Result 嚴格

定義於 fuchsia.component/introspector.fidl

序數Variant類型說明
response Introspector_GetMoniker_Response
err Error
framework_err internal

Namespace_Create_Result 嚴格 資源

定義於 fuchsia.component/namespace.fidl

序數Variant類型說明
response Namespace_Create_Response
err NamespaceError
framework_err internal

Realm_CreateChild_Result 嚴格

定義於 fuchsia.component/realm.fidl

序數Variant類型說明
response Realm_CreateChild_Response
err Error

Realm_DestroyChild_Result 嚴格

定義於 fuchsia.component/realm.fidl

序數Variant類型說明
response Realm_DestroyChild_Response
err Error

Realm_ListChildren_Result 嚴格

定義於 fuchsia.component/realm.fidl

序數Variant類型說明
response Realm_ListChildren_Response
err Error

Realm_OpenExposedDir_Result 嚴格

定義於 fuchsia.component/realm.fidl

序數Variant類型說明
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_CONFIG_COUNT 128 uint32
已新增：HEAD
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 歲

別名

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