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