Programming Guide

Shell Plug-In

OpenDoc provides users the ability to customize their OpenDoc run-time by installing OpenDoc Shell Plug-Ins. An OpenDoc Shell Plug-In is simply a shared library located in the OpenDoc Shell Plug-Ins folder or directory that exports a symbol called ODShellPlugInInstall. This document provides sample code for implementing a Shell Plug-In.

Elements

Create a source file with an entry point called ODShellPlugInInstall. If using C++, be sure to type it extern C so that the right calling conventions will be used.
Set up your build system do the following:
- Produce a DLL on the Windows or OS/2 platform or a shared object on the AIX platform from the source file.
- Export the symbol ODShellPlugInInstall in the module definition file.
- Compile and link the library.

Installation

On the OS/2 platform, once you have successfully built the DLL, place it in the OpenDoc Shell Plug-Ins folder. The ID string of the folder is <OD_SHELLPLUGINS>.

For Windows and AIX, once you have successfully built the DLL, or shared object, place it in the directory defined by the ODSHELLPLUGINS environment variable.

Sample Code

#define  INCL_DOSERRORS
#define  INCL_ODAPI
#define  INCL_ODDRAFT
#include <ODos2.h>
#include <ShPlugIn.h>
#ifdef __cplusplus
extern "C"
{
#endif

APIRET APIENTRY ODShellPluginInstall(Environment* ev,
                                     ODDraft* draft,
                                     ODShellPluginActionCodes* action);
#ifdef __cplusplus
}
#endif

APIRET APIENTRY ODShellPluginInstall(Environment* ev,
                                     ODDraft* draft,
                                     ODShellPluginActionCodes* action)
{
  somPrintf("\pPlugin got called");

  // Now tell the Shell to free our library
  // as soon as we return.
  // This is not what most plugins will want to do, but it is the right
  // thing to do if you are just displaying a debug string.
  // If you wanted to leave the library open, say because you would
  // registered an object in an object name space, you would clear the
  // kODShellPluginCloseConnection bit.
  *action |= kODShellPluginCloseConnection;

  // Return NO_ERROR if there are no problems.
  // Any other error causes the Shell to unload the plug-in.
  // Note that the Shell ignores errors returned via the Environment*
  // parameter.
  // Pass ev to OpenDoc routines that you call from here if they require it,
  // but if any of them returns an error that way you will have to deal
  // with it yourself (if it needs dealing with at all).
  // If the Shell gets NO_ERROR back from your plugin it assumes all is
  // well and continues.
  return NO_ERROR;
}

Note:

When you link the shell plug-in, you must export the ODShellPluginInstall function in the module definition file.