src/extension/xwalk/XW_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_PUBLIC_XW_EXTENSION_H_
   6 #define XWALK_EXTENSIONS_PUBLIC_XW_EXTENSION_H_
   7
   8 // Crosswalk Extensions are modules of code loaded by Crosswalk runtime that
   9 // allow extending its capabilities. The extension is expected to define a
  10 // XW_Initialize() function as declared below, get the interfaces it need to
  11 // use and register to whatever callbacks it needs, then return XW_OK.
  12 //
  13 // The Extension is represented by the type XW_Extension. Each extension
  14 // loaded may be used multiple times for different pages, so to each execution
  15 // there will be an associated XW_Instance. A reasonable analogy is that the
  16 // XW_Extension represent a "class", and have concrete instances running.
  17 //
  18 // An interface is a struct with a set of functions, provided by Crosswalk,
  19 // that allow the extension code to interact with the web content. Certain
  20 // functions in an interface are used to register callbacks, so that Crosswalk
  21 // can call the extension at specific situations.
  22 //
  23 // Crosswalk won't call an extension's XW_Initialize() multiple times in the
  24 // same process.
  25
  26 #ifdef __cplusplus
  27 extern "C" {
  28 #endif
  29
  30 #if __GNUC__ >= 4
  31 #define XW_EXPORT __attribute__ ((visibility("default")))
  32 #elif defined(_MSC_VER)
  33 #define XW_EXPORT __declspec(dllexport)
  34 #endif
  35
  36 #include <stdint.h>
  37
  38
  39 // XW_Extension is used to identify your extension when calling functions from
  40 // the API. You should always use the XW_Extension received at XW_Initialize().
  41 //
  42 // XW_Instance is used to identify different web contents using your
  43 // extension. Each time a new web content is created you can be notified
  44 // registering the XW_CreatedInstanceCallback, that receives the new
  45 // XW_Instance. When interacting with an Instance (for example to post a
  46 // message), you should pass the corresponding XW_Instance.
  47 //
  48 // In both types the zero value is never used by Crosswalk, so can be used to
  49 // initialize variables.
  50 typedef int32_t XW_Extension;
  51 typedef int32_t XW_Instance;
  52
  53 enum {
  54   XW_OK = 0,
  55   XW_ERROR = -1
  56 };
  57
  58 // Returns a struct containing functions to be used by the extension. Those
  59 // structs can be stored statically and used until the extension is unloaded.
  60 // Extensions should use definitions like XW_CORE_INTERFACE, instead of using
  61 // the versioned definition or the literal string. Returns NULL if the
  62 // interface is not supported.
  63 typedef const void* (*XW_GetInterface)(const char* interface_name);
  64
  65
  66 typedef int32_t (*XW_Initialize_Func)(XW_Extension extension,
  67                                       XW_GetInterface get_interface);
  68
  69 // XW_Initialize is called after the extension code is loaded. The 'extension'
  70 // value should be used in further calls that expect XW_Extension argument.
  71 //
  72 // The 'get_interface' function should be used to get access to functions that
  73 // interact with the web content. It is only valid during the execution of the
  74 // XW_Initialize() function.
  75 //
  76 // This function should return XW_OK when the extension was succesfully
  77 // loaded, otherwise XW_ERROR.
  78 XW_EXPORT int32_t XW_Initialize(XW_Extension extension,
  79                                 XW_GetInterface get_interface);
  80
  81
  82 //
  83 // XW_CORE_INTERFACE: Basic functionality for Crosswalk Extensions. All
  84 // extensions should use this interface to set at least their name.
  85 //
  86
  87 #define XW_CORE_INTERFACE_1 "XW_CoreInterface_1"
  88 #define XW_CORE_INTERFACE XW_CORE_INTERFACE_1
  89
  90 typedef void (*XW_CreatedInstanceCallback)(XW_Instance instance);
  91 typedef void (*XW_DestroyedInstanceCallback)(XW_Instance instance);
  92 typedef void (*XW_ShutdownCallback)(XW_Extension extension);
  93
  94 struct XW_CoreInterface_1 {
  95   // Set the name of the extension. It is used as the namespace for the
  96   // JavaScript code exposed by the extension. So extension named
  97   // 'my_extension', will expose its JavaScript functionality inside
  98   // the 'my_extension' namespace.
  99   //
 100   // This function should be called only during XW_Initialize().
 101   void (*SetExtensionName)(XW_Extension extension, const char* name);
 102
 103   // Set the JavaScript code loaded in the web content when the extension is
 104   // used. This can be used together with the messaging mechanism to implement
 105   // a higher-level API that posts messages to extensions, see
 106   // XW_MESSAGING_INTERFACE below.
 107   //
 108   // The code will be executed inside a JS function context with the following
 109   // objects available:
 110   //
 111   // - exports: this object should be filled with properties and functions
 112   //            that will be exposed in the namespace associated with this
 113   //            extension.
 114   //
 115   // - extension.postMessage(): post a string message to the extension native
 116   //                            code. See below for details.
 117   // - extension.setMessageListener(): allow setting a callback that is called
 118   //                                   when the native code sends a message
 119   //                                   to JavaScript. Callback takes a string.
 120   //
 121   // This function should be called only during XW_Initialize().
 122   void (*SetJavaScriptAPI)(XW_Extension extension, const char* api);
 123
 124   // Register callbacks that are called when an instance of this extension
 125   // is created or destroyed. Everytime a new web content is loaded, it will
 126   // get a new associated instance.
 127   //
 128   // This function should be called only during XW_Initialize().
 129   void (*RegisterInstanceCallbacks)(XW_Extension extension,
 130                                     XW_CreatedInstanceCallback created,
 131                                     XW_DestroyedInstanceCallback destroyed);
 132
 133   // Register a callback to be executed when the extension will be unloaded.
 134   //
 135   // This function should be called only during XW_Initialize().
 136   void (*RegisterShutdownCallback)(XW_Extension extension,
 137                                    XW_ShutdownCallback shutdown_callback);
 138
 139   // These two functions are conveniences used to associated arbitrary data
 140   // with a given XW_Instance. They can be used only with instances that were
 141   // created but not yet completely destroyed. GetInstanceData() can be used
 142   // during the destroyed instance callback. If not instance data was set,
 143   // getting it returns NULL.
 144   void (*SetInstanceData)(XW_Instance instance, void* data);
 145   void* (*GetInstanceData)(XW_Instance instance);
 146 };
 147
 148 typedef struct XW_CoreInterface_1 XW_CoreInterface;
 149
 150
 151 //
 152 // XW_MESSAGING_INTERFACE: Exchange asynchronous messages with JavaScript
 153 // code provided by extension.
 154 //
 155
 156 #define XW_MESSAGING_INTERFACE_1 "XW_MessagingInterface_1"
 157 #define XW_MESSAGING_INTERFACE XW_MESSAGING_INTERFACE_1
 158
 159 typedef void (*XW_HandleMessageCallback)(XW_Instance instance,
 160                                          const char* message);
 161
 162 struct XW_MessagingInterface_1 {
 163   // Register a callback to be called when the JavaScript code associated
 164   // with the extension posts a message. Note that the callback will be called
 165   // with the XW_Instance that posted the message as well as the message
 166   // contents.
 167   void (*Register)(XW_Extension extension,
 168                    XW_HandleMessageCallback handle_message);
 169
 170   // Post a message to the web content associated with the instance. To
 171   // receive this message the extension's JavaScript code should set a
 172   // listener using extension.setMessageListener() function.
 173   //
 174   // This function is thread-safe and can be called until the instance is
 175   // destroyed.
 176   void (*PostMessage)(XW_Instance instance, const char* message);
 177 };
 178
 179 typedef struct XW_MessagingInterface_1 XW_MessagingInterface;
 180
 181 #ifdef __cplusplus
 182 }  // extern "C"
 183 #endif
 184
 185 #endif  // XWALK_EXTENSIONS_PUBLIC_XW_EXTENSION_H_