mojo/application/public/interfaces/shell.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 "network/public/interfaces/url_loader.mojom";
   9
  10 // Specifies a whitelist of applications and services an application can connect
  11 // to. Connections to applications not explicitly specified here as a key are
  12 // rejected. Connections to services not specified in an application's allowed
  13 // interfaces value are not made.
  14 // A "*" value as the only key in an otherwise empty map means the application
  15 // may connect to any other application.
  16 // A "*" value as the only string in an otherwise empty array of interface names
  17 // means the application may connect to any service in that application.
  18 // An empty interface name array means the application may not connect to any
  19 // services exposed by the application it is connecting to.
  20 struct CapabilityFilter {
  21   map<string, array<string>> filter;
  22 };
  23
  24 // An interface through which a Mojo application may communicate with the Mojo
  25 // system and request connections to other applications.
  26 interface Shell {
  27   // Establishes a connection with another application ("target application")
  28   // (located at |request->url|) through which the calling application and the
  29   // target application may request services from one another.
  30   // |application_url| is a URLRequest in case this is called for an HTTP
  31   // navigation, in which case HTTP specific information like POST data,
  32   // referrer header etc... needed.
  33   //
  34   // If the calling application would like to request services from the target
  35   // application, it should pass a valid interface request in the |services|
  36   // parameter (i.e. one containing a valid message pipe endpoint). If the
  37   // target application does not wish to offer services, it may either not bind
  38   // an implementation to the interface request, or else bind an implementation
  39   // that will reject some or all service requests.
  40   //
  41   // If the calling application would like to offer services to the target
  42   // application, it should pass a bound interface through the
  43   // |exposed_services| parameter. The target application may then request
  44   // services through that interface.
  45   //
  46   // At least one of |services| or |exposed_services| should be valid/bound in
  47   // the call.
  48   //
  49   // If the |application_url| does not contain a domain, but is of the form
  50   // "mojo:{service}", it is up to the Mojo shell to select an appropriate
  51   // application for the service. Currently, the shell does this based on the
  52   // value of its --origin flag.
  53   //
  54   // |filter| is a whitelist of application URLs and services that the target
  55   // application is permitted to connect to. See documentation for
  56   // CapabilityFilter above. Note also that this parameter may be NULL, which
  57   // has the same meaning as allowing the target application to connect to
  58   // any application and service.
  59   ConnectToApplication(URLRequest application_url,
  60                        ServiceProvider&? services,
  61                        ServiceProvider? exposed_services,
  62                        CapabilityFilter? filter);
  63
  64   // When there are no more instantiated services in an application, it should
  65   // start its shutdown process by calling this method. Additionally, it should
  66   // keep track of any new service requests that come in. The shell will then
  67   // call Application::OnQuitRequested and start queueing new service requests.
  68   // If the application didn't get any new service requests in the meantime, it
  69   // should call the callback with a true value. Otherwise it should call it
  70   // with false.
  71   QuitApplication();
  72 };