src/xwalk/extensions/common/xwalk_extension.h

   1 // Copyright (c) 2013 Intel Corporation. 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 XWALK_EXTENSIONS_COMMON_XWALK_EXTENSION_H_
   6 #define XWALK_EXTENSIONS_COMMON_XWALK_EXTENSION_H_
   7
   8 #include <string>
   9 #include <vector>
  10 #include "base/callback.h"
  11 #include "base/values.h"
  12
  13 namespace xwalk {
  14 namespace extensions {
  15
  16 // Crosswalk Extensions are used to provide native code functionality associated
  17 // with a JS API. The native side and JS side communicate by exchanging
  18 // messages. The message semantics are up to the extension implementer. The
  19 // architecture allows us to run the native side of the extension in a separated
  20 // process.
  21 //
  22 // In Crosswalk we provide a C API for external extensions implemented separated
  23 // out of Crosswalk binary. Those are loaded when application starts. See
  24 // XWalkExternalExtension for it's implementation and XW_Extension.h for the C
  25 // API.
  26
  27 class XWalkExtensionInstance;
  28
  29 // XWalkExtension is a factory class to be implemented by each extension, and
  30 // used to create extension instance objects. It also holds information valid
  31 // for all the instances, like the JavaScript API. See also
  32 // XWalkExtensionInstance.
  33 class XWalkExtension {
  34  public:
  35   class PermissionsDelegate {
  36    public:
  37     // The delegate is responsible for caching the requests for the sake of
  38     // performance.
  39     virtual bool CheckAPIAccessControl(const std::string& extension_name,
  40         const std::string& api_name);
  41     virtual bool RegisterPermissions(const std::string& extension_name,
  42         const std::string& perm_table);
  43
  44     ~PermissionsDelegate() {}
  45   };
  46
  47   virtual ~XWalkExtension();
  48
  49   virtual XWalkExtensionInstance* CreateInstance() = 0;
  50
  51   std::string name() const { return name_; }
  52   std::string javascript_api() const { return javascript_api_; }
  53
  54   // Returns a list of entry points for which the extension should be loaded
  55   // when accessed. Entry points are used when the extension needs to have
  56   // objects outside the namespace that is implicitly created using its name.
  57   virtual const std::vector<std::string>& entry_points() const;
  58
  59   void set_permissions_delegate(XWalkExtension::PermissionsDelegate* delegate) {
  60     permissions_delegate_ = delegate;
  61   }
  62
  63   bool CheckAPIAccessControl(const char* api_name) const;
  64   bool RegisterPermissions(const char* perm_table) const;
  65
  66  protected:
  67   XWalkExtension();
  68   void set_name(const std::string& name) { name_ = name; }
  69   void set_javascript_api(const std::string& javascript_api) {
  70     javascript_api_ = javascript_api;
  71   }
  72   void set_entry_points(const std::vector<std::string>& entry_points) {
  73     entry_points_.insert(entry_points_.end(), entry_points.begin(),
  74                          entry_points.end());
  75   }
  76
  77  private:
  78   // Name of extension, used for dispatching messages.
  79   std::string name_;
  80
  81   // JavaScript API code that will be executed in the render process. It allows
  82   // the extension provide a function or object based interface on top of the
  83   // message passing.
  84   std::string javascript_api_;
  85
  86   std::vector<std::string> entry_points_;
  87
  88   // Permission check delegate for both in and out of process extensions.
  89   PermissionsDelegate* permissions_delegate_;
  90
  91   DISALLOW_COPY_AND_ASSIGN(XWalkExtension);
  92 };
  93
  94 // XWalkExtensionInstance represents an instance of a certain extension, which
  95 // is created per ScriptContext created by Crosswalk (which happens for every
  96 // frame loaded).
  97 //
  98 // XWalkExtensionInstance objects allow us to keep separated state for each
  99 // execution.
 100 class XWalkExtensionInstance {
 101  public:
 102   virtual ~XWalkExtensionInstance();
 103
 104   // Allow to handle messages sent from JavaScript code running in renderer
 105   // process.
 106   virtual void HandleMessage(scoped_ptr<base::Value> msg) = 0;
 107
 108   // Allow to handle synchronous messages sent from JavaScript code. Renderer
 109   // will block until SendSyncReplyToJS() is called with the reply. The reply
 110   // can be sent after HandleSyncMessage() function returns.
 111   virtual void HandleSyncMessage(scoped_ptr<base::Value> msg);
 112
 113   // Callbacks used by extension instance to communicate back to JS. These are
 114   // set by the extension system. Callbacks will take the ownership of the
 115   // message.
 116   typedef base::Callback<void(scoped_ptr<base::Value> msg)> PostMessageCallback;
 117   typedef base::Callback<void(scoped_ptr<base::Value> msg)>
 118       SendSyncReplyCallback;
 119
 120   void SetPostMessageCallback(const PostMessageCallback& callback);
 121   void SetSendSyncReplyCallback(const SendSyncReplyCallback& callback);
 122
 123   // Function to be used by extensions Instances to post messages back to
 124   // JavaScript in the renderer process. This function will take the ownership
 125   // of the message.
 126   void PostMessageToJS(scoped_ptr<base::Value> msg) {
 127     post_message_.Run(msg.Pass());
 128   }
 129
 130  protected:
 131   XWalkExtensionInstance();
 132
 133   // Unblocks the renderer waiting on a SyncMessage.
 134   void SendSyncReplyToJS(scoped_ptr<base::Value> reply) {
 135     send_sync_reply_.Run(reply.Pass());
 136   }
 137
 138  private:
 139   PostMessageCallback post_message_;
 140   SendSyncReplyCallback send_sync_reply_;
 141
 142   DISALLOW_COPY_AND_ASSIGN(XWalkExtensionInstance);
 143 };
 144
 145 }  // namespace extensions
 146 }  // namespace xwalk
 147
 148 #endif  // XWALK_EXTENSIONS_COMMON_XWALK_EXTENSION_H_