Hey! My plug-in won’t load in Adobe Reader

| No Comments

You completed your Integration Key License Agreement for Adobe Reader, you got your certificate, followed all of the steps exactly and your plug-in still won’t load. Why?

Richard Relph, a Senior Computer Scientist at Adobe, has compiled a list of the four common issues that result in a plug-in failing to load and forcing Reader to quit.

1: User error – Signing the plug-in

Signing the plug-in with the tools we have in the field can be an error-prone process. It is absolutely essential that the instructions be followed very carefully. The most common mistake is to "rebuild" instead of "build" the plug-in after computing the signature value, but other mistakes are certainly possible.

2: READER_PLUGIN

The most common problem is a plug-in not being compiled for Reader. Reader does not support the full set of APIs that Acrobat does. The compile-time switch forces the plug-in loading code to NOT fetch certain "HFTs" (an HFT is a table of pointers to APIs) that aren’t available in Reader. If the plug-in loading code (which is a part of the plug-in) wasn’t compiled with READER_PLUGIN, it will attempt to fetch an HFT that Reader doesn’t support, the loading code will return an error, and loading will stop.

3: ACRO_COLOR

Unfortunately, in the samples that ship with the Acrobat SDK for Acrobat 8, we didn’t correctly deal with one particular HFT when READER_PLUGIN is defined. If the developer is attempting to compile or modify a sample we shipped with the Acrobat 8 SDK, besides setting READER_PLUGIN, they will have to modify AcroDspOptions.rsp, which is located in the Samples folder of the SDK. In that file is a /D that assigns a specific version to the ACRO_COLOR HFT. That forces the loading of the HFT, even in the presence of READER_PLUGIN, which will prevent the plug-in from working in Reader. Delete the line in the RSP file.

4: DLL Hell

Some developers have a development machine with Acrobat and Visual Studio and another machine that has just Reader. The problem is that the machine with just Reader doesn’t have all the C Run-time DLLs that are installed "for free" when Visual Studio is installed. The solution to this is to either build the plug-in such that the C Run-time libraries are statically linked in to the plug-in (my preferred solution), or to ensure that the necessary DLLs are loaded on to the target machine with the plug-in. (Yes, this would have to be done as part of the plug-in installation process for end-user machines.) Sometimes this isn’t an issue, because Reader itself installs some of the C Run-time DLLs. Other times, it is because the plug-in was built using a newer or slightly different variation (debug vs. release or multi-threaded vs. single-threaded) of the run-time libraries.

Richard recommends that new Reader developers use the Visual Studio Plug-in Wizard to create a "trivial" Reader plug-in (say with a help item and nothing else). By clicking on the "Reader" check box at the appropriate step in the wizard, problems #2 and #3 and #4 above are avoided. That only leaves problem #1. Once the developer is successful in building a trivial plug-in that works with Reader, especially including the signing process, they have the confidence and experience necessary to move on to signing their own "real" plug-ins and knowing that whatever problems remain aren’t due to any "issues" with the key we’ve sent them or the tools they’ve never used before.