// Copyright 2017 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.modular;

using fuchsia.sys;

/// Provided to all component instances in their respective initialization
/// information by the framework. For example, a Module gets it from its
/// ModuleContext and an Agent gets it from its AgentContext.
[Discoverable]
protocol ComponentContext {
    /// DEPRECATED: use the component's incoming namespace (for C++, see sys.ComponentContext)
    /// to connect to services provided by agents. See
    /// /docs/concepts/modular/guide/how_to_write_an_agent_cc.md for an example.
    ///
    /// Used to start an agent in the user scope if it isn't already running, and
    /// connect to it.
    ConnectToAgent(string url,
                   request<fuchsia.sys.ServiceProvider> incoming_services,
                   request<AgentController> controller);

    /// DEPRECATED: use the component's incoming namespace (for C++, see sys.ComponentContext)
    /// to connect to services provided by agents. See
    /// /docs/concepts/modular/guide/how_to_write_an_agent_cc.md for an example.
    ///
    /// Connects to an agent that provides the given `request.service_name`, and
    /// then connects the given `request.channel` to that service.
    /// `request.agent_controller` must be kept alive until the service is no
    /// longer required.
    ///
    /// If an error is encountered, the `request.channel` will be closed with
    /// a status code, such as:
    ///   * `ZX_ERR_NOT_FOUND` -- if a `request.handler` agent URL is not
    ///     specified, and an agent for the `request.service_name` is not found
    ///   * `ZX_ERR_PEER_CLOSED` -- if `request.service_name` is not available from
    ///     the agent (either specified or discovered)
    [Transitional]
    ConnectToAgentService(AgentServiceRequest request);

    /// Gets the EntityResolver service, which can be used to resolve an entity
    /// reference to an Entity interface.
    GetEntityResolver(request<EntityResolver> request);
};

/// Used by ComponentContext.ConnectToAgentService
table AgentServiceRequest {
    /// The name of the requested service.
    1: string service_name;

    /// The channel that will be used to communicate with the requested service.
    2: handle<channel> channel;

    /// The component URL of the Agent that is to provide the specified service.
    /// If no handler is specified, the framework will perform resolution to
    /// find an appropriate handler.
    3: fuchsia.sys.component_url handler;

    /// The AgentController that keeps the agent alive.
    4: request<AgentController> agent_controller;
};