Developer’s Guide

Understanding external function plug-ins 12-11
The Initialization message
The Initialization message, kFMXT_Init, is sent to the plug-in
whenever it is enabled in FileMaker Pro. This may or may not
correspond with the startup of the FileMaker Pro application,
depending on whether the plug-in is enabled in the Application
Preferences dialog box.
There are three possible result values that the plug-in should return
in response to the Initialization message:
• 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
incompatible version of the API it was compiled with.
• kDoNotEnable should be returned if the plug-in should not be
enabled. This could be the result of a specific piece of hardware
missing or that a certain system software component was not of the
proper version number. If the plug-in is going to return this value, it
should first display some type of alert telling the user why it could
not be enabled.
• kCurrentExtnVersion is the only other result value that should be
returned. This causes the plug-in to be enabled.
For the FMExample plug-ins, 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 if it’s compatible with the version of
FileMaker Pro 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 the
Mac OS, 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. The preprocessor flags controlling the selection
process can be found in the FMFlags.h file.
If the preferences are set properly and the API version is okay, the
Do_PluginInit function in the FMExample plug-in will return
kCurrentExtnVersion—otherwise, it will return an error and the plug-
in will not be enabled by FileMaker Pro.
The Shutdown message
The Shutdown message kFMXT_Shutdown, is sent to the plug-in
whenever it is disabled in FileMaker Pro. This may or may not
correspond with the quitting of the FileMaker Pro application,
depending on whether the plug-in is disabled in the Application
Preferences dialog box.
The FMExample 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 OS services you may be using. Remember that it’s
possible for a plug-in to be enabled and disabled multiple times
during a session so it’s important that your plug-in will clean up
memory.
The Idle message
The Idle message, kFMXT_Idle, is only sent to the plug-in during idle
time if the idle feature flag was set to “
Y” in the feature string and the
plug-in is currently enabled.