Developer’s Guide

Writing external function plug-ins 10-11
1 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.
1 kCurrentExtnVersion is the only other result value that should be
returned. This causes the plug-in to be enabled.
For the Full Example plug-ins, the Do_Init function is called when
the Initialization message is received. The Do_Init 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_Init 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_Init function in the Full Example 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 Full Example 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.
There are two times when this message is called by the
FileMaker Pro application:
1 If the unsafeCalls parameter is non-zero, then the routine has been
called at the same time that the FileMaker Pro application’s low-
level networking code has been called.
Do not perform any lengthy, user interface, or event processing when
the
unsafeCalls parameter is non-zero.
1 The other time when the Idle message will be sent is when
FileMaker Pro detects free time and does its own internal idle
handling.
The External Function message
The External Function message, kFMXT_External, is sent to the plug-
in when FileMaker Pro is processing a calculation that contains one
of the plug-in’s external functions. This is where the majority of the
action takes place.