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:
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.