sdk/fidl/fuchsia.sys2/events.fidl - fuchsia - Git at Google

 // 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.sys2;

 using fuchsia.component;
 using fuchsia.io;
 using zx;

 /// The maximum number of event types that a receiver can listen to.
 /// This capacity should match the actual number of event types.
 const uint64 MAX_NUM_EVENTS_RECEIVED = 8;

 /// The maximum string length of a capability ID.
 /// This value is currently set arbitrarily.
 const uint64 MAX_CAPABILITY_ID_LENGTH = 50;

 /// The maximum string length of an error description.
 const uint64 MAX_ERROR_DESCRIPTION_LENGTH = 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.
 enum EventType {
     /// A capability exposed to the framework by a component is available.
     CAPABILITY_READY = 1;

     /// A capability is being requested by a component and its routing
     /// has also been determined.
     /// The event propagation system is used to supply the capability being requested.
     CAPABILITY_ROUTED = 2;

     /// An instance was destroyed successfully. The instance is stopped and no longer
     /// exists in the parent's realm.
     DESTROYED = 3;

     /// 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 = 4;

     /// Destruction of an instance has begun. The instance may/may not be stopped by this point.
     /// The instance still exists in the parent's realm but will soon be removed.
     /// TODO(fxb/39417): Ensure the instance is stopped before this event.
     MARKED_FOR_DESTRUCTION = 5;

     /// An instance's declaration was resolved successfully for the first time.
     RESOLVED = 6;

     /// 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 = 7;

     /// An instance was stopped successfully.
     /// This event must occur before Destroyed.
     STOPPED = 8;

     /// If requested, this event is dispatched on subscription and indicates
     /// that the instance has already started and is still running.
     RUNNING = 9;
 };

 /// Describes the source of a routed capability.
 flexible union CapabilitySource {
     /// The capability is provided by the framework and may be
     /// scoped down to a component.
     1: FrameworkCapability framework;

     /// The capability is provided by another component.
     2: ComponentCapability component;
 };

 /// Describes a capability provided by the framework
 table FrameworkCapability {
     /// The moniker of the instance that this capability is scoped to.
     1: string:fuchsia.component.MAX_MONIKER_LENGTH scope_moniker;
 };

 /// Describes a capability provided by a component
 table ComponentCapability {
     /// The moniker of the instance that is providing this capability.
     1: string:fuchsia.component.MAX_MONIKER_LENGTH source_moniker;
 };

 /// Describes the result of a state transition.
 flexible union EventResult {
     /// The payload of the event if the state transition described by the event
     /// succeeds.
     1: EventPayload payload;

     /// The error that caused the state transition described by the event to
     /// fail.
     2: EventError error;
 };

 /// Corresponds to an error that occurred during a state transition.
 table EventError {
     /// A string describing the error that occurred.
     /// TODO(fxb/49792): We should be sending structured errors, and not simply strings.
     /// This is a placeholder pending further internal component manager refactors.
     1: string:MAX_ERROR_DESCRIPTION_LENGTH description;

     /// The error payload of the event if any.
     2: EventErrorPayload error_payload;
 };

 /// Encapsulates additional data for some event errors.
 flexible union EventErrorPayload {
     /// Payload for CapabilityReady events
     1: CapabilityReadyError capability_ready;

     /// Payload for CapabilityRouted events
     2: CapabilityRoutedError capability_routed;
 };

 /// Error payload for CapabilityReady events
 table CapabilityReadyError {
     /// The path of the capability.
     1: string:fuchsia.component.MAX_PATH_LENGTH path;
 };

 /// Error payload for CapabilityRouted events
 table CapabilityRoutedError {
     /// Identifier of capability being requested.
     /// For a path-based capability, this is the path.
     /// For a runner capability, this is the name.
     1: string:MAX_CAPABILITY_ID_LENGTH capability_id;
 };

 /// Encapsulates additional data/protocols for some event types.
 flexible union EventPayload {
     /// Payload for CapabilityReady events
     1: CapabilityReadyPayload capability_ready;

     /// Payload for CapabilityRouted events
     2: CapabilityRoutedPayload capability_routed;
 };

 /// Payload for CapabilityReady events
 table CapabilityReadyPayload {
     /// The path of the capability.
     1: string:fuchsia.component.MAX_PATH_LENGTH path;

     /// Channel to the node exposed by the event source at `path`.
     2: fuchsia.io.Node node;
 };

 /// Payload for CapabilityRouted events
 table CapabilityRoutedPayload {
     /// Allows setting a capability provider for
     /// CapabilityRouted events
     /// This will not be available with an async event.
     1: RoutingProtocol routing_protocol;

     /// Identifier of capability being requested.
     /// For a path-based capability, this is the path.
     /// For a runner capability, this is the name.
     2: string:MAX_CAPABILITY_ID_LENGTH capability_id;

     /// Source of the capability that needs to be routed.
     3: CapabilitySource source;
 };

 /// Contains all information about a single event
 table Event {
     /// Event type corresponding to the event
     1: EventType event_type;

     /// Moniker of instance corresponding to the event
     2: string:fuchsia.component.MAX_MONIKER_LENGTH target_moniker;

     /// Handler for resuming from event
     /// This will be absent if this is an async event.
     3: Handler handler;

     /// Optional payload for some event types
     4: EventResult event_result;

     /// Time when the event occurred.
     5: zx.time timestamp;
 };

 /// Subscribe to events in component manager.
 [Discoverable, FragileBase]
 protocol EventSource {
     /// Subscribes to the events of the provided EventTypes.
     ///
     /// Returns a EventStreamSync which can be used
     /// to expect the registered types.
     ///
     /// Errors:
     /// - `RESOURCE_UNAVAILABLE` when the component hasn't been granted the capability to subscribe
     ///   to some event in the requested `events`.
     Subscribe(vector<fuchsia.component.event_name>:MAX_NUM_EVENTS_RECEIVED events,
               EventStream stream)
         -> () error fuchsia.component.Error;
 };

 /// Subscribe to events in component manager.
 [Discoverable]
 protocol BlockingEventSource {
     compose EventSource;

     /// Resume the execution of components within the realm using a scoped
     /// BlockingEventSource.  This method is idempotent.
     StartComponentTree() -> ();
 };

 /// Listener for events on the component hierarchy. The server won't wait for the client
 /// to handle the request before sending more events.
 protocol EventStream {
     OnEvent(Event event);
 };

 /// Every Event supports this basic handler to allow resumption.
 protocol Handler {
     /// Resumes/unblocks from an event.
     Resume() -> ();
 };

 /// Allows injecting capabilities over FIDL.
 /// Used by RouteFrameworkCapability and RouteBuiltinCapability
 protocol RoutingProtocol {
     /// Set a CapabilityProvider. Invoking this method will replace
     /// any existing provider.
     ///
     /// When a component attempts to connect to a capability,
     /// this method can be used to mock/inject that capability.
     SetProvider(CapabilityProvider client_end) -> ();

     /// Replace the existing provider with the given client_end and
     /// open the existing provider with given server end.
     ///
     /// This method is used to interpose between a client and service:
     /// Client <---> Interposer <---> Server
     ///
     /// Opening the existing provider sets up Interposer <---> Server
     /// Replacing the existing provider sets up Client <---> Interposer
     ReplaceAndOpen(CapabilityProvider client_end, handle<channel> server_end) -> ();
 };

 /// A FIDL-based version of a CapabilityProvider
 protocol CapabilityProvider {
     /// Called to bind a server end of a channel to the provided framework capability.
     /// TODO(xbhatnag): provide all arguments (flags, mode, path) to this method.
     Open(handle<channel> server_end) -> ();
 };
	// 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.sys2;

	using fuchsia.component;
	using fuchsia.io;
	using zx;

	/// The maximum number of event types that a receiver can listen to.
	/// This capacity should match the actual number of event types.
	const uint64 MAX_NUM_EVENTS_RECEIVED = 8;

	/// The maximum string length of a capability ID.
	/// This value is currently set arbitrarily.
	const uint64 MAX_CAPABILITY_ID_LENGTH = 50;

	/// The maximum string length of an error description.
	const uint64 MAX_ERROR_DESCRIPTION_LENGTH = 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.
	enum EventType {
	/// A capability exposed to the framework by a component is available.
	CAPABILITY_READY = 1;

	/// A capability is being requested by a component and its routing
	/// has also been determined.
	/// The event propagation system is used to supply the capability being requested.
	CAPABILITY_ROUTED = 2;

	/// An instance was destroyed successfully. The instance is stopped and no longer
	/// exists in the parent's realm.
	DESTROYED = 3;

	/// 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 = 4;

	/// Destruction of an instance has begun. The instance may/may not be stopped by this point.
	/// The instance still exists in the parent's realm but will soon be removed.
	/// TODO(fxb/39417): Ensure the instance is stopped before this event.
	MARKED_FOR_DESTRUCTION = 5;

	/// An instance's declaration was resolved successfully for the first time.
	RESOLVED = 6;

	/// 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 = 7;

	/// An instance was stopped successfully.
	/// This event must occur before Destroyed.
	STOPPED = 8;

	/// If requested, this event is dispatched on subscription and indicates
	/// that the instance has already started and is still running.
	RUNNING = 9;
	};

	/// Describes the source of a routed capability.
	flexible union CapabilitySource {
	/// The capability is provided by the framework and may be
	/// scoped down to a component.
	1: FrameworkCapability framework;

	/// The capability is provided by another component.
	2: ComponentCapability component;
	};

	/// Describes a capability provided by the framework
	table FrameworkCapability {
	/// The moniker of the instance that this capability is scoped to.
	1: string:fuchsia.component.MAX_MONIKER_LENGTH scope_moniker;
	};

	/// Describes a capability provided by a component
	table ComponentCapability {
	/// The moniker of the instance that is providing this capability.
	1: string:fuchsia.component.MAX_MONIKER_LENGTH source_moniker;
	};

	/// Describes the result of a state transition.
	flexible union EventResult {
	/// The payload of the event if the state transition described by the event
	/// succeeds.
	1: EventPayload payload;

	/// The error that caused the state transition described by the event to
	/// fail.
	2: EventError error;
	};

	/// Corresponds to an error that occurred during a state transition.
	table EventError {
	/// A string describing the error that occurred.
	/// TODO(fxb/49792): We should be sending structured errors, and not simply strings.
	/// This is a placeholder pending further internal component manager refactors.
	1: string:MAX_ERROR_DESCRIPTION_LENGTH description;

	/// The error payload of the event if any.
	2: EventErrorPayload error_payload;
	};

	/// Encapsulates additional data for some event errors.
	flexible union EventErrorPayload {
	/// Payload for CapabilityReady events
	1: CapabilityReadyError capability_ready;

	/// Payload for CapabilityRouted events
	2: CapabilityRoutedError capability_routed;
	};

	/// Error payload for CapabilityReady events
	table CapabilityReadyError {
	/// The path of the capability.
	1: string:fuchsia.component.MAX_PATH_LENGTH path;
	};

	/// Error payload for CapabilityRouted events
	table CapabilityRoutedError {
	/// Identifier of capability being requested.
	/// For a path-based capability, this is the path.
	/// For a runner capability, this is the name.
	1: string:MAX_CAPABILITY_ID_LENGTH capability_id;
	};

	/// Encapsulates additional data/protocols for some event types.
	flexible union EventPayload {
	/// Payload for CapabilityReady events
	1: CapabilityReadyPayload capability_ready;

	/// Payload for CapabilityRouted events
	2: CapabilityRoutedPayload capability_routed;
	};

	/// Payload for CapabilityReady events
	table CapabilityReadyPayload {
	/// The path of the capability.
	1: string:fuchsia.component.MAX_PATH_LENGTH path;

	/// Channel to the node exposed by the event source at `path`.
	2: fuchsia.io.Node node;
	};

	/// Payload for CapabilityRouted events
	table CapabilityRoutedPayload {
	/// Allows setting a capability provider for
	/// CapabilityRouted events
	/// This will not be available with an async event.
	1: RoutingProtocol routing_protocol;

	/// Identifier of capability being requested.
	/// For a path-based capability, this is the path.
	/// For a runner capability, this is the name.
	2: string:MAX_CAPABILITY_ID_LENGTH capability_id;

	/// Source of the capability that needs to be routed.
	3: CapabilitySource source;
	};

	/// Contains all information about a single event
	table Event {
	/// Event type corresponding to the event
	1: EventType event_type;

	/// Moniker of instance corresponding to the event
	2: string:fuchsia.component.MAX_MONIKER_LENGTH target_moniker;

	/// Handler for resuming from event
	/// This will be absent if this is an async event.
	3: Handler handler;

	/// Optional payload for some event types
	4: EventResult event_result;

	/// Time when the event occurred.
	5: zx.time timestamp;
	};

	/// Subscribe to events in component manager.
	[Discoverable, FragileBase]
	protocol EventSource {
	/// Subscribes to the events of the provided EventTypes.
	///
	/// Returns a EventStreamSync which can be used
	/// to expect the registered types.
	///
	/// Errors:
	/// - `RESOURCE_UNAVAILABLE` when the component hasn't been granted the capability to subscribe
	/// to some event in the requested `events`.
	Subscribe(vector<fuchsia.component.event_name>:MAX_NUM_EVENTS_RECEIVED events,
	EventStream stream)
	-> () error fuchsia.component.Error;
	};

	/// Subscribe to events in component manager.
	[Discoverable]
	protocol BlockingEventSource {
	compose EventSource;

	/// Resume the execution of components within the realm using a scoped
	/// BlockingEventSource. This method is idempotent.
	StartComponentTree() -> ();
	};

	/// Listener for events on the component hierarchy. The server won't wait for the client
	/// to handle the request before sending more events.
	protocol EventStream {
	OnEvent(Event event);
	};

	/// Every Event supports this basic handler to allow resumption.
	protocol Handler {
	/// Resumes/unblocks from an event.
	Resume() -> ();
	};

	/// Allows injecting capabilities over FIDL.
	/// Used by RouteFrameworkCapability and RouteBuiltinCapability
	protocol RoutingProtocol {
	/// Set a CapabilityProvider. Invoking this method will replace
	/// any existing provider.
	///
	/// When a component attempts to connect to a capability,
	/// this method can be used to mock/inject that capability.
	SetProvider(CapabilityProvider client_end) -> ();

	/// Replace the existing provider with the given client_end and
	/// open the existing provider with given server end.
	///
	/// This method is used to interpose between a client and service:
	/// Client <---> Interposer <---> Server
	///
	/// Opening the existing provider sets up Interposer <---> Server
	/// Replacing the existing provider sets up Client <---> Interposer
	ReplaceAndOpen(CapabilityProvider client_end, handle<channel> server_end) -> ();
	};

	/// A FIDL-based version of a CapabilityProvider
	protocol CapabilityProvider {
	/// Called to bind a server end of a channel to the provided framework capability.
	/// TODO(xbhatnag): provide all arguments (flags, mode, path) to this method.
	Open(handle<channel> server_end) -> ();
	};