Adobe Acrobat Technology White Paper

Introduction
The External
Window Handler Plug-in
Page-at-a-Time Downloading
Integration Considerations

Adobe(R) Acrobat(R) 3.0 Technology
A Mini-White Paper for Developers
Introduction
The Acrobat 3.0 Reader provides an Interapplication Communication (IAC) interface designed for integrating the Acrobat Viewer into environments where existing applications, such as World Wide Web browsers, permit viewing PDF files in-line. The IAC interface provides two main capabilities:

It allows the Acrobat Viewer to render and manage a live PDF document in the window of another application (such as a Web browser). All of the normal Acrobat Viewer capabilities such as document scrolling, hypertext links, annotations, and an optional Acrobat toolbar are available in the calling application's window.

It allows the calling application to supply the Acrobat Viewer with an interface for reading PDF files from arbitrary data sources such as Web servers.
In a typical scenario, a Web browser sends an IAC message to the Acrobat Viewer. The message specifies a handle to the window in which the document will be displayed and a handle to a stream from which the Acrobat Viewer can read the PDF file's data. The Acrobat Viewer then sends an IAC message back to the Web browser to request to read bytes from the stream. The Web browser sends the requested bytes to the Acrobat Viewer, which then displays the document in the application's window.
The IAC mechanism is platform-dependent. It uses shared memory on the Macintosh(R) and Windows(R) platforms. Event handling is also platform-dependent; the Acrobat Viewer can get events directly from the window handle on the Windows platform, while events must be explicitly passed to the Acrobat Viewer through the IAC interface on the Macintosh platform.

The External Window Handler Plug-in
The Acrobat 3.0 Reader includes a new Acrobat Viewer plug-in called the External Window Handler plug-in, which implements the Acrobat Viewer's IAC interface. It is not compatible with previous versions of the Acrobat Viewer (versions 2.1 and earlier). The External Window Handler supports simultaneous rendering in multiple windows from one or more calling applications.
In the case of the Acrobat integration with Netscape(TM) Navigator(TM) 2.0 browser, the browser communicates with the Acrobat External Window Handler plug-in (called ewh32.api in Windows 95) through a Netscape plug-in (called nppdf32.dll in Windows 95).

Page-at-a-Time Downloading
The Portable Document Format (PDF) used by the Acrobat products is capable of representing rich electronic documents that include formatted text, line art and scanned images. PDF documents can be thousands of pages long and have built-in navigation aids such as document-specific bookmarks and page thumbnails. PDF files can include embedded fonts to allow the look of an electronic document to be precisely replicated on different computer systems. Objects such as fonts can be shared across multiple pages in a PDF document. The Acrobat Viewer needs to be able to randomly access the PDF file to read the resources that are required to render a given page. To support this, PDF files have an internal cross-reference table that specifies the locations of every object in the PDF file.
To provide good performance on the Web, the Viewer must download and view one page of a PDF file at a time, rather than requiring the entire file (including fonts and images) to be downloaded before any of it can be viewed. This is addressed by the Acrobat 3.0 Viewer in conjunction with an appropriate Web browser and Web server. The Web browser must support a proposed HTTP extension for specifying byte ranges of a file to be downloaded, and the Web server must support byte range downloading using a CGI script or other mechanism. Ari Luotonen from Netscape and John Franks from Northwestern University have proposed an extension to HTTP in an IETF Internet-Draft: Byte Ranges With HTTP URLs. This extension allows a Web browser to request portions of a file specified by byte ranges.

To provide optimal page-at-a-time viewing, PDF files must be optimized by Acrobat Exchange(R). Optimization adds hint tables to the PDF file and restructures it for maximum compression. The Acrobat 3.0 Viewer uses these hint tables to make smart requests of the Web browser, requesting only the bytes required to view the next page. The Acrobat Viewer can specify the complete list of byteranges required for a given page in a single call to the Web browser. This allows the Web browser to retrieve the bytes for an entire page in a single HTTP connection with the Web server. As each byterange is returned in a multipart MIME, those bytes should be pushed at Acrobat so it can begin incrementally drawing the page as more bytes are arriving.
In addition, the optimized PDF file is structured so that the first page can begin displaying immediately as a result of the initial read. Because of this, the initial byterange request that the Acrobat Viewer makes of the Web browser is for the entire file. As the user is viewing page one of the file, the rest of the document is being downloaded and the Acrobat Viewer is caching the bytes being passed to the Acrobat Viewer so that it can begin. When the user requests a different page of the document, the first connection is broken through a call to the Web browser and a new read is issued for the byteranges necessary to view the next page of the document (unless those bytes were already cached because of the read-ahead).
Because the intelligence for what bytes to download for each page is encapsulated in the PDF hint tables and the Acrobat 3.0 Viewer, the Byteserver CGI script is very simple (less than 100 lines of PERL). Its only responsibilities are to parse the HTTP request, extract the bytes from the file, and return a properly formed HTTP response. Adobe intends to freely distribute an implementation of the Byteserver CGI script. Netscape and some other server vendors have announced that they are planning to build Byteserving support directly into their Web servers. If PDF files are not optimized and there is no Byteserver present, the PDF files will be downloaded entirely before any pages are viewed in the calling application's window. If the PDF files are not optimized but a Byteserver is present on the Web server, the Acrobat 3.0 Viewer will attempt to approximate page-at-a-time downloading, but without optimal efficiency.

Integration Considerations
A goal of Acrobat 3.0 Viewer's integration capabilities is to make PDF files first-class citizens in the Web browsing experience. To assist this, a browser should integrate PDF files into the goback stack, so that viewing a PDF file has the same goback semantics as viewing an HTML file. Installation is another integration consideration. Ideally, the Acrobat 3.0 Reader will be bundled with the Web browser when it is distributed on disk, or at least the user will be prompted to download and install Acrobat when the first PDF file is encountered on the Web.

| Home | What's New | Overview | Details | At Work | Getting Help | Download |

Questions, comments, or problems regarding this service?
Copyright © 1996 Adobe Systems Incorporated.
All rights reserved.
Legal notices and trademark attributions.

Introduction The External Window Handler Plug-in Page-at-a-Time Downloading Integration Considerations		Adobe(R) Acrobat(R) 3.0 Technology A Mini-White Paper for Developers Introduction The Acrobat 3.0 Reader provides an Interapplication Communication (IAC) interface designed for integrating the Acrobat Viewer into environments where existing applications, such as World Wide Web browsers, permit viewing PDF files in-line. The IAC interface provides two main capabilities: It allows the Acrobat Viewer to render and manage a live PDF document in the window of another application (such as a Web browser). All of the normal Acrobat Viewer capabilities such as document scrolling, hypertext links, annotations, and an optional Acrobat toolbar are available in the calling application's window. It allows the calling application to supply the Acrobat Viewer with an interface for reading PDF files from arbitrary data sources such as Web servers. In a typical scenario, a Web browser sends an IAC message to the Acrobat Viewer. The message specifies a handle to the window in which the document will be displayed and a handle to a stream from which the Acrobat Viewer can read the PDF file's data. The Acrobat Viewer then sends an IAC message back to the Web browser to request to read bytes from the stream. The Web browser sends the requested bytes to the Acrobat Viewer, which then displays the document in the application's window. The IAC mechanism is platform-dependent. It uses shared memory on the Macintosh(R) and Windows(R) platforms. Event handling is also platform-dependent; the Acrobat Viewer can get events directly from the window handle on the Windows platform, while events must be explicitly passed to the Acrobat Viewer through the IAC interface on the Macintosh platform.
		The External Window Handler Plug-in The Acrobat 3.0 Reader includes a new Acrobat Viewer plug-in called the External Window Handler plug-in, which implements the Acrobat Viewer's IAC interface. It is not compatible with previous versions of the Acrobat Viewer (versions 2.1 and earlier). The External Window Handler supports simultaneous rendering in multiple windows from one or more calling applications. In the case of the Acrobat integration with Netscape(TM) Navigator(TM) 2.0 browser, the browser communicates with the Acrobat External Window Handler plug-in (called ewh32.api in Windows 95) through a Netscape plug-in (called nppdf32.dll in Windows 95).
		Page-at-a-Time Downloading The Portable Document Format (PDF) used by the Acrobat products is capable of representing rich electronic documents that include formatted text, line art and scanned images. PDF documents can be thousands of pages long and have built-in navigation aids such as document-specific bookmarks and page thumbnails. PDF files can include embedded fonts to allow the look of an electronic document to be precisely replicated on different computer systems. Objects such as fonts can be shared across multiple pages in a PDF document. The Acrobat Viewer needs to be able to randomly access the PDF file to read the resources that are required to render a given page. To support this, PDF files have an internal cross-reference table that specifies the locations of every object in the PDF file. To provide good performance on the Web, the Viewer must download and view one page of a PDF file at a time, rather than requiring the entire file (including fonts and images) to be downloaded before any of it can be viewed. This is addressed by the Acrobat 3.0 Viewer in conjunction with an appropriate Web browser and Web server. The Web browser must support a proposed HTTP extension for specifying byte ranges of a file to be downloaded, and the Web server must support byte range downloading using a CGI script or other mechanism. Ari Luotonen from Netscape and John Franks from Northwestern University have proposed an extension to HTTP in an IETF Internet-Draft: Byte Ranges With HTTP URLs. This extension allows a Web browser to request portions of a file specified by byte ranges. To provide optimal page-at-a-time viewing, PDF files must be optimized by Acrobat Exchange(R). Optimization adds hint tables to the PDF file and restructures it for maximum compression. The Acrobat 3.0 Viewer uses these hint tables to make smart requests of the Web browser, requesting only the bytes required to view the next page. The Acrobat Viewer can specify the complete list of byteranges required for a given page in a single call to the Web browser. This allows the Web browser to retrieve the bytes for an entire page in a single HTTP connection with the Web server. As each byterange is returned in a multipart MIME, those bytes should be pushed at Acrobat so it can begin incrementally drawing the page as more bytes are arriving. In addition, the optimized PDF file is structured so that the first page can begin displaying immediately as a result of the initial read. Because of this, the initial byterange request that the Acrobat Viewer makes of the Web browser is for the entire file. As the user is viewing page one of the file, the rest of the document is being downloaded and the Acrobat Viewer is caching the bytes being passed to the Acrobat Viewer so that it can begin. When the user requests a different page of the document, the first connection is broken through a call to the Web browser and a new read is issued for the byteranges necessary to view the next page of the document (unless those bytes were already cached because of the read-ahead). Because the intelligence for what bytes to download for each page is encapsulated in the PDF hint tables and the Acrobat 3.0 Viewer, the Byteserver CGI script is very simple (less than 100 lines of PERL). Its only responsibilities are to parse the HTTP request, extract the bytes from the file, and return a properly formed HTTP response. Adobe intends to freely distribute an implementation of the Byteserver CGI script. Netscape and some other server vendors have announced that they are planning to build Byteserving support directly into their Web servers. If PDF files are not optimized and there is no Byteserver present, the PDF files will be downloaded entirely before any pages are viewed in the calling application's window. If the PDF files are not optimized but a Byteserver is present on the Web server, the Acrobat 3.0 Viewer will attempt to approximate page-at-a-time downloading, but without optimal efficiency.
		Integration Considerations A goal of Acrobat 3.0 Viewer's integration capabilities is to make PDF files first-class citizens in the Web browsing experience. To assist this, a browser should integrate PDF files into the goback stack, so that viewing a PDF file has the same goback semantics as viewing an HTML file. Installation is another integration consideration. Ideally, the Acrobat 3.0 Reader will be bundled with the Web browser when it is distributed on disk, or at least the user will be prompted to download and install Acrobat when the first PDF file is encountered on the Web.