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 base::ListValue& 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_.AppendStrings(entry_points);
  74   }
  75
  76  private:
  77   // Name of extension, used for dispatching messages.
  78   std::string name_;
  79
  80   // JavaScript API code that will be executed in the render process. It allows
  81   // the extension provide a function or object based interface on top of the
  82   // message passing.
  83   std::string javascript_api_;
  84
  85   // FIXME(jeez): convert this to std::vector<std::string> to avoid
  86   // extra conversions later on.
  87   base::ListValue entry_points_;
  88
  89   // Permission check delegate for both in and out of process extensions.
  90   PermissionsDelegate* permissions_delegate_;
  91
  92   DISALLOW_COPY_AND_ASSIGN(XWalkExtension);
  93 };
  94
  95 // XWalkExtensionInstance represents an instance of a certain extension, which
  96 // is created per ScriptContext created by Crosswalk (which happens for every
  97 // frame loaded).
  98 //
  99 // XWalkExtensionInstance objects allow us to keep separated state for each
 100 // execution.
 101 class XWalkExtensionInstance {
 102  public:
 103   virtual ~XWalkExtensionInstance();
 104
 105   // Allow to handle messages sent from JavaScript code running in renderer
 106   // process.
 107   virtual void HandleMessage(scoped_ptr<base::Value> msg) = 0;
 108
 109   // Allow to handle synchronous messages sent from JavaScript code. Renderer
 110   // will block until SendSyncReplyToJS() is called with the reply. The reply
 111   // can be sent after HandleSyncMessage() function returns.
 112   virtual void HandleSyncMessage(scoped_ptr<base::Value> msg);
 113
 114   // Callbacks used by extension instance to communicate back to JS. These are
 115   // set by the extension system. Callbacks will take the ownership of the
 116   // message.
 117   typedef base::Callback<void(scoped_ptr<base::Value> msg)> PostMessageCallback;
 118   typedef base::Callback<void(scoped_ptr<base::Value> msg)>
 119       SendSyncReplyCallback;
 120
 121   void SetPostMessageCallback(const PostMessageCallback& callback);
 122   void SetSendSyncReplyCallback(const SendSyncReplyCallback& callback);
 123
 124   // Function to be used by extensions Instances to post messages back to
 125   // JavaScript in the renderer process. This function will take the ownership
 126   // of the message.
 127   void PostMessageToJS(scoped_ptr<base::Value> msg) {
 128     post_message_.Run(msg.Pass());
 129   }
 130
 131  protected:
 132   XWalkExtensionInstance();
 133
 134   // Unblocks the renderer waiting on a SyncMessage.
 135   void SendSyncReplyToJS(scoped_ptr<base::Value> reply) {
 136     send_sync_reply_.Run(reply.Pass());
 137   }
 138
 139  private:
 140   PostMessageCallback post_message_;
 141   SendSyncReplyCallback send_sync_reply_;
 142
 143   DISALLOW_COPY_AND_ASSIGN(XWalkExtensionInstance);
 144 };
 145
 146 }  // namespace extensions
 147 }  // namespace xwalk
 148
 149 #endif  // XWALK_EXTENSIONS_COMMON_XWALK_EXTENSION_H_