// Copyright 2014 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

module mojo;

import "mojo/application/public/interfaces/service_provider.mojom";
import "mojo/application/public/interfaces/shell.mojom";

// This is the primary interface implemented by every Mojo application. It
// allows the application to receive its startup arguments from the shell, and
// to be notified of events that occur during its execution.
//
// TODO(aa): It would be good to reorder the parameters once we have interface
// versioning.
interface Application {
  // Initializes the application with the specified arguments. This method is
  // guaranteed to be called before any other method is called, and will only be
  // called once.
  //
  // The |url| parameter is the identity of the application as far as the shell
  // is concerned. This will be the URL the application was found at, after all
  // mappings, resolution, and redirects. And it will not include the
  // querystring, since the querystring is not part of an application's
  // identity.
  Initialize(Shell shell, array<string>? args, string url);

  // Called when another application (identified by |requestor_url|) attempts to
  // open a connection to this application.
  //
  // If the other application wants to request services from this application,
  // it will have passed a valid interface request through the |services|
  // parameter (i.e. one containing a valid message pipe endpoint). This
  // application may then bind an implementation of |ServiceProvider| to that
  // request in order to make services available to the other application.
  //
  // If the other application wants to offer services to this application, it
  // will have passed a bound interface through the |exposed_services|
  // parameter. This application may then request services through that
  // interface.
  //
  // It is possible that both parameters will be valid/bound if the other
  // application wants to both request services from and offer services to this
  // application.
  //
  // This application is free to ignore the |services| or |exposed_services|
  // parameters if it does not wish to offer or request services.
  //
  // resolved_url is the URL that was requested to create this connection, after
  // all mappings, resolutions, and redirects. This will include any querystring
  // that was part of the request.
  AcceptConnection(string requestor_url,
                   ServiceProvider&? services,
                   ServiceProvider? exposed_services,
                   string resolved_url);

  // Called to request the application shut itself down gracefully.
  RequestQuit();
};