Creating C plug-ins

You must create a separate plug-in for each of the three types of plug-ins. For example, you cannot create one plug-in that supports AREA and ARDBC.

To create a C plug-in

1. Write a C or C++ program that includes these elements:
   • A reference to the arplugin.h file for plug-in definitions and declarations.
   • Plug-in API calls for initialization, termination, object creation, and object deletion (see Common plug-in C functions and Java methods).
   • One of these type-specific API calls:
     • AREA (see AREA plug-ins)
     • ARDBC (see ARDBC plug-in Java and C API methods)
     • AR Filter (see AR filter API plug-ins introduction)
   • Code to implement the calls. Use sample Microsoft Developer Studio projects (Windows) or makefiles (UNIX), which you install with AR System , to build your program into your DLL or shared object library.
     For examples and templates for C plug-ins, see the ardbc, area, and arfilterapi subdirectories of the Api directory in your  AR System server installation.
     C plug-in call sequence shows the general structure of a plug-in program.
2. Compile and link your plug-in as follows:
   • On Windows platforms, compile your plug-in using Microsoft Visual Studio .NET 2003.
   • On Linux, compile your plug-in with the -malign-double option to make sure that your plug-in library is correctly aligned for the plug-in server. If you do not use this option, the plug-in might produce unexpected results.
   • If you compile and link your plug-in on HP-UX using aCC and enable exception handling, your plug-in will have dependencies on libraries that are not standard C/C++ libraries, for example, libCsup_v2 and libstd_v2. If your plug-in has dependencies on any libraries like these, explicitly link to them and make sure they are available at run time in the shared library path for the plug-in server to find them.
3. Put your plug-in DLL or shared library file in the directory that contains the AR System server  and plug-in server executable files or any other directory listed in your PATH environment variable.
4. Add an entry for the plug-in to the plug-in server configuration file. See Configuring the Java plug-in server.
   At run time, the plug-in server reads the configuration file and loads the specified plug-ins. 

Managing memory

Do not free memory that the plug-in passes to your functions as arguments or that you return to the plug-in. Plug-ins can allocate and deallocate memory associated with the object argument for each call. The plug-in does not deallocate this memory.

Specifying input and return values

In a C API program, developers specify input values for the functions and receive return values. In a plug-in program, the plug-in provides the input values to the plug-ins, and the plug-ins provide return values.

If the  AR System server  returns AR_RETURN_WARN or AR_RETURN_OK to the arplugin log file after a call is issued, the plug-in considers that call successful. The plug-in considers the call unsuccessful if the server returns AR_RETURN_ERROR or AR_RETURN_FATAL.

If you do not implement a call, the plug-in performs a default action. The default action might be to proceed or to return an error message.

Protecting global information

To ensure thread safety, protect any global information or resources that you access through plug-in API calls with appropriate mutual exclusion locks. Global information and resource protection applies to all plug-in calls except ARPluginIdentify, ARPluginInitialization, ARPluginSetProperties, and ARPluginTermination, which are always called by one thread at a time.

At run time, the plug-in server reads the configuration file and creates the plug-ins that the file specifies. After the plug-in server creates the plug-ins, they remain active until a system failure or until you modify the plug-in configuration information and restart the plug-in server. For more information, see Restarting the plug-in server.