sample - sample code for DinkeyPro/FD in 4D
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This sample code is written using 4D v12 but will work with later versions of 4D.

The sample code calls a 4D plugin which we provide. This plugin is compatible with
4D versions 11 and higher. It is called ddpro.bundle. This is a series of directories
and files. The most important are shown here:

ddpro.bundle
    Contents
	    Windows
		    ddpro.4dx
	    Windows64
		    ddpro.4dx
		MacOS
		    ddpro
        Resources

This same bundle is provided in the Windows and Mac OSX SDKs and will support Mac OS X and
Windows 32-bit and 64-bit Operating Systems.		
		
For Mac OS X this directory structure is recognised as a single file: ddpro.bundle. You can
explore the contents of the bundle by choosing "Show Package Contents".

For the sample database to work properly you need to have a Plugins folder (located in the same
place as the sample database) and include the protected ddpro.bundle in the Plugins folder. 

For Mac machines you just place ddpro.bundle in this folder. For Windows you need to copy
the whole structure to the Plugins folder.

Note - the actual Plugin file you need to protect is the file in Contents\<OS name>.
For Windows it is called ddpro.4dx. For Mac OSX it is called ddpro. You need to protect
this file (and not your database) with DinkeyAdd with the API Method. You should protect
the relevant file for each Operating System you want to support. So, for example, if you
want to support MacOSX and 32-bit, 64-bit Windows you should protect these files:
ddpro.bundle\Contents\Windows\ddpro.4dx
ddpro.bundle\Contents\Windows64\ddpro.4dx
ddpro.bundle\Contents\MacOS\ddpro

If you don't want to support a particular operating system you can delete that folder. 

Because your database is dependent on the protected plugin then it is itself protected. 

You can then supply the whole protected bundle to your customers.

The sample code contains many Project Methods. However, there are 10 main functions
that you can use in your code. You will not need to use all these functions in your
code. Just use which ever functions are most appropriate and customise in your own way.
The sample code is just a guide. You should implement the protection in a stronger way
using the techniques described in the "Increasing your Protection" chapter of the manual.

For example you can call one (or more) of these functions when your database opens.
(Database Methods | On Startup). This has been implemented in the sample code but has
been commented out otherwise you would need a correctly programmed dongle to open it!
For this reason it is probably best to keep an unprotected copy of your database before
you start adding protection.

The 10 main functions are:

// this file contains 10 protection-check functions.
ProtCheck                 a standard protection check
ProtCheckWithAlg          a protection check & executing an Algorithm
WriteBytes                a protection check & write data to the dongle
ReadBytes                 a protection check & read data from the dongle
EncryptUserData           a protection check & encrypting data and then decrypting the data
// these functions are the same as the functions listed above but encrypting all parameters passed to our API
ProtCheckEnc              a standard protection check
ProtCheckWithAlgEnc       a protection check & executing an Algorithm
WriteBytesEnc             a protection check & write data to the dongle
ReadBytesEnc              a protection check & read data from the dongle
EncryptUserDataEnc        a protection check & encrypting data and then decrypting the data

If you are using Dinkey Lite then you can only use 4 functions:
ProtCheck, ProtCheckWithAlg, ProtCheckEnc, ProtCheckWithAlgEnc

These functions also depend on some other simpler functions (check to see which functions
are references and also include those in your code). For example, you will always need
to include:

InitialiseDris
SetDrisFunction
SetDrisFlags
DisplayError
GetDrisSDSN
GetDrisExtErr

The sample code has been implemented so that you build up the DRIS as a BLOB variable.
We have provided SetDris... functions to set various values in the DRIS and GetDris...
functions to get values fro the Dris. So you will also need to include all the GetDris...
and SetDris... functions that you need. 

Code marked with !!!! are places where you should customise the sample code so
that it will work properly:

* Change the SDSN value from 10101 to the value of your SDSN in the 10 main functions.
* Change the Product Code value from DEMO if you are using ProtCheck or ProtCheckEnc functions.
* Change the MyAlgorithm code (if you call a user algorithm)
* Change the CryptDRIS code (if you encrypt the DRIS)
* Change the CryptApiData (if you encrypt Data you send to our API)
* Change the MyRWAlgorithm code (if encrypt Data you send to our API using the R/W algorithm)

You will also probably want to replace our error messages (DisplayError) with your own.

Note:

When you first use the plug-in you will get error 413. This is because you have not
protected it. To do this run DinkeyAdd and protect the plug-in file specifying the API Method.
Note - you should protect our 4D plugin and not your program. Because your program depends
on the 4D plugin it is also protected. See notes at the beginning of this file for more details.

Note:

We needed to insert an extra line of code into the sample just before the protection check:

// this line is only required because of a bug in 4D (see readme.txt for more info)
SET BLOB SIZE($dris;DRIS SIZE;0)

This is due to a bug in 4D which causes 4D to crash if the database is running in compiled
mode (or as a 4DC file). This bug existed in 4D v12.6. It may have been fixed in later versions
in which case you can remove this line. However, there is no harm in continuing to include
this line in your code.
 