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* |
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.* |
Member | Description |
lcb | Byte count |
lprgb | Pointer to a buffer |
lpfn | Pointer to a Microsoft Excel callback function |
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. |
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 |
Member | Description |
lcb | Size of the input file. |
Lprgb | Pointer to a buffer containing the locale ID (LCID). |
Lpfn | NULL |
Member | Description |
lcb | Unused |
lprgb | Unused |
lpfn | Unused |
Member | Description |
lcb | Unused |
lprgb | Unused |
lpfn | Unused |
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 |
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. |
Member | Description |
lcb | Unused |
lprgb | Unused |
lpfn | Unused |
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 |
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 |
Member | Description |
lpb | Pointer to the buffer that contains the file data |
Member | Description |
lpb | Pointer to a 32-bit variable (DWORD or long) that stores the address of the allocated buffer |
lcb | Requested buffer size |
Member | Description |
lpb | Pointer to a 32-bit variable (DWORD or long) that stores the address of the allocated buffer |
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 |
Member | Description |
lpb | lPointer to a 32-bit variable (DWORD or long) to store the stream offset |
lcb | lUnused |
Member | Description |
lpb | Pointer to a 32-bit variable (DWORD or long) that contains the current input stream offset |
Member | Description |
lpb | Pointer to a 32-bit variable (DWORD or long) that contains the offset you want |
lcb | Unused |