Issue
Description of DLL's, Acrobat SDK samples, PIRequire.h, PIMain.c, HFT.
Solution
Acrobat Plug-Ins are DLLs on Windows and Shared Object Libraries on Mac and Unix platforms. Acrobat cannot simply load any DLL or shared object library, however. A set of conventions has been developed that allow Acrobat to query the DLL for the functionality it provides and the functionality it requires from Acrobat. These conventions include required functions and symbols that all plug-ins must include. DLLs which do not include these features will not be loaded by the viewer.

If you are using the Acrobat SDK to develop your plug-in and starting with one of the provided samples, the base functionality is provided for you in the sample projects. Please see the document Acrobat API Development for information on project settings and helpful hints for developing plug-ins. This tutorial document steps through the utility code provided in the SDK which implements the required functions for your plug-in. Most plug-in developers will simply be able to include the utility files from the SDK and not need to modify them, however, understanding what they are doing provides a basis for understanding the implemenation of the Acrobat API and will aid in troubleshooting plug-in load and unload problems.

There are two files included with the Acrobat SDK which must be included in every plug-in. These are PIRequir.h and PIMain.c/PIMain.cpp. These files work together to implement the "handshaking" mechanism by which the plug-in accesses functionality in the viewer.

PIRequir.h-

The Acrobat API is divided into a series of Host Function Tables(HFTs). A Host Function Table is a structure of function pointers. Plug-Ins access functionality in Acrobat by importing an HFT and then calling functions made available in that HFT. HFTs will be covered in more detail later. What is important to realize now is that plug-ins may be loaded by viewers with different sets of HFTs available (eg the free Reader vs the Full Acrobat) and different versions (eg Acrobat 3.x vs 4.0). HFTs allow the plug-in to determine whether the functionality they need is available and behave appropriately in response.

PIRequir.h is the header file provided in the SDK which determines the HFTs and versions of HFTs which will be imported by the plug-in. Each HFT is controlled be a descriptive Macro

PI_CORE_VERSION
PI_PDMODEL_VERSION

Defining the macro to anything besides 0 specifies that methods from the HFT are needed and therefore the HFT it should be imported. Versioning is accomplished with the value of the macro. Each time an HFT's methods are modified or added to, the version number of the HFT is changed. The value of the macro in PIRequir.h is the version of the HFT that the plug-in requires.

#define PI_CORE_VERSION ((4L<<16) + 0)

As shipped with the Acrobat 4.0 SDK, PIRequir.h specifies the most current HFT version of all available HFTs. This means that a plug-in compiled using PIRequir.h from the 4.0 SDK will only load in Acrobat 4.0. It is possible to build a plug-in that will load in both Acrobat 3.x and 4.0 by specifying older version numbers as specified in the Acrobat 3.x SDK.

With the 4.0 Release of the Acrobat SDK there have been two new HFTs added to the Acrobat Viewer. These are PDFEdit and PDSEdit. Please see the Acrobat API Overview for more information on the features made available by these HFTs. Two new macros must be defined to access these HFTs. These are:

NEW_PDFEDIT_HFTS
NEW_PDSEDIT_HFTS

To access these HFTs the above macros need only be defined as 1.

#define NEW_PDFEDIT_HFTS 1

Because there are dependencies on these macros in multiple header files, these macros should be defined in the preprocessor definitions (Windows and Unix) or the precompiled header file (Mac).

It should be noted that as new versions of Acrobat and the SDK are released with new and updated functionality, older functionality may become deprecated. Please contact Adobe Developer Support for official support information if you are developing for a version of Acrobat more than two versions prior to the most current version.

Was this Knowledgebase document helpful? Yes  No