apps/nsplugins/README

   1 nsplugins
   2 =========
   3
   4 The 'nsplugins' directory contains various tools used to utilize Netscape(R)
   5 browser plugins in KDE applications.
   6
   7  - ./       - common headers and utilities
   8
   9  - viewer/  - provides means to embed a Netscape(R) browser plugin
  10               into a KDE application.
  11
  12  - sdk/     - headers from the Netscape(R) browser plugin SDK.
  13
  14  - control/ - KDE Control Center applet for managing plugins
  15
  16  - test/    - simple applications to test nsplugin
  17
  18  - wrapper/ - currently unused.
  19
  20
  21 At the time of writing, nsplugins supports Navigator 4 API plugins
  22 and doesn't support new Mozilla XPCOM components.
  23
  24 Parts
  25 =====
  26
  27 The Netscape(R) browser plugin support consists of 3 parts:
  28 - "PluginPart" KPart which is embedded into KHTML pages
  29   (alone, it looks no different than a gray rectangle)
  30 - "nspluginviewer", a separate application which is capable of
  31   actually loading and playing the various Netscape(R) plugins.
  32 - "pluginscan", a small utility to scan predefined directories
  33   for Netscape(R) browser plugins.
  34
  35 PluginPart's responsibility is to run "nspluginviewer" and instruct
  36 it to display the plugin inside its' rectangle.
  37
  38 * KParts is KDE's standard for embeddable objects, much like
  39   Microsoft's OLE.
  40
  41 PluginPart / nspluginviewer separation
  42 ======================================
  43
  44 Plugins contain 3rd-party code which might crash if badly written
  45 (especially inside our "Netscape emulation" environment).
  46 The PluginPart runs inside the memory space of the embedding application,
  47 making the embedding application susceptible to a crash in the PluginPart.
  48 In our case, the "embedding application" would be the browser, and having
  49 the whole browser shut down just because some plugin crashed is bad.
  50 By loading and talking to the plugin is a separate process
  51 ("nspluginviewer"), we prevent such crashes from taking
  52 the browser down with them -- the worst that could happen
  53 is the plugin suddenly disappearing from the page, revealing
  54 PluginPart's gray background.
  55
  56 nspluginviewer to PluginPart communications
  57 ===========================================
  58
  59 The communications between the PluginPart and nspluginviewer
  60 are done via DCOP. Messages which nspluginviewer could send
  61 to PluginPart include:
  62 - requestURL(url, target) - make the browser load a URL
  63 - statusMessage(msg)      - change the status bar in the
  64                             embedding application
  65
  66 (For an updated list of messages, see NSPluginCallbackIface.h)
  67
  68 When received, those messages are mapped to functions in
  69 NSPluginCallback, which in turn calls PluginPart functions.
  70
  71 * DCOP is KDE's standard for RPC, typically used by local
  72   processes to pass messages.
  73
  74 PluginPart to nspluginviewer communications
  75 ===========================================
  76
  77 nspluginviewer's window is, all in all, a simple X11 window,
  78 it can be resized, focused and unfocused with standard X11 functions
  79 as long as we know its' window ID.
  80
  81 PluginPart gets a NSPluginInstance (from NSPluginLoader::newInstance),
  82 which it sees as a regular QWidget. e.g. it can resize the QWidget and
  83 nspluginviewer's window will resize.
  84
  85 This magic happens thanks to KJavaEmbed which NSPluginInstance inherits.
  86 KJavaEmbed inherits QWidget and hooks up to QWidget's events, mapping
  87 those events to the appropriate X11 window operations.
  88 Resizing, focusing in and out is about all PluginPart could ever do
  89 with the nspluginviewer.
  90
  91 How does KJavaEmbed know the window ID of the nspluginviewer window?
  92 NSPluginInstance retrieves it from nspluginviewer with a DCOP call
  93 ("int winId()") and gives it to KJavaEmbed.
  94
  95 Main classes
  96 ============
  97
  98 - PluginPart class (plugin_part.h, plugin_part.cpp)
  99
 100   A KParts::ReadOnlyPart.
 101
 102 - PluginFactory class (plugin_part.h, plugin_part.cpp)
 103
 104   Creates PluginPart objects.
 105
 106 - NSPluginInstance class (nspluginloader.h, nspluginloader.cpp)
 107
 108   PluginPart's "looking glass" to "nspluginviewer".
 109
 110 - NSPluginLoader class (nspluginloader.h, nspluginloader.cpp)
 111
 112   Responsible for starting a new independant process of the
 113   plugin viewer and initiating DCOP communications with it.
 114
 115 - NSPluginCallbackIface (NSPluginCallbackIface.h)
 116
 117   Defines functions which the nspluginviewer can call in the PluginPart.
 118   Those function calls would be transfered over DCOP and implemented
 119   in PluginPart's NSPluginCallback class.
 120
 121
 122 Plugin Scanner
 123 ==============
 124
 125 Implemented in: pluginscan.cpp
 126
 127 Utility which scans for Netscape(R) browser plugins in pre-defined
 128 directories (according to KDE's configuration) and writes down
 129 information about the located plugins into the plugin information
 130 cache. To locate all the plugins, it doesn't limit itself to files
 131 with .so extension. A forking mechanism is implemented to prevent
 132 faulty .so's from crashing the scanning process.
 133
 134 This utility is usually not invoked standalone, but used by the
 135 KDE Control Center applet which invokes it on:
 136 - explicit request (ie. pressing "Scan for new plugins" button)
 137 - KDE startup (in the applet's initialization code)
 138 - first time the applet is ran
 139
 140
 141 Viewer
 142 ======
 143
 144 Implemented in: viewer/
 145
 146 The viewer is a KDE component used to embed Netscape(R) plugins
 147 into KDE applications (such as KHTML / Konqueror). To the plugin, it
 148 emulates a Netscape(R) browser, while outside - it offers a standard KParts
 149 object.
 150
 151 NSPluginCallbackIface.h
 152
 153   Defines functions which the nspluginviewer can call in the PluginPart.
 154   Those function calls would be transfered over DCOP and implemented
 155   in PluginPart's NSPluginCallback class.
 156
 157 kxt.h, kxt.cpp
 158
 159   ...
 160
 161 resolve.h
 162
 163   Some macros to resolve symbols.
 164
 165 nsplugin.h, nsplugin.cpp
 166
 167   The implementation of the interface between KDE and the Netscape(R)
 168   browser plugin as a KParts object.
 169
 170   Note: This file implements its own NSPluginInstance, which should
 171   not be confused with PluginPart's NSPluginInstance.
 172
 173   It implements:
 174   - The Netscape(R) emulation side:
 175     g_NPN_* functions, which implement Netscape(R) browser
 176     plugin API NPN_* C methods accordingly. Our emulation
 177     of a Netscape(R) browser is as good as those functions are.
 178
 179     By definition, all functions are passed with an NPN ("plugin
 180     instance") struct, and each NPN has an 'ndata'  pointer member.
 181     That's good news to us, since we now can use it to point to
 182     our NSPluginInstance object.
 183
 184     Those functions contain the minimum necessary code to
 185     call the NSPluginInstance function for the requested operation
 186
 187   - The KDE side:
 188     NSPluginInstance implements functions for various g_NPN_*
 189     operations. Typically those operations will be passed via DCOP
 190     to the PluginPart -- e.g. a operation which changes the window's
 191     status bar.
 192
 193 viewer.cpp
 194
 195   A standalone application that executes Netscape plugins.
 196
 197 Control Center applet
 198 =====================
 199
 200 The Control Center applet allows the user to:
 201 - Add additional directories which "pluginscan" would scan for
 202   Netscape(R) plugins.
 203 - See which plugins "pluginscan" found (by reading the plugin cache).
 204 - Force a "pluginscan" rescan.
 205
 206 The KDE Control Center API is well documented in the KDE SDK.
 207
 208 Compatibility notes
 209 ===================
 210
 211 Although nsplugins strive for full compatibility with the Netscape(R)
 212 browser plugin execution environment, it still lacks the following features:
 213
 214 - LiveConnect (Netscape Navigator 3.0) Java / JavaScript connectivity
 215
 216   Support for LiveConnect (for JavaScript support) requires:
 217   - Reimplementation of Netscape's JRI functions (see sdk/jri.h)
 218     to communicate back (via DCOP?) with the PluginPart, which'll
 219     signal them to KHTML's KJS interpretor. KParts::BrowserExtension
 220     should be extended to support those signals. Of course, only
 221     JRI calls in the "netscape.javascript" namespace should be handled.
 222   - Implementation of g_NPN_GetJavaEnv and g_NPN_GetJavaPeer
 223     (currently they're empty placeholders).
 224   - Implementing g_NPN_GetValue(NPNVjavascriptEnabledBool, ...)
 225     (currently always returns "false").
 226     Should involve adding a slot to KParts::BrowserExtension
 227     and making KHTML signal it whenever JS gets enabled or disabled.
 228
 229   LiveConnect will probably never be supported due to JRE ABI issues, and
 230   the fact that we need to have a JRE with JNI inside the nspluginviewer.
 231   LiveConnect is almost obsolete as well.  XPConnect will not be integrated
 232   either.
 233
 234 The current support is enough to run common plugins such as Macromedia(R)
 235 Flash(R) and RealPlayer(R), but some of their functionality might be missing.
 236 For instance, Flash(R) animations cannot call user-defined JavaScript
 237 routines nor can the user control the Flash(R) animation via JavaScript.
 238
 239 Additional documentation
 240 ========================
 241
 242 Additional documentation on the Netscape(R) plugin API is available at:
 243
 244 - http://developer.netscape.com/docs/manuals/plugins.html
 245 - http://www.mozilla.org/docs/plugin.html
 246
 247 Author
 248 ======
 249
 250 This README was authored Ilya Konstantinov <kde-devel@future.shiny.co.il>.
 251 Thanks go to Matthias Hoelzer-Kluepfel and Stefan Schimanski for writing
 252 the actual code and making it all possible.
 253
 254 Present maintainer of the nsplugin code is George Staikos <staikos@kde.org>
 255