Build a Custom Importer [InfoPath 2003 SDK Documentation]

Applies to:

Microsoft Office InfoPath 2003 Service Pack 1

The Microsoft Office InfoPath 2003 Software Development Kit (SDK) custom importer code library contains components with which you can customize the Import Wizard to import legacy forms from other applications into InfoPath. This topic describes the interfaces you use to create the custom importer and discusses deployment requirements and a custom importer sample included with the SDK. The library containing the components and sample is located in the <drive>:\Program Files\Microsoft Office 2003 Developer Resources\Microsoft Office InfoPath 2003 SDK\CodeLibrary\InfoPathImporterCodeLib folder.

Custom importer interfaces

A custom importer must implement the IFormTemplateConverter interface, and uses the IConversionManager interface to communicate with the InfoPath Import Form user interface, as discussed in the following sections. A custom importer must be implemented as a Component Object Model (COM) object. InfoPath instantiates the custom importer object by using CoCreateInstance with the programmatic identifier (ProgID) stored in the Windows Registry.

The IFormTemplateConverter interface

What follows is the definition of the IFormTemplateConverter interface in Interface Definition Language (IDL) syntax.

[
    object,
    uuid(096cd700-0786-11d1-95fa-0080c78ee3bb),
    nonextensible,
    helpstring("IFormTemplateConverter Interface"),
    pointer_default(unique)
]
interface IFormTemplateConverter : IUnknown
{       
    HRESULT Initialize(
        [in]    IConversionManager* pConversionManager);

    HRESULT UnInitialize();
    
    HRESULT Convert(
        [in]    BSTR    srcPath, 
        [in]    BSTR    destPath,
        [out]   BSTR*   pMessage);

    HRESULT ShowOptionsDialog();

    HRESULT SetLcid(
        [in]    UINT    lcid);
};  

The following table describes the members of the IFormTemplateConverter interface.

The Initialize function is called before the Convert function. The Uninitialize function is called after the Convert function.

Note  Dialogs should only be shown when called via ShowOptionsDialog. The options dialog should be a modal dialog. To make the dialog modal, the Win32 function GetActiveWindow() should be used to get the HWND handle and make that window the dialog's parent window.

The IConversionManager interface

What follows is the definition of the IConversionManager interface in Interface Definition Language (IDL) syntax.

typedef enum preference
{
    prefNil = 0,
    prefSupportProgressDialog = 1,
    prefSupportOptionsDialog = 2,
} ConversionPreference;

[
    object,
    uuid(096cd703-0786-11d1-95fa-0080c78ee3bb),
    nonextensible,
    helpstring("IConversionManager Interface"),
    pointer_default(unique)
]
interface IConversionManager : IUnknown{

    [propget] HRESULT ProductVersion(
        [out, retval]   BSTR*   pProductVersion);

    HRESULT SetPreference(
        [in]    ConversionPreference    conversionPreference);
        
    HRESULT SetProgressDialogPosition(
        [in]    UINT    position);
    
    HRESULT SetProgressDialogCaption(
        [in]    BSTR    caption);
};

The following table describes the members of the IConversionManager interface.

Requirements to deploy a custom importer

Before you can use a custom importer, the importer DLL must be registered, just as any other COM DLL on the computer. The DLL can be registered on a user's computer by using a setup program or by running the Regsvr32.exe command-line utility that is included with Microsoft Windows.

InfoPath uses a set of Windows Registry entries to detect the presence of a custom importer. When a custom importer is installed on a computer, a minimum of two Windows Registry keys must be created. The registry keys must be created under the following key:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\InfoPath\Converters\Import

The Programmatic Identifier Key

The first key that must be created identifies the custom importer by its programmatic identifier (ProgID). The following table describes this registry key and required values.

The LCID Key

This key is created below the custom importer's ProdID key. The following table describes this registry key and required values.

Build the custom importer sample

A custom importer sample included in this SDK demonstrates how to create a custom importer for InfoPath. The sample imports text (.txt) files into InfoPath.

Note  Microsoft Visual Studio .NET 2003 is required to build the custom importer.

To build the sample custom importer, open the InfoPathImporterCodeLib.sln file that is located in the <drive>:\Program Files\Microsoft Office 2003 Developer Resources\Microsoft Office InfoPath 2003 SDK\CodeLibrary\InfoPathImporterCodeLib folder. Then, click Build Solution on the Build menu. By default, the sample custom importer InfoPathImporterCodeLib.dll will be built in the <drive>:\Program Files\Microsoft Office 2003 Developer Resources\Microsoft Office InfoPath 2003 SDK\CodeLibrary\InfoPathImporterCodeLib\Debug folder.

Once you have built the custom importer, you must add the required values to the Windows Registry. The following table lists the required keys to be created under the key:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\InfoPath\Converters\Import

Follow these steps to use the custom text file importer:

1. In design mode, click Import Form on the File menu.

2. Click Sample Text Importer in the Select the import method to use list on the first page of the Import Wizard and then click Next.

3. Click Browse. Locate the text file that you want to import and then click Open.

4. Click Finish.

   The Import Wizard displays the status of the import operation.

5. Click Close.

Note  This object model member is not supported when the Disable Service Pack features option on the Advanced tab of the Options dialog box in InfoPath is selected or when Microsoft Office 2003 Service Pack 1 or later is not installed. Any form that implements this object model member in its code will generate an error message if it is opened in InfoPath when service pack features are disabled or unavailable.