Development Guide

Chapter 5
|
Developing third-party FileMaker plug-ins 43
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 Pro Advanced, 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 Pro Advanced, 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 Pro Advanced, 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.
The FMPluginExample plug-in does not allocate any persistent memory on the heap, and therefore does not
do anything when it receives the Shutdown message. You should implement a clean-up function in your
plug-in, however, to deallocate anything you have on the heap and exit from any operating system services
you may be using. It’s possible for a plug-in to be enabled and disabled multiple times during a session, so
it’s important for your plug-in to clean up memory.
Unregister each external function registered during the Initialization message using
fmx::ExprEnv::UnRegisterExternalFunction.