Development Guide

Chapter 5
|
Developing third-party FileMaker plug-ins 39
Naming conventions for external functions
The function name prefix for all of the plug-in’s external functions must
be a unique value containing four or five characters and must not begin
with the characters “
FM” or “Web.” Four-character prefixes are reserved
by FileMaker. For example, the FMPluginExample plug-in’s function
name prefix is “XMpl.”
FileMaker messages sent to the plug-in
There are six possible calls that FileMaker Pro, FileMaker Pro
Advanced, or FileMaker Server can request of your plug-in. Messages
sent to your plug-in are supplied in the
whichCall field of the parameter
block,
FMExternCallStruct, defined in the FMXExtern.h file.
1 kFMXT_Init — the Initialization message
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.
Characters
in the option
string Description of characters
1-4 Characters 1-4 are the plug-in ID. Register the ID as a Creator code
on the Apple Developer Support website at www.apple.com.
5 Character 5 is always “1.”
6 Set the sixth character of the option string to “Y” if you want to
enable the Configure button for plug-ins in the Preferences
dialog box. Use “n” if there is no plug-in configuration needed.
If the flag is set to “Y,” then make sure to handle the
kFMXT_DoAppPreferences message. For more information,
see “FileMaker messages sent to the plug-in” on page 39.
7 Set to “n” for the new style plug-in registration and function
callbacks demonstrated in the FMExample. Only set to “Y” if
your plug-in requires the legacy function string list and single
external callback.
8 Character is always “n.”
9 Set the ninth character of the option string to “Y” if the kFMXT_Idle
message is required. For simple external functions this may not be
needed and can be turned off by setting the character to “n.”
10 Character 10 is always “n.”
11 Character 11 is always “n.”