mojo/application/public/interfaces/application.mojom

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 module mojo;
   6
   7 import "mojo/application/public/interfaces/service_provider.mojom";
   8 import "mojo/application/public/interfaces/shell.mojom";
   9
  10 // This is the primary interface implemented by every Mojo application. It
  11 // allows the application to receive its startup arguments from the shell, and
  12 // to be notified of events that occur during its execution.
  13 //
  14 // TODO(aa): It would be good to reorder the parameters once we have interface
  15 // versioning.
  16 interface Application {
  17   // Initializes the application with the specified arguments. This method is
  18   // guaranteed to be called before any other method is called, and will only be
  19   // called once.
  20   //
  21   // The |url| parameter is the identity of the application as far as the shell
  22   // is concerned. This will be the URL the application was found at, after all
  23   // mappings, resolution, and redirects. And it will not include the
  24   // querystring, since the querystring is not part of an application's
  25   // identity.
  26   Initialize(Shell shell, string url);
  27
  28   // Called when another application (identified by |requestor_url|) attempts to
  29   // open a connection to this application.
  30   //
  31   // If the other application wants to request services from this application,
  32   // it will have passed a valid interface request through the |services|
  33   // parameter (i.e. one containing a valid message pipe endpoint). This
  34   // application may then bind an implementation of |ServiceProvider| to that
  35   // request in order to make services available to the other application.
  36   //
  37   // If the other application wants to offer services to this application, it
  38   // will have passed a bound interface through the |exposed_services|
  39   // parameter. This application may then request services through that
  40   // interface.
  41   //
  42   // It is possible that both parameters will be valid/bound if the other
  43   // application wants to both request services from and offer services to this
  44   // application.
  45   //
  46   // This application is free to ignore the |services| or |exposed_services|
  47   // parameters if it does not wish to offer or request services.
  48   //
  49   // |allowed_interfaces| is a set of interface names that the shell has
  50   // determined can be exposed by this application to the connecting
  51   // application. When this parameter is empty, this application should expose
  52   // no services to the connecting application. When this parameter contains
  53   // only the single string value "*" the application may expose all of its
  54   // services to the connecting application.
  55   //
  56   // |resolved_url| is the URL that was requested to create this connection,
  57   // after all mappings, resolutions, and redirects. This will include any
  58   // querystring that was part of the request.
  59   //
  60   AcceptConnection(string requestor_url,
  61                    ServiceProvider&? services,
  62                    ServiceProvider? exposed_services,
  63                    array<string> allowed_interfaces,
  64                    string resolved_url);
  65
  66   // Called by the shell in response to calling Shell's QuitApplication. The
  67   // application should run the callback with true if shutdown can proceed.
  68   // See Shell::QuitApplication for details about shutdown workflow.
  69   OnQuitRequested() => (bool can_quit);
  70 };