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 檢視畫面)，或為 Flatland 檢視畫面的 viewport_creation_token，但絕對不可同時包含兩者。如果兩者都設定，會傳回錯誤 PresentViewError.INVALID_ARGS。
  • 錯誤 PresentViewError.INVALID_ARGS 表示 spec.view_holder_token、spec.view_ref 遺失或無效。

要求

名稱類型
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。

Manager 錯誤 (嚴格)

類型：uint32

在 fuchsia.element/element_manager.fidl 中定義

新增時間：19 歲

名稱值說明
1

元素規格格式錯誤。
2

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

寫入永久儲存空間時發生問題，因此無法保留提議的元素。提議的元素尚未開始。

PresentViewError 嚴格

類型：uint32

定義於 fuchsia.element/graphical_presenter.fidl

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

名稱值說明
1

提供的 ViewSpec 無效。

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 相符。

ViewSpec 資源

定義於 fuchsia.element/graphical_presenter.fidl

可由 GraphicalPresenter 呈現的檢視畫面說明。

序數欄位類型說明
view_holder_token fuchsia.ui.views/ViewHolderToken

所呈現 Gfx 檢視畫面的檢視持有者權杖。如為平地景觀，則不得設定。必須設定 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]

元素的註解清單。