Chapter 5
|
Developing third-party FileMaker plug-ins 51
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, FileMaker Server, or FileMaker
Server
Advanced 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,
FileMaker Server or FileMaker Server Advanced. 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.
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 option string and the
plug-in is currently enabled.
There are five times when this message is called by the FileMaker
application.
