Extern Tips

The Extern header file contains the main/initial Callback Structure which is passed into your plug-in's Entry Point function, as well as several useful defines and enumerations. This header also includes several callbacks and things for developing plug-ins using the older "External ( )" style interface. Those items will not be discussed here as they are not recommended.

Callback functions

There are 2 callback functions that are useful for developing FM7+ plug-ins:

FMX_StartScript(fileName, scriptName, control, parameter)

The StartScript function is what you use to call scripts in FileMaker Pro from your plug-in. This function takes 4 parameters:

• fileName - The file name of the database that contains the script you want to call. You do not need to include the file extension (".fp7") here, and in fact, any 1 to 4 character extension you define will be completely ignored. (eg. If you pass in "mydb.A" or "mydb.fake", FileMaker will choose "mydb.fp7" as the database.)
• scriptName - The name of the script you want to call. The script name is case-insensitive.
• control - This parameter tells FileMaker what to do with the currently paused script once the script you are calling finishes. This has no bearing on the current script if it's actively running (not paused). In the Extern header file, there is an enumeration below the FMX_ScriptControl typedef that defines the values you can pass for this parameter. These values mean the exact same thing as the values you use when defining a button to Perform a Script. Note: FM7 behaves differently.
• parameter - This is the script parameter to pass to the script. It can be any of the fundamental data types. Ref: Data Tips

StartScript Example

FMX_SetToCurrentEnv(env)

The SetToCurrentEnv function will return to you an instance of the ExprEnv class (Ref: Calc Tips) containing the current calculation environment. You can use this function within a call to your plug-in's idle routine to get the current environment the user is in. It only takes 1 parameter:

• env - Pass in a reference to an ExprEnv object for the function to update with the current environment

SetToCurrentEnv Example

FMX_ExternCallStruct Enumerations

There are a number of enumerations used by the FMX_ExternCallStruct structure. We'll look at each one to see what they are:

API Version Enumeration

This enumeration holds values for the version of the FileMaker Plug-in API. When FileMaker Pro calls your Entry Point function, it will pass in one of k##ExtnVersion values. It's your job (in your Init function) to examine this value and make sure your plug-in supports the calling version of FileMaker Pro. If it does, you return the kCurrentExtnVersion value. If it does not, or if you don't want to enable the plug-in for some other reason, pass back kDoNotEnable.

FMX_ExternCallSwitch Enumeration

This enumerations holds the command values for the actions FileMaker Pro wants you to perform each time it calls your Entry Point function.

FMX_Strings Enumeration

These are the values passed in with the kFMXT_GetString command to tell your plug-in what string/information to return.

FMX_IdleLevel Enumeration

These values tell your plug-in how idle FileMaker Pro is when it calls your Entry Point function with the kFMXT_Idle command. If the kFMXT_Unsafe value is passed, do not attempt to interact with FileMaker Pro at all. Don't try to call a script or use the SQL interface or anything. You should probably return as fast as possible when sent the kFMXT_Unsafe value. Personal Opinion: Take all of these values with a grain of salt. In my experience they aren't always accurate except for the kFMXT_Unsafe value.

FMX_Application Enumeration

These values tell your plug-in what FileMaker Pro product is calling your plug-in. The "kFMXT_Developer" value is the same/original name as the FileMaker Pro Advanced product. The kFMXT_Mobile value is useless at this time because there is currently no version of FileMaker Mobile that has a plug-in interface, nor is there a shipping version of FileMaker Mobile. Note: The API Headers that come on the FileMaker Developer 7 cd have the kFMXT_Developer and kFMXT_Pro values swapped, so make sure you are using the latest API Headers from a current version of FileMaker Pro.

FMX_ExternCallStruct structure

An instance of this structure is passed into your Entry Point function each time it is called. It holds the values for all the enumerations above as well as the callback function pointers for the functions mentioned above. There are several useful values in this structure:

extnVersion

This holds the value from the API Version Enumeration to tell your plug-in what version of the API the calling FileMaker Pro is using.

resourceID

This is the Resource Fork ID of your plug-in on Mac. This is basically a holdover from the FileMaker Pro 4-6 API that you would use with UseResFile so that subsequent calls to FindResource and the like will search your plug-ins resources instead of someone else's plug-in. Since FileMaker Pro 7 plug-ins are bundles, you can ignore this value and either use the instanceID value described below or use CFBundleGetBundleWithIdentifier or an equivalent function to get access to your plug-ins resources.

entryPoint

This is a pointer to your Entry Point function. Not sure why it's needed. I've never used it. :)

cfmCalls

This is set to true if your mac plug-in is in the old CFM format. I've never used this either, and I'm not sure why you wouldn't know your plug-in is CFM.

whichCall

This will contain a value from the FMX_ExternCallSwitch Enumeration. This is how FileMaker Pro tells you what command it wants your Entry Point function to perform.

unsafeCalls

This is set to true if your plug-in should not interact with FileMaker in any way. This is similar/the same as the kFMXT_Unsafe FMXT_IdleLevel value mentioned above.

parm1, parm2, parm3

The values of these variables depend on what command FileMaker Pro is asking your Entry Point function to perform:

whichCall	parm1	parm2	parm3
kFMXT_Init	FMX_Application Value	FMP App Version Str*	unused
kFMXT_Idle	FMX_IdleLevel Value	reserved	unused
kFMXT_External	unused	Function ID	Parameter Text**
kFMXT_Shutdown	unused	unused	unused
kFMXT_DoAppPreferences	unused	unused	unused
kFMXT_GetString	FMXT_Strings Value	Windows Language ID	Max size of returned string

* The FMP App Version Str passed in with kFMXT_Init is a Unicode c str that contains the exact same value as the "Get ( ApplicationVersion )" calculation function.

** The Parameter Text passed in with kFMXT_External is the text from the second parameter to the "External ( )" calculation function used to call your plug-in. The encoding is either kEncoding_ASCII_Mac or kEncoding_ShiftJIS_Mac and your return text must be in the same encoding. Note: The kFMXT_External call is only used if you have set up FileMaker Pro 4-6 style plug-in function calls. You probably will not need this functionality if you are developing a FileMaker Pro 7+ plug-in unless you are setting up a backward compatibility option for users migrating from a FileMaker Pro 4-6 style plug-in to your new FileMaker Pro 7+ plug-in.

instanceID

On Windows, this is the DLL HInstance of your plug-in. You can use this value to determine where your plug-in is located on the hard drive among other things. On Mac, this is the BundleRef of your plug-in. You can use this to load resources from your plug-in and determine where it is located on the hard drive, among other things.

result

Set this to the result of the command FileMaker Pro asked your Entry Point function to perform. There are only a few commands in which you need to return a result:

whichCall	result
kFMXT_Init	Pass back kCurrentExtnVersion to enable your plug-in or kDoNotEnable to disable it.
kFMXT_External	Pass back a pointer to your text result.
kFMXT_GetString	Pass back a pointer to your Unicode text c str value.

unused

The name says it all.

Various Callbacks

These are the function callback pointers for the callbacks mentioned above. You don't need to do anything with them or access them directly. Use the macros defined earlier in the header file to call these functions.

Forward Definitions

Somewhere in the sources for your plug-in, you must define the FMExternCallProc Entry Point function and a global instance of the FMX_ExternCall structure named gFMX_ExternCallPtr. The Entry Point function is how FileMaker Pro talks to your plug-in on a basic level, and the gFMX_ExternCallPtr must be defined so that the callback macros and other things work.