Guidelines for Creating InfoPath 2007 Converters

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Summary: Learn how to create InfoPath 2007 converters for importing data from other types of forms and data sources, and for importing and exporting form templates from other form file formats. (24 printed pages)

Microsoft Corporation

May 2007

**Applies to:**Microsoft Office InfoPath 2007

Contents

• Overview of Converters in InfoPath 2007

• Converter Types and Examples

• Converter Development Scenarios

• Converter Requirements

• Accessing Converters

• Creating Form Template Importers and Exporters

• Creating Form Data Importers

• Conclusion

• Additional Resources

Overview of Converters in InfoPath 2007

Microsoft Office InfoPath 2007 includes enhancements that enable you to access external converter applications within InfoPath. Converter applications can import data into forms as they are filled out and import and export form templates as they are designed. At Microsoft Office Marketplace, customers can obtain converters and other products and services that work with Microsoft Office products.

Benefits of using InfoPath converters include the following:

• The converters can be accessed from within InfoPath.

• The InfoPath framework provides information to help import forms and data.

• The imported forms and data are available immediately after import.

InfoPath converters fall into two categories:

• Form template importers and exporters

• Data importers

This article describes the goals of InfoPath converter applications, how converters are built, and how you can access them in Office InfoPath 2007.

Converter Types and Examples

Form template importers were introduced in Microsoft Office InfoPath 2003 Service Pack 1, and support for them has been expanded in Office InfoPath 2007. A form template importer enables an external application to create an InfoPath form template by converting a file from another format. For example, a form template importer could create an InfoPath form template from a paper form, an HTML page, or another application's format.

Office InfoPath 2007 includes form template importers for Microsoft Office Word forms and Microsoft Office Excel forms. Both importers were created by using the InfoPath converter framework described in this article. To use these importers, start designing a form template in InfoPath, and then click Import in the Design a Form Template dialog box. Alternatively, if you are already designing a blank form template, click Import Form on the File menu. For more information about using the Word importer, see Convert a Word document to an InfoPath form template.

Form template exporters are new to InfoPath 2007. You can use them to export InfoPath form templates into third-party file formats.

Data importers bring data from completed forms in other formats into an InfoPath form. Examples of data that can be imported include scanned paper forms, faxes received electronically, and forms or documents in another file format.

Form template importers and data importers can be designed to work with the same formats: one creates a blank form, and another imports filled-in forms. They can also be designed to do only one of the two tasks.

Form Template Importer Example

Wingtip Toys has many paper forms that track factory floor production information. They want to deploy portable computers that contain InfoPath forms to collect this information. To create matching InfoPath forms quickly, they use a form template importer. It is designed to scan paper forms and create InfoPath form templates that have a similar layout and also have InfoPath features such as editing controls.

Data Importer Example

Wingtip Toys also has many completed paper forms in storage. They want an easy way to move these forms into their new computer system as InfoPath forms. They create an InfoPath form template that matches their existing paper form. Using a data importer, they can scan existing paper documents and insert the recognized text into InfoPath forms.

Converter Development Scenarios

Microsoft wants users who currently have forms and data in other formats to be able to easily move their processes into InfoPath forms. Importers should have broad appeal to InfoPath users, and they should accurately import the formats they support. Importers should extend and add value to the InfoPath system.

Paper Forms

InfoPath 2007 does not give users functionality that helps them directly interact with paper forms. But with an appropriately designed form template importer, you can treat a paper form as a template for creating an InfoPath form template. Similarly, with an appropriately designed data importer, you can convert paper forms that contain data into InfoPath forms.

You can scan a paper form as part of the import process and then create an InfoPath form template that has a similar layout. The boxes on the paper form would be replaced with controls, and a data source would contain fields with names derived from names on the paper. You could also create a data importer to scan matching paper forms and copy recognized text from the paper forms into corresponding InfoPath electronic forms.

Electronic Forms

Users can create electronic forms in several applications. These applications can have specific form design functionality. An InfoPath form template importer for the application's form file format interprets the layout and functionality of the form, such as controls or typing areas, and creates an InfoPath 2007 form template.

Likewise, you could use a data importer to move information into InfoPath forms from completed electronic forms in other applications.

HTML Forms

You could also have an importer for HTML or ASP.NET forms. A form template importer could create an InfoPath form template with the same layout, connect the form to the same data sources, and perhaps preserve some business logic in the form. In this scenario, you probably would not need to convert existing data because that data would already be in a database.

Converter Requirements

Anyone can apply to have a product listed on Office Marketplace. For an overview, including how to join, see Become an Office Marketplace provider. For an introduction to the requirements for products on the Office Marketplace, see Requirements and instructions for applying to the Office Marketplace.

Figure 1 shows an example of how you can connect to the Office Marketplace from InfoPath.

Figure 1. Linking to install a new converter

Installation Support

In addition to meeting all the requirements set forth by Office Marketplace, InfoPath converter applications must provide the following:

• A Web site where users can obtain the software.

• An installer application to configure the software for use in InfoPath.

• Customer support for troubleshooting problems with the converter.

• Support for the application in future versions of Microsoft Office.

Testing Converters Before Release

Regarding testing, converter providers must do the following:

• Test the behavior of their importer software, Web site, and installer application.

• Provide a copy of the software, with any necessary licenses, to be used by Office testers to enable them to provide feedback before its release.

Released Product Support

Converter providers must provide a dedicated contact for questions that arise while the functionality of the importer is being verified. When the product is released to customers, converter providers must also provide online or telephone customer help and easy-to-use Help content.

Reliability and Error Handling

Converters must be able to reliably import or export at least one file format, and they should provide useful error messages whenever necessary. Converters must also meet the following user expectations of InfoPath forms:

• Original form layout should be preserved.

• Forms can make use of relevant InfoPath features, such as binding text values to Text Box controls, and binding dates to Date Picker controls.

• Forms can be further designed and completed in InfoPath.

Security

The converter should not disclose personal information in unauthorized ways. In addition, all COM objects exposed by your converter should be marked as unsafe for initialization and scripting so that they cannot be used by a malicious Web page.

Accessing Converters

You can access form template importers and exporters while you are designing form templates, and you can access data importers while you are completing forms. InfoPath provides a similar user experience for both kinds of importers. Figure 2 shows the Import Wizard dialog box with the Microsoft Office Word Form form template converter selected.

Figure 2. Form Template Import Wizard

Figure 3 shows the Import Form Data dialog box, which provides access to form data importers after a user installs them.

Figure 3. Import Form Data dialog box

Installing Converters

The installation process for both types of importers is very similar. You should install importers through an installer application. The installer is responsible for putting the relevant applications and libraries on your system, registering them for use with Microsoft Windows, and registering those libraries for use with InfoPath.

Converter Scenario

Tali has a stack of paper forms that take up space in filing cabinets and are difficult to find information in. She recently installed InfoPath 2007 and wants to move those forms and their data into InfoPath. She uses the Import Form command on the File menu to connect to Office Marketplace, where she discovers a variety of importers.

Tali successfully downloads and installs a converter that promises to import her paper forms. After installation, she restarts InfoPath, opens the Import Wizard, and sees the Contoso importer, as shown in Figure 4.

Figure 4. Selecting the Contoso Paper to InfoPath Form Importer

Tali can then select a file to import. In this case, she selects a scanned image in TIFF format, as shown in Figure 5. She can also set options by using the dialog box provided by the importer.

Figure 5. Selecting the file to import

After Tali clicks Finish, the importer interprets the source file and creates an InfoPath form template. The template opens so that she can continue editing. After she creates the form template, she installs a data importer, which can accept a scanned paper form as input. It uses the data from the form to complete an instance of the InfoPath form.

Tali opens a blank form and starts the Import Form Data wizard. She selects the data importer that she installed, and clicks Next. When prompted, she scans in the form to be converted. In the data importer user interface, she can correct the scanned-in data as needed. She clicks a button, and the importer fills the empty InfoPath form with the data from the paper form. Tali saves the InfoPath form and continues to import the rest of her paper forms.

Creating Form Template Importers and Exporters

Form template converters specify a list of file types they support, and they parse those file types to produce an InfoPath form template with manifest (.xsf), view (.xsl), and other files that make up an InfoPath form template file (.xsn).

To view the kinds of files that an InfoPath form template contains, create or open a form template in design mode, and then click Save as Source Files on the File menu. For information about the schema of the InfoPath form definition file (manifest.xsf), see the InfoPath 2007 XSF Schema Reference.

Figure 6 shows the workflow for an InfoPath form template importer.

Figure 6. Form template importer workflow

The form template converter should be a standard Automation object. The IPDESIGN.dll that is installed in C:\Program Files\Microsoft Office\Office12 provides the type library that exposes the interfaces that are required to create a form template converter. InfoPath 2007 should be able to create the converter object by using the CoCreateInstance function with the ProgID stored in the registry. The form template converter implements the interfaces provided by the InfoPath converter framework to create the basic functions of the converter such as Initialize(), Import(), Export(), and UnInitialize().

Converter Framework Versioning

To show or hide converters in a given version of InfoPath, InfoPath must be able to determine the versions of the converter framework that are supported by the converter. A converter can support multiple versions of the converter framework.

Supporting a version of the converter framework implies that the converter does the following:

• Implements a specific COM interface.

• Produces a specific file format version when called through that interface.

Table 1 lists the versions of the framework that exist with InfoPath 2007.

Table 1. Converter framework versions

Converter Framework Version	Interface Version	File Format Version	Included With
11.0	IFormTemplateConverter	InfoPath 2003	InfoPath 2003 Service Pack 1 and later
12.0	IFormTemplateConverter2	InfoPath 2007	InfoPath 2007

InfoPath 2007 can use converters that support either version 11.0 or version 12.0 of the framework. For converters that support both versions, only the IFormTemplateConverter2 (version 12.0) interface is used.

InfoPath 2003 supports only version 11.0 of the framework. Because framework versioning is new in InfoPath 2007, InfoPath 2003 displays all converters regardless of version; however, converters that do not implement the IFormTemplateConverter interface will not function correctly.

Future versions of InfoPath will support one or more versions of the converter framework. Converters that correctly register their supported versions will be shown in the versions of InfoPath that also support that version of the framework. InfoPath has not determined an deprecation policy for framework versions.

Form Template Converter Registry Entries

When the converter is installed on a user's computer, it should add registry information in addition to the standard COM registration entries. Installation of converters is in the HKEY_LOCAL_MACHINE branch of the registry, so users are expected to have software installation permissions. InfoPath uses the information in the registry to load the converter and display converter properties.

Converters can be installed in one or both of the registry branches, depending on their capabilities.

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\Infopath\Converters\Import\ConverterProgID

or

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\Infopath\Converters\Export\ConverterProgID

Converters are symmetrical, so both the import key and the export key must contain the following information.

@DefaultLCID

\LCID

@Name

@Description

@Extensions

@ExtensionsDescription

\Versions

Table 2 describes the registry entries for an InfoPath converter.

Table 2. Converter registry entries

Name	Type	Max Len	Description
ConverterProgID	key	39 (COM limit)	COM ProgID of the converter. InfoPath uses this information to load the converter.
DefaultLCID	REG_DWORD	LONG	Default LCID to use if the converter does not support the current LCID used in InfoPath. For example, the DefaultLCID is 1033 and the current LCID is 1034, so InfoPath loads the strings stored under key 1033.
LCID	key	LONG	Locale ID. For example, the US English LCID is 1033. Gives the converter an option to support multiple languages.
Name	REG_SZ	64	Display name of the converter.
Description	REG_SZ	128	Description of the converter
Extensions	REG_SZ	32	File name extensions that the converter can handle, separated by a space, for example, "doc dot."
ExtensionsDescription	REG_SZ	64	Description of the file name extensions that the converter can handle, for example, "Microsoft Office Word forms."
Versions	key	Not applicable	The Versions key contains one REG_SZ value for each version of the converter framework supported by the converter. For example, a converter that supports version 11.0 and version 12.0 of the framework would contain the following \Versions @11.0 @12.0 The value of these string values is not significant and should be left blank. InfoPath considers only the name of the string value when determining the converters to display. If the Versions key is omitted, the converter is assumed to support only version 11.0 of the framework. If the Versions key exists but is empty, the converter is not displayed in InfoPath 2007 or future versions.

Important
When a form template converter is uninstalled, it should remove these registry keys and any program files that were created during installation.

IFormTemplateConverter2 Interface

All form template converters must implement the IFormTemplateConverter2 interface.

The following listing shows the Interface Definition Language (IDL) definition for the IFormTemplateConverter2 interface.

[
    object,
    uuid(096cd705-0786-11d1-95fa-0080c78ee3bb),
    dual, nonextensible,
    helpstring("IFormTemplateConverter2 Interface"),
    pointer_default(unique)
]
interface IFormTemplateConverter2 : IDispatch
{
     [id(DISPID_IFORMTEMPLATECONVERTER2_INITIALIZE)]
    HRESULT Initialize(
         [in]    IConversionManager*    pConversionManager);

     [id(DISPID_IFORMTEMPLATECONVERTER2_UNINITIALIZE)]
    HRESULT UnInitialize();
    
     [id(DISPID_IFORMTEMPLATECONVERTER2_IMPORT)]
    HRESULT Import(
         [in]    BSTR            srcPath, 
         [in]    BSTR            destPath,
         [in]    VARIANT_BOOL        vfShowUI,
         [out]    BSTR*    pMessage);

    [id(DISPID_IFORMTEMPLATECONVERTER2_EXPORT)]
    HRESULT Export(
        [in]    BSTR             srcPath, 
        [in]    BSTR             destPath,
        [in]    VARIANT_BOOL        vfShowUI,
        [out]    BSTR*            pMessage);

    [id(DISPID_IFORMTEMPLATECONVERTER2_SHOWOPTIONSDLG)]
    HRESULT ShowOptionsDialog(
        [in]    long             lHwnd, 
        [in]    VARIANT_BOOL        fExporting);

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

Note

The IFormTemplateConverter2 interface supersedes the IFormTemplateConverter interface from InfoPath 2003 Service Pack 1. IFormTemplateConverter is deprecated in InfoPath 2007, but it is still present. Existing converters that implement IFormtemplateConverter will continue to work in InfoPath 2007. New converters should implement IFormTemplateConverter2, and optionally, they can implement IFormTemplateConverter if InfoPath 2003 compatibility is desired. IFormTemplateConverter is documented in Build a Custom Importer [InfoPath 2003 SDK Documentation].

Table 4 provides links to topics that document the methods of the IFormTemplateConverter2 interface.

Table 4. IFormTemplateConverter2 interface methods

Method	Description
Export	Converts an InfoPath form template to a provider-defined format.
Import	Converts a provider-defined format to InfoPath form template files.
Initialize	Initializes the custom importer or exporter.
ShowOptionsDialog	Displays a custom Import Options dialog box to the user when the Options button is clicked in the last step of the wizard.
SetLcid	Sets the language used by the custom importer or exporter.
UnInitialize	Uninitializes the custom importer or exporter.

IConversionManager Interface

The IConversionManager interface is implemented by InfoPath and is available to converters during import or export.

The following listing shows the IDL definition for the IConversionManager interface.

enum ConversionPreference
{
    prefSupportProgressDialog = 1,
    prefSupportOptionsDialog = 2,
};
[
    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);
};
[
    object,
    uuid(096cd704-0786-11d1-95fa-0080c78ee3bb),
    nonextensible,
    helpstring("IConversionManager2 Interface"),
    pointer_default(unique)
]

Table 5 provides links to topics that document the members of the IConversionManager interface.

Table 5. IConversionManager interface members

Property/Method	Description
ProductVersion property	Gets the current version of InfoPath.
SetPreference method	Sets the preferences of the custom importer.
SetProgressDialogCaption method	Sets the caption of the Import Progress dialog box.
SetProgressDialogPosition method	Sets the value of the Progress bar in the Import Progress dialog box.

Note
The IConversionManager interface exists in both InfoPath 2003 and InfoPath 2007.

IConversionManager2 Interface

The IConversionManager2 interface was added in InfoPath 2007. It extends the IConversionManager interface to enable callers to set the status text in the Import Progress dialog box.

interface IConversionManager2 : IUnknown{
    HRESULT SetProgressDialogStatus(
        [in]    BSTR     caption);
}

Table 6 provides a link to the single method topic of the IConversionManager2 interface.

Table 6. IConversionManager2 interface member

Method	Description
SetProgressDialogStatus method	Sets the window text of the Import Progress dialog box in the InfoPath 2007 Import Wizard.

Error Handling

If errors occur during conversion, converters should return an error code and populate the IErrorLog object. Users can view the error information stored in the IErrorLog object.

Design Checker Messages

Form template import converters can specify messages to be shown in the Design Checker task pane after a successful import. Messages appear in the Design Checker task pane any time it is shown, until you remove the ImportErrors.xml file from the form template using the Resource Files command on the Tools menu.

An importer typically uses Design Checker messages to warn the user about parts of the form template that might not have imported as expected, or to give the user instructions for the next steps in creating a form template.

InfoPath reads Design Checker messages from the ImportErrors.xml file, which the converter includes in the form template. If the file is not present, InfoPath does not show import errors. If the file is present, InfoPath displays messages in the Design Checker task pane, subject to the following limits:

• Maximum Errors per file: 200

• Maximum text in an error: 512 characters

The following listing shows a sample ImportErrors.xml file.

<importErrors xmlns="http://schemas.microsoft.com/office/infopath/2006/ImportErrors">
  <view name="View 1">
    <errorCategory categoryId="0" name="">
      <importError shortErrorString="Object of type OLEObject was replaced by a placeholder">
The embedded object of type Word.Picture.8 in the Microsoft Office Word file cannot be imported.      
      </importError>
      <importError shortErrorString="Object may be positioned incorrectly">
The correct position of the floating object cannot be determined.
      </importError>
      <importError shortErrorString="Object may be positioned incorrectly">
The correct position of the floating object cannot be determined.
      </importError>
      <importError shortErrorString="Object may be positioned incorrectly">
The correct position of the floating object cannot be determined.
      </importError>
      <importError shortErrorString="Object may be positioned incorrectly">
The correct position of the floating object cannot be determined.
      </importError>
      <importError shortErrorString="Error importing page borders">
InfoPath does not support setting borders for the page.
      </importError>
    </errorCategory>
  </view>
</importErrors>

Figure 7 shows how the resulting messages are displayed in the Design Checker task pane.

Figure 7. Import messages in the Design Checker task pane

Table 7 describes the elements and attributes in the ImportErrors.xml file.

Table 7. Elements and attributes of the ImportErrors.xml file

Name	Type	Description
importErrors	element	Root element for the file. The target namespace must be http://schemas.microsoft.com/office/infopath/2006/ImportErrors
view	element	Specifies the view that the enclosed errors apply to.
view/@name	Attribute	Name of the view.
errorCategory	element	Category for the errors. In InfoPath 2007, only one category is allowed per file.
errorCategory/@categoryId	attribute	Must be "0".
errorCategory/@name	attribute	Name of the error category. Reserved for future use; ignored in InfoPath 2007.
importError	element	Specifies one Design Checker warning. The content of this element is the text shown when the short error string is clicked in the Design Checker task pane.
importError/@shortErrorString	attribute	The short error string shown in the Design Checker task pane.

The following code listing shows the InfoPath form definition file (manifest.xsf) entries to expose the ImportErrors.xml file.

<xsf:file name="ImportErrors.xml">
  <xsf:fileProperties>
    <xsf:property name="fileType" type="string" value="resource">
    </xsf:property>
    <xsf:property name="filePurpose" type="string" value="ImportErrors">
    </xsf:property>
    <xsf:property name="displayOnLoad" type="string" value="yes">
    </xsf:property>
  </xsf:fileProperties>
</xsf:file>

Note
You can copy the manifest.xsf file entry for ImportErrors.xml from this example.

Creating Form Data Importers

Form data importers are used to bring data from a completed form in another format into an InfoPath form. An example might be a stack of paper forms that you need to scan and then insert the text into an InfoPath form.

Figure 8 shows the workflow for a data importer to import data from paper forms.

Figure 8. Form data importer workflow

Form template importers receive limited control over the user experience. They have access only to an Options dialog box and an Import Progress dialog box. However, to allow for importing data directly from a source, form data importers allow the importer to display whatever user interface is necessary: File Open dialog boxes, custom data import dialog boxes, and progress dialog boxes.

The IPEDITOR.dll installed in C:\Program Files\Microsoft Office\Office12 provides the type library that exposes the interfaces required to create a form data importer.

Data Importer Installation Registry Entries

Data importers must be registered by creating a registry key with the ProgID of the importer. They must register under the HKEY_LOCAL_MACHINE registry branch. The importer itself should be a standard COM object.

InfoPath uses the list of ProgID values at this location to determine the importers that are available to the user, and to create the COM object.

HKEY_LOCAL_MACHINE

\SOFTWARE\Microsoft\Office\12.0\InfoPath\Data Importers\ImporterProgID

Table 8 describes the InfoPath data importer registry key.

Table 8. InfoPath data importer registry key

Name	Type	Length	Description
ImporterProgID	key	39	COM ProgID of the importer. InfoPath uses this information to load the importer.

InfoPath uses the name and description data under each importer's ProgID to display information to the user. InfoPath looks for an LCID key for the current Office language to retrieve the name and description.

There can be any number of LCID values to provide localized resources to the Import Form Data wizard. If there is no LCID for the current Office language, InfoPath references the DefaultLCID value to determine what language to use. If there is no DefaultLCID, the converter is not listed.

Used Name/Value pairs:

HKEY_LOCAL_MACHINE

\SOFTWARE\Microsoft\Office\12.0\InfoPath\Data Importers\ImporterProgID\

@DefaultLCID

and

\SOFTWARE\Microsoft\Office\12.0\InfoPath\Data Importers\ ImporterProgID\LCID

@Name

@Description

Table 9 describes the InfoPath data importer LCID registry keys and values.

Table 9. InfoPath data importer LCID registry keys and values

Name	Type	Length	Description
DefaultLCID	REG_SZ		LCID to retrieve localized names and descriptions from if current Office language is not supported.
LCID	Key		No limit on number of supported locales. There must be an LCID entry for the DefaultLCID value.
Name	REG_SZ	64	Used to display the name to the user.
Description (Optional)	REG_SZ	255	Displays information about the converter being used.

Long Strings   Names longer than 64 characters are not listed, and descriptions longer than 255 characters are truncated.

Missing Name   The importer is not listed.

Missing Description   No text is shown.

IInfoPathDataImporter Interface

Implement the IInfoPathDataImporter interface to create a custom data importer.

The following listing shows the IDL definition for the IInfoPathDataImporter interface.

[
object,
uuid(096cd6d9-0786-11d1-95fa-0080c78ee3bb),
helpstring("IInfoPathDataImporter Interface"),
pointer_default(unique),
nonextensible
]
interface IInfoPathDataImporter : IUnknown
{
HRESULT Initialize(
[in] UINT            lcid);
 
HRESULT Import(
[in] IPropertyBag*        pPrintSettings,
[in] IEnumUnknown*        punkViewControls );
 
HRESULT Uninitialize();
};

Initialization

After the user selects the importer to use, InfoPath starts it by calling the required Initialize method. The importer could fail at this point because of missing system resources, invalid license, or other checks.

Localizability

To allow each importer to target multiple locales, InfoPath provides the locale as an Initialize method parameter for the importer. The importer can choose to display a localized user interface or implement a fallback locale, such as English – International.

Import Method

The Import method provides access to the form's controls collection and print settings. This method is called one time per importer instance.

The converter might not support the current locale, but the developer of the converter must determine whether it is appropriate to fall back to the default language, fall back to another language, or fail to run.

IPropertyBag Interface

The property bag that is implemented using the IPropertyBag interface passes print setting information to the converter. It has read-only access.

The following listing shows the IDL definition for the IIPropertyBag interface.

Interface IPropertyBag
{
    HRESULT Read( 
        LPCOLESTR pszPropName, 
        VARIANT* pVar, 
        IErrorlog* pErrorLog);

    // This will return E_ACCESSDENIED
    HRESULT Write( 
        LPCOLESTR pszPropName, 
        VARIANT* pVar);
}

Print Settings

The print settings allow a data importer to make assumptions about how the form might be printed from InfoPath to paper. Because the user can change the values at print time, only the form's default print settings are given and not the actual print-time settings.

Table 10 describes the properties provided for print settings.

Table 10. Print settings properties

Property	Description
PageSize	Returns an unparsed string that corresponds to the current page size: A4, B4, Letter, and so on.
TopMargin	numeric
BottomMargin	numeric
LeftMargin	numeric
RightMargin	numeric
MarginUnitsType	in or cm

Note
These values might not be available if the user has no installed printers.

Controls Collection

The controls collection provides an ENUM for accessing individual IInfopathViewControl objects that represent the controls in the current view. The collection is generated at the time that the importer is created. It is not updated during the import process.

The controls collection does not provide access to higher-level InfoPath controls, such as Optional Section, Repeating Section, or Repeating Table controls. Table 11 provides the complete list of included and excluded controls in the collection.

Table 11. Included and excluded controls

Included Controls	Excluded Controls
Textbox	Section
Rich Text Box	Optional Section
Drop-Down List Box	Repeating Section
List Box	Repeating Table
Date Picker	Master/Detail
Check Box	Expression Box
Option Button	Vertical Text
Bulleted List	Button
Numbered List	Hyperlink
Plain List	Scrolling Region
Picture	Choice Group
Ink Picture	Repeating Choice Group
File Attachment	Choice Section
Combo box	Repeating Recursive Section
	Custom Controls (ActiveX)
	Multi-select

IInfopathViewControl Object

Implement the IInfoPathViewControl interface to represent a control present in the imported view.

The following listing shows the IDL definition for the IInfoPathViewControl interface.

[
object,
uuid(096cd6da-0786-11d1-95fa-0080c78ee3bb),
helpstring("IInfoPathViewControl Interface"),
pointer_default(unique),
nonextensible
]

interface IInfoPathViewControl : IUnknown
{
[propget]
HRESULT Left(
[out, retval]    long*        plLeft);

[propget]
HRESULT Top(
[out, retval] long* plTop);

[propget]
HRESULT Width(
[out, retval] long* plWidth);

[propget]
HRESULT Height(
[out, retval] long* plHeight);

[propget]
HRESULT ControlType(
[out, retval] BSTR* pbstrControlType);

[propget]
HRESULT DataType(
[out, retval] BSTR* pbstrDataType);

[propget]
HRESULT NodeName(
[out, retval] BSTR* pbstrNodeName);

[propget]
HRESULT Value(
[out, retval] BSTR* pbstrValue);

[propput]
HRESULT Value(
    [in] BSTR bstrValue);

};

Table 12 describes the properties of an IInfopathViewControl object.

Table 12. Properties of an IInfopathViewControl object

Property	Type	Limit	Description
Top	LONG	None	Offset of the control from the top of the view.
Bottom	LONG	None	Offset of the control from the bottom of the view.
Left	LONG	None	Offset of the control from the left of the view.
Right	LONG	None	Offset of the control from the right of the view.
DataType	BSTR	None	XSD Type of the XML value.
ControlType	BSTR	None	xd:xctname attribute from the XSL.
NodeName	BSTR	None	XML Node name for the current field (base name, not fully qualified name).
Value	BSTR	None	Current XML value of the control (read/write).

InfoPath lets the importer set the Value property of a control. The return is only success or failure (HRESULT). Failures could result from a value that was rejected by business or schema logic in the form. InfoPath ignores failures.

Values that are passed to the importer could differ from the final value that is stored in the XML because of the data formatting functionality in InfoPath. Therefore, passing a date value of "1/1/2000" stores the UTC value in the XML. If the actual stored value is needed, you should check the Value property after setting it.

Calculations that modify field values, rules that set values, or custom code could affect the value of other fields as values in the importer are changed. Some controls are limited to certain values, as if a user were entering data. Table 13 contains the appropriate values for specific controls.

Table 13. Control values

Control	Type	Description
Text Box	BSTR	Any xsd:string value.
Rich Text Box	BSTR	XHTML string with XHTML namespaces on top level elements. This XHTML string will be parsed into a tree and tree will be inserted into the XML DOM.
Drop-down List Box	BSTR	Any xsd:string value.
List Box	BSTR	Any xsd:string value.
Date Picker	BSTR	Any xsd:string value.
Check Box	BOOL	BSTR, values accepted are "CHECKED," "SELECTED." Any other value indicates unselected.
Option Button	BSTR(set_value), BSTR(get_value)	Values accepted are "CHECKED," "SELECTED." Any other value indicates unselected.
Bulleted List Numbered List Plain List	BSTR	Any xsd:string value.
Picture Ink Picture	BSTR	Any xsd:base64Binary data.

UnInitialize Method

After the data importer has returned from the Import method call, InfoPath calls the importer's UnInitialize method to perform any necessary cleanup.

Conclusion

You can create an external converter application that can be accessed from InfoPath by creating a COM object that implements the appropriate interfaces exposed by the type libraries in IPDESIGN.dll and IPEDITOR.dll. These applications can import data into InfoPath forms as they are filled out, or they can import and export form templates from InfoPath design mode. You can create InfoPath converters and have them listed on Microsoft Office Marketplace, the Web site that customers visit to obtain products and services that work with Microsoft Office products.

Additional Resources

For more information about developing with InfoPath, see the following resources:

• InfoPath Developer Portal

  Information about InfoPath developer resources.

• Microsoft Office InfoPath Portal

  Office Online site that provides information about InfoPath form design, declarative logic, and other features available through the InfoPath user interface.

• InfoPath 2007 Developer Reference

  Information about developing form templates and applications for Office InfoPath 2007 using scripting and COM languages.

• Welcome to the InfoPath Developer's Reference for Managed Code Form Templates

  Information about developing form templates and applications for Office InfoPath 2007 using managed code.

• Welcome to the Microsoft Office Forms Server 2007 SDK

  Information about developing applications for InfoPath Forms Services, which is available as part of either Microsoft Office Forms Server 2007 or Microsoft Office SharePoint Server 2007.