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