File: 5-cgi.html

package info (click to toggle)
htmldoc 1.8.27-8
links: PTS, VCS
area: main
in suites: jessie, jessie-kfreebsd, stretch, wheezy
size: 11,708 kB
ctags: 5,685
sloc: ansic: 43,156; cpp: 22,678; perl: 395; makefile: 303; java: 59; php: 36; xml: 10; sh: 7
file content (656 lines) | stat: -rw-r--r-- 19,925 bytes
parent folder | download | duplicates (4)
<html>
<body>

<!-- FOOTER RIGHT "5-$CHAPTERPAGE" -->
<div align='justify'>

<h1 align='right'><a name='CGI'>Chapter 5 - Using HTMLDOC on a
Web Server</a></h1>

<p>This chapter describes how to interface HTMLDOC to your web
server using CGI and your own server-side scripts and
programs.</p>

<h2>The Basics</h2>

<p>HTMLDOC can be used in a variety of ways to generate
formatted reports on a web server. The most common way is to use
HTMLDOC as a CGI program with your web server to provide
PDF-formatted output of a web page. Examples are provided for
Microsoft IIS and the Apache web servers.</p>

<p>HTMLDOC can also be called from your own server-side scripts
and programs. Examples are provided for PHP and Java.</p>

<!-- NEED 2in -->
<center><table width='80%' cellpadding='5' border='1' bgcolor='#cccccc'>
<tr>
	<td>

	<b>WARNING:</b>

	<p>Passing information directly from the web browser to
	HTMLDOC can potentially expose your system to security
	risks. Always be sure to "sanitize" any input from the
	web browser so that filenames, URLs, and options passed
	to HTMLDOC are not acted on by the shell program or
	other processes.</p>

	</td>
</tr>
</table></center>

<h2>Using HTMLDOC as a CGI Program</h2>

<p>HTMLDOC 1.8.24 and higher supports operation as a CGI
program. You can copy or symlink the <var>htmldoc</var> (all but
Windows) or <var>htmldoc.exe</var> (Windows) executable to your
web server's <var>cgi-bin</var> directory and then use it to
produce PDF versions of your web pages.</p>

<p>The CGI converts a page on your local server to PDF and sends
it to the client's web browser. For example, to convert a page
called <var>superproducts.html</var> at the following URL:</p>

<pre>
    http://servername/superproducts.html
</pre>

<p>and if you installed HTMLDOC in your server's
<var>cgi-bin</var> directory, you would direct your clients to
the following URL:</p>

<pre>
    http://servername<b>/cgi-bin/htmldoc</b>/superproducts.html
</pre>

<p>The boldface portion represents the location of the
HTMLDOC executable on the web server. You simply place
that path before the page you want to convert.</p>

<p>Form data using the <code>GET</code> method can be passed at
the end of the URL, for example:</p>

<pre>
    http://servername/cgi-bin/htmldoc/superproducts.html<b>?name=value</b>
</pre>

<h3>Server-Side Preferences</h3>

<p>When run as a CGI program, HTMLDOC will try to read a
book file to set any preferences for the conversion to PDF. For
the <var>superproducts.html</var> file described previously,
HTMLDOC will look at the following URLs for a book
file:</p>

<pre>
    http://servername/superproducts.html.book
    http://servername/.book
    http://servername/cgi-bin/.book
</pre>

<p>The first book file that is found will be used.</p>

<h3>Configuring HTMLDOC with Apache</h3>

<p>The Apache web server is easily configured to use
HTMLDOC. The simplest way is to copy or symlink the
<var>htmldoc</var> executable to the configured
<var>cgi-bin</var> directory. For example, if your Apache
installation is configured to look for CGI programs in the
<var>/var/www/cgi-bin</var> directory, the default for Apache on
Red Hat Linux, then the command to install HTMLDOC on
your web server would be:</p>

<pre>
    <kbd>ln -s /usr/bin/htmldoc /var/www/cgi-bin ENTER</kbd>
</pre>

<p>If you are using Apache 2.0.30 or higher, you will also need
to enable <tt>PATH_INFO</tt> support by adding the following
line to your <var>httpd.conf</var> file:</p>

<pre>
    AcceptPathInfo On
</pre>

<p>Apache also allows you to associate CGI programs with a
specific extension. If you add the following line to your
<var>httpd.conf</var> file:</p>

<pre>
    AddHandler cgi-script .cgi
</pre>

<p>and enable CGI execution with the <tt>Options</tt> directive
for a directory:</p>

<pre>
    Options +ExecCGI
</pre>

<p>then you can copy or symlink the <var>htmldoc</var>
executable to an alternate location. For example, if you have a
web directory called <var>/var/www/htdocs/products</var>, you
can install HTMLDOC in this directory with the following
command:</p>

<pre>
    <kbd>ln -s /usr/bin/htmldoc /var/www/htdocs/products/htmldoc.cgi ENTER</kbd>
</pre>

<h3>Configuring HTMLDOC with Microsoft IIS</h3>

<p>The IIS web server is configured to run CGI programs by
either modifying the permissions of an existing directory or by
creating a new virtual directory that allows for execution of
programs. Start by running the <var>Internet Services
Manager</var> program (Figure 5-1):</p>

<ol>

	<li>Click on <var>Start</var></li>

	<li>Click on <var>Settings</var></li>

	<li>Click on <var>Control Panel</var></li>

	<li>Double-click on <var>Administrative Tools</var></li>

	<li>Double-click on <var>Internet Services Manager</var></li>

</ol>

<p>After the <var>Internet Services Manager</var> window (Figure
5-1) appears, perform the following steps to add a virtual
folder for HTMLDOC:</p>

<ol>

	<li>Click on your server in the list to show the default
	web site service in the list (Figure 5-2)</li>

	<li>Choose <var>New->Virtual Directory</var> from the
	<var>Action</var> menu (Figure 5-3)</li>

	<li>Click <var>Next</var> when the <var>Virtual Directory
	Creation Wizard</var> window appears (Figure 5-4)</li>

	<li>Enter the name <tt>htmldoc</tt> in the
	<var>Alias</var> field and click <var>Next</var> (Figure
	5-5)</li>

	<li>Enter the HTMLDOC program folder in the <var>Directory</var>
	field and click <var>Next</var> (Figure 5-6)</li>

	<li>Check the <var>Execute (such as ISAPI applications or CGI)</var>
	box and click <var>Next</var> (Figure 5-7)</li>

	<li>Click <var>Finish</var> to dismiss the wizard (Figure 5-8)</li>

</ol>

<p>If you are using IIS 6.0, proceed to the next section titled,
<a href="#IIS6.0">"Additional Configuration for IIS 6.0"</a>.</p>

<p align='center'><img src='htmldoc-fig51.png' width='600' alt='The Internet Services Manager Window'><br />
<i>Figure 5-1: The Internet Services Manager Window</i></p>

<p align='center'><img src='htmldoc-fig52.png' width='600' alt='The Default Web Site Service'><br />
<i>Figure 5-2: The Default Web Site Service</i></p>

<p align='center'><img src='htmldoc-fig53.png' width='600' alt='Adding a New Virtual Directory'><br />
<i>Figure 5-3: Adding a New Virtual Directory</i></p>

<p align='center'><img src='htmldoc-fig54.png' width='482' alt='The Virtual Directory Creation Wizard Window'><br />
<i>Figure 5-4: The Virtual Directory Creation Wizard Window</i></p>

<p align='center'><img src='htmldoc-fig55.png' width='482' alt='Entering the Alias Name'><br />
<i>Figure 5-5: Entering the Alias Name</i></p>

<p align='center'><img src='htmldoc-fig56.png' width='482' alt='Entering the HTMLDOC Program Folder'><br />
<i>Figure 5-6: Entering the HTMLDOC Program Folder</i></p>

<p align='center'><img src='htmldoc-fig57.png' width='482' alt='Enabling CGI Mode'><br />
<i>Figure 5-7: Enabling CGI Mode</i></p>

<p align='center'><img src='htmldoc-fig58.png' width='482' alt='Completion of IIS Configuration'><br />
<i>Figure 5-8: Completion of IIS Configuration</i></p>

<p>Once configured, the <var>htmldoc.exe</var> program will be
available in the web server directory. For example, for a
virtual directory called <var>cgi-bin</var>, the PDF converted
URL for the <var>superproducts.html</var> page would be as
follows:</p>

<pre>
    http://servername<b>/cgi-bin/htmldoc.exe</b>/superproducts.html
</pre>

<p>The boldface portion represents the location of the
HTMLDOC program on the web server.</p>

<h3><a name='IIS6.0'>Additional Configuration for IIS 6.0</a></h3>

<p>IIS 6.0 requires additional configuration steps due to its
increased focus on security. Start by running the <var>Internet
Services Manager</var> program (Figure 5-1):</p>

<ol>

	<li>Click on <var>Start</var></li>

	<li>Click on <var>Settings</var></li>

	<li>Click on <var>Control Panel</var></li>

	<li>Double-click on <var>Administrative Tools</var></li>

	<li>Double-click on <var>Internet Services Manager</var></li>

</ol>

<p>After the <var>Internet Services Manager</var> window (Figure
5-1) appears, perform the following steps to add a new Wed
Service Extension for HTMLDOC:</p>

<ol>

	<li>Click on <var>Web Service Extensions</var></li>

	<li>Click <var>Add a new Web Service Extension</var></li>

	<li>Enter the name "HTMLDOC" when the <var>Web Service
	Extension</var> window appears</li>

	<li>Click <var>Add...</var> and choose the
	<var>htmldoc.exe</var> file from the program folder,
	typically
	<var>C:\Program&nbsp;Files\Easy&nbsp;Software&nbsp;Products\HTMLDOC</var></li>

	<li>Check the <var>Set extension status to Allowed</var> box</li>

	<li>Click <var>OK</var> to add the extension and dismiss
	the window</li>

</ol>

<p>Finally, double-click the <var>My Computer</var> icon on the
desktop or start the <var>Windows Explorer</var>. When the
explorer window appears, perform the following steps to provide
write access to the Windows temporary folder:</p>

<ol>

	<li>Open the windows temporary file folder, typically
	<var>C:\WINDOWS\TEMP</var></li>

	<li>Choose <var>Properties</var> from the <var>File</var>
	menu</li>

	<li>Click on the <var>Security</var> tab</li>

	<li>Click <var>Add...</var>, enter the username for
	the web server, typically "SERVER\IUSR_SERVER"
	where "SERVER" is the name you gave your server,
	and click <var>OK</var></li>

	<li>Click on the username you just added in the list</li>

	<li>Check the <var>Read</var> and <var>Write</var>
	permissions</li>

	<li>Click <var>OK</var> to save the changes</li>

</ol>

<h2>Using HTMLDOC From Server-Side Scripts and Programs</h2>

<p>To make this work the CGI script or program must send the
appropriate HTTP attributes, the required empty line to signify
the beginning of the document, and then execute the HTMLDOC
program to generate the HTML, PostScript, or PDF file as needed.
Since HTMLDOC looks for CGI environment variables when it is run,
you must also set the <tt>HTMLDOC_NOCGI</tt> environment variable
to a value of 1 before running HTMLDOC from your CGI script or
program.</p>

<p>Another way to generate PDF files from your reports is to use
HTMLDOC as a "portal" application. When used as a portal,
HTMLDOC automatically retrieves the named document or
report from your server and passes a PDF version to the web
browser. See the next sections for more information.</p>

<!-- NEED 6in -->
<h3>Calling HTMLDOC from a Shell Script</h3>

<p>Shell scripts are probably the easiest to work with, but are normally
limited to GET type requests. Here is a script called
<var>topdf</var> that acts as a portal, converting the named file to PDF:</p>

<pre>
    #!/bin/sh
    #
    # Sample "portal" script to convert the named HTML file to PDF on-the-fly.
    #
    # Usage: http://www.domain.com/path/topdf/path/filename.html
    #

    #
    # Tell HTMLDOC not to run in CGI mode...
    #

    HTMLDOC_NOCGI=1; export HTMLDOC_NOCGI

    #
    # The "options" variable contains any options you want to pass to HTMLDOC.
    #

    options='-t pdf --webpage --header ... --footer ..."

    #
    # Tell the browser to expect a PDF file...
    #

    echo "Content-Type: application/pdf"
    echo ""

    #
    # Run HTMLDOC to generate the PDF file...
    #

    htmldoc $options http://${SERVER_NAME}:${SERVER_PORT}$PATH_INFO
</pre>

<p>Users of this CGI would reference the URL
"http://www.domain.com/topdf.cgi/index.html" to generate a PDF
file of the site's home page.</p>

<p>The <var>options</var> variable in the script can be set to use any
supported command-line option for HTMLDOC; for a complete list see
<a href='#CMDREF'>Chapter 8 - Command-Line Reference</a>.</p>

<!-- NEED 5in -->
<h3>Calling HTMLDOC from Perl</h3>

<p>Perl scripts offer the ability to generate more complex reports, pull
data from databases, etc. The easiest way to interface Perl scripts
with HTMLDOC is to write a report to a temporary file and then
execute HTMLDOC to generate the PDF file.</p>

<p>Here is a simple Perl subroutine that can be used to write a PDF report
to the HTTP client:</p>

<pre>
    sub topdf {
	# Get the filename argument...
	my $filename = shift;

	# Make stdout unbuffered...
	select(STDOUT); $| = 1;

	# Tell HTMLDOC not to run in CGI mode...
        $ENV{HTMLDOC_NOCGI} = 1;

	# Write the content type to the client...
	print "Content-Type: application/pdf\n\n";

	# Run HTMLDOC to provide the PDF file to the user...
	system "htmldoc -t pdf --quiet --webpage $filename";
    }
</pre>

<h3>Calling HTMLDOC from PHP</h3>

<p>PHP is quickly becoming the most popular server-side
scripting language available. PHP provides a
<code>passthru()</code> function that can be used to run
HTMLDOC. This combined with the <code>header()</code>
function can be used to provide on-the-fly reports in PDF
format.</p>

<p>Here is a simple PHP function that can be used to convert a HTML report
to PDF and send it to the HTTP client:</p>

<pre>
    function topdf($filename, $options = "") {
	# Tell HTMLDOC not to run in CGI mode...
        putenv("HTMLDOC_NOCGI=1");

	# Write the content type to the client...
	header("Content-Type: application/pdf");
	flush();

	# Run HTMLDOC to provide the PDF file to the user...
	passthru("htmldoc -t pdf --quiet --jpeg --webpage $options '$filename'");
    }
</pre>

<p>The function accepts a filename and an optional "options"
string for specifying the header, footer, fonts, etc.</p>

<p>To prevent malicious users from passing in unauthorized
characters into this function, the following function can be
used to verify that the URL/filename does not contain any
characters that might be interpreted by the shell:</p>

<!-- NEED 5in -->
<pre>
    function bad_url($url) {
	// See if the URL starts with http: or https:...
	if (strncmp($url, "http://", 7) != 0 &amp;&amp;
	    strncmp($url, "https://", 8) != 0) {
            return 1;
	}

	// Check for bad characters in the URL...
	$len = strlen($url);
	for ($i = 0; $i &lt; $len; $i ++) {
            if (!strchr("~_*()/:%?+-&amp;@;=,$.", $url[$i]) &amp;&amp;
		!ctype_alnum($url[$i])) {
		return 1;
	    }
	}

	return 0;
    }
</pre>

<p>Another method is to use the <code>escapeshellarg()</code>
function provided with PHP 4.0.3 and higher to generate a quoted
shell argument for HTMLDOC.</p>

<p>To make a "portal" script, add the following code to complete the
example:</p>

<pre>
    global $SERVER_NAME;
    global $SERVER_PORT;
    global $PATH_INFO;
    global $QUERY_STRING;

    if ($QUERY_STRING != "") {
	$url = "http://${SERVER_NAME}:${SERVER_PORT}${PATH_INFO}?${QUERY_STRING}";
    } else {
	$url = "http://${SERVER_NAME}:${SERVER_PORT}$PATH_INFO";
    }

    if (bad_url($url)) {
      print("&lt;html>&lt;head>&lt;title>Bad URL&lt;/title>&lt;/head>\n"
	   ."&lt;body>&lt;h1>Bad URL&lt;/h1>\n"
	   ."&lt;p>The URL &lt;b>&lt;tt>$url&lt;/tt>&lt;/b> is bad.&lt;/p>\n"
	   ."&lt;/body>&lt;/html>\n");
    } else {
      topdf($url);
    }
</pre>

<!-- NEED 5in -->
<h3>Calling HTMLDOC from C</h3>

<p>C programs offer the best flexibility and easily supports
on-the-fly report generation without the need for temporary
files.</p>

<p>Here are some simple C functions that can be used to generate
a PDF report to the HTTP client from a temporary file or
pipe:</p>

<pre>
    #include &lt;stdio.h&gt;
    #include &lt;stdlib.h&gt;


    /* topdf() - convert a HTML file to PDF */
    FILE *topdf(const char *filename)           /* I - HTML file to convert */
    {
      char	command[1024];			/* Command to execute */


     /*
      * Tell HTMLDOC not to run in CGI mode...
      */

      putenv("HTMLDOC_NOCGI=1");

     /*
      * Write the content type to the client...
      */

      puts("Content-Type: application/pdf\n");

     /*
      * Run HTMLDOC to provide the PDF file to the user...
      */

      sprintf(command, "htmldoc --quiet -t pdf --webpage %s", filename);

      return (popen(command, "w"));
    }


    /* topdf2() - pipe HTML output to HTMLDOC for conversion to PDF */
    FILE *topdf2(void)
    {
     /*
      * Tell HTMLDOC not to run in CGI mode...
      */

      putenv("HTMLDOC_NOCGI=1");

     /*
      * Write the content type to the client...
      */

      puts("Content-Type: application/pdf\n");

     /*
      * Open a pipe to HTMLDOC...
      */

      return (popen("htmldoc --quiet -t pdf --webpage -", "w"));
    }
</pre>

<!-- NEED 5in -->
<h3>Calling HTMLDOC from Java</h3>

<p>Java programs are a portable way to add PDF support to your web
server. Here is a class called <var>htmldoc</var> that acts as a
portal, converting the named file to PDF. It can also be called
by your Java servlets to process an HTML file and send the
result to the client in PDF format:</p>

<pre>
    class htmldoc
    {
      // Convert named file to PDF on stdout...
      public static int topdf(String filename)// I - Name of file to convert
      {
        String              command;          // Command string
        Process             process;          // Process for HTMLDOC
        Runtime             runtime;          // Local runtime object
        java.io.InputStream input;            // Output from HTMLDOC
        byte                buffer [];        // Buffer for output data
        int                 bytes;            // Number of bytes


        // First tell the client that we will be sending PDF...
        System.out.print("Content-type: application/pdf\n\n");

        // Construct the command string
        command = "htmldoc --quiet --jpeg --webpage -t pdf --left 36 " +
                  "--header .t. --footer .1. " + filename;

        // Run the process and wait for it to complete...
        runtime = Runtime.getRuntime();

        try
        {
          // Create a new HTMLDOC process...
          process = runtime.exec(command);

          // Get stdout from the process and a buffer for the data...
          input  = process.getInputStream();
          buffer = new byte[8192];

          // Read output from HTMLDOC until we have it all...
          while ((bytes = input.read(buffer)) > 0)
            System.out.write(buffer, 0, bytes);

          // Return the exit status from HTMLDOC...
          return (process.waitFor());
        }
        catch (Exception e)
        {
          // An error occurred - send it to stderr for the web server...
          System.err.print(e.toString() + " caught while running:\n\n");
          System.err.print("    " + command + "\n");
          return (1);
        }
      }

      // Main entry for htmldoc class
      public static void main(String[] args)// I - Command-line args
      {
        String server_name,                 // SERVER_NAME env var
               server_port,                 // SERVER_PORT env var
               path_info,                   // PATH_INFO env var
               query_string,                // QUERY_STRING env var
               filename;                    // File to convert


        if ((server_name = System.getProperty("SERVER_NAME")) != null &amp;&amp;
            (server_port = System.getProperty("SERVER_PORT")) != null &amp;&amp;
            (path_info = System.getProperty("PATH_INFO")) != null)
        {
          // Construct a URL for the resource specified...
          filename = "http://" + server_name + ":" + server_port + path_info;

          if ((query_string = System.getProperty("QUERY_STRING")) != null)
          {
            filename = filename + "?" + query_string;
          }
        }
        else if (args.length == 1)
        {
          // Pull the filename from the command-line...
          filename = args[0];
        }
        else
        {
          // Error - no args or env variables!
          System.err.print("Usage: htmldoc.class filename\n");
          return;
        }

        // Convert the file to PDF and send to the web client...
        topdf(filename);
      }
    }
</pre>

</div>

</body>
</html>