fuchsia.element

新增：7

通訊協定

AnnotationController

在 fuchsia.element/annotations.fidl 中定義

建立、讀取、更新及刪除註解的介面，通常是元素或其檢視畫面。

GetAnnotations

傳回元素目前的 Annotations。

  • 無法傳回註解，就會發生 GetAnnotationsError 錯誤。

要求

<EMPTY>

回應

名稱類型
payload AnnotationController_GetAnnotations_Result

UpdateAnnotations

新增、更新及移除註解。

伺服器應遵守以下慣例：

  • 如果 annotations_to_set 中的索引鍵是新的，則會加入新註解
  • 如果 annotations_to_set 中已有索引鍵，則會更新註解值
  • 如果 annotations_to_delete 中的索引鍵不存在，系統會忽略該鍵

在對 UpdateAnnotations() 的呼叫中不能重複出現相同索引鍵。換句話說，設定兩個具有相符索引鍵的註解是違法行為，因為系統會嘗試設定註解並將其刪除。

如果作業造成錯誤，註解會維持不變，且不會部分更新。

  • 如果 annotations_to_set 和 annotations_to_delete 中都有相同的鍵，則會傳回 UpdateAnnotationsError.INVALID_ARGS 錯誤。
  • 如果 annotations_to_set 或 annotations_to_delete 中的金鑰包含空白命名空間，則會傳回 UpdateAnnotationsError.INVALID_ARGS 錯誤。
  • 如果無法讀取 annotations_to_set 中的 AnnotationValue.buffer，則會傳回 UpdateAnnotationsError.INVALID_ARGS 錯誤。
  • 如果作業產生超過 MAX_ANNOTATIONS_PER_ELEMENT 個註解，則會傳回 UpdateAnnotationsError.TOO_MANY_ANNOTATIONS 錯誤。

要求

名稱類型
annotations_to_set Annotations
annotations_to_delete AnnotationKeys

回應

名稱類型
payload AnnotationController_UpdateAnnotations_Result

WatchAnnotations

當一或多個物件已變更，或用戶端首次呼叫這個方法時，會傳回完整的 Annotations。

這項作業不會封鎖來自用戶端的其他要求，但一次只能在連線中提出一個 WatchAnnotations 要求。如果用戶端在等待上一個要求完成前，發出第二個 WatchAnnotations 要求，系統就會關閉連線。

  • 無法傳回註解，就會發生 WatchAnnotationsError 錯誤。

要求

<EMPTY>

回應

名稱類型
payload AnnotationController_WatchAnnotations_Result

控制器

在 fuchsia.element/element_manager.fidl 中定義的

這個介面可讓 Manager (元素建議工具) 用戶端控管建議元素的生命週期和註解。

生命週期

用戶端必須讓 Controller 保持連線，確保元素會留在工作階段中且不會遭到刪除。Controller 關閉後，元素及其元件就會終止。元素也可以自行終止，導致 Controller 關閉。

GetAnnotations

傳回元素目前的 Annotations。

  • 無法傳回註解，就會發生 GetAnnotationsError 錯誤。

要求

<EMPTY>

回應

名稱類型
payload AnnotationController_GetAnnotations_Result

UpdateAnnotations

新增、更新及移除註解。

伺服器應遵守以下慣例：

  • 如果 annotations_to_set 中的索引鍵是新的，則會加入新註解
  • 如果 annotations_to_set 中已有索引鍵，則會更新註解值
  • 如果 annotations_to_delete 中的索引鍵不存在，系統會忽略該鍵

在對 UpdateAnnotations() 的呼叫中不能重複出現相同索引鍵。換句話說，設定兩個具有相符索引鍵的註解是違法行為，因為系統會嘗試設定註解並將其刪除。

如果作業造成錯誤，註解會維持不變，且不會部分更新。

  • 如果 annotations_to_set 和 annotations_to_delete 中都有相同的鍵，則會傳回 UpdateAnnotationsError.INVALID_ARGS 錯誤。
  • 如果 annotations_to_set 或 annotations_to_delete 中的金鑰包含空白命名空間，則會傳回 UpdateAnnotationsError.INVALID_ARGS 錯誤。
  • 如果無法讀取 annotations_to_set 中的 AnnotationValue.buffer，則會傳回 UpdateAnnotationsError.INVALID_ARGS 錯誤。
  • 如果作業產生超過 MAX_ANNOTATIONS_PER_ELEMENT 個註解，則會傳回 UpdateAnnotationsError.TOO_MANY_ANNOTATIONS 錯誤。

要求

名稱類型
annotations_to_set Annotations
annotations_to_delete AnnotationKeys

回應

名稱類型
payload AnnotationController_UpdateAnnotations_Result

WatchAnnotations

當一或多個物件已變更，或用戶端首次呼叫這個方法時，會傳回完整的 Annotations。

這項作業不會封鎖來自用戶端的其他要求，但一次只能在連線中提出一個 WatchAnnotations 要求。如果用戶端在等待上一個要求完成前，發出第二個 WatchAnnotations 要求，系統就會關閉連線。

  • 無法傳回註解，就會發生 WatchAnnotationsError 錯誤。

要求

<EMPTY>

回應

名稱類型
payload AnnotationController_WatchAnnotations_Result

GraphicalPresenter

在 fuchsia.element/graphical_presenter.fidl 中定義

這個介面用於指示伺服器顯示圖形檢視畫面，以及觀察及控制檢視區塊的生命週期。

PresentView

顯示view_spec描述的檢視畫面。

如果提供 view_controller_request，就會連線至由 GraphicalPresenter 伺服器實作的 ViewController。當檢視畫面關閉時，ViewController 管道會使用 ZX_OK 關閉，此時可以放心清除備份檢視畫面的資源。如要關閉檢視畫面，用戶端應呼叫 ViewController.Dismiss() 並等待 ZX_OK 程式碼。如未提供 view_controller_request 控制代碼，用戶端就無法觀測檢視畫面的生命週期。

  • view_spec 說明要顯示的檢視畫面
  • annotation_controller 是 AnnotationController 的控制代碼，可讓 GraphicalPresenter 伺服器觀察及更新檢視畫面的註解。
  • view_controller_request：對檢視區塊控制器的選用要求
  • 錯誤 view_spec 包含 view_holder_token 和 view_ref (用於 Gfx 檢視區塊) 或 viewport_creation_token (適用於 Flatland 檢視表)，但不能同時包含兩者。如果同時設定兩者，系統會傳回錯誤 PresentViewError.INVALID_ARGS。
  • 如果 spec.view_holder_token 或 spec.view_ref 遺失或無效，就會發生 PresentViewError.INVALID_ARGS 錯誤。

要求

名稱類型
view_spec ViewSpec
annotation_controller AnnotationController?
view_controller_request server_end<ViewController>?

回應

名稱類型
payload GraphicalPresenter_PresentView_Result

經理

在 fuchsia.element/element_manager.fidl 中定義的

用於在工作階段中加入元素的介面。

「元素」元件應被例項化為工作階段的子項，並 (可選擇是否要) 以某種方式與使用者互動。

工作階段通常會實作 Manager，並在需要時轉送流量。為了讓 ffx session add 等工具順利運作，工作階段必須將 Manager 公開給其父項。

舉例來說，工作階段中的元件可能是非互動式應用程式，會監聽網路來向使用者顯示元素。收到指令後，元件會呼叫 ProposeElement()。

ProposeElement

新增日期：19

要求

名稱類型
spec Spec
controller server_end<Controller>?

回應

名稱類型
payload Manager_ProposeElement_Result

RemoveElement

將 name 識別的元素從工作階段中移除。如果元素是永久元素，就會永久移除。該元素可能已使用的永久儲存空間不會受到影響。

新增日期：19

要求

名稱類型
name string

回應

名稱類型
payload Manager_RemoveElement_Result

ViewController

在 fuchsia.element/graphical_presenter.fidl 中定義

讓 GraphicalPresenter 的用戶端控管透過 PresentView() 呈現的個別檢視畫面。

關閉

指示簡報者關閉相關檢視畫面。關閉後，ViewController 管道就會關閉，並顯示 ZX_OK 憑證。此時，您可以放心清除任何支援檢視區塊的資源 (例如終止元件)。

用戶端應先呼叫 Dismiss()，再關閉 ViewController 管道。

要求

<EMPTY>

OnPresented

表示檢視畫面現在呈現的事件。

回應

<EMPTY>

結構

註解資源

在 fuchsia.element/annotations.fidl 中定義

由鍵/值組合動態定義的註解。

工作階段架構不會以任何方式限制 key 和 value 的內容。交換註解的合作元件必須根據自己的慣例定義及驗證註解項目。

廣闊類型說明預設
key AnnotationKey

這個註解的 ID。

 無預設
value AnnotationValue

這個註解的內容。

 無預設

AnnotationController_GetAnnotations_Response 資源

在 fuchsia.element/annotations.fidl 中定義的

廣闊類型說明預設
annotations Annotations 無預設

AnnotationController_UpdateAnnotations_Response

在 fuchsia.element/annotations.fidl 中定義的

<EMPTY>

AnnotationController_WatchAnnotations_Response 資源

在 fuchsia.element/annotations.fidl 中定義的

廣闊類型說明預設
annotations Annotations 無預設

AnnotationKey

在 fuchsia.element/annotations.fidl 中定義

fuchsia.element/Annotation 的鍵。

廣闊類型說明預設
namespace string[128]

區分用戶端中金鑰群組的命名空間。

這麼做是為了將相關的金鑰分組在同一個 ID 下，並避免命名衝突。例如，工作階段可能會使用自訂命名空間定義實作作業專屬的註解。

必須提供命名空間，且不得留空。

命名空間「global」代表全域命名空間，保留給許多產品和工作階段元件通用的註解。

為確保相容性，用戶端在介紹新金鑰時，應使用不重複的命名空間，例如 UUID 或用戶端的元件網址。

 無預設
value string[128]

這個註解的 ID，用於識別 namespace 中的註解。

 無預設

GraphicalPresenter_PresentView_Response

在 fuchsia.element/graphical_presenter.fidl 中定義的

<EMPTY>

Manager_ProposeElement_Response

在 fuchsia.element/element_manager.fidl 中定義的

<EMPTY>

Manager_RemoveElement_Response

在 fuchsia.element/element_manager.fidl 中定義的

<EMPTY>

ENUMS

GetAnnotationsError 嚴格限制

類型：uint32

在 fuchsia.element/annotations.fidl 中定義

ElementController/GetAnnotations 傳回錯誤。

名稱物超所值說明
1

無法讀取註解的 AnnotationValue.buffer。

ManagerError 嚴格

類型：uint32

在 fuchsia.element/element_manager.fidl 中定義的

新增日期：19

名稱物超所值說明
1

元素規格格式錯誤。
2

無法解析元素的元件網址。
3

寫入永久儲存空間時發生問題，因此無法保留提議的元素。你提議的元素不會啟動。

PresentViewError 嚴格

類型：uint32

在 fuchsia.element/graphical_presenter.fidl 中定義

當 GraphicalPresenter 無法顯示檢視畫面時傳回錯誤。

名稱物超所值說明
1

提供的 ViewSpec 無效。

ProposeElementError strict

類型：uint32

在 fuchsia.element/element_manager.fidl 中定義的

使用 Manager 通訊協定時可能傳回的錯誤。

已移除：19

名稱物超所值說明
1

元素規格格式錯誤。
2

無法解析元素的元件網址。

UpdateAnnotationsError 嚴格

類型：uint32

在 fuchsia.element/annotations.fidl 中定義

AnnotationController/UpdateAnnotations 傳回錯誤

名稱物超所值說明
1

傳遞至 UpdateAnnotations 的引數格式錯誤。
2

由於註解更新後，註解總數會超過 MAX_ANNOTATIONS_PER_ELEMENT 個。

WatchAnnotationsError 彈性

類型：uint32

在 fuchsia.element/annotations.fidl 中定義

AnnotationController/WatchAnnotations 和 ElementController/WatchAnnotations 傳回錯誤。

名稱物超所值說明
1

無法讀取註解的 AnnotationValue.buffer。

資料表

規格資源

在 fuchsia.element/element_manager.fidl 中定義的

要新增至工作階段的元素說明。

序數廣闊類型說明
component_url fuchsia.url/Url

元素的元件網址。必填。
annotations Annotations

元素的初始註解。必要，但可以是空白向量。如果包含元素管理員網址註解 (允許但非必要)，則「必須」與 component_url 相符。

查看規格資源

在 fuchsia.element/graphical_presenter.fidl 中定義

可透過 GraphicalPresenter 呈現的檢視區塊說明。

序數廣闊類型說明
view_holder_token fuchsia.ui.views/ViewHolderToken

呈現的 Gfx 檢視畫面的檢視畫面持有人權杖。請務必設定 Flatland 檢視畫面。必須設定 view_holder_token 或 viewport_creation_token 的其中一個。
view_ref fuchsia.ui.views/ViewRef

呈現的 Gfx 檢視畫面的 ViewRef。請務必為 Flatland 檢視畫面設定。
annotations Annotations

與呈現檢視畫面相關聯的初始註解。系統會透過傳遞至 PresentView() 的 AnnotationController 來觀察註解的更新情形。

選用。
viewport_creation_token fuchsia.ui.views/ViewportCreationToken

呈現的 Flatland 檢視畫面的可視區域建立憑證。如為 Gfx 檢視畫面，則須未設定。必須設定 view_holder_token 或 viewport_creation_token 的其中一個。

聯合國

AnnotationController_GetAnnotations_Result 嚴格 資源

在 fuchsia.element/annotations.fidl 中定義

序數Variant類型說明
response AnnotationController_GetAnnotations_Response
err GetAnnotationsError

AnnotationController_UpdateAnnotations_Result 嚴格

在 fuchsia.element/annotations.fidl 中定義

序數Variant類型說明
response AnnotationController_UpdateAnnotations_Response
err UpdateAnnotationsError

AnnotationController_WatchAnnotations_Result 嚴格 資源

在 fuchsia.element/annotations.fidl 中定義

序數Variant類型說明
response AnnotationController_WatchAnnotations_Response
err WatchAnnotationsError

AnnotationValue 嚴格 資源

在 fuchsia.element/annotations.fidl 中定義

fuchsia.element/Annotation 的值。

實際使用的欄位視註解類型而定。

序數Variant類型說明
text string
buffer fuchsia.mem/Buffer

GraphicalPresenter_PresentView_Result 嚴格

在 fuchsia.element/graphical_presenter.fidl 中定義

序數Variant類型說明
response GraphicalPresenter_PresentView_Response
err PresentViewError

Manager_ProposeElement_Result 嚴格

在 fuchsia.element/element_manager.fidl 中定義的

序數Variant類型說明
response Manager_ProposeElement_Response
err ManagerError

Manager_RemoveElement_Result 嚴格

在 fuchsia.element/element_manager.fidl 中定義的

序數Variant類型說明
response Manager_RemoveElement_Response
err ManagerError

觀測站

名稱物超所值類型說明
ANNOTATION_KEY_NAME name String

集合中的元素名稱。如果未提供給 ProposeElement，系統會選擇隨機名稱。

新增日期：19
ANNOTATION_KEY_PERSIST_ELEMENT persist_element String

如果有這類元素，元素會在重新啟動後保留。

新增日期：19
ANNOTATION_KEY_URL url String

元素的元件網址。

新增日期：19
MANAGER_NAMESPACE element_manager String
新增日期：19
MAX_ANNOTATIONS_PER_ELEMENT 1024 uint32

單一元素或檢視畫面的註解數量上限。
MAX_ANNOTATION_KEY_NAMESPACE_SIZE 128 uint32

長度上限為 AnnotationKey.namespace 個字元。
MAX_ANNOTATION_KEY_VALUE_SIZE 128 uint32

長度上限為 AnnotationKey.value 個字元。

別名

名稱物超所值說明
AnnotationKeys vector[MAX_ANNOTATIONS_PER_ELEMENT]

註解鍵清單。
註解 vector[MAX_ANNOTATIONS_PER_ELEMENT]

元素的註解清單。