Introduction to OJI Internals

Purpose of this Document

This document is an introduction to the topic of what Mozilla requires of an OJI plugin. It is assumed the reader already knows what OJI is, and wants to know how to start writing an OJI plugin for Mozilla.
• What You Need to Implement
• Sample Implementation Framework

What You Need to Implement

You must implement four functions in your oji plugin dll, in addition to all the classes that comprise the OJI and plugin interfaces, listed below.
• Shared Library Functions
• Classes

Shared Library Functions

An OJI plugin is a Mozilla plugin that also happens to implement the required OJI interfaces. Like all Mozilla plugins, the entry points from Mozilla to your plugin must be in a shared library with a filename starting with np, as in npoji.dll. This shared library must be in the plugins directory, which is currently mozilla/dist/[WIN32*/]bin/plugins. Your OJI shared library should implement and export the following functions (which are really mozilla's component auto registration functions):

• 
  extern "C" nsresult NSGetFactory(nsISupports *pProvider, 
  				 const nsCID &clsid, 
                                   const char *aClassName,
                                   const char *aProgID,		         
  			         nsIFactory **ppFactory);
  	

  • nsISupports *pProvider
    This points to the current nsIServiceManager.

  • const nsCID %clsid
    This is kPluginCID, from static NS_DEFINE_CID(kPluginCID, NS_PLUGIN_CID);

  • const char *aClass
    This value ends up being null, when mozilla calls NSGetFactory for your OJI plugin.

  • const char *progID
    This value ends up being null, when mozilla calls NSGetFactory for your OJI plugin.

  • nsIFactory **ppFactory
    Where you store the return value, which must be an instance of nsIPlugin.

  This function happens to get called when LiveConnect is started. It is your opportunity to return an instance of nsIPlugin. You may find it convenient to have this instance also implement nsIJVMPlugin.

• 
  extern "C" nsresult NSRegisterSelf(nsISupports* serviceMgr,
  				   const char *path);
  
  

  • nsISupports *serviceMgr
    This points to the current nsIServiceManager.

  • const char *path
    The absolute qualified path to the dll that is being loaded

  This function is not called by the mozilla plugin system.

• 
  extern "C" NS_EXPORT nsresult NSUnregisterSelf(nsISupports* serviceMgr,
  					       const char *path);
  

  • nsISupports *serviceMgr
    This points to the current nsIServiceManager.

  • const char *path
    The absolute qualified path to the dll that is being loaded

  This function is not called by the mozilla plugin system. If this were a XPCOM component that was autoregistering, this function would be called to allow the component to register itself with the serviceManager.

• 
  extern "C" PRBool NSCanUnload(nsISupports* serviceMgr)
  

  • nsISupports *serviceMgr
    This points to the current nsIServiceManager.

  This function isn't called by the mozilla plugin system, but if it were, it's purpose is to determine whether it is safe to unload the plugin.

Classes

This section lists all the classes you need to implement in order to be an OJI plugin, and provides links to the header files via lxr. For each class, we list the interfaces to which they must respond when called by QueryInterface or AggregatedQueryInterface, in addition to the mandatory nsISupports.

OJI Classes
mozilla\modules\oji\public\nsIJVMConsole.h: nsIJVMConsole AggregatedQueryInterface: NS_IJVMCONSOLE_IID
mozilla\modules\oji\public\nsIJVMPlugin.h: nsIJVMPlugin QueryInterface: NS_IJVMPLUGIN_IID, NS_IJVMCONSOLE_IID
mozilla\modules\oji\public\nsIJVMPluginInstance.h: nsIJVMPluginInstance QueryInterface: NS_IPLUGININSTANCE_IID, NS_IJVMPLUGININSTANCE_IID
mozilla\modules\oji\public\nsIJVMPrefsWindow.h: nsIJVMPrefsWindow AggregatedQueryInterface: NS_IJVMPREFSWINDOW_IID
mozilla\modules\oji\public\nsISecureEnv.h: nsISecureEnv AggregatedQueryInterface: NS_ISECUREENV_IID
Plugin classes
mozilla\modules\plugin\public\nsIPlugin.h: nsIPlugin AggregatedQueryInterface: NS_IPLUGIN_IID
mozilla\modules\plugin\public\nsIPluginInstance.h: nsIPluginInstance QueryInterface: NS_IPLUGININSTANCE_IID
mozilla\modules\plugin\public\nsIPluginInstancePeer.h: nsIPluginInstancePeer QueryInterface: NS_IPLUGININSTANCEPEER_IID PENDING(edburns): not sure why the plugin needs to implement this.
mozilla\modules\plugin\public\nsIPluginManager.h: nsIPluginManager QueryInterface: NS_IPLUGINMANAGER_IID PENDING(edburns): not sure why the plugin needs to implement this.
mozilla\modules\plugin\public\nsIPluginStreamInfo.h: nsIPluginStreamInfo QueryInterface: NS_IPLUGINSTREAMINFO_IID
mozilla\modules\plugin\public\nsIPluginStreamListener.h: nsIPluginStreamListener QueryInterface: NS_IPLUGINSTREAMLISTENER_IID
mozilla\modules\plugin\public\nsIPluginTagInfo.h: nsIPluginTagInfo QueryInterface: NS_IPLUGINTAGINFO_IID PENDING(edburns): not sure why the plugin needs to implement this.

Sample Implementation Framework

This section lists sample class definitions and the appropriate mozilla inheritences for each class. You must implement these interfaces in addition to the above mentioned NS* functions in order to implement a Java Plugin.

/**

 * Responsible for creating an instance of the Java Plugin.

 */

class JavaPluginFactory : public nsIJVMPlugin, public nsIPlugin
{
};
	

/**

 * The actual java plugin instance.  

 */

class JavaPlugin : public nsIJVMPluginInstance, public nsIPluginInstance 
{
};
	

/**

 * Instances of this class come from the nsIJVMPlugin instance.  
 * This class provides a secure version of the JNIEnv class, from 
 * Sun's JNI.  There is a 1:1 mapping of methods in this class and
 * methods in JNI.

 */

class SecureJNIEnv : public nsISecureEnv
{
};
	

/**

 * Allow mozilla to pop up or hide a console that displays the console
 * output from the java plugin.

 */

class JavaConsole : public nsIJVMConsole
{
};
	

/**

 * Allow mozilla to pop up or hide a window that allows the user to
 * control settings of the Java plugin.

 */

class JavaPrefsWindow : public nsIJVMPrefsWindow
{
};
	

/**

 * 
PENDING(edburns): not sure why the plugin needs to implement this.

 */

class PluginInstancePeer : public nsIPluginInstancePeer, public nsIPluginTagInfo 
{
};
	

/**

 * 
PENDING(edburns): not sure why the plugin needs to implement this.

 */
class PluginManager : public nsIPluginManager 
{
};
	

/**

 * Allows mozilla to gain information about streams for this plugin
 * 
PENDING(edburns): not sure why the plugin needs to implement this.

 */
class PluginStreamInfo : public nsIPluginStreamInfo 
{
};
	

/**

 * Methods that get called by mozilla for various stream events.

 */
class PluginStreamListener : public nsIPluginStreamListener 
{
};