Programming Guide: Shell Plug-In

# 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

1. 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.
2. 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.

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