Inside Macintosh: OpenDoc Class Reference

Appendix A - Shell Plug-In Installation Function / Programmer-Defined Functions

ODShellPluginInstall

The ODShellPluginInstall function should install whatever functionality your shell plug-in requires.

OSErr ODShellPluginInstall (
                        Environment* ev,
                        ODDraft* draft,
                        ODShellPluginActionCodes* action);

ev

A pointer to the SOM environment parameter used for passing exceptions.

draft

A pointer to the most recent draft of the document being opened.

action

A pointer to the value in which to return action codes specifying actions OpenDoc should perform when this function returns successfully.

return value

noErr if the installation is successful, otherwise a Mac OS error code indicating why installation failed.

DISCUSSION

When the user opens a document, OpenDoc installs all shell plug-in import libraries located in the OpenDoc Shell Plug-Ins folder on the user's machine. To install a shell plug-in, OpenDoc creates a connection to the import library and calls the ODShellPluginInstall function of each import library. If no other code fragment already has a connection to the shell plug-in, the Code Fragment Manager loads the shell plug-in into memory.

The draft parameter points to the draft object for the current draft of the document.

When this function is called, the action parameter points to a value that is equal to kODShellPluginNoAction. If you want OpenDoc to perform particular actions following installation of your shell plug-in, you should set the appropriate flags in that value. You can set the flag for a particular action using a bitwise OR operator (for example, the | or |= operator in C++). Currently, the only supported action is closing the connection to the shell plug-in import library (kODShellPluginCloseConnection).

IMPORTANT

To request actions, you must modify the value that the action parameter addresses (*action). Do not modify the value of the action parameter itself.

If the installation is successful, this function should return noErr. In that case, the document shell performs any actions specified in the value to which the action parameter points. The shell plug-in is then available for the document to use.

If the installation fails for any reason, this function should return an error code. In that case, OpenDoc displays a dialog box asking the user to remove the shell plug-in from the system.

The following code fragment illustrates how to declare and define the C or C++ installation function for your shell plug-in.

//    If you use C++, declare your function within an
//    extern "C" declaration.
#ifdef __cplusplus
extern "C" {
#endif
OSErr ODShellPluginInstall ( Environment* ev, 
                        ODDraft* draft,
                        ODShellPluginActionCodes* action);
#ifdef __cplusplus
}
#endif
//    Define your function.
OSErr ODShellPluginInstall(Environment* ev, 
                        ODDraft* draft
                        ODShellPluginActionCodes* action);
{
   //    Perform any necessary installation; return an 
   //    error code if installation fails.
   ...
   //    If appropriate, set action codes in *action.
   *action |= kODShellPluginCloseConnection;
   //    Return noErr if installation succeeds.
   return noErr;
}

SEE ALSO

The ODShellPluginActionCodes type (page 950).
The ODDraft class (page 147).