| // Copyright 2022 The Fuchsia Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| library fuchsia.sys2; |
| |
| using fuchsia.io; |
| using fuchsia.component; |
| using fuchsia.component.decl; |
| using fuchsia.component.config; |
| using fuchsia.url; |
| |
| /// The maximum length of an instance ID. |
| /// An instance ID is a 256-bit identifier, which when encoded |
| /// in hex notation is 64 characters long. |
| const MAX_INSTANCE_ID_LENGTH uint32 = 64; |
| |
| /// Describes the current state of instance |
| type InstanceState = strict enum { |
| /// The component is created, but has not been resolved by component manager. |
| /// Most information about this component is unknown. |
| UNRESOLVED = 0; |
| |
| /// The component has been resolved by component manager but is not currently running. |
| RESOLVED = 1; |
| |
| /// The component has been resolved and started by component manager. |
| STARTED = 2; |
| }; |
| |
| /// Basic information about a component instance. |
| /// This object contains information that is readily available to component manager. |
| type InstanceInfo = struct { |
| /// The path to this instance relative to the scope root. |
| moniker string:fuchsia.component.MAX_MONIKER_LENGTH; |
| |
| /// The URL of the component manifest for this instance. |
| url fuchsia.url.Url; |
| |
| /// The stable identifier for this instance. |
| instance_id string:<MAX_INSTANCE_ID_LENGTH, optional>; |
| |
| /// The current state of this instance. |
| state InstanceState; |
| }; |
| |
| /// The detailed resolved state of a component instance |
| type ResolvedState = resource struct { |
| /// All `use` declarations as defined in the component manifest. |
| uses vector<fuchsia.component.decl.Use>:MAX; |
| |
| /// All `expose` declarations as defined in the component manifest. |
| exposes vector<fuchsia.component.decl.Expose>:MAX; |
| |
| /// The resolved structured configuration of this component instance. |
| config box<fuchsia.component.config.ResolvedConfig>; |
| |
| /// The package directory containing the component manifest, if one exists. |
| /// This directory has the same permissions given by the package resolver |
| /// (most likely RO permissions). |
| pkg_dir client_end:<fuchsia.io.Directory, optional>; |
| |
| /// The execution state of this instance. |
| started box<StartedState>; |
| |
| /// The directory containing all capabilities exposed by the component. |
| /// This directory has RW permissions. |
| exposed_dir client_end:<fuchsia.io.Directory>; |
| |
| /// The directory representing the component's namespace. |
| /// This directory has RW permissions. |
| ns_dir client_end:<fuchsia.io.Directory>; |
| }; |
| |
| /// The detailed started state of a component instance |
| type StartedState = resource struct { |
| /// The outgoing directory of this instance, if one exists. |
| out_dir client_end:<fuchsia.io.Directory, optional>; |
| |
| /// The debug directory served by the runner of this instance, if one exists. |
| runtime_dir client_end:<fuchsia.io.Directory, optional>; |
| |
| /// The human-readable explanation for why this instance is running. |
| start_reason string:MAX; |
| }; |
| |
| /// An iterator over basic information of all instances in the realm |
| protocol InstanceInfoIterator { |
| Next() -> (struct { |
| infos vector<InstanceInfo>:MAX; |
| }); |
| }; |
| |
| /// Offers detailed introspection into component instances under a realm. |
| @discoverable |
| protocol RealmQuery { |
| /// Gets the detailed information of a particular instance identified by its moniker. |
| /// This response contains handles to resources of the instance. As a result, component manager |
| /// pays a non-trivial cost when this method is invoked. |
| /// |
| /// Errors: |
| /// * INVALID_ARGUMENTS: The given moniker is not valid. |
| /// * INSTANCE_NOT_FOUND: No instance was found matching the given moniker. |
| GetInstanceInfo(struct { |
| moniker string:fuchsia.component.MAX_MONIKER_LENGTH; |
| }) -> (resource struct { |
| /// Basic information about the component instance. |
| info InstanceInfo; |
| |
| /// Detailed information about the resolved component instance. |
| /// If this object does not exist, the instance is not resolved. |
| resolved box<ResolvedState>; |
| }) error fuchsia.component.Error; |
| }; |
| |
| /// Offers basic introspection into component instances under a realm. |
| @discoverable |
| protocol RealmExplorer { |
| /// Returns an iterator over basic information of each instance scoped to this realm. |
| /// When the server receives this call, it will take a snapshot of the current component |
| /// topology and relays that over the iterator. Any changes to the topology *after* this method |
| /// call is received by the server will not be shown by the iterator. |
| /// |
| /// Errors: |
| /// * INSTANCE_NOT_FOUND: The instance at the scope root cannot be found. |
| GetAllInstanceInfos() -> (resource struct { |
| iterator client_end:InstanceInfoIterator; |
| }) error fuchsia.component.Error; |
| }; |