Programming Guide


Shell Plug-Ins

You can extend the capabilities of the document shell or add session-wide functionality to OpenDoc by implementing shell plug-ins. Shell plug-ins are shared libraries, rather than subclasses of ODExtension. A shell plug-in is not associated with any particular part object.

Your shell plug-in must be installed on the user's machine when a document first opens, if it is to be used with that document.

You can create shell plug-ins for any of several purposes, including these:

A shell plug-in has a single exported entry point to OpenDoc: its installation function. Your plug-in library needs to implement only that function, with this interface:

void ODShellPlugInInstall(Environment *ev,
                          ODDraft *draft
                          ODShellPlugInActionCodes *action);

The installation function must have exactly the specified name as well as the specified parameters and return value. You must ensure that the function name ODShellPluginInstall appears in your library's list of exported symbols.

The draft parameter specifies the document draft that is being opened. Use the action parameter to return a value specifying whether the document shell should maintain a connection to your shell plug-in library after the installation function completes.

The installation function must always return noErr, unless it cannot execute. For any ODShellPluginInstall function that returns an error, OpenDoc unloads its shell plug-in library.

Execution of a shell plug-in happens like this:

  1. Whenever the user opens an OpenDoc document, OpenDoc launches the document shell. The document shell initializes itself and the session object, and gains access to the document's current draft.

  2. The document shell then accesses each plug-in library and calls its ODShellPluginInstall function. The ODShellPluginInstall function performs the functions the plug-in is designed for: it installs custom focus modules or dispatch modules, it patches session-level objects, or it otherwise modifies shell functionality. ODShellPluginInstall then returns the appropriate OSErr value and exits.

  3. After all plug-ins have executed, the root part of the OpenDoc document then opens the document window.

For OS/2, if it is to be executed, your shell plug-in file must be located in the OpenDoc Shell Plug-Ins folder on the user's system. For Windows and AIX, if it is to be executed, your shell plug-in file must be located in the path identified by the ODSHELLPLUGINS environment variable.


[ Top | Previous | Next | Contents | Index | Documentation Homepage ]