diff options
Diffstat (limited to 'nsplugins/README')
| -rw-r--r-- | nsplugins/README | 255 |
1 files changed, 255 insertions, 0 deletions
diff --git a/nsplugins/README b/nsplugins/README new file mode 100644 index 000000000..5b45594ab --- /dev/null +++ b/nsplugins/README @@ -0,0 +1,255 @@ +nsplugins +========= + +The 'nsplugins' directory contains various tools used to utilize Netscape(R) +browser plugins in KDE applications. + + - ./ - common headers and utilities + + - viewer/ - provides means to embed a Netscape(R) browser plugin + into a KDE application. + + - sdk/ - headers from the Netscape(R) browser plugin SDK. + + - control/ - KDE Control Center applet for managing plugins + + - test/ - simple applications to test nsplugin + + - wrapper/ - currently unused. + + +At the time of writing, nsplugins supports Navigator 4 API plugins +and doesn't support new Mozilla XPCOM components. + +Parts +===== + +The Netscape(R) browser plugin support consists of 3 parts: +- "PluginPart" KPart which is embedded into KHTML pages + (alone, it looks no different than a gray rectangle) +- "nspluginviewer", a separate application which is capable of + actually loading and playing the various Netscape(R) plugins. +- "pluginscan", a small utility to scan predefined directories + for Netscape(R) browser plugins. + +PluginPart's responsibility is to run "nspluginviewer" and instruct +it to display the plugin inside its' rectangle. + +* KParts is KDE's standard for embeddable objects, much like + Microsoft's OLE. + +PluginPart / nspluginviewer separation +====================================== + +Plugins contain 3rd-party code which might crash if badly written +(especially inside our "Netscape emulation" environment). +The PluginPart runs inside the memory space of the embedding application, +making the embedding application susceptible to a crash in the PluginPart. +In our case, the "embedding application" would be the browser, and having +the whole browser shut down just because some plugin crashed is bad. +By loading and talking to the plugin is a separate process +("nspluginviewer"), we prevent such crashes from taking +the browser down with them -- the worst that could happen +is the plugin suddenly disappearing from the page, revealing +PluginPart's gray background. + +nspluginviewer to PluginPart communications +=========================================== + +The communications between the PluginPart and nspluginviewer +are done via DCOP. Messages which nspluginviewer could send +to PluginPart include: +- requestURL(url, target) - make the browser load a URL +- statusMessage(msg) - change the status bar in the + embedding application + +(For an updated list of messages, see NSPluginCallbackIface.h) + +When received, those messages are mapped to functions in +NSPluginCallback, which in turn calls PluginPart functions. + +* DCOP is KDE's standard for RPC, typically used by local + processes to pass messages. + +PluginPart to nspluginviewer communications +=========================================== + +nspluginviewer's window is, all in all, a simple X11 window, +it can be resized, focused and unfocused with standard X11 functions +as long as we know its' window ID. + +PluginPart gets a NSPluginInstance (from NSPluginLoader::newInstance), +which it sees as a regular QWidget. e.g. it can resize the QWidget and +nspluginviewer's window will resize. + +This magic happens thanks to KJavaEmbed which NSPluginInstance inherits. +KJavaEmbed inherits QWidget and hooks up to QWidget's events, mapping +those events to the appropriate X11 window operations. +Resizing, focusing in and out is about all PluginPart could ever do +with the nspluginviewer. + +How does KJavaEmbed know the window ID of the nspluginviewer window? +NSPluginInstance retrieves it from nspluginviewer with a DCOP call +("int winId()") and gives it to KJavaEmbed. + +Main classes +============ + +- PluginPart class (plugin_part.h, plugin_part.cpp) + + A KParts::ReadOnlyPart. + +- PluginFactory class (plugin_part.h, plugin_part.cpp) + + Creates PluginPart objects. + +- NSPluginInstance class (nspluginloader.h, nspluginloader.cpp) + + PluginPart's "looking glass" to "nspluginviewer". + +- NSPluginLoader class (nspluginloader.h, nspluginloader.cpp) + + Responsible for starting a new independant process of the + plugin viewer and initiating DCOP communications with it. + +- NSPluginCallbackIface (NSPluginCallbackIface.h) + + Defines functions which the nspluginviewer can call in the PluginPart. + Those function calls would be transfered over DCOP and implemented + in PluginPart's NSPluginCallback class. + + +Plugin Scanner +============== + +Implemented in: pluginscan.cpp + +Utility which scans for Netscape(R) browser plugins in pre-defined +directories (according to KDE's configuration) and writes down +information about the located plugins into the plugin information +cache. To locate all the plugins, it doesn't limit itself to files +with .so extension. A forking mechanism is implemented to prevent +faulty .so's from crashing the scanning process. + +This utility is usually not invoked standalone, but used by the +KDE Control Center applet which invokes it on: +- explicit request (ie. pressing "Scan for new plugins" button) +- KDE startup (in the applet's initialization code) +- first time the applet is ran + + +Viewer +====== + +Implemented in: viewer/ + +The viewer is a KDE component used to embed Netscape(R) plugins +into KDE applications (such as KHTML / Konqueror). To the plugin, it +emulates a Netscape(R) browser, while outside - it offers a standard KParts +object. + +NSPluginCallbackIface.h + + Defines functions which the nspluginviewer can call in the PluginPart. + Those function calls would be transfered over DCOP and implemented + in PluginPart's NSPluginCallback class. + +kxt.h, kxt.cpp + + ... + +resolve.h + + Some macros to resolve symbols. + +nsplugin.h, nsplugin.cpp + + The implementation of the interface between KDE and the Netscape(R) + browser plugin as a KParts object. + + Note: This file implements its own NSPluginInstance, which should + not be confused with PluginPart's NSPluginInstance. + + It implements: + - The Netscape(R) emulation side: + g_NPN_* functions, which implement Netscape(R) browser + plugin API NPN_* C methods accordingly. Our emulation + of a Netscape(R) browser is as good as those functions are. + + By definition, all functions are passed with an NPN ("plugin + instance") struct, and each NPN has an 'ndata' pointer member. + That's good news to us, since we now can use it to point to + our NSPluginInstance object. + + Those functions contain the minimum necessary code to + call the NSPluginInstance function for the requested operation + + - The KDE side: + NSPluginInstance implements functions for various g_NPN_* + operations. Typically those operations will be passed via DCOP + to the PluginPart -- e.g. a operation which changes the window's + status bar. + +viewer.cpp + + A standalone application that executes Netscape plugins. + +Control Center applet +===================== + +The Control Center applet allows the user to: +- Add additional directories which "pluginscan" would scan for + Netscape(R) plugins. +- See which plugins "pluginscan" found (by reading the plugin cache). +- Force a "pluginscan" rescan. + +The KDE Control Center API is well documented in the KDE SDK. + +Compatibility notes +=================== + +Although nsplugins strive for full compatibility with the Netscape(R) +browser plugin execution environment, it still lacks the following features: + +- LiveConnect (Netscape Navigator 3.0) Java / JavaScript connectivity + + Support for LiveConnect (for JavaScript support) requires: + - Reimplementation of Netscape's JRI functions (see sdk/jri.h) + to communicate back (via DCOP?) with the PluginPart, which'll + signal them to KHTML's KJS interpretor. KParts::BrowserExtension + should be extended to support those signals. Of course, only + JRI calls in the "netscape.javascript" namespace should be handled. + - Implementation of g_NPN_GetJavaEnv and g_NPN_GetJavaPeer + (currently they're empty placeholders). + - Implementing g_NPN_GetValue(NPNVjavascriptEnabledBool, ...) + (currently always returns "false"). + Should involve adding a slot to KParts::BrowserExtension + and making KHTML signal it whenever JS gets enabled or disabled. + + LiveConnect will probably never be supported due to JRE ABI issues, and + the fact that we need to have a JRE with JNI inside the nspluginviewer. + LiveConnect is almost obsolete as well. XPConnect will not be integrated + either. + +The current support is enough to run common plugins such as Macromedia(R) +Flash(R) and RealPlayer(R), but some of their functionality might be missing. +For instance, Flash(R) animations cannot call user-defined JavaScript +routines nor can the user control the Flash(R) animation via JavaScript. + +Additional documentation +======================== + +Additional documentation on the Netscape(R) plugin API is available at: + +- http://developer.netscape.com/docs/manuals/plugins.html +- http://www.mozilla.org/docs/plugin.html + +Author +====== + +This README was authored Ilya Konstantinov <kde-devel@future.shiny.co.il>. +Thanks go to Matthias Hoelzer-Kluepfel and Stefan Schimanski for writing +the actual code and making it all possible. + +Present maintainer of the nsplugin code is George Staikos <staikos@kde.org> + |