// Copyright 2016 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.media;

struct QueryResponse {
    vector<Proposal> proposals;
};

// An interface enabling Agents and Modules to contribute Proposals reactively
// to the Suggestion engine based on a user query.
protocol QueryHandler {
    // Produces a list of Proposals in response to a query. The query may be empty
    // in the case of an initial ask, and this method is called every time the
    // query changes.
    //
    // Proposals given in the callback have their lifecycle tied to this query.
    // After the query has completed, the proposals are dismissed. When the query
    // changes, any proposals missing from the subsequent callback are likewise
    // dismissed. These Proposals are distinct from Next/Interruption proposals,
    // even if they may share IDs.
    //
    // Alternately, the client is free to call Propose on its
    // ProposalPublisher to make persistent Proposals. However, these
    // proposals may be subject to more stringent filtering by the Suggestion
    // Engine. TODO(rosswang): spec/revisit.
    OnQuery(UserInput query) -> (QueryResponse response);
};