Developer’s Guide

12-12 Developer’s Guide
There are two times when this message is called by the
FileMaker Pro application:
• 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.
• 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.
The names of the external functions start at string ID 144 for
Windows and are defined as a STR# resource with ID 144 for the
Mac OS. The first exported function name is mapped to ID 0 and
increased incrementally by 1 for each following name. These ID
numbers are then used to switch to the correct processing routine.
The input and result parameters of the External Function message are
Mac OS style Handles that contain text using Macintosh character
set encoding. This means that all numbers are also represented as
text. The result Handle is always empty when the External Function
message is sent. You should only manipulate the Handles using the
memory manager callback routines that are defined in FMExtern.h.
In the Mac OS, the parameters will be real Mac OS Handles, but you
cannot depend on which heap they may be located in. In Windows,
these Handles exist in the FileMaker Pro memory manager pool and
have no relation to anything called a HANDLE in the Win32s APIs.
Depending on the value of the param2 variable, the FMExample
plug-in (FMFunct.c) will run the following external functions:
This param2 Corresponds to this And causes the plug-in
value external function name to run this function
0 Xpl-Version PlugInVersion
1 Xpl-NumToChar SimpleNumToChar
2 Xpl-CharToNum SimpleCharToNum
3 Xpl-Format funct_Format
4 Xpl-NumWords funct_Num2Words
For information on each external function, see “Description of the
FMExample plug-in’s external functions” on page 12-4.
The Preferences message
The Preferences message, kFMXT_DoAppPreferences, is sent in
response to a user clicking the Configure button for the selected plug-
in in the Application Preferences dialog box.
The plug-in should display a dialog box of some sort that will allow
the user to set any specific configuration data required by the plug-
in. If the plug-in requires user-definable preferences, you should
implement your UI here. The Configure button will only be enabled if
the sixth character of the feature string is set to “Y” (see
“Feature
string syntax” on page 12-8).
Any options that need to be saved should be placed in their own
registry entry or .INI file (Windows) or in their own preference file
(Mac OS).
The FMExample plug-in needs to implement a configuration dialog
box for the Xpl-Format function, so the flag has been set in the
feature string (
Xmpl1YYYnnn) and the function Do_PluginPrefs is
called when the Preferences message is received.