Filemaker Plug-In 
~~~~~~~~~~~~~~~~~

We provide a Filemaker plug-in so that you can communicate with the dongle from your
filemaker database. The filemaker plugin in the Filemaker\v7 directory is compatible
with Filemaker 7-13 (and also Filemaker 14 in 32-bit mode). The plug-in in the
Filemaker\v14 directory is compatible with Filemaker 14 (64-bit only for Mac) and
higher.

The plug-in is called:

DinkeyPro.fmx      (for 32-bit Windows)
DinkeyPro.fmx64    (for 64-bit Windows)
DinkeyPro.fmplugin (for Mac)

To use the plug-in (as with any plug-in) you must:

1)a) For versions of Filemaker previous to version 12:
   Copy the DinkeyPro plug-in to the Extensions folder (located in the FileMaker folder)
   and then launch Filemaker.
  
  b) For Filemaker 12 (and later) you must install the plug-in by creating a container
   and running an installation script. See the DinkeyPro Test.fmp12 solution for an
   example of how to do this. You should also read the Filemaker documentation on
   installing plug-ins.
   
2) From the menu choose Preferences (under Windows it is Edit | Preferences and
   under Mac OS X it is FileMaker Pro | Preferences). Then choose the plug-ins tab.
   Make sure the box "Dinkey Dongle Pro/FD Plugin" is listed and ticked. If there is a
   tock box that says "All solutions to install files" then make sure it is ticked.

3) You may want to modify the startup script (file | file options | perform script)
   to check the dongle or create a field (of type calculation) that displays a value
   returned by the protection check. View "external function" to see a list of all the
   functions that the plug-in exports. Note - every function returns a text value.
   
4) When you first use the plug-in you may get error 413. This is because you
   have not protected it. To do this run DinkeyAdd and protect the plug-in file
   specifying API Method.
   
5) When you have finished make sure that you add FileMaker security so that a
   user cannot view or modify the scripts you have added. This step does rely on
   the security of the Filemaker password system, however. A better solution would
   be to produce a runtime database file (you need FileMaker Advanced (used to be called
   Developer Edition) to do this).
   
Here is an example of some script you can use to check the protection (Please change the
version number to the current version). It is included in the DinkeyPro Test example
solution. Note: <> signifies 'not equals'. Filemaker has its own symbol for this.
You may want to do more than this so please look at all the functions in the PlugIn,
listed below):

If [DinkeyProVersion("long") <> "Dinkey Dongle Pro/FD Plug-in 7.2.0"]
   Show Custom Dialog ["Dinkey Dongle error"; "Missing or incorrect version of Plug-In."]
   Exit Application
Else
   #check dongle and look to see if returned values are correct
   Set Variable [$ret_code; Value: DDprotCheck(0;0;"")]
   If [$ret_code <> "0"]
      Show Custom Dialog ["Error Detecting Dongle"; "Error " & $ret_code & " detecting dongle"]
      Exit Application
   Else If [DDGetSDSN(0) <> "10101"]
      Show Custom Dialog ["Incorrect dongle detected"; "Contact your administrator to correct this error."]
      Exit Application
   Else If [DDGetProdCode(0) <> "DEMO"]
      Show Custom Dialog ["Incorrect dongle detected"; "Contact your administrator to correct this error."]
      Exit Application
   Else
      Show Custom Dialog ["Success!"; "Dongle checked successfully!"]
   End If
End If
 
Note you should make sure that the user cannot abort your scripts:
Allow User Abort[Off]
This is the default value anyway.
 
The plug-in exports many functions. Here is a description of each function:

Note - every function returns a "text" value.
Note - some of the functions expect dummy parameters. This is because there is 
       a bug with Filemaker 7 so that it will not accept functions with no parameters.
Note - you must call one of the DDProtCheck or DDProtCheckWithAlg or 
       DDWriteData or DDReadData functions before calling the DDGet... functions.

DinkeyProVersion
~~~~~~~~~~~~~~~~
Input:
   string - if set to "long" returns the long description of version info
            if set to "short" or the string is empty - version info
            if set to "platform" - tells you if you are calling "Windows" or "Mac OS X" plug-in

Returns version information about this plug-in. You must call this function
first to verify the Plug-In is present. This is very important because if the
Plug-In is not present then Filemaker forces the function to return 0 - which
for some functions indicates success. 


DDProtCheck
~~~~~~~~~~~
Input:
   integer: flags (see DRIS description and flags values listed below)
   integer: execs_decrement (optional) (see DRIS description)
   text: alt_licence_name (optional) (see DRIS description)
Returns:
   text: return code (0 = success, o.w. error number)

This performs a standard protection check with the flags specified and is the function you
are most likely to use. Although 2 of the parameters are optional, Filemaker 7 (at least)
insists that you enter all 3 parameters.
It will return 0 for success or the dongle error code if there is a failure.

DDProtCheckWithAlg
~~~~~~~~~~~~~~~~~~
Input:
   integer: flags (see DRIS description and flags values listed below)
   integer: alg_number (number of user-defined algorithm to execute)
   integers: var_a...var_h (variable values for user defined algorithm) 
Returns:
   text: return code (0 = success, o.w. error number)

This performs a basic protection check and executes the specified algorithm  with the 
specified variable values. It will return 0 for success or the dongle error code if there is a
failure. NB to get the algorithm answer you should call DDGetAlgAnswer.


DDWriteData
~~~~~~~~~~~
Input:
   integer: flags (see DRIS description and flags values listed below)
   integer: offset (of data area to write to)
   integer: length (of data you want to write)
   text: data you want to write
Returns:
   text: return code (0 is success)

This allows you to write a string to the dongle data area at the offset specified (for Dinkey 2/DinkeyNet).


DDReadData
~~~~~~~~~~
Input:
   integer: flags (see DRIS description and flags values listed below)
   integer: offset (of data area you want to read from)
   integer: length (of data you want to read)
Returns:
   text: The data read (if success), otherwise it is the error code.
return code (0 is success)

This allows you to read data from the dongle data area (for Dinkey 2/DinkeyNet).
     

After you have called either the DDProtCheck or DDProtCheckWithAlg or DDWriteData or
DDReadData functions you can call one of the following functions to get data from
the DRIS. These functions will all return -1 if a protection check has not been
performed. They will return -2 if a protection check has been performed but failed.
They all take a dummy parameter (integer) which can be any value you like (it is
ignored). They all have text outputs. Refer to the documentation regarding the DRIS
for more information on each of these fields.

DDGetExtendedError - returns the extended error (only set if one of the protection check function has failed)
DDGetType - returns the type of dongle detected ("Pro" or "FD")
DDGetModel - returns the model of the dongle detected. Numerical value - see documentation on DRIS.
DDGetSDSN	- returns the SDSN.
DDGetProdCode - returns the Product Code.
DDGetDongleNumber - returns the donglenumber
DDGetUpdateNumber - returns the update number
DDGetDataAreaSize - returns the size of the data are
DDGetMaxAlgNum - returns the maximum algorithm number in the dongle detected
DDGetExecs - returns the execs left (number or "no limit")
DDGetExpDay - returns the expiry day (number or "no limit")
DDGetExpMonth - returns the expiry month (number or "no limit")
DDGetExpYear - returns the expiry year (number or "no limit")
DDGetFeatures - returns the features value.
DDGetNetUsers - returns the maximum number of simultaneous network user allowed by the dongle (number or "no limit")
DDGetAlgAnswer - returns the answer of the Algorithm (if specified)
DDGetFDCapacity - returns the maximum capacity for the data area if an FD dongle is detected
DDGetFDDrive - returns the drive letter (mount name) of FD dongle detected e.g. f:\ 
DDGetSWKeyType - returns whether a software key has been detected and what type it is
DDGetSWKeyExpDay - returns the expiry day of the swkey detected (if one has been detected)
DDGetSWKeyExpMonth - returns the expiry month of the swkey detected (if one has been detected)
DDGetSWKeyExpYear - returns the expiry year of the swkey detected (if one has been detected)

Note - because of the limitations of the Filemaker scripting language you cannot encrypt
the DRIS or data passed to the API.

DRIS Flags Values
~~~~~~~~~~~~~~~~~
In general the flags value will be 0. If you want to use more than one flag then add the values.

Value  Name in Manual           Description
1      DEC_ONE_EXEC             decrement executions by 1 
2      DEC_MANY_EXECS           decrement executions by number specified in execs_decrement
4      START_NET_USER           start a network user
8      STOP_NET_USER            stops a network user (a protection check is NOT performed)
16     USE_FUNCTION_ARGUMENT    use the extra argument in the function to pass data
32     CHECK_LOCAL_FIRST        always look for a dongle locally before looking in network ports
64     CHECK_NETWORK_FIRST      always look for a network dongle before looking for a dongle locally
128    USE_ALT_LICENCE_NAME     use name specified in alt_licence_name instead of the default one
256    DONT_SET_MAXDAYS_EXPIRY  if the max days expiry date has not been calculated then do not do it this time
512    MATCH_DONGLE_NUMBER      restrict the search to match the dongle number specified in the DRIS
1024   DONT_RETURN_FD_DRIVE     if you have protected your solution to a Dinkey FD dongle then this flag
                                means that the flash disk drive letter or mount name will not be returned

Filemaker7 plugin tested on filemaker version 7 (Mac and Windows 32-bit).
Filemaker14 plugin tested on Filemaker 15 (Mac and 64-bit Windows) and on Filemaker 14 (Mac 64-bit mode and Windows 32-bit)
