Overview of Plugin Development
GeoLab supports the use of special DLLs (Windows 32-bit Dynamic Link Libraries) as "plugins" for importing formatted text files. These DLLs need only be placed in the GeoLab installation folder (where the GeoLab program resides), and GeoLab will automatically load them when it starts up. All successfully loaded import formats will be available to the user in the File/Import menu. This page discusses the development of import plugins.
Plugin DLL File Requirements
Each plugin import module consists of two required files: a *.DLL file and a *.TXT file. The DLL file must be named using the format MGIFF_xxx.dll, where "xxx" is the unique portion of the file's name. For example, the DLL filename for the Leica SKI import filter is "MGIFF_LeicaSKI.dll" (without the quotes). If a plugin DLL's filename is not in this format, it will not be loaded. The TXT (text) file must have the same filename as the DLL except that the extension must be "htm". In the example used, the HTM file would be "MGIFF_LeicaSKI.txt". The TXT file is used to supply help information to the user about the formats and other details supported by the DLL.
Format Name Restrictions
Format names (see the GFF_GetFirstFormatName and GFF_GetNextFormatName functions below) must be no more than 50 characters in length. If a retrieved name is longer than 50 characters, it will be truncated. All format names returned must be unique.
Error Report File Format Requirements
When the GFF_TranslateFile function (see below) is called , and if errors are encountered in the specified input text file to be translated, appropriate error message lines should be written to the specified error report file. Each message emitted by the DLL must be one-line comma-delimited messages in the following format:
where MessageText is the text of the message, and LineNumber is the origin-1 (the first line is line 1) number of the line in the input text file where the error was encountered. For example, if an error occurred on the second line of the input file, the error report line would be formatted like:
"Illegal format for a distance value was encountered.","2"
Note that the MessageText portion of the line must always be enclosed in quotes.
For some types of errors a line number does not apply. Use -1 for the line number if you do not want the line number reported by GeoLab.
Internal Plugin Structure
All import plugins must export the functions listed below. An import DLL can contain one or more format definitions, each with a unique name. Note that format names are used as-is in the File/Import menu, so you should make every effort to ensure the names are unique, descriptive, and they must be less than 50 characters in length.
Prototype: BOOL GFF_GetPluginName(LPSTR name, LONG bufferSize);
Description: This function is used to retrieve the NULL-terminated name (string) of the plugin. Note that this function is optional, and if it is not present in the DLL, the plugin name will be derived from the DLL filename as described above.
Return Values: If the plugin name is successfully retrieved, this function should return TRUE (non-zero), otherwise it should return FALSE (zero).
Prototype: LONG GFF_GetFormatCount(VOID);
Description: This function must return the number of formats contained in the DLL. Any number of formats may be contained in one plugin DLL.
Return Values: The number of input formats contained in the DLL must be returned. If zero or less is returned, no formats will be loaded.
Prototype: BOOL GFF_GetFirstFormatName(LPSTR name, LONG bufferSize);
Description: This function must retrieve the NULL-terminated name (string) of the first format contained in the DLL, and copy it into the buffer pointed to by the name parameter. The bufferSize parameter specifies the number of bytes allocated to the name buffer, so that this function can ensure that it doesn't attempt to overwrite the buffer. The name retrieved by this function is used as a menu item name so it must not be too long, and should not contain any "special" (e.g. '&') or control characters.
Return Values: If the first format name is successfully retrieved, this function should return TRUE (non-zero), otherwise it should return FALSE (zero).
Prototype: BOOL GFF_GetNextFormatName(LPSTR name, LONG bufferSize);
Description: This function must retrieve the NULL-terminated name (string) of the next format contained in the DLL. The DLL is responsible for maintaining a record of which previous format name was retrieved using either this function or the GFF_GetFirstFormatName function. The bufferSize parameter specifies the number of bytes allocated to the name buffer, so that this function can ensure that it doesn't attempt to overwrite the buffer.
Return Values: If the next format name is successfully retrieved, this function should return TRUE. If there are no more next formats to retrieve, it must return FALSE.
Prototype: BOOL GFF_TranslateFile(LPCSTR formatname, LPCSTR inputfile, LPCSTR outputfile, LPCSTR errorfile, LONG maxerrors);
Description: This function must translate the specified input text file (inputfile) to the specified GeoLab text file (outputfile). The parameters of this function are as follows:
formatname: A pointer to a buffer containing the NULL-terminated name of the format to use for the translation of the input text file (inputfile) to the output GeoLab text file (outputfile). If the format name specified is not one supported by the DLL, FALSE must be returned.
inputfile: A pointer to a buffer containing the NULL-terminated filename of the text file that the user has chosen for translation. This file must be translated (converted) to the GeoLab "IOB" format.
outputfile: A pointer to a buffer containing the NULL-terminated filename of the text file to which the results of the translation must be written (in the GeoLab "IOB" format).
errorfile: A pointer to a buffer containing the NULL-terminated filename of the text file to which any error messages resulting from the DLL's attempt to perform the file translation. See above for the required format of this file.
maxerrors: This parameter specifies the maximum number of error messages the DLL should write to the specified error report file (errorfile).
Return Values: If the file translation was successfully performed, this function must return TRUE. Otherwise it must return FALSE, and write a summary of the reasons for the failure to the file specified by the errorfile parameter (in the format specified above).
IMPORTANT: When this function returns false, and no messages were written to the error file, GeoLab assumes that the specified formatname was not accepted by this function.