Chapter 5
|
Developing third-party FileMaker plug-ins 49
Requirements for writing external
function plug-ins
FileMaker plug-ins are most useful when they contain a single
function or a set of functions with similar features. When you design
your plug-in, keep in mind that developers who use your plug-in may
not understand programming conventions that you take for granted.
The format of each function’s parameter should be understandable to
the typical user.
If you are creating a FileMaker plug-in with functions that do not
require any parameters, make sure the function “prototype” registered
for that function does not include parentheses. For example, “DoThis”
should be registered instead of “DoThis( )” as the function prototype.
API code files
There are ten API code files in the Headers folder: FMXExtern.h,
FMXCalcEngine.h, FMXBinaryData.h, FMXDateTime.h,
FMXTextStyle.h FMXTypes.h, FMXFixPt.h, FMXClient.h,
FMXText.h, and FMXData.h. The files are not redistributable in
source code (or human readable) form, cannot be modified, and are
only provided to enable licensees of FileMaker
Pro Advanced to
compile plug-ins for use with FileMaker products. Not all the files are
required to build all types of plug-ins.
The FMXExtern.h is absolutely required. The FMXExtern.h defines
the parameter block (the shared data structure used by your plug-in
and FileMaker
Pro, FileMaker Pro Advanced, FileMaker Server, or
FileMaker Server Advanced) and some shared function calls. The
function calls are used to manipulate the parameter and result handles
in the parameter block.
The FMXExtern.h file defines the call-back functions for backward
compatibility operations and the different kinds of plug-in events
(FileMaker
Pro, FileMaker Pro Advanced, FileMaker Server, or
FileMaker Server Advanced messages) sent to the plug-in in a
FMExternCallSwitch definition.
FMExternCallStruct defines the structure of the parameter block.
FMExternCallPtr is a pointer to that structure and gFMExternCallPtr
is a global variable that should be defined in your code.
The FMXCalcEngine.h file contains the register and unregister
functions. It will be used in most plug-ins, as the plug-ins will likely
need to register functions.
The functionality of the remaining API code files is described in
comments that are included in the files themselves.
Option string syntax
The option string must be 11 characters long for plug-ins.
The first four characters of the option string are the ID of the plug-in.
The ID must be unique for each plug-in and must not begin with “
F,”
“
FM,” or “Web.” For the Mac OS X, it is recommended that you set the
creator type of the plug-in to this same value. The ID can only contain
low-ASCII alphanumeric characters (such as
0-9, A-Z,
and a-z).
Note So that there will be a good chance of having a unique ID, you
should register the ID at the Apple Developer Support web site, even
if you won’t be creating a Mac OS X version of your plug-in. To
register plug-in IDs as Creator codes, go to the developer pages on the
Apple Computer web site at www.apple.com. For more information,
see
“Registering your plug-in” on page 53.
The fifth character of the option string is always “1” and the eight,
tenth, and eleventh are always “n.” Other values for these flags are
reserved for FileMaker use only.
For example, “Moc31YnnYnn” is a option string for a plug-in with the
ID of “Moc3” (characters 1-4) that requires configuration (character 6
= “
Y”), uses the new style registration and functions callbacks
(character 7 = “
n”), and requires special idle time
(characters 9 = “Y”).
