blob: c8071b4aadadc5bccd82dd453c07c422d71dda9e [file] [log] [blame]
// 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.app.agent;
using fuchsia.app;
using fuchsia.app.sessioncontrol;
using fuchsia.io;
/// An agent is a component which provides services in support of modules in a
/// story. Agents cannot show UI directly.
///
/// - An agent is a singleton instance within the scope of a session.
/// - Components can connect to an Agent using the Context service provided to
/// each modular component class (fuchsia.app.agent, fuchsia.app.module,
/// fuchsia.app.storyshell, fuchsia.app.sessionshell).
/// - An agent vends services and resources to components that connect to it over a
/// fuchsia.io.Directory.
/// - An agent is started when someone wants to connect to it, or when a task it
/// has scheduled has triggered.
///
/// This FIDL interface MUST be implemented for agent components.
///
/// For more info see:
/// - peridot/docs/modular/agent.md
/// - fuchsia.app.agent.Context for common methods provided by modular to agents.
/// - fuchsia.app.Lifecycle for how agents receive lifecycle events.
[Discoverable]
protocol Agent {
/// Called when a client of this agent wishes to acquire a service directory from this agent.
///
/// `client` describes the identity of the client component. See ClientIdentity below.
///
/// `directory_request` should be bound to a fuchsia.io.Directory implementation or closed
/// if services are denied. The Agent implementation should keep `directory_request` bound
/// and available until the client closes it. At this point, it must NOT assume that
/// the client itself is gone, but rather that the client no longer wishes to open new
/// services connections.
AcceptConnection(ClientIdentity client, request<fuchsia.io.Directory> directory_request);
/// Called when a task identified by `task` is scheduled to run. Tasks are scheduled run when
/// the conditions described in `task.type` become true. Tasks are scheduled using
/// fuchsia.app.agent.Context/ScheduleTask().
///
/// Agents must return from RunTask() when the task has finished. The Agent may be asked to
/// terminate in the middle of task execution.
///
/// TODO(MF-321): The current implementation permits the Agent to run a task until its callback
/// returns, no matter how long. There is no mechanism to cancel an ongoing task.
RunTask(TaskInfo task) -> ();
};
table ClientIdentity {
/// The component URL of the requesting client, as formatted at the time of component creation.
///
/// Always set.
1: fuchsia.app.ComponentUrl component_url;
/// If the client is a module created by this agent (using
/// fuchsia.app.sessioncontrol.StoryController), identifies the StoryId the agent specified at
/// module creation time. Otherwise not set.
///
/// See fuchsia.app.sessioncontrol.StoryController.
2: fuchsia.app.StoryId story_id;
/// If the client is a module created by this agent (using
/// fuchsia.app.sessioncontrol.StoryController), identifies the ModuleId the agent specified at
/// module creation time. Otherwise not set.
///
/// See fuchsia.app.sessioncontrol.StoryController.
3: fuchsia.app.sessioncontrol.ModuleId module_id;
};