Overview of Plug-In Development
GeoLab supports the use of special DLLs (Windows 32-bit
Dynamic Link Libraries) as "plug-ins" 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 plug-ins.
Plug-In DLL File Requirements
Each plug-in import module consists of two required files: a
*.DLL file and a *.HTM 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 plug-in DLL's filename is not in this format, it
will not be loaded. The HTM 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.htm".
The HTM file is used to supply information to the user about
the formats 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:
"MessageText","LineNumber",
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 Plug-In Structure
All import plug-ins 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.
GFF_GetPluginName
Prototype: BOOL GFF_GetPluginName(LPSTR name, LONG
bufferSize);
Description: This function is used to retrieve the
NULL-terminated name (string) of the plug-in. Note that this
function is optional, and if it is not present in the DLL, the
plug-in name will be derived from the DLL filename as described
above.
Return Values: If the plug-in name is successfully
retrieved, this function should return TRUE (non-zero),
otherwise it should return FALSE (zero).
GFF_GetFormatCount
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 plug-in 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.
GFF_GetFirstFormatName
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).
GFF_GetNextFormatName
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.
GFF_TranslateFile
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:
|
Parameter |
Description |
|
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). |
|
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.
|
