fuchsia.io

新增日期：7

通訊協定

AdvisoryLocking

定義於 fuchsia.io/locking.fidl

諮詢鎖定通訊協定。

這個通訊協定應由 |File| 通訊協定組成，以便支援鎖定功能。

顧問專用居家鎖僅供系統建議之用，這些模式不會防止實際的讀取或寫入作業透過此連線或其他連線在檔案上發生。

這些基本功能旨在支援 flock() 和 fcntl()，特別是 F_SETLK、F_SETLKW 和 F_GETLK，讓程式碼在 Fuchsia 上執行的程式碼預期在其他作業系統上執行。

AdvisoryLock

為基礎檔案取得建議鎖定。

在連線關閉或使用 |AdvisoryLockType.UNLOCK| 呼叫此方法的情況下，明確解除鎖定狀態之前，鎖定會一直有效。

顧問專用居家鎖僅供系統建議之用，這些模式不會防止實際的讀取或寫入作業透過此連線或其他連線在檔案上發生。

使用這個方法需要以下權限：

錯誤

  • ZX_ERR_BAD_STATE 無法取得指定的鎖定類型。舉例來說，另一個連線可能處於衝突的鎖定類型。
  • ZX_ERR_NOT_SUPPORTED這個檔案不支援建議鎖定功能。
  • ZX_ERR_ACCESS_DENIED 此連線權限不足，無法取得特定類型的鎖定。

要求

名稱類型
request AdvisoryLockRequest

回應

名稱類型
payload AdvisoryLocking_AdvisoryLock_Result

目錄

定義於 fuchsia.io/directory.fidl

AdvisoryLock

為基礎檔案取得建議鎖定。

在連線關閉或使用 |AdvisoryLockType.UNLOCK| 呼叫此方法的情況下，明確解除鎖定狀態之前，鎖定會一直有效。

顧問專用居家鎖僅供系統建議之用，這些模式不會防止實際的讀取或寫入作業透過此連線或其他連線在檔案上發生。

使用這個方法需要以下權限：

錯誤

  • ZX_ERR_BAD_STATE 無法取得指定的鎖定類型。舉例來說，另一個連線可能處於衝突的鎖定類型。
  • ZX_ERR_NOT_SUPPORTED這個檔案不支援建議鎖定功能。
  • ZX_ERR_ACCESS_DENIED 此連線權限不足，無法取得特定類型的鎖定。

要求

名稱類型
request AdvisoryLockRequest

回應

名稱類型
payload AdvisoryLocking_AdvisoryLock_Result

複製

建立另一個連至相同遠端物件的連線。

flags 可以是下列任一值：

  • OpenFlags.RIGHT_*
  • OpenFlags.APPEND
  • OpenFlags.DESCRIBE
  • OpenFlags.CLONE_SAME_RIGHTS

系統會忽略所有其他標記。

flags 中的 OpenFlags.RIGHT_* 位元會要求對所複製物件對應的權限。複製物件的權限必須小於或等於原始物件的權限，否則會傳回 ZX_ERR_ACCESS_DENIED。或者，您也可以傳遞 OpenFlags.CLONE_SAME_RIGHTS 來繼承來源連線的權限。無法與 OpenFlags.CLONE_SAME_RIGHTS 一併傳送任何 OpenFlags.RIGHT_* 旗標。

要求

名稱類型
flags OpenFlags
object server_end<Node>

關閉

終止連線。

呼叫 Close 後，用戶端不得傳送任何其他要求。

伺服器在傳送狀態回應後，無論狀態為何或不傳送連續指令，都應關閉連線。

關閉管道的用戶端，在語意上應等同於呼叫 Close，且不知道關閉程序何時完成或狀態。

要求

<EMPTY>

回應

名稱類型
payload fuchsia.unknown/Closeable_Close_Result

建立符號連結。

name 是要為已建立的符號連結命名。target 是符號連結的目標，在伺服器上沒有意義。除非伺服器選擇的最大長度，否則伺服器不會執行 target 的驗證。connection 是管道的選用伺服器端，會在成功建立的節點上傳達 Symlink 通訊協定。

  • Rights.MODIFY_DIRECTORY

  • ZX_ERR_ALREADY_EXISTS 錯誤 (如果 name 已存在)。

  • 如果 target 超過符號連結的伺服器長度限制，則傳回 ZX_ERR_BAD_PATH 錯誤。

  • 如果 name 不是有效的名稱，則顯示 ZX_ERR_INVALID_ARGS 錯誤。

  • 伺服器不支援建立符號連結時，發生錯誤 ZX_ERR_NOT_SUPPORTED。

新增時間：18 歲
名稱類型
name Name
target SymlinkTarget
connection server_end<Symlink>?
名稱類型
payload Directory2_CreateSymlink_Result

列舉

針對輸入管道啟動目錄清單作業 (從跳轉偏移 0 開始)。

這種方法需要 Rights.ENUMERATE 。如果沒有這項權利，iterator 會以 ZX_ERR_ACCESS_DENIED 詞獨關閉。

要求

名稱類型
options DirectoryEnumerateOptions
iterator server_end<DirectoryIterator>

GetAttr

取得節點的相關資訊。

這個方法不需要任何權利。

要求

<EMPTY>

回應

名稱類型
s zx/Status
attributes NodeAttributes

GetAttributes

取得節點的相關資訊。

節點的屬性應固定，不受用於存取節點的特定通訊協定無關。

如果特定屬性不適用或不受支援，檔案系統應將對應的欄位留空。

  • query：指定要擷取的屬性的位元遮罩。伺服器不應傳回不必要的次數。
  • attributes 傳回的屬性。

這種方法需要 Rights.GET_ATTRIBUTES 右側。

要求

名稱類型
query NodeAttributesQuery

回應

名稱類型
payload Node2_GetAttributes_Result

GetConnectionInfo

取得連線相關資訊。

這個方法不需要任何權利。

要求

<EMPTY>

回應

名稱類型
payload ConnectionInfo

GetExtendedAttribute

取得與這個節點的指定屬性 name 相關聯的值。

屬性名稱的長度上限為 MAX_ATTRIBUTE_NAME。這類執行個體沒有設有特定結構。

這種方法需要 Rights.GET_ATTRIBUTES 右側。

新增時間：18 歲

要求

名稱類型
name ExtendedAttributeName

回應

名稱類型
payload Node2_GetExtendedAttribute_Result

GetFlags

取得用來存取這個檔案的 Directory.Open 權限和旗標。

這個方法不需要任何權利。

要求

<EMPTY>

回應

名稱類型
s zx/Status
flags OpenFlags

GetToken

為目錄取得權杖，以供日後用來識別權限。只要要求權杖的連線保持開啟，權杖就會持續有效。

這個方法需要下列權限：OpenFlags.RIGHT_WRITABLE，否則傳回 ZX_ERR_BAD_HANDLE。

要求

<EMPTY>

回應

名稱類型
s zx/Status
token handle<handle>?

以符記 dst 的名稱建立物件連結，該物件位於符記代表的目錄中。

src 必須是已解析的物件名稱。在字串中加入「/」會傳回 ZX_ERR_INVALID_ARGS。

dst 必須是已解析的物件名稱。在字串中加入「/」會傳回 ZX_ERR_INVALID_ARGS。

這個方法需要下列權限：OpenFlags.RIGHT_WRITABLE 和 OpenFlags.RIGHT_READABLE，否則會傳回 ZX_ERR_BAD_HANDLE。

這對於同時重新命名或取消連結來源而言 (例如當有兩個發動者同時運作，而一名演員執行重新命名後會影響此目錄中的來源，而另一個發動者則以不可指定的順序顯示)。

名稱類型
src string[255]
dst_parent_token handle<handle>
dst string[255]
名稱類型
s zx/Status

ListExtendedAttributes

針對與這個節點相關聯的所有延伸屬性名稱建立疊代器。如果發生錯誤，系統會在疊代器要求管道中以劇集形式傳回錯誤，然後再關閉管道。

GetExtendedAttributes 可以與這些名稱搭配使用，以擷取相關值。

這種方法需要 Rights.GET_ATTRIBUTES 右側。

新增時間：18 歲

要求

名稱類型
iterator server_end<ExtendedAttributeIterator>

OnOpen

FIDL 伺服器在 OpenFlags.DESCRIBE 要求的情況下迅速產生的事件。

指出開啟作業成功或失敗，並視需要描述物件。如果狀態為 ZX_OK，則 info 包含物件的描述性資訊 (與 Describe 傳回的資訊相同)。

回應

名稱類型
s zx/Status
info NodeInfoDeprecated?

OnRepresentation

NodeFlags.GET_REPRESENTATION 要求時，由伺服器快速產生的事件。這個事件將是伺服器傳送的第一則訊息，並僅傳送一次。

使用中的變化版本會對應至節點支援的其中一個通訊協定，代表連線期間交涉的結果。提供輔助帳號代碼 (如適用)。

如果在 Directory.Open 期間，用戶端在 protocols 中指定多個通訊協定，則表示法會透過其標記執行連線期間協商的結果。

元素與 NodeProtocolKinds 成員有一對一對應。

這是 fuchsia.unknown/Queryable.Query 與特定通訊協定的固有 Describe 方法的特殊案例。此函式可做為最佳化使用，以避免額外的來回行程。

回應

名稱類型
payload Representation

公開

開啟相對於這個目錄物件的新物件。

path 可能包含多個片段，以「/」字元分隔，而且不可空白；也就是說，「」是無效路徑。結尾的斜線代表 OpenFlags.DIRECTORY。元件不可為空白 (即「foo//bar」無效)。「..」禁止在路徑中的任何位置使用。「.」只有在路徑完全符合「.」時才允許，其他情況則不行。可使用開頭的「/」(且處理方式與不存在相同，也就是「/foo/bar」和「foo/bar」相同)。

如果傳送不明的值給標記，應關閉連線。

flags 中提供的 OpenFlags.RIGHT_* 旗標會限制連結至已開啟實體的 object 管道存取權。

權利絕不會增加。在目錄中開啟巢狀實體時，您只能要求與目錄連線現有的相同權限，或要求其中一部分的權限。超過這些權限會導致在 OnOpen 事件中傳輸存取遭拒的錯誤，並關閉 object 連線。

系統會忽略 mode。

新增時間：12 張

要求

名稱類型
flags OpenFlags
mode ModeType
path string[4095]
object server_end<Node>

Open2

開啟或建立相對於這個目錄節點的新節點。

如要運用這個方法，你必須擁有目前連線的下列權限：

錯誤會在 object_request 管道中以劇集的形式呈現。

  • 錯誤：ZX_ERR_ACCESS_DENIED。
  • 如果 path 無效，則傳回 ZX_ERR_BAD_PATH 錯誤。

要求

名稱類型
path Path
protocols ConnectionProtocols
object_request handle<channel>

查詢

要求

<EMPTY>

回應

名稱類型
protocol vector<uint8>

QueryFilesystem

向檔案系統查詢檔案系統專屬資訊。

要求

<EMPTY>

回應

名稱類型
s zx/Status
info FilesystemInfo?

ReadDirents

這個外掛程式能在緩衝區中，讀取各種大小不一的目錄。目錄中的目錄數量可能非常龐大：如同對檔案多次呼叫讀取，目錄具有尋找偏移，而後者會在後續呼叫 ReadDirents 時更新。每次呼叫 ReadDirents 都只會傳回完整結構結構，不會分割到 ReadDirent 呼叫之間。當跳轉偏移結束時，dirents 就會是空的。

這些目錄的格式如下：

struct dirent {
  // Describes the inode of the entry.
  uint64 ino;
  // Describes the length of the dirent name in bytes.
  uint8 size;
  // Describes the type of the entry. Aligned with the
  // POSIX d_type values. Use `DirentType` constants.
  uint8 type;
  // Unterminated name of entry.
  char name[0];
}

此方法不需要任何權限，因為在建立檔案時，系統可以隨時藉由觸發名稱衝突來探測目錄內容。

要求

名稱類型
max_bytes uint64

回應

名稱類型
s zx/Status
dirents vector<uint8>[8192]

RemoveExtendedAttribute

移除指定的擴充屬性。

如果屬性不存在，系統會傳回 ZX_ERR_NOT_FOUND。

這種方法需要 Rights.UPDATE_ATTRIBUTES 右側。

新增時間：18 歲

要求

名稱類型
name ExtendedAttributeName

回應

名稱類型
payload Node2_RemoveExtendedAttribute_Result

重新命名

在 dst_parent_token 代表的目錄中，將名為 src 的節點重新命名為 dst。

src 和 dst 必須是有效的節點名稱。如要瞭解有效名稱的定義，請參閱名稱。

這種方法需要對目前連線和 dst_parent_token 識別的連線都具備下列權限：

您必須符合下列規定，才能避免權利提報問題。

如果來源和目的地目錄不同，來源目錄也必須具有支援的檔案最大功能組合，通常是 Rights.READ_BYTES、Rights.WRITE_BYTES、Rights.GET_ATTRIBUTES 和 Rights.UPDATE_ATTRIBUTES。部分檔案系統可能也支援 Rights.EXECUTE。

如果 src 參照目錄，與目的地目錄不同，則來源目錄也必須擁有 Rights.CONNECT 和 Rights.TRAVERSE 權限。

  • 如果 src 或 dst 無效，則為 ZX_ERR_INVALID_ARGS 錯誤。
  • 錯誤資訊：ZX_ERR_ACCESS_DENIED。

要求

名稱類型
src Name
dst_parent_token Token
dst Name

回應

名稱類型
payload Directory2_Rename_Result

重新開啟

建立連至同一節點的另一個連線。

要求

名稱類型
rights_request RightsRequest
object_request server_end<Node>

倒轉

重設目錄跳轉偏移量。

這個方法不需要任何權限，類似 ReadDirents 的做法。

要求

<EMPTY>

回應

名稱類型
s zx/Status

SetAttr

更新有關節點的資訊。

這個方法需要下列權限：OpenFlags.RIGHT_WRITABLE，否則傳回 ZX_ERR_BAD_HANDLE。

要求

名稱類型
flags NodeAttributeFlags
attributes NodeAttributes

回應

名稱類型
s zx/Status

SetExtendedAttribute

將這個節點的指定屬性 name 值設為 value。

屬性名稱可能存在，而屬性名稱也會隨之更新。如果該屬性不存在，則會建立該屬性。名稱不得包含空值位元組。如果是，系統會傳回 ZX_ERR_INVALID_ARGS。

這種方法需要 Rights.UPDATE_ATTRIBUTES 右側。

新增時間：18 歲

要求

名稱類型
name ExtendedAttributeName
value ExtendedAttributeValue
mode SetExtendedAttributeMode

回應

名稱類型
payload Node2_SetExtendedAttribute_Result

SetFlags

變更用於存取檔案的 Directory.Open 旗標。支援啟用 / 關閉的旗標：

  • OpenFlags.APPEND

這個方法不需要任何權利。

要求

名稱類型
flags OpenFlags

回應

名稱類型
s zx/Status

同步

將節點的更新內容同步處理至基礎媒體 (如果有的話)。

當檔案系統伺服器清除基礎媒體的相關更新時，這個方法將傳回，但不保證基礎媒體會保存資訊，也不會保證任何資訊會提供給硬體。用戶端可利用 Sync 確保在作業之間排序。

這個方法不需要任何權利。

要求

<EMPTY>

回應

名稱類型
payload Node2_Sync_Result

從這個目錄的項目清單中移除子節點。

注意：這不保證基礎物件會遭到刪除。 雖然連結會從內含的目錄中移除，但具有多個參照的物件 (例如仍開啟的檔案) 實際上不會遭到刪除，直到所有參照都關閉為止。

  • 如果連線沒有 Rights.WRITE_BYTES 則傳回錯誤 ZX_ERR_ACCESS_DENIED。
  • 錯誤：ZX_ERR_NOT_SUPPORTED。
  • 如果 name 無效，則傳回 ZX_ERR_BAD_PATH 錯誤。
  • 如果 name 參照非空白目錄，則傳回 ZX_ERR_NOT_EMPTY 錯誤。
  • 如果 name 參照包含遠端管道的掛接點，則會發生 ZX_ERR_UNAVAILABLE 錯誤。
  • 如果選項要求目錄，但系統找到目錄以外的項目，則會發生錯誤 ZX_ERR_NOT_DIR。

其他錯誤也可能因檔案系統特定原因而傳回。

使用這個方法需要以下權限：

名稱類型
name Name
options UnlinkOptions
名稱類型
payload Directory2_Unlink_Result

UpdateAttributes

更新有關節點的資訊。

  • attributes如果 attributes 中有資料表欄位，表示要更新對應屬性的意圖。

這種方法需要 Rights.UPDATE_ATTRIBUTES 右側。

要求

名稱類型
payload MutableNodeAttributes

回應

名稱類型
payload Node2_UpdateAttributes_Result

觀看

監控目錄，在監看器要求管道上接收新增的訊息事件。

選項必須為零；此為保留選項。

這個方法不需要任何權限，類似 ReadDirents 的做法。

要求

名稱類型
mask WatchMask
options uint32
watcher server_end<DirectoryWatcher>

回應

名稱類型
s zx/Status

Directory1

定義於 fuchsia.io/directory.fidl

目錄會定義能夠包含其他物件的節點。

複製

建立另一個連至相同遠端物件的連線。

flags 可以是下列任一值：

  • OpenFlags.RIGHT_*
  • OpenFlags.APPEND
  • OpenFlags.DESCRIBE
  • OpenFlags.CLONE_SAME_RIGHTS

系統會忽略所有其他標記。

flags 中的 OpenFlags.RIGHT_* 位元會要求對所複製物件對應的權限。複製物件的權限必須小於或等於原始物件的權限，否則會傳回 ZX_ERR_ACCESS_DENIED。或者，您也可以傳遞 OpenFlags.CLONE_SAME_RIGHTS 來繼承來源連線的權限。無法與 OpenFlags.CLONE_SAME_RIGHTS 一併傳送任何 OpenFlags.RIGHT_* 旗標。

要求

名稱類型
flags OpenFlags
object server_end<Node>

GetAttr

取得節點的相關資訊。

這個方法不需要任何權利。

要求

<EMPTY>

回應

名稱類型
s zx/Status
attributes NodeAttributes

GetFlags

取得用來存取這個檔案的 Directory.Open 權限和旗標。

這個方法不需要任何權利。

要求

<EMPTY>

回應

名稱類型
s zx/Status
flags OpenFlags

GetToken

為目錄取得權杖，以供日後用來識別權限。只要要求權杖的連線保持開啟，權杖就會持續有效。

這個方法需要下列權限：OpenFlags.RIGHT_WRITABLE，否則傳回 ZX_ERR_BAD_HANDLE。

要求

<EMPTY>

回應

名稱類型
s zx/Status
token handle<handle>?

以符記 dst 的名稱建立物件連結，該物件位於符記代表的目錄中。

src 必須是已解析的物件名稱。在字串中加入「/」會傳回 ZX_ERR_INVALID_ARGS。

dst 必須是已解析的物件名稱。在字串中加入「/」會傳回 ZX_ERR_INVALID_ARGS。

這個方法需要下列權限：OpenFlags.RIGHT_WRITABLE 和 OpenFlags.RIGHT_READABLE，否則會傳回 ZX_ERR_BAD_HANDLE。

這對於同時重新命名或取消連結來源而言 (例如當有兩個發動者同時運作，而一名演員執行重新命名後會影響此目錄中的來源，而另一個發動者則以不可指定的順序顯示)。

名稱類型
src string[255]
dst_parent_token handle<handle>
dst string[255]
名稱類型
s zx/Status

OnOpen

FIDL 伺服器在 OpenFlags.DESCRIBE 要求的情況下迅速產生的事件。

指出開啟作業成功或失敗，並視需要描述物件。如果狀態為 ZX_OK，則 info 包含物件的描述性資訊 (與 Describe 傳回的資訊相同)。

回應

名稱類型
s zx/Status
info NodeInfoDeprecated?

公開

開啟相對於這個目錄物件的新物件。

path 可能包含多個片段，以「/」字元分隔，而且不可空白；也就是說，「」是無效路徑。結尾的斜線代表 OpenFlags.DIRECTORY。元件不可為空白 (即「foo//bar」無效)。「..」禁止在路徑中的任何位置使用。「.」只有在路徑完全符合「.」時才允許，其他情況則不行。可使用開頭的「/」(且處理方式與不存在相同，也就是「/foo/bar」和「foo/bar」相同)。

如果傳送不明的值給標記，應關閉連線。

flags 中提供的 OpenFlags.RIGHT_* 旗標會限制連結至已開啟實體的 object 管道存取權。

權利絕不會增加。在目錄中開啟巢狀實體時，您只能要求與目錄連線現有的相同權限，或要求其中一部分的權限。超過這些權限會導致在 OnOpen 事件中傳輸存取遭拒的錯誤，並關閉 object 連線。

系統會忽略 mode。

新增時間：12 張

要求

名稱類型
flags OpenFlags
mode ModeType
path string[4095]
object server_end<Node>

QueryFilesystem

向檔案系統查詢檔案系統專屬資訊。

要求

<EMPTY>

回應

名稱類型
s zx/Status
info FilesystemInfo?

ReadDirents

這個外掛程式能在緩衝區中，讀取各種大小不一的目錄。目錄中的目錄數量可能非常龐大：如同對檔案多次呼叫讀取，目錄具有尋找偏移，而後者會在後續呼叫 ReadDirents 時更新。每次呼叫 ReadDirents 都只會傳回完整結構結構，不會分割到 ReadDirent 呼叫之間。當跳轉偏移結束時，dirents 就會是空的。

這些目錄的格式如下：

struct dirent {
  // Describes the inode of the entry.
  uint64 ino;
  // Describes the length of the dirent name in bytes.
  uint8 size;
  // Describes the type of the entry. Aligned with the
  // POSIX d_type values. Use `DirentType` constants.
  uint8 type;
  // Unterminated name of entry.
  char name[0];
}

此方法不需要任何權限，因為在建立檔案時，系統可以隨時藉由觸發名稱衝突來探測目錄內容。

要求

名稱類型
max_bytes uint64

回應

名稱類型
s zx/Status
dirents vector<uint8>[8192]

倒轉

重設目錄跳轉偏移量。

這個方法不需要任何權限，類似 ReadDirents 的做法。

要求

<EMPTY>

回應

名稱類型
s zx/Status

SetAttr

更新有關節點的資訊。

這個方法需要下列權限：OpenFlags.RIGHT_WRITABLE，否則傳回 ZX_ERR_BAD_HANDLE。

要求

名稱類型
flags NodeAttributeFlags
attributes NodeAttributes

回應

名稱類型
s zx/Status

SetFlags

變更用於存取檔案的 Directory.Open 旗標。支援啟用 / 關閉的旗標：

  • OpenFlags.APPEND

這個方法不需要任何權利。

要求

名稱類型
flags OpenFlags

回應

名稱類型
s zx/Status

觀看

監控目錄，在監看器要求管道上接收新增的訊息事件。

選項必須為零；此為保留選項。

這個方法不需要任何權限，類似 ReadDirents 的做法。

要求

名稱類型
mask WatchMask
options uint32
watcher server_end<DirectoryWatcher>

回應

名稱類型
s zx/Status

Directory2

定義於 fuchsia.io/directory2.fidl

包含其他節點的 Node2。

AdvisoryLock

為基礎檔案取得建議鎖定。

在連線關閉或使用 |AdvisoryLockType.UNLOCK| 呼叫此方法的情況下，明確解除鎖定狀態之前，鎖定會一直有效。

顧問專用居家鎖僅供系統建議之用，這些模式不會防止實際的讀取或寫入作業透過此連線或其他連線在檔案上發生。

使用這個方法需要以下權限：

錯誤

  • ZX_ERR_BAD_STATE 無法取得指定的鎖定類型。舉例來說，另一個連線可能處於衝突的鎖定類型。
  • ZX_ERR_NOT_SUPPORTED這個檔案不支援建議鎖定功能。
  • ZX_ERR_ACCESS_DENIED 此連線權限不足，無法取得特定類型的鎖定。

要求

名稱類型
request AdvisoryLockRequest

回應

名稱類型
payload AdvisoryLocking_AdvisoryLock_Result

關閉

終止連線。

呼叫 Close 後，用戶端不得傳送任何其他要求。

伺服器在傳送狀態回應後，無論狀態為何或不傳送連續指令，都應關閉連線。

關閉管道的用戶端，在語意上應等同於呼叫 Close，且不知道關閉程序何時完成或狀態。

要求

<EMPTY>

回應

名稱類型
payload fuchsia.unknown/Closeable_Close_Result

建立符號連結。

name 是要為已建立的符號連結命名。target 是符號連結的目標，在伺服器上沒有意義。除非伺服器選擇的最大長度，否則伺服器不會執行 target 的驗證。connection 是管道的選用伺服器端，會在成功建立的節點上傳達 Symlink 通訊協定。

  • Rights.MODIFY_DIRECTORY

  • ZX_ERR_ALREADY_EXISTS 錯誤 (如果 name 已存在)。

  • 如果 target 超過符號連結的伺服器長度限制，則傳回 ZX_ERR_BAD_PATH 錯誤。

  • 如果 name 不是有效的名稱，則顯示 ZX_ERR_INVALID_ARGS 錯誤。

  • 伺服器不支援建立符號連結時，發生錯誤 ZX_ERR_NOT_SUPPORTED。

新增時間：18 歲
名稱類型
name Name
target SymlinkTarget
connection server_end<Symlink>?
名稱類型
payload Directory2_CreateSymlink_Result

列舉

針對輸入管道啟動目錄清單作業 (從跳轉偏移 0 開始)。

這種方法需要 Rights.ENUMERATE 。如果沒有這項權利，iterator 會以 ZX_ERR_ACCESS_DENIED 詞獨關閉。

要求

名稱類型
options DirectoryEnumerateOptions
iterator server_end<DirectoryIterator>

GetAttributes

取得節點的相關資訊。

節點的屬性應固定，不受用於存取節點的特定通訊協定無關。

如果特定屬性不適用或不受支援，檔案系統應將對應的欄位留空。

  • query：指定要擷取的屬性的位元遮罩。伺服器不應傳回不必要的次數。
  • attributes 傳回的屬性。

這種方法需要 Rights.GET_ATTRIBUTES 右側。

要求

名稱類型
query NodeAttributesQuery

回應

名稱類型
payload Node2_GetAttributes_Result

GetConnectionInfo

取得連線相關資訊。

這個方法不需要任何權利。

要求

<EMPTY>

回應

名稱類型
payload ConnectionInfo

GetExtendedAttribute

取得與這個節點的指定屬性 name 相關聯的值。

屬性名稱的長度上限為 MAX_ATTRIBUTE_NAME。這類執行個體沒有設有特定結構。

這種方法需要 Rights.GET_ATTRIBUTES 右側。

新增時間：18 歲

要求

名稱類型
name ExtendedAttributeName

回應

名稱類型
payload Node2_GetExtendedAttribute_Result

ListExtendedAttributes

針對與這個節點相關聯的所有延伸屬性名稱建立疊代器。如果發生錯誤，系統會在疊代器要求管道中以劇集形式傳回錯誤，然後再關閉管道。

GetExtendedAttributes 可以與這些名稱搭配使用，以擷取相關值。

這種方法需要 Rights.GET_ATTRIBUTES 右側。

新增時間：18 歲

要求

名稱類型
iterator server_end<ExtendedAttributeIterator>

OnRepresentation

NodeFlags.GET_REPRESENTATION 要求時，由伺服器快速產生的事件。這個事件將是伺服器傳送的第一則訊息，並僅傳送一次。

使用中的變化版本會對應至節點支援的其中一個通訊協定，代表連線期間交涉的結果。提供輔助帳號代碼 (如適用)。

如果在 Directory.Open 期間，用戶端在 protocols 中指定多個通訊協定，則表示法會透過其標記執行連線期間協商的結果。

元素與 NodeProtocolKinds 成員有一對一對應。

這是 fuchsia.unknown/Queryable.Query 與特定通訊協定的固有 Describe 方法的特殊案例。此函式可做為最佳化使用，以避免額外的來回行程。

回應

名稱類型
payload Representation

Open2

開啟或建立相對於這個目錄節點的新節點。

如要運用這個方法，你必須擁有目前連線的下列權限：

錯誤會在 object_request 管道中以劇集的形式呈現。

  • 錯誤：ZX_ERR_ACCESS_DENIED。
  • 如果 path 無效，則傳回 ZX_ERR_BAD_PATH 錯誤。

要求

名稱類型
path Path
protocols ConnectionProtocols
object_request handle<channel>

查詢

要求

<EMPTY>

回應

名稱類型
protocol vector<uint8>

RemoveExtendedAttribute

移除指定的擴充屬性。

如果屬性不存在，系統會傳回 ZX_ERR_NOT_FOUND。

這種方法需要 Rights.UPDATE_ATTRIBUTES 右側。

新增時間：18 歲

要求

名稱類型
name ExtendedAttributeName

回應

名稱類型
payload Node2_RemoveExtendedAttribute_Result

重新命名

在 dst_parent_token 代表的目錄中，將名為 src 的節點重新命名為 dst。

src 和 dst 必須是有效的節點名稱。如要瞭解有效名稱的定義，請參閱名稱。

這種方法需要對目前連線和 dst_parent_token 識別的連線都具備下列權限：

您必須符合下列規定，才能避免權利提報問題。

如果來源和目的地目錄不同，來源目錄也必須具有支援的檔案最大功能組合，通常是 Rights.READ_BYTES、Rights.WRITE_BYTES、Rights.GET_ATTRIBUTES 和 Rights.UPDATE_ATTRIBUTES。部分檔案系統可能也支援 Rights.EXECUTE。

如果 src 參照目錄，與目的地目錄不同，則來源目錄也必須擁有 Rights.CONNECT 和 Rights.TRAVERSE 權限。

  • 如果 src 或 dst 無效，則為 ZX_ERR_INVALID_ARGS 錯誤。
  • 錯誤資訊：ZX_ERR_ACCESS_DENIED。

要求

名稱類型
src Name
dst_parent_token Token
dst Name

回應

名稱類型
payload Directory2_Rename_Result

重新開啟

建立連至同一節點的另一個連線。

要求

名稱類型
rights_request RightsRequest
object_request server_end<Node>

SetExtendedAttribute

將這個節點的指定屬性 name 值設為 value。

屬性名稱可能存在，而屬性名稱也會隨之更新。如果該屬性不存在，則會建立該屬性。名稱不得包含空值位元組。如果是，系統會傳回 ZX_ERR_INVALID_ARGS。

這種方法需要 Rights.UPDATE_ATTRIBUTES 右側。

新增時間：18 歲

要求

名稱類型
name ExtendedAttributeName
value ExtendedAttributeValue
mode SetExtendedAttributeMode

回應

名稱類型
payload Node2_SetExtendedAttribute_Result

同步

將節點的更新內容同步處理至基礎媒體 (如果有的話)。

當檔案系統伺服器清除基礎媒體的相關更新時，這個方法將傳回，但不保證基礎媒體會保存資訊，也不會保證任何資訊會提供給硬體。用戶端可利用 Sync 確保在作業之間排序。

這個方法不需要任何權利。

要求

<EMPTY>

回應

名稱類型
payload Node2_Sync_Result

從這個目錄的項目清單中移除子節點。

注意：這不保證基礎物件會遭到刪除。 雖然連結會從內含的目錄中移除，但具有多個參照的物件 (例如仍開啟的檔案) 實際上不會遭到刪除，直到所有參照都關閉為止。

  • 如果連線沒有 Rights.WRITE_BYTES 則傳回錯誤 ZX_ERR_ACCESS_DENIED。
  • 錯誤：ZX_ERR_NOT_SUPPORTED。
  • 如果 name 無效，則傳回 ZX_ERR_BAD_PATH 錯誤。
  • 如果 name 參照非空白目錄，則傳回 ZX_ERR_NOT_EMPTY 錯誤。
  • 如果 name 參照包含遠端管道的掛接點，則會發生 ZX_ERR_UNAVAILABLE 錯誤。
  • 如果選項要求目錄，但系統找到目錄以外的項目，則會發生錯誤 ZX_ERR_NOT_DIR。

其他錯誤也可能因檔案系統特定原因而傳回。

使用這個方法需要以下權限：

名稱類型
name Name
options UnlinkOptions
名稱類型
payload Directory2_Unlink_Result

UpdateAttributes

更新有關節點的資訊。

  • attributes如果 attributes 中有資料表欄位，表示要更新對應屬性的意圖。

這種方法需要 Rights.UPDATE_ATTRIBUTES 右側。

要求

名稱類型
payload MutableNodeAttributes

回應

名稱類型
payload Node2_UpdateAttributes_Result

DirectoryIterator

定義於 fuchsia.io/directory2.fidl

GetNext

這個外掛程式能將不同大小的目錄項目讀取至緩衝區中。

目錄中的項目數量可能非常龐大：如同對檔案多次呼叫讀取，目錄具有尋找偏移，而後續呼叫 Enumerate 時就會更新。呼叫端應一律使用最大管道上限的接收緩衝區空間。

疊代結束時，傳回的 entries 向量會是空白。

此方法不需要任何權限，因為權限會在 Directory.Enumerate 呼叫中完成檢查。

要求

<EMPTY>

回應

名稱類型
payload DirectoryIterator_GetNext_Result

DirectoryWatcher

定義於 fuchsia.io/directory.fidl

DirectoryWatcher 會從檔案系統伺服器傳送有關檔案系統中事件的訊息。用戶端可以使用 Directory.Watch 方法註冊新的觀察器，並在其中篩選要接收哪些事件的通知。

DirectoryWatcher 會傳送下列格式的訊息：

struct {
  uint8 event;
  uint8 len;
  char name[];
};

其中名稱「不得」以空值終止。名稱是事件參照的項目相對路徑。如果事件未參照特定項目 (例如 IDLE 事件)，則為空白。

ExtendedAttributeIterator

定義於 fuchsia.io/node2.fidl

新增時間：18 歲

GetNext

取得下一個延伸屬性名稱區塊。如果這是最後一個區塊，則最後會設為「是」，且管道會在呼叫後關閉。

要求

<EMPTY>

回應

名稱類型
payload ExtendedAttributeIterator_GetNext_Result

檔案

定義於 fuchsia.io/file2.fidl

節點，包含指定長度的位元組序列。

注意：複製的連線不會與來源連線共用搜尋偏移。

AdvisoryLock

為基礎檔案取得建議鎖定。

在連線關閉或使用 |AdvisoryLockType.UNLOCK| 呼叫此方法的情況下，明確解除鎖定狀態之前，鎖定會一直有效。

顧問專用居家鎖僅供系統建議之用，這些模式不會防止實際的讀取或寫入作業透過此連線或其他連線在檔案上發生。

使用這個方法需要以下權限：

錯誤

  • ZX_ERR_BAD_STATE 無法取得指定的鎖定類型。舉例來說，另一個連線可能處於衝突的鎖定類型。
  • ZX_ERR_NOT_SUPPORTED這個檔案不支援建議鎖定功能。
  • ZX_ERR_ACCESS_DENIED 此連線權限不足，無法取得特定類型的鎖定。

要求

名稱類型
request AdvisoryLockRequest

回應

名稱類型
payload AdvisoryLocking_AdvisoryLock_Result

分配

預先分配這個檔案的磁碟空間。

已新增：HEAD

要求

名稱類型
offset uint64
length uint64
mode AllocateMode

回應

名稱類型
payload File_Allocate_Result

複製

建立另一個連至相同遠端物件的連線。

flags 可以是下列任一值：

  • OpenFlags.RIGHT_*
  • OpenFlags.APPEND
  • OpenFlags.DESCRIBE
  • OpenFlags.CLONE_SAME_RIGHTS

系統會忽略所有其他標記。

flags 中的 OpenFlags.RIGHT_* 位元會要求對所複製物件對應的權限。複製物件的權限必須小於或等於原始物件的權限，否則會傳回 ZX_ERR_ACCESS_DENIED。或者，您也可以傳遞 OpenFlags.CLONE_SAME_RIGHTS 來繼承來源連線的權限。無法與 OpenFlags.CLONE_SAME_RIGHTS 一併傳送任何 OpenFlags.RIGHT_* 旗標。

要求

名稱類型
flags OpenFlags
object server_end<Node>

關閉

終止連線。

呼叫 Close 後，用戶端不得傳送任何其他要求。

伺服器在傳送狀態回應後，無論狀態為何或不傳送連續指令，都應關閉連線。

關閉管道的用戶端，在語意上應等同於呼叫 Close，且不知道關閉程序何時完成或狀態。

要求

<EMPTY>

回應

名稱類型
payload fuchsia.unknown/Closeable_Close_Result

說明

要求

<EMPTY>

回應

名稱類型
payload FileInfo

EnableVerity

啟用 (永久) 檔案的驗證，針對檔案計算 Merkle 樹。在建立 Merkle 樹之前，強制進行清除，以確保擷取快取資料。日後的讀取會根據計算出的 Merkle 樹狀圖進行驗證，寫入作業也會遭到拒絕。此方法可能需要一段時間才能完成，視檔案大小而定。 關閉使用該方法的連線即可取消。

這種方法需要 Rights.UPDATE_ATTRIBUTES 右側。如果檔案系統不支援版本，則傳回 ZX_ERR_NOT_SUPPORTED。 如果檔案已啟用 fsverity，則傳回 ZX_ERR_ALREADY_EXISTS。 系統還會傳回任何可能因讀取檔案或清除檔案而發生的錯誤，例如 ZX_ERR_IO。

已新增：HEAD

要求

名稱類型
options VerificationOptions

回應

名稱類型
payload File_EnableVerity_Result

GetAttr

取得節點的相關資訊。

這個方法不需要任何權利。

要求

<EMPTY>

回應

名稱類型
s zx/Status
attributes NodeAttributes

GetAttributes

取得節點的相關資訊。

節點的屬性應固定，不受用於存取節點的特定通訊協定無關。

如果特定屬性不適用或不受支援，檔案系統應將對應的欄位留空。

  • query：指定要擷取的屬性的位元遮罩。伺服器不應傳回不必要的次數。
  • attributes 傳回的屬性。

這種方法需要 Rights.GET_ATTRIBUTES 右側。

要求

名稱類型
query NodeAttributesQuery

回應

名稱類型
payload Node2_GetAttributes_Result

GetBackingMemory

取得代表這個檔案的 zx.Handle:VMO (如果有的話)，並為其要求存取權。

您不需要實作即可實作 VMO 支援的檔案，因此這項要求可能會失敗。此外，實作可能僅支援部分標記。如果這項要求失敗，用戶端就應準備備用行為。

如果用戶端未指定 PRIVATE_CLONE 和 SHARED_BUFFER，實作可自由選擇傳回的 VMO 的語意。

  • 要求 flags VmoFlags，指出所需存取模式。

使用這個方法需要以下權限：

要求

名稱類型
flags VmoFlags

回應

名稱類型
payload File_GetBackingMemory_Result

GetConnectionInfo

取得連線相關資訊。

這個方法不需要任何權利。

要求

<EMPTY>

回應

名稱類型
payload ConnectionInfo

GetExtendedAttribute

取得與這個節點的指定屬性 name 相關聯的值。

屬性名稱的長度上限為 MAX_ATTRIBUTE_NAME。這類執行個體沒有設有特定結構。

這種方法需要 Rights.GET_ATTRIBUTES 右側。

新增時間：18 歲

要求

名稱類型
name ExtendedAttributeName

回應

名稱類型
payload Node2_GetExtendedAttribute_Result

GetFlags

取得用來存取這個檔案的 Directory.Open 權限和旗標。

這個方法不需要任何權利。

要求

<EMPTY>

回應

名稱類型
s zx/Status
flags OpenFlags

LinkInto

使用 dst_parent_token 代表目錄中的 dst 名稱，建立此物件的連結。

dst 必須是已解析的物件名稱。在字串中加入「/」會傳回 ZX_ERR_INVALID_ARGS。

這種方法需要檔案系統支援的最大權限組合。對檔案而言，這類檔案通常會是 Rights.READ_BYTES、Rights.WRITE_BYTES、Rights.GET_ATTRIBUTES 和 Rights.UPDATE_ATTRIBUTES。部分檔案系統可能也支援 Rights.EXECUTE 權限。權利不足會導致 ZX_ERR_ACCESS_DENIED。

如果這個物件沒有連結，就會失敗並顯示 ZX_ERR_NOT_FOUND。

這個方法沒有相同的不可分割屬性含有 Directory::Link 方法，也就是說，呼叫 Open 後 LinkInto 就不會等於 Directory::Link，因為 LinkInto 不會防止來源重新命名或取消連結。

要求

名稱類型
dst_parent_token Token
dst Name

回應

名稱類型
payload Linkable_LinkInto_Result

ListExtendedAttributes

針對與這個節點相關聯的所有延伸屬性名稱建立疊代器。如果發生錯誤，系統會在疊代器要求管道中以劇集形式傳回錯誤，然後再關閉管道。

GetExtendedAttributes 可以與這些名稱搭配使用，以擷取相關值。

這種方法需要 Rights.GET_ATTRIBUTES 右側。

新增時間：18 歲

要求

名稱類型
iterator server_end<ExtendedAttributeIterator>

OnOpen

FIDL 伺服器在 OpenFlags.DESCRIBE 要求的情況下迅速產生的事件。

指出開啟作業成功或失敗，並視需要描述物件。如果狀態為 ZX_OK，則 info 包含物件的描述性資訊 (與 Describe 傳回的資訊相同)。

回應

名稱類型
s zx/Status
info NodeInfoDeprecated?

OnRepresentation

NodeFlags.GET_REPRESENTATION 要求時，由伺服器快速產生的事件。這個事件將是伺服器傳送的第一則訊息，並僅傳送一次。

使用中的變化版本會對應至節點支援的其中一個通訊協定，代表連線期間交涉的結果。提供輔助帳號代碼 (如適用)。

如果在 Directory.Open 期間，用戶端在 protocols 中指定多個通訊協定，則表示法會透過其標記執行連線期間協商的結果。

元素與 NodeProtocolKinds 成員有一對一對應。

這是 fuchsia.unknown/Queryable.Query 與特定通訊協定的固有 Describe 方法的特殊案例。此函式可做為最佳化使用，以避免額外的來回行程。

回應

名稱類型
payload Representation

查詢

要求

<EMPTY>

回應

名稱類型
protocol vector<uint8>

QueryFilesystem

向檔案系統查詢檔案系統專屬資訊。

要求

<EMPTY>

回應

名稱類型
s zx/Status
info FilesystemInfo?

已讀

搜尋偏移量最多讀取「count」位元組。 搜尋偏移量會透過讀取的位元組數向前移動。

不變體

  • 傳回的 data.length 絕不會大於 count。
  • 如果 data.length 小於 count，表示這項作業包含搜尋偏移量已到達檔案結尾。
  • 如果 data.length 為零，但 count 不是，表示尋找偏移量已等於或超過檔案結尾，且無法讀取任何資料。
  • 如果 count 為零，伺服器應執行所有檢查，確保讀取權限不會實際讀取任何內容，並傳回空白的 data 向量。

這個方法需要 Rights.READ_BYTES 權限。

如果 count 大於 MAX_TRANSFER_SIZE，則傳回 ZX_ERR_OUT_OF_RANGE。

要求

名稱類型
count uint64

回應

名稱類型
payload Readable_Read_Result

ReadAt

在指定偏移處讀取最多「count」位元組。 這項設定不會影響跳轉偏移量。

不變體

  • 傳回的 data.length 絕不會大於 count。
  • 如果 data.length 小於 count，表示在這項作業中，ReadAt 已到達檔案結尾。
  • 如果 data.length 為零，但 count 不等於，表示 offset 已位於檔案結尾或超過檔案結尾，因此無法讀取任何資料。
  • 如果 count 為零，伺服器應執行所有檢查，確保讀取權限不會實際讀取任何內容，並傳回空白的 data 向量。

這個方法需要 Rights.READ_BYTES 權限。

如果 count 大於 MAX_TRANSFER_SIZE，則傳回 ZX_ERR_OUT_OF_RANGE。

要求

名稱類型
count uint64
offset uint64

回應

名稱類型
payload File_ReadAt_Result

RemoveExtendedAttribute

移除指定的擴充屬性。

如果屬性不存在，系統會傳回 ZX_ERR_NOT_FOUND。

這種方法需要 Rights.UPDATE_ATTRIBUTES 右側。

新增時間：18 歲

要求

名稱類型
name ExtendedAttributeName

回應

名稱類型
payload Node2_RemoveExtendedAttribute_Result

重新開啟

建立連至同一節點的另一個連線。

要求

名稱類型
rights_request RightsRequest
object_request server_end<Node>

調整大小

縮減或使檔案大小增加至「長度」位元組。

如果透過這項作業縮減檔案大小，則會捨棄多餘的結尾資料。如果檔案大小因這項作業增加，擴充區域會顯示為 0。

這個方法需要 Rights.WRITE_BYTES 權限。

要求

名稱類型
length uint64

回應

名稱類型
payload File_Resize_Result

跳轉

移動下次叫用 Read 或 Write 的偏移。搜尋位移會因檔案連線而異。

  • 要求 origin 做為 offset 做為依據的參考點。
  • 要求 offset 要搜尋的位元組數。
  • 回應 offset_from_start，從檔案開頭開始調整的搜尋偏移值。

這個方法不需要任何權利。

要求

名稱類型
origin SeekOrigin
offset int64

回應

名稱類型
payload File_Seek_Result

SetAttr

更新有關節點的資訊。

這個方法需要下列權限：OpenFlags.RIGHT_WRITABLE，否則傳回 ZX_ERR_BAD_HANDLE。

要求

名稱類型
flags NodeAttributeFlags
attributes NodeAttributes

回應

名稱類型
s zx/Status

SetExtendedAttribute

將這個節點的指定屬性 name 值設為 value。

屬性名稱可能存在，而屬性名稱也會隨之更新。如果該屬性不存在，則會建立該屬性。名稱不得包含空值位元組。如果是，系統會傳回 ZX_ERR_INVALID_ARGS。

這種方法需要 Rights.UPDATE_ATTRIBUTES 右側。

新增時間：18 歲

要求

名稱類型
name ExtendedAttributeName
value ExtendedAttributeValue
mode SetExtendedAttributeMode

回應

名稱類型
payload Node2_SetExtendedAttribute_Result

SetFlags

變更用於存取檔案的 Directory.Open 旗標。支援啟用 / 關閉的旗標：

  • OpenFlags.APPEND

這個方法不需要任何權利。

要求

名稱類型
flags OpenFlags

回應

名稱類型
s zx/Status

同步

將節點的更新內容同步處理至基礎媒體 (如果有的話)。

當檔案系統伺服器清除基礎媒體的相關更新時，這個方法將傳回，但不保證基礎媒體會保存資訊，也不會保證任何資訊會提供給硬體。用戶端可利用 Sync 確保在作業之間排序。

這個方法不需要任何權利。

要求

<EMPTY>

回應

名稱類型
payload Node2_Sync_Result

UpdateAttributes

更新有關節點的資訊。

  • attributes如果 attributes 中有資料表欄位，表示要更新對應屬性的意圖。

這種方法需要 Rights.UPDATE_ATTRIBUTES 右側。

要求

名稱類型
payload MutableNodeAttributes

回應

名稱類型
payload Node2_UpdateAttributes_Result

寫入

這個外掛程式能在跳轉時間點寫入資料。搜尋偏移量會透過寫入的位元組數向前移動。如果檔案處於附加模式，搜尋偏移量會先設為檔案結尾，然後是寫入作業，一個不可分割步驟。

如果搜尋偏移量加上 data.length 超過檔案目前的結尾，檔案大小可能會增加。

  • 要求 data 要寫入檔案的位元組緩衝區。
  • 回應 actual_count 則是寫入的位元組數。

不變體

  • 傳回的 actual_count 絕不會大於 data.length。
  • 如果伺服器因空間不足而無法寫入所有資料，actual_count 可能小於 data.length。如果無法寫入任何位元組，系統會傳回錯誤。
  • 如果 data.length 為零，伺服器應在不變更檔案的情況下執行所有檢查以確保寫入權限，並傳回零個位元組的成功寫入。如果使用附加模式，搜尋位移仍會更新。

這個方法需要 Rights.WRITE_BYTES 權限。

要求

名稱類型
data Transfer

回應

名稱類型
payload Writable_Write_Result

WriteAt

按照提供的偏移值寫入資料。這項設定不會影響跳轉偏移量。

如果 offset 加上 data.length 超過檔案目前的結尾，檔案大小可能會增加。

  • 要求 data 要寫入檔案的位元組緩衝區。
  • 要求 offset 從檔案開頭開始寫入的偏移值。
  • 回應 actual_count 則是寫入的位元組數。

不變體

  • 傳回的 actual_count 絕不會大於 data.length。
  • 如果伺服器因空間不足而無法寫入所有資料，actual_count 可能小於 data.length。如果無法寫入任何位元組，系統會傳回錯誤。
  • 如果 data.length 為零，伺服器應在不變更檔案的情況下執行所有檢查以確保寫入存取權，並傳回零個位元組的成功寫入。

這個方法需要 Rights.WRITE_BYTES 權限。

要求

名稱類型
data Transfer
offset uint64

回應

名稱類型
payload File_WriteAt_Result

可連結

定義於 fuchsia.io/node2.fidl

新增時間：18 歲

LinkInto

使用 dst_parent_token 代表目錄中的 dst 名稱，建立此物件的連結。

dst 必須是已解析的物件名稱。在字串中加入「/」會傳回 ZX_ERR_INVALID_ARGS。

這種方法需要檔案系統支援的最大權限組合。對檔案而言，這類檔案通常會是 Rights.READ_BYTES、Rights.WRITE_BYTES、Rights.GET_ATTRIBUTES 和 Rights.UPDATE_ATTRIBUTES。部分檔案系統可能也支援 Rights.EXECUTE 權限。權利不足會導致 ZX_ERR_ACCESS_DENIED。

如果這個物件沒有連結，就會失敗並顯示 ZX_ERR_NOT_FOUND。

這個方法沒有相同的不可分割屬性含有 Directory::Link 方法，也就是說，呼叫 Open 後 LinkInto 就不會等於 Directory::Link，因為 LinkInto 不會防止來源重新命名或取消連結。

要求

名稱類型
dst_parent_token Token
dst Name

回應

名稱類型
payload Linkable_LinkInto_Result

節點

定義於 fuchsia.io/node.fidl

複製

建立另一個連至相同遠端物件的連線。

flags 可以是下列任一值：

  • OpenFlags.RIGHT_*
  • OpenFlags.APPEND
  • OpenFlags.DESCRIBE
  • OpenFlags.CLONE_SAME_RIGHTS

系統會忽略所有其他標記。

flags 中的 OpenFlags.RIGHT_* 位元會要求對所複製物件對應的權限。複製物件的權限必須小於或等於原始物件的權限，否則會傳回 ZX_ERR_ACCESS_DENIED。或者，您也可以傳遞 OpenFlags.CLONE_SAME_RIGHTS 來繼承來源連線的權限。無法與 OpenFlags.CLONE_SAME_RIGHTS 一併傳送任何 OpenFlags.RIGHT_* 旗標。

要求

名稱類型
flags OpenFlags
object server_end<Node>

關閉

終止連線。

呼叫 Close 後，用戶端不得傳送任何其他要求。

伺服器在傳送狀態回應後，無論狀態為何或不傳送連續指令，都應關閉連線。

關閉管道的用戶端，在語意上應等同於呼叫 Close，且不知道關閉程序何時完成或狀態。

要求

<EMPTY>

回應

名稱類型
payload fuchsia.unknown/Closeable_Close_Result

GetAttr

取得節點的相關資訊。

這個方法不需要任何權利。

要求

<EMPTY>

回應

名稱類型
s zx/Status
attributes NodeAttributes

GetAttributes

取得節點的相關資訊。

節點的屬性應固定，不受用於存取節點的特定通訊協定無關。

如果特定屬性不適用或不受支援，檔案系統應將對應的欄位留空。

  • query：指定要擷取的屬性的位元遮罩。伺服器不應傳回不必要的次數。
  • attributes 傳回的屬性。

這種方法需要 Rights.GET_ATTRIBUTES 右側。

要求

名稱類型
query NodeAttributesQuery

回應

名稱類型
payload Node2_GetAttributes_Result

GetConnectionInfo

取得連線相關資訊。

這個方法不需要任何權利。

要求

<EMPTY>

回應

名稱類型
payload ConnectionInfo

GetExtendedAttribute

取得與這個節點的指定屬性 name 相關聯的值。

屬性名稱的長度上限為 MAX_ATTRIBUTE_NAME。這類執行個體沒有設有特定結構。

這種方法需要 Rights.GET_ATTRIBUTES 右側。

新增時間：18 歲

要求

名稱類型
name ExtendedAttributeName

回應

名稱類型
payload Node2_GetExtendedAttribute_Result

GetFlags

取得用來存取這個檔案的 Directory.Open 權限和旗標。

這個方法不需要任何權利。

要求

<EMPTY>

回應

名稱類型
s zx/Status
flags OpenFlags

ListExtendedAttributes

針對與這個節點相關聯的所有延伸屬性名稱建立疊代器。如果發生錯誤，系統會在疊代器要求管道中以劇集形式傳回錯誤，然後再關閉管道。

GetExtendedAttributes 可以與這些名稱搭配使用，以擷取相關值。

這種方法需要 Rights.GET_ATTRIBUTES 右側。

新增時間：18 歲

要求

名稱類型
iterator server_end<ExtendedAttributeIterator>

OnOpen

FIDL 伺服器在 OpenFlags.DESCRIBE 要求的情況下迅速產生的事件。

指出開啟作業成功或失敗，並視需要描述物件。如果狀態為 ZX_OK，則 info 包含物件的描述性資訊 (與 Describe 傳回的資訊相同)。

回應

名稱類型
s zx/Status
info NodeInfoDeprecated?

OnRepresentation

NodeFlags.GET_REPRESENTATION 要求時，由伺服器快速產生的事件。這個事件將是伺服器傳送的第一則訊息，並僅傳送一次。

使用中的變化版本會對應至節點支援的其中一個通訊協定，代表連線期間交涉的結果。提供輔助帳號代碼 (如適用)。

如果在 Directory.Open 期間，用戶端在 protocols 中指定多個通訊協定，則表示法會透過其標記執行連線期間協商的結果。

元素與 NodeProtocolKinds 成員有一對一對應。

這是 fuchsia.unknown/Queryable.Query 與特定通訊協定的固有 Describe 方法的特殊案例。此函式可做為最佳化使用，以避免額外的來回行程。

回應

名稱類型
payload Representation

查詢

要求

<EMPTY>

回應

名稱類型
protocol vector<uint8>

QueryFilesystem

向檔案系統查詢檔案系統專屬資訊。

要求

<EMPTY>

回應

名稱類型
s zx/Status
info FilesystemInfo?

RemoveExtendedAttribute

移除指定的擴充屬性。

如果屬性不存在，系統會傳回 ZX_ERR_NOT_FOUND。

這種方法需要 Rights.UPDATE_ATTRIBUTES 右側。

新增時間：18 歲

要求

名稱類型
name ExtendedAttributeName

回應

名稱類型
payload Node2_RemoveExtendedAttribute_Result

重新開啟

建立連至同一節點的另一個連線。

要求

名稱類型
rights_request RightsRequest
object_request server_end<Node>

SetAttr

更新有關節點的資訊。

這個方法需要下列權限：OpenFlags.RIGHT_WRITABLE，否則傳回 ZX_ERR_BAD_HANDLE。

要求

名稱類型
flags NodeAttributeFlags
attributes NodeAttributes

回應

名稱類型
s zx/Status

SetExtendedAttribute

將這個節點的指定屬性 name 值設為 value。

屬性名稱可能存在，而屬性名稱也會隨之更新。如果該屬性不存在，則會建立該屬性。名稱不得包含空值位元組。如果是，系統會傳回 ZX_ERR_INVALID_ARGS。

這種方法需要 Rights.UPDATE_ATTRIBUTES 右側。

新增時間：18 歲

要求

名稱類型
name ExtendedAttributeName
value ExtendedAttributeValue
mode SetExtendedAttributeMode

回應

名稱類型
payload Node2_SetExtendedAttribute_Result

SetFlags

變更用於存取檔案的 Directory.Open 旗標。支援啟用 / 關閉的旗標：

  • OpenFlags.APPEND

這個方法不需要任何權利。

要求

名稱類型
flags OpenFlags

回應

名稱類型
s zx/Status

同步

將節點的更新內容同步處理至基礎媒體 (如果有的話)。

當檔案系統伺服器清除基礎媒體的相關更新時，這個方法將傳回，但不保證基礎媒體會保存資訊，也不會保證任何資訊會提供給硬體。用戶端可利用 Sync 確保在作業之間排序。

這個方法不需要任何權利。

要求

<EMPTY>

回應

名稱類型
payload Node2_Sync_Result

UpdateAttributes

更新有關節點的資訊。

  • attributes如果 attributes 中有資料表欄位，表示要更新對應屬性的意圖。

這種方法需要 Rights.UPDATE_ATTRIBUTES 右側。

要求

名稱類型
payload MutableNodeAttributes

回應

名稱類型
payload Node2_UpdateAttributes_Result

Node1

定義於 fuchsia.io/node.fidl

節點為可在檔案系統中存取的實體定義最小介面。

複製

建立另一個連至相同遠端物件的連線。

flags 可以是下列任一值：

  • OpenFlags.RIGHT_*
  • OpenFlags.APPEND
  • OpenFlags.DESCRIBE
  • OpenFlags.CLONE_SAME_RIGHTS

系統會忽略所有其他標記。

flags 中的 OpenFlags.RIGHT_* 位元會要求對所複製物件對應的權限。複製物件的權限必須小於或等於原始物件的權限，否則會傳回 ZX_ERR_ACCESS_DENIED。或者，您也可以傳遞 OpenFlags.CLONE_SAME_RIGHTS 來繼承來源連線的權限。無法與 OpenFlags.CLONE_SAME_RIGHTS 一併傳送任何 OpenFlags.RIGHT_* 旗標。

要求

名稱類型
flags OpenFlags
object server_end<Node>

GetAttr

取得節點的相關資訊。

這個方法不需要任何權利。

要求

<EMPTY>

回應

名稱類型
s zx/Status
attributes NodeAttributes

GetFlags

取得用來存取這個檔案的 Directory.Open 權限和旗標。

這個方法不需要任何權利。

要求

<EMPTY>

回應

名稱類型
s zx/Status
flags OpenFlags

OnOpen

FIDL 伺服器在 OpenFlags.DESCRIBE 要求的情況下迅速產生的事件。

指出開啟作業成功或失敗，並視需要描述物件。如果狀態為 ZX_OK，則 info 包含物件的描述性資訊 (與 Describe 傳回的資訊相同)。

回應

名稱類型
s zx/Status
info NodeInfoDeprecated?

QueryFilesystem

向檔案系統查詢檔案系統專屬資訊。

要求

<EMPTY>

回應

名稱類型
s zx/Status
info FilesystemInfo?

SetAttr

更新有關節點的資訊。

這個方法需要下列權限：OpenFlags.RIGHT_WRITABLE，否則傳回 ZX_ERR_BAD_HANDLE。

要求

名稱類型
flags NodeAttributeFlags
attributes NodeAttributes

回應

名稱類型
s zx/Status

SetFlags

變更用於存取檔案的 Directory.Open 旗標。支援啟用 / 關閉的旗標：

  • OpenFlags.APPEND

這個方法不需要任何權利。

要求

名稱類型
flags OpenFlags

回應

名稱類型
s zx/Status

Node2

定義於 fuchsia.io/node2.fidl

Node 針對可在檔案系統中存取的實體定義最低通訊協定。

關閉

終止連線。

呼叫 Close 後，用戶端不得傳送任何其他要求。

伺服器在傳送狀態回應後，無論狀態為何或不傳送連續指令，都應關閉連線。

關閉管道的用戶端，在語意上應等同於呼叫 Close，且不知道關閉程序何時完成或狀態。

要求

<EMPTY>

回應

名稱類型
payload fuchsia.unknown/Closeable_Close_Result

GetAttributes

取得節點的相關資訊。

節點的屬性應固定，不受用於存取節點的特定通訊協定無關。

如果特定屬性不適用或不受支援，檔案系統應將對應的欄位留空。

  • query：指定要擷取的屬性的位元遮罩。伺服器不應傳回不必要的次數。
  • attributes 傳回的屬性。

這種方法需要 Rights.GET_ATTRIBUTES 右側。

要求

名稱類型
query NodeAttributesQuery

回應

名稱類型
payload Node2_GetAttributes_Result

GetConnectionInfo

取得連線相關資訊。

這個方法不需要任何權利。

要求

<EMPTY>

回應

名稱類型
payload ConnectionInfo

GetExtendedAttribute

取得與這個節點的指定屬性 name 相關聯的值。

屬性名稱的長度上限為 MAX_ATTRIBUTE_NAME。這類執行個體沒有設有特定結構。

這種方法需要 Rights.GET_ATTRIBUTES 右側。

新增時間：18 歲

要求

名稱類型
name ExtendedAttributeName

回應

名稱類型
payload Node2_GetExtendedAttribute_Result

ListExtendedAttributes

針對與這個節點相關聯的所有延伸屬性名稱建立疊代器。如果發生錯誤，系統會在疊代器要求管道中以劇集形式傳回錯誤，然後再關閉管道。

GetExtendedAttributes 可以與這些名稱搭配使用，以擷取相關值。

這種方法需要 Rights.GET_ATTRIBUTES 右側。

新增時間：18 歲

要求

名稱類型
iterator server_end<ExtendedAttributeIterator>

OnRepresentation

NodeFlags.GET_REPRESENTATION 要求時，由伺服器快速產生的事件。這個事件將是伺服器傳送的第一則訊息，並僅傳送一次。

使用中的變化版本會對應至節點支援的其中一個通訊協定，代表連線期間交涉的結果。提供輔助帳號代碼 (如適用)。

如果在 Directory.Open 期間，用戶端在 protocols 中指定多個通訊協定，則表示法會透過其標記執行連線期間協商的結果。

元素與 NodeProtocolKinds 成員有一對一對應。

這是 fuchsia.unknown/Queryable.Query 與特定通訊協定的固有 Describe 方法的特殊案例。此函式可做為最佳化使用，以避免額外的來回行程。

回應

名稱類型
payload Representation

查詢

要求

<EMPTY>

回應

名稱類型
protocol vector<uint8>

RemoveExtendedAttribute

移除指定的擴充屬性。

如果屬性不存在，系統會傳回 ZX_ERR_NOT_FOUND。

這種方法需要 Rights.UPDATE_ATTRIBUTES 右側。

新增時間：18 歲

要求

名稱類型
name ExtendedAttributeName

回應

名稱類型
payload Node2_RemoveExtendedAttribute_Result

重新開啟

建立連至同一節點的另一個連線。

要求

名稱類型
rights_request RightsRequest
object_request server_end<Node>

SetExtendedAttribute

將這個節點的指定屬性 name 值設為 value。

屬性名稱可能存在，而屬性名稱也會隨之更新。如果該屬性不存在，則會建立該屬性。名稱不得包含空值位元組。如果是，系統會傳回 ZX_ERR_INVALID_ARGS。

這種方法需要 Rights.UPDATE_ATTRIBUTES 右側。

新增時間：18 歲

要求

名稱類型
name ExtendedAttributeName
value ExtendedAttributeValue
mode SetExtendedAttributeMode

回應

名稱類型
payload Node2_SetExtendedAttribute_Result

同步

將節點的更新內容同步處理至基礎媒體 (如果有的話)。

當檔案系統伺服器清除基礎媒體的相關更新時，這個方法將傳回，但不保證基礎媒體會保存資訊，也不會保證任何資訊會提供給硬體。用戶端可利用 Sync 確保在作業之間排序。

這個方法不需要任何權利。

要求

<EMPTY>

回應

名稱類型
payload Node2_Sync_Result

UpdateAttributes

更新有關節點的資訊。

  • attributes如果 attributes 中有資料表欄位，表示要更新對應屬性的意圖。

這種方法需要 Rights.UPDATE_ATTRIBUTES 右側。

要求

名稱類型
payload MutableNodeAttributes

回應

名稱類型
payload Node2_UpdateAttributes_Result

可開啟

定義於 fuchsia.io/directory.fidl

公開

開啟相對於這個目錄物件的新物件。

path 可能包含多個片段，以「/」字元分隔，而且不可空白；也就是說，「」是無效路徑。結尾的斜線代表 OpenFlags.DIRECTORY。元件不可為空白 (即「foo//bar」無效)。「..」禁止在路徑中的任何位置使用。「.」只有在路徑完全符合「.」時才允許，其他情況則不行。可使用開頭的「/」(且處理方式與不存在相同，也就是「/foo/bar」和「foo/bar」相同)。

如果傳送不明的值給標記，應關閉連線。

flags 中提供的 OpenFlags.RIGHT_* 旗標會限制連結至已開啟實體的 object 管道存取權。

權利絕不會增加。在目錄中開啟巢狀實體時，您只能要求與目錄連線現有的相同權限，或要求其中一部分的權限。超過這些權限會導致在 OnOpen 事件中傳輸存取遭拒的錯誤，並關閉 object 連線。

系統會忽略 mode。

新增時間：12 張

要求

名稱類型
flags OpenFlags
mode ModeType
path string[4095]
object server_end<Node>

可讀性

定義於 fuchsia.io/file2.fidl

已讀

搜尋偏移量最多讀取「count」位元組。 搜尋偏移量會透過讀取的位元組數向前移動。

不變體

  • 傳回的 data.length 絕不會大於 count。
  • 如果 data.length 小於 count，表示這項作業包含搜尋偏移量已到達檔案結尾。
  • 如果 data.length 為零，但 count 不是，表示尋找偏移量已等於或超過檔案結尾，且無法讀取任何資料。
  • 如果 count 為零，伺服器應執行所有檢查，確保讀取權限不會實際讀取任何內容，並傳回空白的 data 向量。

這個方法需要 Rights.READ_BYTES 權限。

如果 count 大於 MAX_TRANSFER_SIZE，則傳回 ZX_ERR_OUT_OF_RANGE。

要求

名稱類型
count uint64

回應

名稱類型
payload Readable_Read_Result

定義於 fuchsia.io/symlink.fidl

含有符號連結的 ['節點']。

新增時間：18 歲

複製

建立另一個連至相同遠端物件的連線。

flags 可以是下列任一值：

  • OpenFlags.RIGHT_*
  • OpenFlags.APPEND
  • OpenFlags.DESCRIBE
  • OpenFlags.CLONE_SAME_RIGHTS

系統會忽略所有其他標記。

flags 中的 OpenFlags.RIGHT_* 位元會要求對所複製物件對應的權限。複製物件的權限必須小於或等於原始物件的權限，否則會傳回 ZX_ERR_ACCESS_DENIED。或者，您也可以傳遞 OpenFlags.CLONE_SAME_RIGHTS 來繼承來源連線的權限。無法與 OpenFlags.CLONE_SAME_RIGHTS 一併傳送任何 OpenFlags.RIGHT_* 旗標。

要求

名稱類型
flags OpenFlags
object server_end<Node>

關閉

終止連線。

呼叫 Close 後，用戶端不得傳送任何其他要求。

伺服器在傳送狀態回應後，無論狀態為何或不傳送連續指令，都應關閉連線。

關閉管道的用戶端，在語意上應等同於呼叫 Close，且不知道關閉程序何時完成或狀態。

要求

<EMPTY>

回應

名稱類型
payload fuchsia.unknown/Closeable_Close_Result

說明

要求

<EMPTY>

回應

名稱類型
payload Symlink_Describe_Result

GetAttr

取得節點的相關資訊。

這個方法不需要任何權利。

要求

<EMPTY>

回應

名稱類型
s zx/Status
attributes NodeAttributes

GetAttributes

取得節點的相關資訊。

節點的屬性應固定，不受用於存取節點的特定通訊協定無關。

如果特定屬性不適用或不受支援，檔案系統應將對應的欄位留空。

  • query：指定要擷取的屬性的位元遮罩。伺服器不應傳回不必要的次數。
  • attributes 傳回的屬性。

這種方法需要 Rights.GET_ATTRIBUTES 右側。

要求

名稱類型
query NodeAttributesQuery

回應

名稱類型
payload Node2_GetAttributes_Result

GetConnectionInfo

取得連線相關資訊。

這個方法不需要任何權利。

要求

<EMPTY>

回應

名稱類型
payload ConnectionInfo

GetExtendedAttribute

取得與這個節點的指定屬性 name 相關聯的值。

屬性名稱的長度上限為 MAX_ATTRIBUTE_NAME。這類執行個體沒有設有特定結構。

這種方法需要 Rights.GET_ATTRIBUTES 右側。

新增時間：18 歲

要求

名稱類型
name ExtendedAttributeName

回應

名稱類型
payload Node2_GetExtendedAttribute_Result

GetFlags

取得用來存取這個檔案的 Directory.Open 權限和旗標。

這個方法不需要任何權利。

要求

<EMPTY>

回應

名稱類型
s zx/Status
flags OpenFlags

LinkInto

使用 dst_parent_token 代表目錄中的 dst 名稱，建立此物件的連結。

dst 必須是已解析的物件名稱。在字串中加入「/」會傳回 ZX_ERR_INVALID_ARGS。

這種方法需要檔案系統支援的最大權限組合。對檔案而言，這類檔案通常會是 Rights.READ_BYTES、Rights.WRITE_BYTES、Rights.GET_ATTRIBUTES 和 Rights.UPDATE_ATTRIBUTES。部分檔案系統可能也支援 Rights.EXECUTE 權限。權利不足會導致 ZX_ERR_ACCESS_DENIED。

如果這個物件沒有連結，就會失敗並顯示 ZX_ERR_NOT_FOUND。

這個方法沒有相同的不可分割屬性含有 Directory::Link 方法，也就是說，呼叫 Open 後 LinkInto 就不會等於 Directory::Link，因為 LinkInto 不會防止來源重新命名或取消連結。

要求

名稱類型
dst_parent_token Token
dst Name

回應

名稱類型
payload Linkable_LinkInto_Result

ListExtendedAttributes

針對與這個節點相關聯的所有延伸屬性名稱建立疊代器。如果發生錯誤，系統會在疊代器要求管道中以劇集形式傳回錯誤，然後再關閉管道。

GetExtendedAttributes 可以與這些名稱搭配使用，以擷取相關值。

這種方法需要 Rights.GET_ATTRIBUTES 右側。

新增時間：18 歲

要求

名稱類型
iterator server_end<ExtendedAttributeIterator>

OnOpen

FIDL 伺服器在 OpenFlags.DESCRIBE 要求的情況下迅速產生的事件。

指出開啟作業成功或失敗，並視需要描述物件。如果狀態為 ZX_OK，則 info 包含物件的描述性資訊 (與 Describe 傳回的資訊相同)。

回應

名稱類型
s zx/Status
info NodeInfoDeprecated?

OnRepresentation

NodeFlags.GET_REPRESENTATION 要求時，由伺服器快速產生的事件。這個事件將是伺服器傳送的第一則訊息，並僅傳送一次。

使用中的變化版本會對應至節點支援的其中一個通訊協定，代表連線期間交涉的結果。提供輔助帳號代碼 (如適用)。

如果在 Directory.Open 期間，用戶端在 protocols 中指定多個通訊協定，則表示法會透過其標記執行連線期間協商的結果。

元素與 NodeProtocolKinds 成員有一對一對應。

這是 fuchsia.unknown/Queryable.Query 與特定通訊協定的固有 Describe 方法的特殊案例。此函式可做為最佳化使用，以避免額外的來回行程。

回應

名稱類型
payload Representation

查詢

要求

<EMPTY>

回應

名稱類型
protocol vector<uint8>

QueryFilesystem

向檔案系統查詢檔案系統專屬資訊。

要求

<EMPTY>

回應

名稱類型
s zx/Status
info FilesystemInfo?

RemoveExtendedAttribute

移除指定的擴充屬性。

如果屬性不存在，系統會傳回 ZX_ERR_NOT_FOUND。

這種方法需要 Rights.UPDATE_ATTRIBUTES 右側。

新增時間：18 歲

要求

名稱類型
name ExtendedAttributeName

回應

名稱類型
payload Node2_RemoveExtendedAttribute_Result

重新開啟

建立連至同一節點的另一個連線。

要求

名稱類型
rights_request RightsRequest
object_request server_end<Node>

SetAttr

更新有關節點的資訊。

這個方法需要下列權限：OpenFlags.RIGHT_WRITABLE，否則傳回 ZX_ERR_BAD_HANDLE。

要求

名稱類型
flags NodeAttributeFlags
attributes NodeAttributes

回應

名稱類型
s zx/Status

SetExtendedAttribute

將這個節點的指定屬性 name 值設為 value。

屬性名稱可能存在，而屬性名稱也會隨之更新。如果該屬性不存在，則會建立該屬性。名稱不得包含空值位元組。如果是，系統會傳回 ZX_ERR_INVALID_ARGS。

這種方法需要 Rights.UPDATE_ATTRIBUTES 右側。

新增時間：18 歲

要求

名稱類型
name ExtendedAttributeName
value ExtendedAttributeValue
mode SetExtendedAttributeMode

回應

名稱類型
payload Node2_SetExtendedAttribute_Result

SetFlags

變更用於存取檔案的 Directory.Open 旗標。支援啟用 / 關閉的旗標：

  • OpenFlags.APPEND

這個方法不需要任何權利。

要求

名稱類型
flags OpenFlags

回應

名稱類型
s zx/Status

同步

將節點的更新內容同步處理至基礎媒體 (如果有的話)。

當檔案系統伺服器清除基礎媒體的相關更新時，這個方法將傳回，但不保證基礎媒體會保存資訊，也不會保證任何資訊會提供給硬體。用戶端可利用 Sync 確保在作業之間排序。

這個方法不需要任何權利。

要求

<EMPTY>

回應

名稱類型
payload Node2_Sync_Result

UpdateAttributes

更新有關節點的資訊。

  • attributes如果 attributes 中有資料表欄位，表示要更新對應屬性的意圖。

這種方法需要 Rights.UPDATE_ATTRIBUTES 右側。

要求

名稱類型
payload MutableNodeAttributes

回應

名稱類型
payload Node2_UpdateAttributes_Result

可寫入

定義於 fuchsia.io/file2.fidl

寫入

這個外掛程式能在跳轉時間點寫入資料。搜尋偏移量會透過寫入的位元組數向前移動。如果檔案處於附加模式，搜尋偏移量會先設為檔案結尾，然後是寫入作業，一個不可分割步驟。

如果搜尋偏移量加上 data.length 超過檔案目前的結尾，檔案大小可能會增加。

  • 要求 data 要寫入檔案的位元組緩衝區。
  • 回應 actual_count 則是寫入的位元組數。

不變體

  • 傳回的 actual_count 絕不會大於 data.length。
  • 如果伺服器因空間不足而無法寫入所有資料，actual_count 可能小於 data.length。如果無法寫入任何位元組，系統會傳回錯誤。
  • 如果 data.length 為零，伺服器應在不變更檔案的情況下執行所有檢查以確保寫入權限，並傳回零個位元組的成功寫入。如果使用附加模式，搜尋位移仍會更新。

這個方法需要 Rights.WRITE_BYTES 權限。

要求

名稱類型
data Transfer

回應

名稱類型
payload Writable_Write_Result

結構化

AdvisoryLockRange

定義於 fuchsia.io/locking.fidl

廣闊類型說明預設
origin SeekOrigin

系統在檔案中計算 offset 的位置。

 無預設
offset int64

位元組範圍的起始值，以與 origin 之間的偏移表示。如果 origin 是 SeekOrigin.START，則不得為負數。

 無預設
length int64

位元組範圍的長度 (以位元組為單位)。

如果長度為 0，則無論檔案有多大，位元組範圍都會延長至檔案結尾。

如果長度是負數，位元組範圍會包含 offset 到 length 到 (含) 為止 (包含 offset - 1) 的位元組，前提是這個範圍不得超出檔案開頭。

 無預設

AdvisoryLocking_AdvisoryLock_Response

定義於 fuchsia.io/locking.fidl

<EMPTY>

定義於 fuchsia.io/directory2.fidl

<EMPTY>

Directory2_Rename_Response

定義於 fuchsia.io/directory2.fidl

<EMPTY>

定義於 fuchsia.io/directory2.fidl

<EMPTY>

DirectoryIterator_GetNext_Response

定義於 fuchsia.io/directory2.fidl

廣闊類型說明預設
entries vector<DirectoryEntry>[8192]

目錄直接子項節點的相關資訊。

如果某個特定屬性不適用或不受支援，實作時應將對應欄位留空。

 無預設

DirectoryObject

定義於 fuchsia.io/node.fidl

<EMPTY>

ExtendedAttributeIterator_GetNext_Response

定義於 fuchsia.io/node2.fidl

廣闊類型說明預設
attributes vector<vector<uint8>>[128] 無預設
last bool 無預設

檔案物件資源

定義於 fuchsia.io/node.fidl

廣闊類型說明預設
event handle<event>?

選用事件，可傳送物件的可讀性或可寫入性相關資訊。這個事件會轉發基礎物件的相關資訊，而非授予用戶端的功能：當連線沒有能力讀取時，這個事件的信號可能是「可讀取」。

這個事件可能會觀察到「FILE_SIGNAL_」值。

 無預設
stream handle<stream>?

用於日後支援串流的預留位置。

目前伺服器不需要傳送這個欄位中的帳號代碼。

 無預設

File_Allocate_Response

定義於 fuchsia.io/file2.fidl

<EMPTY>

File_EnableVerity_Response

定義於 fuchsia.io/file2.fidl

<EMPTY>

File_GetBackingMemory_Response 資源

定義於 fuchsia.io/file2.fidl

廣闊類型說明預設
vmo handle<vmo> 無預設

File_ReadAt_Response

定義於 fuchsia.io/file2.fidl

廣闊類型說明預設
data Transfer 無預設

File_Resize_Response

定義於 fuchsia.io/file2.fidl

<EMPTY>

File_Seek_Response

定義於 fuchsia.io/file2.fidl

廣闊類型說明預設
offset_from_start uint64 無預設

File_WriteAt_Response

定義於 fuchsia.io/file2.fidl

廣闊類型說明預設
actual_count uint64 無預設

FilesystemInfo

定義於 fuchsia.io/node.fidl

廣闊類型說明預設
total_bytes uint64

可儲存在檔案系統中的資料位元組數。這不會計入中繼資料或其他檔案系統的負擔，例如區塊四捨五入。

 無預設
used_bytes uint64

檔案系統使用的資料位元組數。這不會計入中繼資料或其他檔案系統的負擔，例如區塊四捨五入。

 無預設
total_nodes uint64

可儲存在檔案系統中的節點數量。

 無預設
used_nodes uint64

檔案系統使用的節點數量。

 無預設
free_shared_pool_bytes uint64

從基礎磁碟區管理員分配的額外空間大小。如果系統不支援或沒有空間可擴增，這個值會是零。

 無預設
fs_id uint64

此檔案系統執行個體的專屬 ID。不會在重新啟動後保留。

實作工具應建立核心物件 (通常為事件)，並使用 Koid 做為檔案系統 ID。這個小金可保證系統中的唯一性。

 無預設
block_size uint32

單一檔案系統區塊的大小 (以位元組為單位)。

 無預設
max_filename_size uint32

檔案系統名稱的長度上限。

 無預設
fs_type uint32

基礎檔案系統類型的專屬 ID。

 無預設
padding uint32 無預設
name int8[32] 無預設

Linkable_LinkInto_Response

定義於 fuchsia.io/node2.fidl

<EMPTY>

Node2_RemoveExtendedAttribute_Response

定義於 fuchsia.io/node2.fidl

<EMPTY>

Node2_SetExtendedAttribute_Response

定義於 fuchsia.io/node2.fidl

<EMPTY>

Node2_Sync_Response

定義於 fuchsia.io/node2.fidl

<EMPTY>

Node2_UpdateAttributes_Response

定義於 fuchsia.io/node2.fidl

<EMPTY>

NodeAttributes

定義於 fuchsia.io/node.fidl

NodeAttributes 會定義檔案系統節點的一般資訊。

廣闊類型說明預設
mode uint32

保護措施位元和節點類型資訊會在「模式」中說明。

 無預設
id uint64

檔案系統專屬 ID。

 無預設
content_size uint64

節點大小，以位元組為單位。

 無預設
storage_size uint64

用於儲存節點 (可能大於大小) 所需的空間 (以位元組為單位)。

 無預設
creation_time uint64

自 Unix 紀元 (世界標準時間) 以來的建立時間 (可在建立後手動更新)。

 無預設
modification_time uint64

上次修改時間，單位為 Unix 紀元 (世界標準時間)。

 無預設

NodeAttributes2

定義於 fuchsia.io/node2.fidl

廣闊類型說明預設
mutable_attributes MutableNodeAttributes 無預設
immutable_attributes ImmutableNodeAttributes 無預設

Readable_Read_Response

定義於 fuchsia.io/file2.fidl

廣闊類型說明預設
data Transfer 無預設

服務

定義於 fuchsia.io/node.fidl

<EMPTY>

SymlinkObject

定義於 fuchsia.io/node.fidl

廣闊類型說明預設
target SymlinkTarget 無預設

Writable_Write_Response

定義於 fuchsia.io/file2.fidl

廣闊類型說明預設
actual_count uint64 無預設

ENUMS

AdvisoryLockType 嚴格

類型：uint32

定義於 fuchsia.io/locking.fidl

名稱物超所值說明
1

零或多個連線可以同時保留檔案的讀取鎖定。
2

最多只有一個連線可以同時保留某個檔案的寫入鎖定。在檔案上保留寫入鎖定時，該檔案無法保留其他類型的鎖定。
3

區域指定要解鎖的區域。

CreationMode 嚴格

類型：uint32

定義於 fuchsia.io/directory2.fidl

名稱物超所值說明
0

只開啟現有物件，切勿建立新物件。
1
已淘汰：19
2

如果沒有物件，請建立新物件，否則開啟現有的物件。
3

如果沒有物件，請建立新物件，否則要求會以 ZX_ERR_ALREADY_EXISTS 失敗。

DirentType strict

類型：uint8

定義於 fuchsia.io/directory.fidl

名稱物超所值說明
0

類型不明的目錄。
4

代表目錄物件的目錄。
6

代表區塊裝置物件的目錄。
8

代表檔案物件的目錄。
16

代表服務物件的目錄。

HashAlgorithm 彈性

類型：uint8

定義於 fuchsia.io/file2.fidl

表示會使用哪些雜湊演算法為啟用 fsverity 的檔案建構 Merkle 樹狀結構。

已新增：HEAD

名稱物超所值說明
1
2

SeekOrigin 嚴格

類型：uint32

定義於 fuchsia.io/file2.fidl

更新跳轉偏移的參考點。請參閱 File.Seek。

這個列舉與 zx_stream_seek_origin_t 列舉相符。

名稱物超所值說明
0

從檔案開頭跳轉。 搜尋偏移值將設為 offset 個位元組。在此情況下，搜尋偏移值不得為負數。
1

從檔案中的目前位置跳轉。 搜尋偏移量將為目前的搜尋偏移量加上 offset 個位元組。
2

從檔案結尾跳轉。 搜尋偏移量為檔案大小加上 offset 個位元組。

SetExtendedAttributeMode 嚴格

類型：uint32

定義於 fuchsia.io/node2.fidl

名稱物超所值說明
1

設定擴充屬性的值，不論該值是否已存在。
2

建立新的延伸屬性。失敗 (如果已存在)。
3

替換現有的延伸屬性值。如果該程式碼不存在，則會失敗。

WatchEvent 嚴格

類型：uint8

定義於 fuchsia.io/directory.fidl

名稱物超所值說明
0

指出監控的目錄已刪除。由於這個事件參照目錄本身，因此回傳的名稱會是 . (點)。
1

表示節點已建立 (新或移動) 目錄。
2

辨識已從目錄中移除 (已刪除或已移動) 的節點。
3

識別開始觀看時存在於目錄中的節點。
4

表示不會再傳送任何 EXISTING 事件。這個事件傳回的名稱不會參照特定項目，因此會是空白。

資料表

AdvisoryLockRequest

定義於 fuchsia.io/locking.fidl

序數廣闊類型說明
type AdvisoryLockType

要取得的鎖定類型。

如果沒有這個欄位，AdvisoryLock 方法會失敗並顯示 ZX_ERR_INVALID_ARGS。
range AdvisoryLockRange

要鎖定的位元組範圍。

這個範圍可以超出檔案結尾，但不能超出檔案開頭。

如果沒有這個欄位，範圍會預設為整個檔案。
wait bool

檔案是否應等待回應 AdvisoryLock 方法，直到取得要求的鎖定。

如果沒有這個欄位，檔案就不會等待。

ConnectionInfo 資源

定義於 fuchsia.io/node2.fidl

序數廣闊類型說明
rights Rights

目前連結所具備的權利。注意：rights 會限制連線上可執行的作業組合，但無法保證這些作業的可用性。例如，檔案連線可能具有 Rights.EXECUTE 權限，但檔案本身不具備 EXECUTE 功能，因此無法執行。請參閱 ConnectionOptions.rights。

ConnectorInfo

定義於 fuchsia.io/node2.fidl

序數廣闊類型說明
attributes NodeAttributes2

要求的物件屬性。只有在收到要求時，系統才會填入這個值。

新增時間：18 歲

DirectoryEntry

定義於 fuchsia.io/directory2.fidl

序數廣闊類型說明
name Name

節點名稱。必須填寫此欄位。
protocols NodeProtocolKinds

說明節點支援的表示法類型。
abilities Abilities

說明節點支援的作業類型。
id Id

節點的 ID。請參閱 ID。在目錄中的所有項目中，這個 id 不得重複。

DirectoryEnumerateOptions

定義於 fuchsia.io/directory2.fidl

序數廣闊類型說明

DirectoryInfo

定義於 fuchsia.io/directory2.fidl

序數廣闊類型說明
attributes NodeAttributes2

要求的目錄屬性。只有在收到要求時，系統才會填入這個值。

新增時間：18 歲

DirectoryProtocolOptions

定義於 fuchsia.io/directory2.fidl

序數廣闊類型說明
optional_rights Rights

要協商的選擇性權利。

如果存在，表示呼叫端要求額外的選用權限，相當於這個值和要求連線權限的交集。這項要求是藉由透過多個躍點進行 Proxy 處理，因此可以防止權限提升；每個 Proxy 必須在透過 Proxy 執行 Proxy 之前，先將值與要求連線的權限相交。

如要表達 POSIX 語意 (其中目錄的 open 必須為 O_RDONLY)，但 openat 可用於開啟該目錄中的非目錄節點 (權限超過 O_RDONLY)。這表示 POSIX 用戶端必須一律將其設為所有的「Rights」，才能實作不會禁止目錄的 open 或 openat 呼叫 (例如 O_WRONLY 和 O_RDWR 會禁止禁止目錄)。

FileInfo 資源

定義於 fuchsia.io/file2.fidl

節點檔案表示法的輔助資料。

序數廣闊類型說明
is_append bool

如果檔案是以附加模式開啟，則為「是」。 在附加模式中，搜尋偏移會在每次寫入前移至結尾，並以不可分割的方式執行這兩個步驟。
observer handle<event>

選用事件，可傳送物件的可讀性或可寫入性相關資訊。這個事件會轉發基礎物件的相關資訊，而非授予用戶端的功能：如果連線沒有能力讀取，這個事件就可能是表示「可讀取」。

系統會在符合下列條件時顯示這個事件：

  • 檔案連線上的 available_operations 並非空白目錄。
  • 檔案系統支援可讀性/可寫入性事件的信號。

這個事件可能會觀察到 FileSignal 值。
stream handle<stream>

選用的串流物件，可用來讀取檔案及從檔案寫入。

使用串流物件讀取和寫入檔案，速度最多比使用檔案通訊協定中的讀取和寫入作業讀取和寫入檔案快 20 倍。
attributes NodeAttributes2

要求的檔案屬性。只有在收到要求時，系統才會填入這個值。

新增時間：18 歲

ImmutableNodeAttributes

定義於 fuchsia.io/node2.fidl

序數廣闊類型說明
protocols NodeProtocolKinds

說明節點支援的表示法類型。注意：這並非透過 representation 傳遞的連線時交涉結果。
abilities Abilities

說明節點支援的作業類型。注意：這與在連線時使用的權利不同，
content_size uint64

節點大小，以位元組為單位。
storage_size uint64

儲存節點所需的空間 (可能大於大小)，以位元組為單位。
id Id

節點的 ID。請參閱 ID。在目錄中的所有項目中，這個 id 不得重複。
change_time uint64

中繼資料的上次變更時間，自 Unix 紀元 (世界標準時間) 起，以奈秒為單位。

已新增：HEAD
options VerificationOptions

包含啟用驗證檔案時使用的驗證選項。

已新增：HEAD
root_hash vector<uint8>[64]

檔案的根雜湊。並非所有檔案系統都支援這項功能。

已新增：HEAD
verity_enabled bool

如果這個檔案已啟用永久性，則為「是」。

已新增：HEAD

MutableNodeAttributes

定義於 fuchsia.io/node2.fidl

序數廣闊類型說明
creation_time uint64

自 Unix 紀元 (世界標準時間) 起的建立時間，以奈秒為單位。
modification_time uint64

上次修改時間，自 Unix 紀元 (世界標準時間) 起，以奈秒表示。
mode uint32

POSIX 相容性屬性。大多數檔案系統均不支援這些方式。這些函式必須儲存和擷取這些事件 (例如擴充屬性)，不得嘗試解譯 (例如以特殊方式執行權限檢查或處理裝置開啟)。

新增時間：18 歲
uid uint32
新增時間：18 歲
gid uint32
新增時間：18 歲
rdev uint64
新增時間：18 歲
access_time uint64

上次存取時間 (以奈秒為單位)，自 Unix 紀元以來 (世界標準時間)。請注意，如果這是唯一需要更新的屬性，伺服器可能不會一律更新這個屬性。

新增時間：18 歲

NodeOptions

定義於 fuchsia.io/directory2.fidl

開啟節點時使用的選項。

序數廣闊類型說明
flags NodeFlags
protocols NodeProtocols

呼叫端可以設定與預期類型相對應的通訊協定，藉此斷言物件的類型：

  • 如果呼叫端預期的目錄，但無法將節點做為目錄存取，則錯誤為 ZX_ERR_NOT_DIR。

  • 如果呼叫端預期是檔案，但無法將節點存取為檔案，則錯誤為 ZX_ERR_NOT_FILE。

  • 在其他不相符的情況下，如果是空白資料表，則錯誤為 ZX_ERR_WRONG_TYPE。

如果存在多個通訊協定，產生的通訊協定可能會成為其中一個通訊協定。呼叫端應指定 NodeFlags.GET_REPRESENTATION 以接收 Node.OnRepresentation 事件，用來確認通訊協定。

如未列出，表示呼叫端接受任何 Node 通訊協定 (例如連接器節點本身包括 Node)。
mode CreationMode

指定建立目標物件的方式。如果要建立物件，其類型必須由 protocols 指定。系統會以不可分割的形式，檢查新物件的是否存在與建立作業。

如果類型不明確 (例如同時設定了 directory 和 file)，要求就必須因 ZX_ERR_INVALID_ARGS 而失敗。

新增時間：19 歲
rights Rights

已要求新連線的權限。如有任何權利超過目前連線，object_request 就會使用 ZX_ERR_ACCESS_DENIED 關閉。

授予連線的權限範圍將縮小至目標節點類型支援的作業。例如，如果目標節點是檔案，同時要求 Rights.WRITE_BYTES 和 Rights.MODIFY_DIRECTORY，則產生的連線將只會授予 Rights.WRITE_BYTES。
attributes NodeAttributesQuery

如果設定了 NodeFlags.GET_REPRESENTATION 標記，則 Node.OnRepresentation 傳回的屬性。這需要父項連線的 Rights.GET_ATTRIBUTES，但產生的連線並不需要。

新增時間：18 歲
create_attributes MutableNodeAttributes

要建立物件時，此屬性會指定建立時應與物件一併儲存的屬性。如果伺服器不支援設定任何或所有屬性，就會傳回 ZX_ERR_NOT_SUPPORTED。

新增時間：18 歲

NodeProtocols

定義於 fuchsia.io/directory2.fidl

序數廣闊類型說明
directory DirectoryProtocolOptions
file FileProtocolFlags
node NodeProtocolFlags

要求節點通訊協定。系統僅支援 Rights.GET_ATTRIBUTES 屬性。針對產生的連線呼叫 SetFlags 會產生 ZX_ERR_BAD_HANDLE。如果指定 NodeFlags.GET_REPRESENTATION，則即使物件支援不同的表示法，系統仍會傳回 connector 變數。

新增時間：18 歲

RightsRequest

定義於 fuchsia.io/node2.fidl

序數廣闊類型說明
rights Rights

已要求新連線的權限。

如果 rights 超過要求連線的權利，則 object_request 會以 ZX_ERR_ACCESS_DENIED 冪等鍵關閉。

如未顯示，則會繼承提出要求的連線權利。

SymlinkInfo

定義於 fuchsia.io/symlink.fidl

新增時間：18 歲

序數廣闊類型說明
target SymlinkTarget

在伺服器上，符號連結在伺服器上沒有意義；用戶端可自由根據自己選擇的方式解讀目標。
attributes NodeAttributes2

符號連結要求的屬性。只有在收到要求時，系統才會填入這個值。

UnlinkOptions

定義於 fuchsia.io/directory2.fidl

序數廣闊類型說明
flags UnlinkFlags

VerificationOptions

定義於 fuchsia.io/file2.fidl

用於啟用檔案驗證性的選項集。

已新增：HEAD

序數廣闊類型說明
hash_algorithm HashAlgorithm
salt vector<uint8>[32]

系統會在完成雜湊處理前，在每個區塊前面加上 salt。

聯合國

AdvisoryLocking_AdvisoryLock_Result 嚴格

定義於 fuchsia.io/locking.fidl

序數Variant類型說明
response AdvisoryLocking_AdvisoryLock_Response
err zx/Status

ConnectionProtocols 彈性

定義於 fuchsia.io/directory2.fidl

序數Variant類型說明
connector ConnectorFlags

要求在連線中提供節點的基礎通訊協定。
node NodeOptions

會在連線中提供基礎 Node 通訊協定的要求。

定義於 fuchsia.io/directory2.fidl

序數Variant類型說明

Directory2_Rename_Result 嚴格

定義於 fuchsia.io/directory2.fidl

序數Variant類型說明
response Directory2_Rename_Response
err zx/Status

定義於 fuchsia.io/directory2.fidl

序數Variant類型說明

DirectoryIterator_GetNext_Result 嚴格

定義於 fuchsia.io/directory2.fidl

序數Variant類型說明
response DirectoryIterator_GetNext_Response
err zx/Status

ExtendedAttributeIterator_GetNext_Result 嚴格

定義於 fuchsia.io/node2.fidl

序數Variant類型說明
response ExtendedAttributeIterator_GetNext_Response
err zx/Status

ExtendedAttributeValue 嚴格 資源

定義於 fuchsia.io/node2.fidl

擴充屬性的值類型。如果值小於 32768 個位元組，則會以內嵌方式納入。大於這個大小的值會寫入 vmo 緩衝區。

新增時間：18 歲
序數Variant類型說明
bytes vector<uint8>[32768]
buffer handle<vmo>

File_Allocate_Result 嚴格

定義於 fuchsia.io/file2.fidl

序數Variant類型說明
response File_Allocate_Response
err zx/Status

File_EnableVerity_Result 嚴格

定義於 fuchsia.io/file2.fidl

序數Variant類型說明
response File_EnableVerity_Response
err zx/Status

File_GetBackingMemory_Result 嚴格 資源

定義於 fuchsia.io/file2.fidl

序數Variant類型說明
response File_GetBackingMemory_Response
err zx/Status

File_ReadAt_Result 嚴格

定義於 fuchsia.io/file2.fidl

序數Variant類型說明
response File_ReadAt_Response
err zx/Status

File_Resize_Result 嚴格

定義於 fuchsia.io/file2.fidl

序數Variant類型說明
response File_Resize_Response
err zx/Status

File_Seek_Result 嚴格

定義於 fuchsia.io/file2.fidl

序數Variant類型說明
response File_Seek_Response
err zx/Status

File_WriteAt_Result 嚴格

定義於 fuchsia.io/file2.fidl

序數Variant類型說明
response File_WriteAt_Response
err zx/Status

Linkable_LinkInto_Result 嚴格

定義於 fuchsia.io/node2.fidl

序數Variant類型說明
response Linkable_LinkInto_Response
err zx/Status

Node2_GetAttributes_Result 嚴格

定義於 fuchsia.io/node2.fidl

序數Variant類型說明
response NodeAttributes2
err zx/Status

Node2_GetExtendedAttribute_Result 嚴格 資源

定義於 fuchsia.io/node2.fidl

序數Variant類型說明
response ExtendedAttributeValue
err zx/Status

Node2_RemoveExtendedAttribute_Result 嚴格

定義於 fuchsia.io/node2.fidl

序數Variant類型說明
response Node2_RemoveExtendedAttribute_Response
err zx/Status

Node2_SetExtendedAttribute_Result 嚴格

定義於 fuchsia.io/node2.fidl

序數Variant類型說明
response Node2_SetExtendedAttribute_Response
err zx/Status

Node2_Sync_Result 嚴格

定義於 fuchsia.io/node2.fidl

序數Variant類型說明
response Node2_Sync_Response
err zx/Status

Node2_UpdateAttributes_Result 嚴格

定義於 fuchsia.io/node2.fidl

序數Variant類型說明
response Node2_UpdateAttributes_Response
err zx/Status

NodeInfo 已淘汰嚴格 資源

定義於 fuchsia.io/node.fidl

序數Variant類型說明
service Service

這個連線未提供通訊協定資訊。
file FileObject

連線會建立 File。
directory DirectoryObject

連線會建立 Directory。

Readable_Read_Result 嚴格

定義於 fuchsia.io/file2.fidl

序數Variant類型說明
response Readable_Read_Response
err zx/Status

表示法彈性 資源

定義於 fuchsia.io/node2.fidl

序數Variant類型說明
connector ConnectorInfo

節點連接器表示法的輔助資料，用於探索通訊協定及連線。

它支援連線至檔案系統伺服器在路徑中匯出的任意通訊協定，包括不組合 Node2 的通訊協定。

請參閱 NodeProtocolKinds.CONNECTOR。
directory DirectoryInfo

節點目錄表示法的輔助資料。在「Representation」(表示法) 中選取這個變化版本，即表示連線遵循 Directory 通訊協定。

請參閱 NodeProtocolKinds.DIRECTORY。
file FileInfo

節點檔案表示法的輔助資料。在「Representation」(表示法) 中選取此變數，即表示連線採用檔案通訊協定。

請參閱 NodeProtocolKinds.FILE。

定義於 fuchsia.io/symlink.fidl

序數Variant類型說明

Writable_Write_Result 嚴格

定義於 fuchsia.io/file2.fidl

序數Variant類型說明
response Writable_Write_Response
err zx/Status

帳單

AllocateMode 彈性

類型：uint32

定義於 fuchsia.io/file2.fidl

名稱物超所值說明
1
2
4
8
16
32

ConnectorFlags 彈性

類型：uint64

定義於 fuchsia.io/directory2.fidl

名稱物超所值說明

FileProtocolFlags 彈性

類型：uint64

定義於 fuchsia.io/directory2.fidl

名稱物超所值說明
1

在附加模式中開啟檔案，例如，連線應在每次寫入前跳轉至檔案結尾。

如果檔案不支援附加內容，則會產生 ZX_ERR_NOT_SUPPORTED 復原碼。目前只有 NodeProtocolKinds.FILE 連線支援附加功能。
2

使用 0 將物件截斷。連線需要立即 Rights.WRITE_BYTES。

如果檔案不支援截斷，則應產生 ZX_ERR_NOT_SUPPORTED 單詞。

檔案信號嚴格

類型：uint32

定義於 fuchsia.io/file2.fidl

名稱物超所值說明
16777216

表示檔案已準備好讀取。
33554432

表示檔案已可供寫入。

ModeType strict

類型：uint32

定義於 fuchsia.io/directory.fidl

名稱物超所值說明
2147483648

NodeAttributeFlags 嚴格

類型：uint32

定義於 fuchsia.io/node.fidl

用來更新節點的「attributes」欄位會以「flags」引數表示。

名稱物超所值說明
1
2

NodeAttributesQuery 嚴格

類型：uint64

定義於 fuchsia.io/node2.fidl

名稱物超所值說明
1

要求 NodeAttributes.protocols。
2

要求 NodeAttributes.abilities 功能。
4

要求 NodeAttributes.content_size。
8

要求 NodeAttributes.storage_size。
32

要求 NodeAttributes.id。
64

要求 NodeAttributes.creation_time。
128

要求 NodeAttributes.modification_time。
256

POS 屬性。

新增時間：18 歲
512
新增時間：18 歲
1024
新增時間：18 歲
2048
新增時間：18 歲
4096
新增時間：18 歲
8192
新增時間：18 歲
16384

詳細屬性。

已新增：HEAD
32768
已新增：HEAD
65536
已新增：HEAD

NodeFlags 彈性

類型：uint64

定義於 fuchsia.io/directory2.fidl

名稱物超所值說明
1

系統會在通訊協定要求中，以第一則訊息的形式傳送 Node.OnRepresentation 事件的要求。

這是特定通訊協定的 fuchsia.unknown/Queryable.Query + 固有的 Describe 方法的特殊案例。此函式可做為最佳化結果，以避免額外的來回行程。

NodeProtocolFlags 彈性

類型：uint64

定義於 fuchsia.io/directory2.fidl

名稱物超所值說明
1

只有在基礎物件為目錄的情況下，才允許連線。如果嘗試開啟目錄以外的項目，將會產生 ZX_ERR_NOT_DIR 禮儀。

NodeProtocolKinds 彈性

類型：uint64

定義於 fuchsia.io/node-protocols.fidl

即使節點具有固定的基礎身分，節點開啟時仍可能有多種支援的表示法。

目前，系統會透過 File 通訊協定存取檔案，並在使用 GET_REPRESENTATION 開啟時傳送 Representation.FileInfo。不過，我們日後可能會推出更複雜的 FileV2 通訊協定，或由特殊核心物件支援的更有效率 SuperFastFile。新用戶端可在 NodeProtocolKinds 中指定對應的位元，要求更進階的表示法，而現有用戶端則會繼續透過舊表示法與節點通訊。

NodeProtocolKinds 透過通訊協定交涉形式啟用前瞻相容性。

元素與 Representation 的成員一對一對應。

名稱物超所值說明
1

節點的連接器表示法。

視開啟期間使用的標記而定，連線會說出 Node 或目標通訊協定。
2

節點的目錄表示法。

連線會朗讀 Directory 通訊協定。
4

節點的檔案表示法。

連線會說出檔案通訊協定。

嚴格 OpenFlags

類型：uint32

定義於 fuchsia.io/directory.fidl

名稱物超所值說明
1

可以從目標物件讀取資料。
2

可以寫入目標物件。
8

連線可以對應目標物件可執行檔。
65536

建立物件 (如果不存在)。
131072

(含 Create) 如果物件已存在，則無法執行。
262144

在使用前截斷物件。
524288

斷言要開啟的物件是目錄。 如果目標物件不是目錄，則傳回錯誤。
1048576

在所有寫入作業之前跳轉至物件的結尾。
4194304

開啟對物件 (而非物件本身) 的參照。 只有將下列標記與 NODE_REFERENCE 一起傳遞才有效：

  • DIRECTORY
  • NOT_DIRECTORY
  • DESCRIBE 否則系統會傳回錯誤。 如果使用這個方法開啟或複製物件，產生的連線就不會含有任何權限標記。產生的連線允許部分作業：GetAttr、Clone、Close、Describe 和 GetFlags。連線會朗讀 Node 通訊協定。呼叫 SetAttr 或 SetFlags 會導致 ZX_ERR_BAD_HANDLE。
8388608

有「OnOpen」事件傳送至介面要求的要求。

如果開啟/複製作業成功，事件會包含非空值的 NodeInfoDeprecated。這可用於開啟不會組合 fuchsia.io/Node 的通訊協定；系統會比照 fuchsia.io/Node 傳送事件，然後只使用目標通訊協定。
134217728

指定這個旗標來要求與寫入權限處理相關的 POSIX 相容性。目前，這會影響公開期間的權限處理方式：

  • 如果目標路徑是目錄，只有在目前連線和所有中繼掛接點可寫入時，新連線的權限才會擴展以包含 WRITABLE。
  • 否則系統會忽略此標記。如果要求的權限比目前連線或任何中繼掛接點更多，就會發生存取遭拒錯誤。

如果省略這個旗標，開啟功能一律會使用要求的權利，如果要求的權限超過目前連線附加的權限，則作業會失敗，並顯示存取遭拒錯誤。

如果要求的連線為唯讀狀態，且要求的權限是唯讀狀態，則伺服器可能會忽略這個標記，且不會在下游轉送。這是實作詳細資料，如要跨掛接點強制執行階層權限，對用戶端的預期行為並不會造成任何影響。
268435456

指定這個旗標來要求 POSIX 相容性，以便在執行權限處理作業時進行。目前，這會影響公開期間的權限處理方式：

  • 如果目標路徑是目錄，只有在目前連線和所有中繼掛接點可執行的情況下，新連線的權限才會擴展以包含 EXECUTABLE。
  • 否則系統會忽略此標記。如果要求的權限比目前連線或任何中繼掛接點更多，就會發生存取遭拒錯誤。

如果省略這個旗標，開啟功能一律會使用要求的權利，如果要求的權限超過目前連線附加的權限，則作業會失敗，並顯示存取遭拒錯誤。

如果要求的連線為唯讀狀態，且要求的權限是唯讀狀態，則伺服器可能會忽略這個標記，且不會在下游轉送。這是實作詳細資料，如要跨掛接點強制執行階層權限，對用戶端的預期行為並不會造成任何影響。
33554432

斷言要開啟的物件並非目錄。 如果目標物件是目錄，則傳回錯誤。
67108864

在複製期間使用時，無論來源是檔案或目錄，新連線都會繼承來源連線的權限。否則，系統會執行複製作業，嘗試使用要求的權限。無法與 OpenFlags.CLONE_SAME_RIGHTS 一併傳送任何 RIGHT_* 旗標。
16777216

以區塊裝置的形式開啟目標物件。

作業嚴格

類型：uint64

定義於 fuchsia.io/rights-abilities.fidl

構成權利和特性的共同成員定義。部分作業可能只適用於特定節點類型 (例如，Operations.MODIFY_DIRECTORY 僅適用於目錄)。

名稱物超所值說明
1

連線至目錄中的服務。
2

讀取節點或其子項的位元組內容。
4

寫入節點或其子項的位元組內容。
8

執行節點或其子項的位元組內容。
16

讀取節點和/或其子項的屬性。
32

更新節點和/或其子項的屬性。
64

讀取目錄中的節點清單。
128

從目錄開啟節點。必須以 Rights.ENUMERATE 指定，因為點選子項即可探測目錄內容。
256

修改目錄中的節點清單，例如建立、重新命名、連結/取消連結等... 必須以 Rights.ENUMERATE 指定，因為可在節點建立期間透過名稱衝突探測目錄內容。

SymlinkProtocolFlags 彈性

類型：uint64

定義於 fuchsia.io/directory2.fidl

名稱物超所值說明

取消連結旗標嚴格

類型：uint64

定義於 fuchsia.io/directory2.fidl

名稱物超所值說明
1

設定之後，如果物件不是目錄，取消連結就會失敗 (透過 ZX_ERR_NOT_DIR)。

VmoFlags 嚴格

類型：uint32

定義於 fuchsia.io/file2.fidl

名稱物超所值說明
1

VMO 可讀取的要求。
2

可寫入 VMO 的要求。
4

要求 VMO 為執行檔。
65536

需要基礎 VMO 的寫入時複製副本。如果無法複製 VMO，要求將會失敗。可能無法與 SHARED_BUFFER 一併提供。

私人本機副本至少會使用 ZX_VMO_CHILD_SNAPSHOT_AT_LEAST_ON_WRITE 旗標的保證為 zx_vmo_create_child()。也就是說，傳回的 VMO 會在寫入時複製 (如果要求 WRITE)，但其中不一定會反映基礎檔案的後續內容變更。傳回的 VMO 不會反映檔案的大小變更。這些語意與 POSIX mmap() MAP_PRIVATE 旗標的語意相符。

在某些情況下，需要檔案保證快照的用戶端可以使用 SHARED_BUFFER，然後將 zx_vmo_create_child() 與 ZX_VMO_CHILD_SNAPSHOT 搭配使用。但是，如果實作無法傳回 SHARED_BUFFER，如果 VMO 已附加至分頁器，建立完整快照也會失敗。由於大多數檔案系統都會使用分頁系統，因此完整快照方法只應在用戶端與已知伺服器通訊的特定情況下使用。
131072

需要 VMO，必須能夠直接存取檔案基礎 VMO 的內容。如果無法提供這類 VMO，要求就會失敗。可能不適用於 PRIVATE_CLONE。

即使系統要求 WRITE 存取權，傳回的 VMO 可能也無法調整大小。在這種情況下，請使用 File.Resize 調整檔案大小。

手錶遮罩嚴格

類型：uint32

定義於 fuchsia.io/directory.fidl

名稱物超所值說明
1

由 Directory.Watch 使用。要求傳輸 WatchEvent.DELETED。
2

由 Directory.Watch 使用。要求傳輸 WatchEvent.ADDED。
4

由 Directory.Watch 使用。要求傳輸 WatchEvent.REMOVED。
8

由 Directory.Watch 使用。要求傳輸 WatchEvent.EXISTING。
16

由 Directory.Watch 使用。要求傳輸 WatchEvent.IDLE。

業者

名稱物超所值類型說明
DIRECTORY_PROTOCOL_NAME fuchsia.io/Directory String
FILE_PROTOCOL_NAME fuchsia.io/File String
INO_UNKNOWN 18446744073709551615 uint64

沒有 ino 值的節點應從 Readdir 和 GetAttr 傳回這個值。
MAX_ATTRIBUTE_NAME 255 uint64

延伸屬性名稱的大小上限。

新增時間：18 歲
MAX_BUF 8192 uint64

緩衝區空間上限，適用於緩衝作業。這個容量目前略有設定。
MAX_FILENAME 255 uint64

單一檔案系統元件的長度上限 (以位元組為單位)。
MAX_FS_NAME_BUFFER 32 uint64
MAX_INLINE_ATTRIBUTE_VALUE 32768 uint64

要內嵌的擴充屬性值大小上限。大於這個大小的值會以 vmo 形式傳遞。

新增時間：18 歲
MAX_LIST_ATTRIBUTES_CHUNK 128 uint64

ListExtendedAttributes 疊代器中區塊的大小上限。

新增時間：18 歲
MAX_NAME_LENGTH 255 uint64

單一檔案系統元件的長度上限 (以位元組為單位)。
MAX_PATH_LENGTH 4095 uint64

檔案系統路徑的長度上限 (以位元組為單位)。
MAX_TRANSFER_SIZE 8192 uint64

使用位元組向量進行讀取/寫入作業的 I/O 大小上限。
MODE_PROTECTION_MASK 4095 uint32

為 posix 保護措施保留位元。原生 fuchsia 檔案系統不需要設定包含在 MODE_PROTECTION_MASK 中的位元，但是想要這麼做的檔案系統可能會參考 sys/stat.h 以瞭解其定義。
MODE_TYPE_BLOCK_DEVICE 24576 uint32
MODE_TYPE_DIRECTORY 16384 uint32
MODE_TYPE_FILE 32768 uint32
MODE_TYPE_MASK 1044480 uint32

以位元表示節點類型。檢查節點類型的標準機制為「mode」，以位元表示並搭配 MODE_TYPE_MASK，然後依據模式類型檢查確切相等。
MODE_TYPE_SERVICE 65536 uint32
NODE_PROTOCOL_NAME fuchsia.io/Node String
OPEN_FLAGS_ALLOWED_WITH_NODE_REFERENCE

開啟節點參照時使用的旗標必須位於這個遮罩中。
OPEN_RIGHTS

所有已知的權利。
RW_STAR_DIR

目錄權限別名 rw 的別名*
RX_STAR_DIR

目錄權限別名 rx 的別名*
R_STAR_DIR

目錄權限別名 r 的別名*
W_STAR_DIR

目錄權限別名的別名 w*
X_STAR_DIR

目錄權限別名 x 的別名*

別名

名稱物超所值說明
功能 fuchsia.io/Operations

能力是節點固有的屬性。用於指定支援哪些作業。

在不支援該作業的節點上叫用作業會導致 ZX_ERR_NOT_SUPPORTED。請注意，同時套用兩者時，ZX_ERR_ACCESS_DENIED 的優先順序高於 ZX_ERR_NOT_SUPPORTED。
ExtendedAttributeName vector[MAX_ATTRIBUTE_NAME]

擴充屬性的名稱。不得包含任何空值位元組。除了大小上限外，名稱中不會有特定結構。

新增時間：18 歲
ID uint64

如果實作支援一些唯一節點 ID 的概念，用於識別節點的類型。

獨特性保證

用戶端通常會呈現目錄樹狀結構，而這個樹狀結構的成果是組合多個支援實作執行個體的結果。ID 在對應的執行個體中不得重複。至於在 Fuchsia 上，由於其邊界是透明的目錄 Proxy，因此較不隱含。用戶端在周遊目錄樹狀結構時，經常發現相同的 Id (遇到來自不同支援執行個體的節點)。因此，這個 ID 最適合用於偵錯和提供資訊。

fuchsia.fs/FilesystemInfo.fs_id 欄位可用來區分與不同的支援執行個體 ID。
名稱 string[MAX_NAME_LENGTH]

節點名稱的類型，即單一路徑元件。例如：foo

不變體

有效的節點名稱必須符合下列條件：

  • 這個值不得大於 MAX_NAME_LENGTH。
  • 不得留空。
  • 不得為「..」(點點號)。
  • 不得為「.」(單點)。
  • 不得包含「/」。
  • 但不得包含嵌入的 NUL。
路徑 string[MAX_PATH_LENGTH]

路徑是一或多個元件的字串，以「/」分隔。例如：foo/bar/baz

不變體

有效的路徑必須符合下列條件：

  • 不得留空。
  • 這個值不得大於 MAX_PATH_LENGTH。
  • 開頭不得為「/」。
  • 結尾不得為「/」。
  • 且必須與「.」完全相符，「或是」其每個元件都必須是有效的「名稱」。

路徑應在用戶端轉換為標準格式。舉例來說，用戶端必須先將 "foo/bar/.././baz/" 轉換為 "foo/baz"，才能將其做為路徑使用。
權利 fuchsia.io/Operations

權限是連線專屬的屬性。限制會限制允許連線的作業，包括可授予新連線的作業。

在 ZX_ERR_ACCESS_DENIED 中叫用沒有相應正確結果的作業，即使節點不支援該作業也一樣。
SymlinkTarget vector[MAX_PATH_LENGTH]
權杖 zx/Handle

用於識別節點連線的類型。其代表能力：對具備關聯權限的節點參照。
轉移 vector[MAX_TRANSFER_SIZE]

用於讀取/寫入作業的位元組向量類型。