HDL Plug-in for Adobe Acrobat and Acrobat Reader

The HDL Plug-in for Adobe Acrobat® and Acrobat Reader® is an extension that adds functionality to PDF documents which are identified by embedded handles. When a PDF with an embedded handle is opened, the plug-in resolves the handle and performs tasks based on the expected standard data types and values returned from the Handle System. The plug-in has a modular design so that support for new data types can be added incrementally as the need arises. When installed, the plug-in may add buttons to the Toolbars, or open windows or display alerts, depending on the type of data stored with the handle that identifies the document and is embedded within it.

The plug-in was developed primarily to demonstrate the potential of such an approach. Its utility depends on an agreed upon set of functions and an agreed upon set of handle type/value pairs corresponding to those functions. This would be similar to an unpopulated database whose utility depends on adding real data. A number of groups are currently collaborating on the development of specifications for various applications. If you wish to participate in that activity, please send email to <> referencing this note. This version has not been tested using the latest versions of Windows or Adobe Acrobat software.

See a demonstration of some possible applications of the plug-in in the HDL Plug-in for Acrobat slide presentation.




System Requirements

  • Windows 98/NT/2000/XP
  • Adobe Acrobat or Acrobat Reader version 8.0 or greater.


Download and run the hdlacro.exe program. It may be necessary to reboot in order for Acrobat to see the plug-in.

Firewall Note: If you do not have a direct Internet connection, the plug-in will attempt to use the proxy settings used by Internet Explorer. Make sure that Internet Explorer's settings are valid. Currently, only HTTP and SOCKS5 proxies are supported. SOCKS4 proxies and proxies requiring authentication will not work. If you connect to the Internet through a proxy, please examine your settings. You can find the proxy settings dialog under the Internet applet in the control panel.



CNRI has developed ways to use the HDL Plug-in for Adobe Acrobat. In particular, CNRI has worked with members of the International DOI Foundation to offer new services to customers who view journal articles or other published documents represented as digital objects.

Sample files illustrating some of the services developed are described below. The files, and a readme.txt file, are included in the download are installed by default on your Desktop in a folder named "Handle Acrobat Plug-in Documents". Note that in order to view the services using your web browser and the links below, your web browser must use Adobe Acrobat Reader version 8.

  • Latest version (newest-version-demo.pdf)
    In this sample PDF file, resolution of a handle embedded in the file notifies the user via a pop-up window that a newer version of the document exists, with the option to download.
  • Related links (related-links-demo.pdf)
    In this sample PDF file, resolution of a handle embedded in the eBook PDF generates a hierarchical menu, "Related Links", displayed along the top window menu bar, that contains pointers to web sites related to the current document.
  • HDL Kernel Metadata (kernel-metadata-demo.pdf)
    In this sample PDF file, resolution of a handle retrieves metadata specific to this document and activates the "hdl" button. Clicking the "hdl" button opens a dialog box that displays the metadata.
  • CrossRef Metadata (crossref-demo.pdf)
    In this sample PDF file, resolution of a handle retrieves metadata from the CrossRef metadata database and activates the "cr" button. Clicking the "cr" button opens a dialog box that displays the metadata.
  • Reproduction Rights (rights-demo.pdf)
    In this sample PDF file, the embedded handle is resolved to obtain a link to a web site where the user can learn the current reproduction rights for the document. Resolving the handle also activates the "©" button. Clicking that button opens a web browser that displays the rights web site.
  • Collections (collections-demo-1.pdf, collections-demo-2.pdf, collections-demo-3.pdf)
    In this sample PDF file, the document is part of a larger collection of related documents. The plug-in resolves the embedded handle to obtain information needed to construct a bookmark tree with the name of the collection as the root, and each node representing a document that is part of the collection. (Note that the collection bookmarks are not actionable in Adobe Reader, a result of a limitation of the Acrobat Reader SDK.)


To remove the plug-in, delete the hdl.api file from the Acrobat Plug_ins directory. If you have Adobe Acrobat Reader 8 installed, the directory is:

C:\Program Files\Adobe\Reader 8.0\Reader\plug_ins

You will need to close all running instances of Adobe Acrobat before you can delete the plug-in, and you may need to reboot.


July 2012