| // Copyright 2019 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.component; |
| |
| using fuchsia.io; |
| using fuchsia.url; |
| using zx; |
| |
| /// The maximum string length of a capability ID. |
| /// This value is currently set arbitrarily. |
| @available(added=11) |
| const MAX_CAPABILITY_ID_LENGTH uint64 = 50; |
| |
| /// The maximum string length of an error description. |
| @available(added=11) |
| const MAX_ERROR_DESCRIPTION_LENGTH uint64 = 100; |
| |
| /// These EventTypes are used for the EventStream protocol. |
| /// They are FIDL versions of the EventType enum in hooks.rs and have |
| /// the same meaning. |
| @available(added=11) |
| type EventType = strict enum { |
| /// A capability provided by this component has been requested. The event |
| /// payload carries the request channel. |
| CAPABILITY_REQUESTED = 1; |
| |
| /// A directory exposed to the framework by a component is available. |
| @available(removed=20) |
| DIRECTORY_READY = 2; |
| |
| /// A component instance was discovered. This is the first stage in the lifecycle |
| /// of components. Dispatched for dynamic children when they're created, for static |
| /// children when their parent is resolved, and for the root when the component manager |
| /// starts. |
| DISCOVERED = 3; |
| |
| /// The instance is destroyed and no longer exists. |
| DESTROYED = 4; |
| |
| /// An instance's declaration was resolved successfully for the first time. |
| RESOLVED = 5; |
| |
| /// This instance has started, according to component manager. However, if this is an |
| /// executable component, the runner has further work to do to launch the component. |
| STARTED = 6; |
| |
| /// An instance was stopped successfully. |
| STOPPED = 7; |
| |
| /// Similar to STARTED, except the payload will carry an eventpair that the subscriber |
| /// could use to defer the launch of the component. This allows, e.g., a debugger to |
| /// perform some setup before any processes are created. |
| DEBUG_STARTED = 8; |
| |
| /// An instance was unresolved successfully. |
| UNRESOLVED = 9; |
| }; |
| |
| /// Encapsulates additional data/protocols for some event types. |
| @available(added=11) |
| type EventPayload = flexible resource union { |
| /// Payload for CapabilityRequested events |
| 1: capability_requested CapabilityRequestedPayload; |
| |
| /// Payload for Purged events. |
| 2: purged PurgedPayload; |
| |
| /// Payload for DirectoryReady events |
| @available(deprecated=19, removed=20) |
| 3: directory_ready DirectoryReadyPayload; |
| |
| /// Payload for Discovered events. |
| 4: discovered DiscoveredPayload; |
| |
| /// Payload for Destroyed events. |
| 5: destroyed DestroyedPayload; |
| |
| /// Payload for Resolved events |
| 6: resolved ResolvedPayload; |
| |
| /// Payload for Started events |
| 7: started StartedPayload; |
| |
| /// Payload for Stopped events |
| 8: stopped StoppedPayload; |
| |
| /// Payload for DebugStarted events |
| 9: debug_started DebugStartedPayload; |
| |
| /// Payload for Unresolved events |
| 10: unresolved UnresolvedPayload; |
| }; |
| |
| /// Payload for DirectoryReady events |
| @available(added=11, deprecated=19, removed=20) |
| type DirectoryReadyPayload = resource table { |
| /// The name of the capability. |
| 1: name name; |
| |
| /// Channel to the directory capability. |
| 2: node client_end:fuchsia.io.Node; |
| }; |
| |
| /// Payload for CapabilityRequested events |
| @available(added=11) |
| type CapabilityRequestedPayload = resource table { |
| /// The name of the capability. |
| 1: name name; |
| |
| /// A handle to the server end of the channel to host |
| /// capability. |
| 2: capability zx.Handle:CHANNEL; |
| }; |
| |
| /// Payload for Purged events. |
| @available(added=11) |
| type PurgedPayload = table {}; |
| |
| /// Payload for Discovered events. |
| @available(added=11) |
| type DiscoveredPayload = table {}; |
| |
| /// Payload for Destroyed events. |
| @available(added=11) |
| type DestroyedPayload = table {}; |
| |
| /// Payload for Resolved events. |
| @available(added=11) |
| type ResolvedPayload = table {}; |
| |
| /// Payload for Unresolved events. |
| @available(added=11) |
| type UnresolvedPayload = table {}; |
| |
| /// Payload for Started events. |
| @available(added=11) |
| type StartedPayload = table {}; |
| |
| /// Payload for Stopped events. |
| @available(added=11) |
| type StoppedPayload = table { |
| /// The epitaph set on the fuchsia.component.runner/ComponentController |
| /// protocol channel. This is the exit status of the component. The |
| /// possible status values and their meaning are described in the definition |
| /// of the ComponentController protocol. |
| 1: status zx.Status; |
| }; |
| |
| /// Payload for DebugStarted events. |
| @available(added=11) |
| type DebugStartedPayload = resource table { |
| /// The directory served by the runner to present runtime and runner-specific information |
| /// about the component. The other side is sent to the runner in ComponentStartInfo. |
| /// For example, it can be queried to know whether the component is an ELF component and |
| /// supports the break_on_start protocol below. |
| 1: runtime_dir client_end:fuchsia.io.Directory; |
| |
| /// An eventpair that can be used by debuggers to defer the launch of the component, |
| /// e.g., ELF debuggers can setup the exception channel on the job while holding |
| /// the eventpair, then drop the eventpair to notify the runner that processes could |
| /// be created. The other side is sent to the runner in ComponentStartInfo. |
| 2: break_on_start zx.Handle:EVENTPAIR; |
| }; |
| |
| /// A head providing metadata about a target component instance. |
| @available(added=11) |
| type EventHeader = table { |
| /// Event type corresponding to the event |
| 1: event_type EventType; |
| |
| /// Relative moniker identifying the component instance. Relative to the scope of the event. |
| 2: moniker string:MAX_MONIKER_LENGTH; |
| |
| /// URL used to resolve the component. |
| 3: component_url fuchsia.url.Url; |
| |
| /// Time when the event occurred. |
| 4: timestamp zx.Time; |
| }; |
| |
| /// Contains all information about a single event |
| @available(added=11) |
| type Event = resource table { |
| /// Information about the component for which this event was generated. |
| 1: header EventHeader; |
| |
| /// Optional payload for some event types |
| 2: payload EventPayload; |
| }; |
| |
| /// Listener for events on the component hierarchy. |
| @discoverable |
| @available(added=11) |
| closed protocol EventStream { |
| strict GetNext() -> (resource struct { |
| events vector<Event>:MAX; |
| }); |
| |
| /// Returns immediately. Used to indicate that the FIDL connection |
| /// completed. This is needed for non-static streams to verify |
| /// that subscribe has completed before components are started. |
| strict WaitForReady() -> (); |
| }; |