Developer’s Guide

66 FileMaker Developer’s Guide
your plug-in. FileMaker has reserved certain naming conventions for
external functions. For more information, see “Registering your
plug-in” on page 68.
FileMaker messages sent to the plug-in
There are six possible calls that FileMaker Pro, FileMaker
Developer, or FileMaker Server can request of your plug-in.
Messages sent to your plug-in are supplied in the
whichCall field of
the parameter block, FMExternCallStruct, defined in the FMXExtern.h
file.
1 kFMXT_Init — the Initialization message
1 kFMXT_Shutdown — the Shutdown message
1 kFMXT_Idle — the Idle message
1 kFMXT_DoAppPreferences — the Preferences message
1 kFMXT_External — the External Function message received by
legacy plug-ins that set character 7 in the options string to “Y” and
that register their functions the old external way
1 kFMXT_GetString — the GetString message received by plug-ins
that use the new style of registration when the plug-ins provide the
option string, plug-in name, and description
Initialization message
The Initialization message, kFMXT_Init, is sent to the plug-in
whenever it is enabled in FileMaker Pro, FileMaker Developer, or
FileMaker Server. This may or may not correspond with the startup
of the application, depending on whether the plug-in is enabled in the
Preferences dialog box.
There are two possible result values that the plug-in should return in
response to the Initialization message:
1 kBadExtnVersion should be returned if the version number passed
is less than the value of kMinExtnVersion or greater than the value of
kMaxExtnVersion. This prevents the plug-in from running on an API
that is incompatible with the API with which it was compiled.
1 kCurrentExtnVersion is the only other result value that should be
returned. This causes the plug-in to be enabled.
For the FMPluginExample plug-in, the Do_PluginInit function is
called when the Initialization message is received. The Do_PluginInit
function first checks the version of the API that the plug-in was
compiled with to verify that it’s compatible with the version of
FileMaker
Pro, FileMaker Developer, or FileMaker Server that has
loaded it. Then the function checks for preferences and sets them if
they exist. If no preferences currently exist, it will create them with
default values.
In Windows, these preferences are stored as registry entries. In
Mac
OS X, they are stored in a file within the Preferences folder of
the System Folder. Due to the differences between the way this
information is stored on the two platforms, the
Do_PluginInit function
uses preprocessor instructions to choose the correct code at compile
time.
If the preferences are set properly and the API version is correct, the
Do_PluginInit function in the FMPluginExample plug-in will return
kCurrentExtnVersion.
After you set the preferences, register each external function by
providing its name, description, and the function to be used. Use
fmx::ExprEnv::RegisterExternalFunction to register your functions.
Shutdown message
The Shutdown message, kFMXT_Shutdown, is sent to the plug-in
whenever it is disabled in FileMaker Pro, FileMaker Developer, or
FileMaker Server. This may or may not correspond with the quitting
of the application, depending on whether the plug-in is disabled in
the Preferences dialog box.