File Converter API

Microsoft Office Technical Documentation Group

Created: November, 1995

Microsoft Excel provides a file converter application programming interface (API) with which you can write a custom input file converter. For example, the Quattro Pro for Windows file converter that is included with Microsoft Excel 7.0 uses the file converter API.

Although the file converter API is identical across operating environments, a converter is platform-specific, which means that it must be compiled into a 32-bit DLL for Windows NT and Windows 95, a 16-bit DLL for Windows 3.1, and a code resource for the Macintosh.

This kit includes a sample file converter that converts the text file created by the BiffView utility. The sources and the compiled 32-bit DLL are in the \Sample\Undump folder. The 32-bit Undump project was developed and tested with Microsoft Visual C++ version 2.2.

Click to open or copy the FILECONV project files

File Converter Background

This section describes the file converter user interface, the file converter selection algorithm, file converter internals and error handling, and system registry settings that expose the converter to Microsoft Excel.

File Converter User Interface

File converters are seamlessly integrated into the Open dialog box (File menu). To expose the converter to the user, you add a filter option to the List Files Of Type box in the Open dialog box. This additional option is created by a key in the System Registry. If you installed the Quattro Pro for Windows converter when you installed Microsoft Excel, you can see the Quattro Pro for Windows (*.wb1) filter option in the List Files Of Type box in the Open dialog box.

If you didn't install the Quattro Pro for Windows converter, you can run the Microsoft Excel setup program to add it. You can also manually add the option for the Undump.dll converter to the System Registry, as described in Exposing the Converter to Microsoft Excel.

File Converter Selection Algorithm

Microsoft Excel tries to detect the file format automatically when you open a file, as shown in the following pseudocode.

For Each built-in file format except TEXT and CSV

Test the first n bytes of the file until either a format is

recognized or until all built-in formats have been tried

(except TEXT and CSV)

If file format is still not recognized Then

For each file format in InstallableInputConvertersList

Tell input converter DLL to sniff the first n bytes of the

file until either a format is recognized or all of the

installable input converters have been tried

If file is still not recognized Then

Assume the file is TEXT format and start the Text Import Wizard

You can force Microsoft Excel to try a particular file converter first by selecting the converter's filter option in the List Files Of Type box. In this case, Microsoft Excel attempts to detect the file format only if the file converter doesn't recognize the file format.

In Undump.c, the IsFormatOk function detects the file format by comparing the passed-in string to the string in the variable szBIFF5.

Inside the File Converter

The file recognition function (in Undump.c, the IsFormatOk function) is the first converter function that Microsoft Excel calls. If your converter recognizes the file format, Microsoft Excel then calls the converter's initialization function to give you an opportunity to do any necessary initialization. The initialization function in Undump.c is called InitLoad.

After initialization, Microsoft Excel repeatedly calls your converter to get BIFF records. Your code must provide the BIFF records in the format shown in the article Microsoft Excel File Format. Your code is also responsible for the actual conversion from the non-native data format to BIFF format. Conversion ends when your converter returns the last EOF record in the file.

The converter is called three times for each BIFF record: the first call returns the BIFF record type, the second call returns the number of bytes in the record data, and the third call returns the data. To see examples of these calls in Undump.c, look for the following three functions: RtNextRecord, CbNextRecord, and DataNextRecord.

To help you write a robust converter, Microsoft Excel exposes a callback function that your converter should use for memory management and for file input and output. For more information, see Callback Function.

You can compile a debug build of Undump.dll and then use the Visual C++ debugger to watch the entire conversion process. Undump is a very straightforward example of a converter, because there is a one-to-one correspondence between Undump "records" and BIFF records. The records can be processed sequentially, as they are read from the BiffView-created text file.

Error Handling

If Microsoft Excel encounters an error during file conversion, it calls your converter before displaying an error message to the user. This mechanism gives your code an opportunity to do last-minute cleanup (for example, freeing allocated buffers). Because Microsoft Excel provides the file input/output services, your code doesn't have to handle file cleanup. In Undump.c, the error handler is the function AbortLoad (although there is no error handling in the program, just a short cleanup function).

Your converter can notify Microsoft Excel of a fatal error by returning the special BIFF record type rtNil, which is defined in the header file Biff.h in the \Sample\Undump\Win32 folder. This record causes Microsoft Excel to call your error handler and then stop the file load. The rtNil record has no record data field.

Exposing the Converter to Microsoft Excel

To expose the file converter in 32-bit Windows products, you add a value to the System Registry. To expose the file converter in 16-bit Windows products, you edit the Excel5.ini file, and on the Macintosh, you edit the Excel Settings (5) file.

Win32

In Microsoft Excel for Windows NT and Windows 95, you add a string value entry to the HKEY_CURRENT_USER\Software\Microsoft\Excel\7.0\Converters key. For example, Setup adds the following string value entry when you install the Quattro Pro for Windows file converter. The value name is QPro:

Quattro Pro for Windows (*.wb1), C:\MSOffice\Excel\xlqpw.dll, *.wb1

The string value entries are in the following form:

<Friendly description>, <DLL filename, including path>,

<Search filter>

Token Description
<Friendly description> The text that appears in the List Files Of Type box in the Open dialog box (File menu).
<DLL filename, including path> The filename and path of the converter DLL. If you omit the path, the DLL must be in the same folder as Excel.exe.
<Search filter> A file-filter string — for example, *.xl*


Note If you did not install any file converters during Microsoft Office setup (or Microsoft Excel setup), then the Converters key will not exist. In this case, you can use the Registry Editor to add the key manually, or create a .reg file to add the key automatically.

Win16

In Microsoft Excel for 16-bit Windows, the [Converters] section of Excel5.ini contains a line for each converter. The line is very similar to the string value entry in the Win32 system registry, except that a tag name is added to the string.

<ConverterTag> = <Friendly description>, <DLL filename, including path>,

<Search filter>

Token Description
<ConverterTag> A unique tag name in the [Converters] section; ignored by Microsoft Excel.
<Friendly description> The text that appears in the List Files Of Type box in the Open dialog box (File menu).
<DLL filename, including path> The filename and path of the converter DLL. If you omit the path, the DLL must be in the same folder as Excel.exe.
<Search filter> A file-filter string — for example, *.xl.*


Macintosh

On the Macintosh, file extensions (for example, .xls) are replaced by one or more four-character file types (for example, XCEL). To add file converters to the Excel Preferences (5) file, you must use ResEdit to add a GRID resource. If a GRID resource named Converters doesn't exist, then create one. Each GRID resource is an array of words that are actually string resource IDs.

Each GRID resource has the following form:

<name that appears in drop-down>,"<full path to file converter>",

<list of 4-letter file types separated by ;>

For example:

Undump BiffView Files,"HD80:Excel5:undump.res",lttr;XLS5

The "full path to file converter" token must contain the full path and filename of the converter code resource, and it must be enclosed in quotation marks, as shown in the preceding example. Quotation marks are optional for the other two tokens.

For more information about editing the Excel Preferences (5) file, see Specifying Settings in Microsoft Excel version 5.0 for the Macintosh.

File Converter API Functions

This section describes the EFCP structure, the XlConverter function, and the callback function EfcCallBack.

The EFCP Structure

When Microsoft Excel calls the file converter, it passes a pointer to an EFCP data structure, which is defined in Xlconv.h, as shown in the following examples and table.

Windows

typedef struct _efcParam

{

long lcb;

BYTE FAR *lprgb;

FARPROC lpfn;

} EFCP, FAR * LPEFCP;

Macintosh

typedef struct _efcParam

{

long lcb;

unsigned char *lprgb;

ProcPtr lpfn;

} EFCP, * PEFCP;

Member Description
lcb

 Byte count

lprgb

 Pointer to a buffer
lpfn

 Pointer to a Microsoft Excel callback function


For more information about using this structure, see the following sections, "Converter Entry Point" and "Callback Function."

Converter Entry Point

The file converter should export a single function as its entry point, as shown in the following examples.

Win32

short FAR PASCAL XlConverter(iAction, lpefcp)

16-bit Windows

short FAR PASCAL __export XlConverter(short iAction, LPEFCP lpefcp)

The __export keyword is required for 16-bit DLLs.

Macintosh

short PASCAL XlConverter(short iAction, LPEFCP lpefcp)

The lpefcp parameter is the pointer to the EFCP structure. The command ID, iAction, is the converter opcode. Its values, defined in Xlconv.h, are listed in the following table.

Value Description
iActionIsFormatOk Returns TRUE if the converter recognizes the file format.
iActionInitLoad Initializes the converter; returns TRUE if successful.
iActionRtNextRecord Returns the record type of the next BIFF record; the record types are defined in BIFF.H.
iActionCbNextRecord Returns the number of bytes in the data field of the next BIFF record.
iActionDataNextRecord Returns the data for the next BIFF record; see the article Microsoft Excel File Format.
iActionAbortLoad Indicates that Microsoft Excel has detected a fatal error; clean up now.


The following sections describe the opcodes in more detail.

iActionIsFormatOk

Microsoft Excel asks the converter whether it recognizes the format of the file that the user is opening.

This is the first opcode sent to the converter. If the converter returns FALSE, Microsoft Excel doesn't call the converter again for this file.

Input

Member Description
lcb Size of the file-recognition string
lprgb Pointer to the buffer containing the file-recognition string
lpfn Pointer to the callback function


Output

None.

Return value

TRUE if the converter recognizes this file format.

FALSE if the converter doesn't recognize this file format.

iActionInitLoad

Microsoft Excel asks the converter to do any preconversion initialization. This opcode is sent after the iActionIsFormatOk call returns TRUE.

Input

Member Description
lcb Size of the input file.
Lprgb Pointer to a buffer containing the locale ID (LCID).
Lpfn NULL


Output

None.

Return value

TRUE if the converter initialized successfully.

FALSE if the converter encountered a fatal error. This return value causes Microsoft Excel to call the converter a final time, using the iActionAbortLoad opcode.

iActionRtNextRecord

Microsoft Excel asks for the record type of the next BIFF record to be received from the converter. Record types are defined in Biff.h.

This is one of the three calls (along with iActionCbNextRecord and iActionDataNextRecord) in the main conversion loop.

Input

Member Description
lcb Unused
lprgb Unused
lpfn Unused


Output

None.

Return value

BIFF record type as defined in Biff.h. The first record type must be rtBOF. Return rtEOF to indicate the end of the conversion.

iActionCbNextRecord

Microsoft Excel asks the converter for the length of the data in the next BIFF record. The return value is used to allocate buffer storage for the following iActionDataNextRecord call.

This is one of the three calls (along with iActionRtNextRecord and iActionDataNextRecord) in the main conversion loop.

Input

Member Description
lcb Unused
lprgb Unused
lpfn Unused


Output

None.

Return value

The size of the next BIFF record, in bytes. This value must be <=cbBiffMax as defined in Biff.h; if it is greater than this, Excel calls iActionAbortLoad.

iActionDataNextRecord

Microsoft Excel asks the converter for the BIFF record data.

This is one of the three calls (along with iActionRtNextRecord and iActionCbNextRecord) in the main conversion loop.

Input

Member Description
lcb Length of data
lprgb Pointer to the buffer for the BIFF record data. (the size of the buffer is cbBiffMax)
lpfn Unused


Output

Member Description
lprgb Pointer to the actual data in the BIFF record; for BIFF record descriptions, see the article Microsoft Excel File Format. The record data starts at offset 4 in the record descriptions in that article.


Return value

An integer from 0 to 100 that indicates the percentage-complete status of the conversion. Microsoft Excel uses this value to update the load progress indicator in the status bar. The return value should equal 100 when your converter returns rtEOF. See the DataNextRecord function in Undump.c for an example of the percentage-complete calculation.

iActionAbortLoad

Microsoft Excel informs the converter that it has detected a fatal load error; called after the converter returns FALSE for the iActionInitLoad call to the converter. This is the only chance for the converter to do any necessary cleanup. Because Microsoft Excel provides file input/output services, your code doesn't have to handle file cleanup.

Input

Member Description
lcb Unused
lprgb Unused
lpfn Unused


Output

None.

Return value

Ignored.

Callback Function

Your converter should always use the callback function for memory management and for file input/output. This helps ensure peaceful coexistence with Microsoft Excel. The callback function is declared within Microsoft Excel as follows:

short FAR PASCAL EfcCallBack( short int iefccmd,

BYTE FAR *lpb,

long int lcb)

The command ID, iefccmd, is the callback opcode. Its values, defined in Xlconv.h, are listed in the following table.

Value Description
iefccmdCbFromFile Asks Microsoft Excel to read lcb bytes from the input file stream
iefccmdAllocCb Asks Microsoft Excel to allocate a buffer
iefccmdFreeCb Asks Microsoft Excel to free a buffer
iefccmdGetPos Asks Microsoft Excel to get the current stream position of the file pointer
iefccmdSetPos Asks Microsoft Excel to set the current stream position of the file pointer


The lpb and lcb parameters take on different meanings, as described in the following sections.

iefccmdCbFromFile

Asks Microsoft Excel to read lcb bytes from the input file stream.

Input

Member Description
lpb Pointer to a buffer to hold file data (remember, the converter is responsible for allocating this buffer)
lcb Size of a file buffer


Output

Member Description
lpb Pointer to the buffer that contains the file data


Return value

The actual byte count written to the file buffer. Microsoft Excel attempts to fill the buffer completely; the actual count will be less than the requested size if an EOF is encountered in the input stream before the buffer is full.

iefccmdAllocCb

Asks Microsoft Excel to allocate a buffer for the converter.

Input

Member Description
lpb Pointer to a 32-bit variable (DWORD or long) that stores the address of the allocated buffer
lcb Requested buffer size


Output

Member Description
lpb Pointer to a 32-bit variable (DWORD or long) that stores the address of the allocated buffer


Return value

The actual count of bytes allocated. Returns 0 to indicate an out-of-memory condition and to give your converter an opportunity to request a smaller amount of memory instead.

Note With the 16-bit Windows version 3.1, you can allocate only a 64K buffer (actually slightly less than 64K because of system overhead). With 32-bit Windows NT, you can allocate a buffer up to either the available memory limit or 4 GB — whichever is smaller.

iefccmdFreeCb

Asks Microsoft Excel to free a buffer that was previously allocated using an iefccmdAllocCb call.

Input

Member Description
lpb Pointer to a 32-bit variable (DWORD or long) that stores the address of the buffer to be freed
lcb Size of the buffer to be freed


Output

None.

Return value

None. The converter should assume that this call always succeeds.

iefccmdGetPos

Asks Microsoft Excel to get the current (zero-based) offset in the input file stream.

Input

Member Description
lpb lPointer to a 32-bit variable (DWORD or long) to store the stream offset
lcb lUnused


Output

Member Description
lpb Pointer to a 32-bit variable (DWORD or long) that contains the current input stream offset


Return value

Unused.

iefccmdSetPos

Asks Microsoft Excel to set the current (zero-based) offset in the input file stream.

Input

Member Description
lpb Pointer to a 32-bit variable (DWORD or long) that contains the offset you want
lcb Unused


Output

None; lpb is unchanged.

Return value

Unused.

Using File Converters from the Macro Languages

In Visual Basic for applications, you can use the FileConverters property to return an n x 3 array that contains information about installed converters, where n is equal to the number of installed converters. The other dimension contains the three strings from the entry in the Excel5.ini (or equivalent) file.

In the Microsoft Excel version 4.0 macro language, you can use the GET.WORKSPACE(62) macro function to list the installed converters. Array-enter this function in enough cells to store the maximum number of expected converters. Uninstalled converters correspond to the #N/A error value in the cells.

The Open method (Visual Basic) and the OPEN() macro function both contain a Converter argument that can be used to override the converter automatic detection algorithm. The argument is a 1-based index to the table of converters (as given by the FileConverters property or the GET.WORKSPACE(62) macro function).