mojo/application/public/cpp/application_connection.h

   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 #ifndef MOJO_APPLICATION_PUBLIC_CPP_APPLICATION_CONNECTION_H_
   6 #define MOJO_APPLICATION_PUBLIC_CPP_APPLICATION_CONNECTION_H_
   7
   8 #include <string>
   9
  10 #include "mojo/application/public/cpp/lib/interface_factory_connector.h"
  11 #include "mojo/application/public/interfaces/service_provider.mojom.h"
  12
  13 namespace mojo {
  14
  15 class ServiceConnector;
  16
  17 // Represents a connection to another application. An instance of this class is
  18 // passed to ApplicationDelegate's ConfigureIncomingConnection() method each
  19 // time a connection is made to this app, and to ApplicationDelegate's
  20 // ConfigureOutgoingConnection() method when the app connects to another.
  21 //
  22 // To use, define a class that implements your specific service API (e.g.,
  23 // FooImpl to implement a service named Foo). Then implement an
  24 // InterfaceFactory<Foo> that binds instances of FooImpl to
  25 // InterfaceRequest<Foo>s and register that on the connection like this:
  26 //
  27 //   connection->AddService(&factory);
  28 //
  29 // Or, if you have multiple factories implemented by the same type, explicitly
  30 // specify the interface to register the factory for:
  31 //
  32 //   connection->AddService<Foo>(&my_foo_and_bar_factory_);
  33 //   connection->AddService<Bar>(&my_foo_and_bar_factory_);
  34 //
  35 // The InterfaceFactory must outlive the ApplicationConnection.
  36 //
  37 // Additionally you specify a ServiceConnector. If a ServiceConnector has
  38 // been set and an InterfaceFactory has not been registered for the interface
  39 // request, than the interface request is sent to the ServiceConnector.
  40 //
  41 // Just as with InterfaceFactory, ServiceConnector must outlive
  42 // ApplicationConnection.
  43 //
  44 // An ApplicationConnection's lifetime is managed by an ApplicationImpl. To
  45 // close a connection, call CloseConnection which will destroy this object.
  46 class ApplicationConnection {
  47  public:
  48   ApplicationConnection();
  49
  50   // Closes the connection and destroys this object. This is the only valid way
  51   // to destroy this object.
  52   void CloseConnection();
  53
  54   // See class description for details.
  55   virtual void SetServiceConnector(ServiceConnector* connector) = 0;
  56
  57   // Makes Interface available as a service to the remote application.
  58   // |factory| will create implementations of Interface on demand.
  59   // Returns true if the service was exposed, false if capability filtering
  60   // from the shell prevented the service from being exposed.
  61   template <typename Interface>
  62   bool AddService(InterfaceFactory<Interface>* factory) {
  63     return SetServiceConnectorForName(
  64         new internal::InterfaceFactoryConnector<Interface>(factory),
  65         Interface::Name_);
  66   }
  67
  68   // Binds |ptr| to an implemention of Interface in the remote application.
  69   // |ptr| can immediately be used to start sending requests to the remote
  70   // service.
  71   template <typename Interface>
  72   void ConnectToService(InterfacePtr<Interface>* ptr) {
  73     if (ServiceProvider* sp = GetServiceProvider()) {
  74       MessagePipe pipe;
  75       ptr->Bind(InterfacePtrInfo<Interface>(pipe.handle0.Pass(), 0u));
  76       sp->ConnectToService(Interface::Name_, pipe.handle1.Pass());
  77     }
  78   }
  79
  80   // Returns the URL that was used by the source application to establish a
  81   // connection to the destination application.
  82   //
  83   // When ApplicationConnection is representing an incoming connection this can
  84   // be different than the URL the application was initially loaded from, if the
  85   // application handles multiple URLs. Note that this is the URL after all
  86   // URL rewriting and HTTP redirects have been performed.
  87   //
  88   // When ApplicationConnection is representing and outgoing connection, this
  89   // will be the same as the value returned by GetRemoveApplicationURL().
  90   virtual const std::string& GetConnectionURL() = 0;
  91
  92   // Returns the URL identifying the remote application on this connection.
  93   virtual const std::string& GetRemoteApplicationURL() = 0;
  94
  95   // Returns the raw proxy to the remote application's ServiceProvider
  96   // interface. Most applications will just use ConnectToService() instead.
  97   // Caller does not take ownership.
  98   virtual ServiceProvider* GetServiceProvider() = 0;
  99
 100   // Returns the local application's ServiceProvider interface. The return
 101   // value is owned by this connection.
 102   virtual ServiceProvider* GetLocalServiceProvider() = 0;
 103
 104   // Register a handler to receive an error notification on the pipe to the
 105   // remote application's service provider.
 106   virtual void SetRemoteServiceProviderConnectionErrorHandler(
 107       const Closure& handler) = 0;
 108
 109  protected:
 110   virtual ~ApplicationConnection();
 111
 112   // Called to give the derived type to perform some cleanup before destruction.
 113   virtual void OnCloseConnection() = 0;
 114
 115  private:
 116   // Returns true if the connector was set, false if it was not set (e.g. by
 117   // some filtering policy preventing this interface from being exposed).
 118   virtual bool SetServiceConnectorForName(ServiceConnector* service_connector,
 119                                           const std::string& name) = 0;
 120
 121   // Ensures that CloseConnection can only be called once and the
 122   // ApplicationConnection's destructor can only be called after the connection
 123   // is closed.
 124   bool connection_closed_;
 125 };
 126
 127 }  // namespace mojo
 128
 129 #endif  // MOJO_APPLICATION_PUBLIC_CPP_APPLICATION_CONNECTION_H_