Creating an Acrobat Reader Plug-In

This chapter describes the tasks required to enable a plug-in to be loaded by Acrobat Reader. his chapter contains the following information.

Topic

Description

Developing and enabling an Acrobat Reader plug-in

Describes the development and contractual tasks required to develop and enable a plug-in to work with Acrobat Reader.

Troubleshooting an Acrobat Reader plug-in

Describes how to solve problems that may occur with an Acrobat Reader plug-in.

Developing and enabling an Acrobat Reader plug-in

This section describes how to develop and enable your plug-in to work with Acrobat Reader. It explains how to set up preprocessor definitions for your plug-in project, how to obtain the public key that Adobe uses to create your Adobe Integrated Key, and how to apply that key to a plug-in.

Before reading this section, you should be familiar with the chapter Creating Plug-in and PDF Library Applications.

The following diagram illustrates the development and contractual tasks required to develop and enable a plug-in to work with Acrobat Reader. The gray-filled boxes indicate tasks that Adobe performs.

Setting up your project with preprocessor definitions

Before building an Acrobat Reader plug-in, you must set up your project properties with preprocessor definitions for READER_PLUGIN.

A common cause of difficulty when Reader-enabling a plug-in is that the plug-in attempts to acquire one or more Host Function Tables (HFTs) during startup that are not available within Acrobat Reader. To avoid this problem on Windows and Mac OS, ensure that the READER_PLUGIN symbol is defined. With this symbol defined, only those HFTs available in Acrobat Reader are acquired. (See Working with Host Function Tables.)

On UNIX platforms, you do not have to provide the preprocessor with a definition for the READER_PLUGIN symbol. UNIX platforms support only Acrobat Reader.

To define the READER_PLUGIN symbol in a Mac OS project:

Add the READER_PLUGIN symbol to the Xcode project-level build settings by selecting the plug-in project in the Groups & Files pane and opening the Project Inspector. On the Build tab, under the GCC 4.0 Preprocessing settings, add READER_PLUGIN=1 to the Preprocessor Macros setting.

To define the READER_PLUGIN symbol in a Visual C++ project (Windows):

To define the READER_PLUGIN symbol in a Win32 project:

  1. Locate the AcroDspOptions.rsp file in the SDK’s /PluginSupport/Samples directory.

  2. Open the AcroDspOptions.rsp file in a text editor.

  3. Change ACRO_SDK_LEVEL to 0x000A0000 from 0x00090000

  4. Remove the AcroColorHFT define by removing the following line from the file:

    /D PI_ACROCOLOR_VERSION=0x00060000

  5. Add the READER_PLUGIN define by adding the following to the file:

    /D READER_PLUGIN

  6. Save the AcroDspOptions.rsp file.

  7. Open and rebuild your Visual C++ plug-in project.

[Note]: This change affects all SDK plug-ins built after the change is made.

Creating the public and private key pairs

Use the MakeKeys tool to create the public and private key pairs for your plug-in. The MakeKeys tool is a command line (Terminal tool). You can find this tool in the PluginSupport/Tools/Reader-enabling Tools directory in the Acrobat DC SDK. You can also download a ZIP file that contains this tool from http://www.adobe.com/go/rikla_tools.

To create public and private key pairs:

  1. Open a Command Prompt (Windows), Terminal (Mac OS), or shell (Linux).

  2. Go to the directory that contains the MakeKeys tool.

  3. Run the MakeKeys tool, providing it with the following parameters:

    • -kp option followed by the name of the file in which to store the key pair. The directory must already exist. The file name cannot exceed the platform limitations on file name lengths.

    • -pk option followed by the name of the file in which to store the public key. The directory must already exist. The file name cannot exceed the platform limitations on file name lengths.

    • A random string that you create. The MakeKeys tool uses the string to generate a random number. The random string must contain only letters and digits. There is no limit on the length of the string.

The following example command line shows the options and parameters you supply to the MakeKeys tool. The italics in the command line indicate placeholders that you must replace with meaningful values.

MakeKeys -kp KeyPairFileName -pk PubKeyFileName RandomString

The size of the resulting key pair file is approximately 450 bytes. The size of the public key pair file is approximately 98 bytes.

  1. Submit the public key file to Adobe using the PDF form that you received by email, as described in Developing and enabling an Acrobat Reader plug-in.

Enabling the plug-in for Acrobat Reader

After receiving the Reader Integrated Key from Adobe, use the SignPlugin tool to enable the plug-in for Acrobat Reader.

The SignPlugin tool is a command line (Terminal tool). You can find this tool in the PluginSupport/Tools/Reader-enabling Tools directory in the Acrobat DC SDK. You can also download a ZIP file that contains this tool from http://www.adobe.com/go/rikla_tools.

To enable the plug-in for Acrobat Reader:

  1. Open a Command Prompt (Windows), Terminal (Mac OS), or shell (Linux).

  2. Go to the directory that contains the SignPlugin tool.

  3. Run the SignPlugin tool, providing it with the following parameters:

    • -kp option followed by the location of the file that contains the key pair. This file was produced by the MakeKeys tool. (See Creating the public and private key pairs.)

    • -cf option followed by the location of the file that contains the Reader Integrated Key provided by Adobe. (See Developing and enabling an Acrobat Reader plug-in.)

    • Location of the plug-in.

The following example command line shows the options and parameters you supply to the SignPlugin tool. The italics in the command line indicate placeholders that you must replace with meaningful values.

SignPlugin -kp keypairFileName -cf Reader_Integrated_Key_FileName
/MyDirectory/MyPlugin

If SignPlugin is successful, it returns the message: “Plug-in.acroplugin successfully Reader Enabled.”

The plug-in can now be loaded by Acrobat Reader. If you encounter any difficulties, see Troubleshooting an Acrobat Reader plug-in.

Note:This procedure must be repeated each time the plug-in is built.

Tip:On Mac OS, to easily copy paths to the command line, drag files from the Finder window to the Terminal window

Troubleshooting an Acrobat Reader plug-in

There are some issues that can cause a plug-in not to load in Acrobat Reader. The most common issues are documented here. If the problem persists, contact Acrobat Developer Support.

Plug-in appears to be ignored by Acrobat Reader

Several problems can cause this symptom:

  • The plug-in was compiled without the READER_PLUGIN symbol being defined (Windows and Mac OS platforms only).

A common cause of difficulty when enabling a Acrobat Reader plug-in is that the plug-in attempts to acquire one or more HFTs during startup that are not available in Acrobat Reader. To avoid this problem on Windows and Mac OS, ensure that the READER_PLUGIN symbol is defined. (See Setting up your project with preprocessor definitions.)

With this symbol defined, only those HFTs available in Acrobat Reader are acquired. On the UNIX platform, only those HFTs available in Acrobat Reader are acquired by default. For information about an HFT, see Working with Host Function Tables.

  • The Certified Plug-ins Only preference is set (Windows and Mac OS platforms only).

Acrobat Reader recognizes only Adobe plug-ins as certified.

Ensure that the Certified Plug-ins Only option is not selected in the Options Preferences dialog box.

  • The plug-in was not correctly enabled.

The resources file sent by Adobe may have been corrupted during delivery. Verify that the file sizes match those documented in the previous sections. If the public/private key pair or public key files are corrupt, you must regenerate new files and request a new Reader Integrated Key from Adobe. If the file that contains the key is corrupt, you must request a new Reader Integrated Key from Adobe, using the existing public key file.

Acrobat Reader error messages

The following are the most commonly received error messages:

  • “There was an error while loading the plug-in name.api. The plug-in is incompatible with this version of the viewer.”

  • “There was an error while loading the plug-in name.api. The plug-in failed to initialize.”

  • “There was an error while loading the plug-in ’your plug-in name’. Two plug-ins are attempting to register with the same name.”

The first error is displayed if the plug-in returns false from the PISetupSDK method (defined in PIMain). The method returns false if the plug-in attempts to acquire an HFT that is not available. (See Working with Host Function Tables.)