Programming with the Microsoft.HtmlTrans.Interface Namespace

Using the Microsoft.HtmlTrans.Interface Namespace

A user may request a document from a document library without having an application capable of displaying the requested document installed on his or her client computer. Windows SharePoint Services provides the Microsoft.HtmlTrans namespace as an infrastructure on which to build custom converter applications, which delivers an HTML version of the requested document to the user in these circumstances in place of the unrecognized binary file format.

Caution  The HTML Viewer feature must be enabled in SharePoint Central Administration in order to use this functionality.

The Microsoft.HtmlTrans namespace consists of two interfaces, IHtmlTrLoadBalancer and IHtmlTrLauncher. An implementation of these interfaces also relies on an XML configuration file, called htmltransinfo.xml, which resides on the server running Windows SharePoint Services.

• The IHtmlTrLoadBalancer interface helps to select the server on which to run the custom converter application.
• The IHtmlTrLauncher interface launches the custom converter application and returns the HTML results to Windows SharePoint Services.
• The htmltransinfo.xml file redirects the document request to an handler page, which calls the load balancer and launcher components. The following iexample of the .xml configuration file shows the entries for Microsoft Office   2003 document types used in conjunction with the custom Microsoft Office HTML conversion tool that is supplied as part of the Office   2003 Resource Kit:

<HtmlTrInfo>
    <Mapping Extension="xls" AcceptHeader="application/vnd.ms-excel" HandlerUrl="HtmlTranslate.aspx" ProgId="SharePoint.OpenDocuments.2"/>
    <Mapping Extension="doc" AcceptHeader="application/msword" HandlerUrl="HtmlTranslate.aspx"  ProgId="SharePoint.OpenDocuments.2"/>
    <Mapping Extension="ppt" AcceptHeader="application/vnd.ms-powerpoint" HandlerUrl="HtmlTranslate.aspx"  ProgId="SharePoint.OpenDocuments.2"/>
    <Mapping Extension="pps" AcceptHeader="application/vnd.ms-powerpoint" HandlerUrl="HtmlTranslate.aspx"  ProgId=""/>
</HtmlTrInfo>

How the Microsoft.HtmlTrans Namespace Works

The following sequence of events occurs when a user requests a document from a server running Windows SharePoint Services:

1. Windows SharePoint Services identifies the file extension of the document in the htmltransinfo.xml file. If found, Windows SharePoint Services retrieves the matching AcceptHeader attribute; if not found, Windows SharePoint Services prompts the user to download the document.
2. Windows SharePoint Services checks the AcceptHeader attribute value against the Accept-Header HTTP header of the request to see whether the client computer recognizes the requested document type. If so, Windows SharePoint Services delivers the document in its native format.
3. Windows SharePoint Services also retrieves the ProgId attribute from the htmltransinfo.xml file and attempts to open the file on the client computer by using the component designated by the ProgId. If this attempt fails, Windows SharePoint Services continues with the HTML conversion process.
4. If the client computer does not recognize the requested document type, Windows SharePoint Services prompts the user: “Do you want to convert the document for viewing in the browser?� If the user chooses not to convert the document, Windows SharePoint Services prompts the user to download the document instead.
5. If the user chooses to convert the document, Windows SharePoint Services forwards the request to the handler page specified by the HandlerUrl attribute in the htmltransinfo.xml file. The handler page manages the conversion process and delivers the converted file to the user for viewing in the browser.

Options for Implementing Custom Document Conversion

Every implementation of custom document conversion on the Windows SharePoint Services platform requires at least the following features:

• An entry in the htmltransinfo.xml file for the document type
• A handler page that launches the document conversion process and returns the HTML output to the user
• A set of custom conversion components

You must choose among three methods to build the set of custom conversion components:

1. Build custom implementations of the IHtmlTrLoadBalancer and IHtmlTrLauncher interfaces to launch a custom converter application and return its results to Windows SharePoint Services.
2. Build a set of custom conversion components that do not use the Microsoft.HtmlTrans interfaces at all.
3. Call the custom implementations of the IHtmlTrLoadBalancer and IHtmlTrLauncher interfaces provided as part of the Office   2003 Resource Kit and provide a custom converter application for the IHtmlTrLauncher implementation to call.