Notes on using AutoCAD with Dinkey Pro/FD
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To access a Dinkey Pro or FD dongle from AutoCAD, you must call an ActiveX DLL
using Visual LISP (AutoLISP). It is called dpcom32.dll (for 32-bit AutoCAD) and
dpcom64.dll (for 64-bit AutoCAD). These files are located in the Modules folder of
your SDK installation directory.

This ActiveX control is an intermediary layer that calls the normal dpwin32.dll (32-bit)
or dpwin64.dll (64-bit) Runtime module. To protect your application, you should add
protection to dpwin32.dll (or dpwin64.dll) using DinkeyAdd specifying the API method
of protection. You should not protect dpcom32.dll (dpcom64.dll). [if you used a version
of the SDK previous to v7.0 please read the notes at the end of this file].

On 64-bit operating systems AutoCAD will always be 64-bit and on 32-bit operating
systems AutoCAD will always be 32-bit. You need to use the appropriate protected
ActiveX control (dpcom32.dll or dpcom64.dll) and protected Runtime module (dpwin32.dll
or dpwin64.dll) depending on whether 32-bit AutoCAD or 64-bit AutoCAD is being used.

We recommend that you rename the protected runtime module. (reason: you may have more than
one Autocad product you want to protect. In this case, for each product, you can protect
our Runtime module (renamed in each case to a different filename) to different protection
parameters).

To use the ActiveX control you must first register it with Windows:

go to Start > All Programs > Accessories, right-click Command Prompt and choose
"Run As Administrator". Then enter:

    regsvr32 "<path to location of DLL>\dpcom32.dll"

To unregister it enter:

    regsvr32 /U "<path to location of DLL>\dpcom32.dll"

[For 64-bit Windows, replace dpcom32.dll with dpcom64.dll].

The ActiveX control needs to be registered on your end-users's machines.
Most installation programs allow you to do this automatically so that your
customers do not have to.

The ActiveX control internally contains a DRIS structure. The idea is that,
after calling the initialisation function, you call one of the protection check
functions and then call as many of the Get... functions as you like to get the
parameters normally filled-in to the DRIS. These values remain valid until the
next protection check call when they are updated.

Protecting AutoCAD programs using this ActiveX is not as secure compared to other
languages because of limitations of the AutoLISP programming language. For example
you cannot encrypt the DRIS or data passed to and from the API. To increase
security you can use an algorithm (see the ProtCheckWithAlg function).

The API provided by dpcom32.dll / dpcom64.dll is listed below. There is also some
very simple sample code - dpsample.lsp. 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.

(See "Structures > DRIS Structure" in the user manual for an explanation of the parameters).

** You must call the Initialisation Function, InitDPCOM, first **

InitDPCOM
~~~~~~~~~
syntax:
    (InitDPCOM bsDllName)
return:
    return code (0 is success, otherwise one of the following errors can be returned:
	             9003 - dll you specified cannot be loaded. Either not present in the correct
                        folder or you specified the wrong name / path.
                 9004 - dll is loaded correctly but is not our runtime module!                 
notes:
    this function must be called first to initialise the COM control
	the parameter you pass is the renamed version of the protected runtime module
	this module should be in the same folder as the COM control (if not you need
	to specify the relative path and the filename). A typical call would be:
	"InitDPCOM" "my_protected_dpwin32.dll"

** Then you should call one of the Protection Check Functions listed below. **
** In addition to the normal runtime errors returned by our runtime modules **
** they can also return the error 9000 (InitDPCom not called).
	
ProtCheck
~~~~~~~~~
syntax:
    (ProtCheck flags execs_decrement alt_licence_name)
returns:
    return code (0 = success, otherwise an error number is returned)
notes:
	performs a standard protection check.
	see table below for details of flags values. You must specify execs_decrement
	and alt_licence_name even if they are not used. A typical call would be:
	"ProtCheck" 0 0 ""

ProtCheckWithAlg
~~~~~~~~~~~~~~~~
syntax:
    (ProtCheckWithAlg flags alg_number var_a var_b var_c var_d var_e var_f var_g var_h )
returns:
    return code (0 = success, o.w. error number)
notes:
    Performs a protection check and executes the user algorithm 'alg_number'
	with variable values 'var_a'...'var_h'.
    Call (GetAlgAnswer) to get the result of this algorithm after successfully calling
	this function.

WriteString
~~~~~~~~~~~
syntax:
	(WriteString flags offset DataString)
returns:
    return code (0 = success, o.w. error number)
notes:
    Performs a protection check and writes the string "DataString" to the dongle
	data area at the offset specified.

ReadString
~~~~~~~~~~~
syntax:
	(ReadString flags offset length)
returns:
    return code (0 = success, o.w. error number)
notes:
    Performs a protection check and reads data from the dongle data area.
	Call (GetDataRead) to read the data string after successfully calling this function.


** After you have called either the ProtCheck or ProtCheckWithAlg or WriteString or  **
** ReadString functions you can call one of the following functions to get data from **
** the DRIS. These functions will all return -2 (or "-2") if a protection check has  **
** not been performed. They will return -3 (or "-3") if a protection check has been  **
** performed but failed. Refer to the documentation regarding the DRIS for more      **
** information on each of these fields.

None of these methods require input parameters.

GetExtendedError - returns the extended error (only set if one of the protection check functions has failed)
GetType - returns the type of dongle detected. Numerical value - see DRIS documentation.
GetModel - returns the model of the dongle detected. Numerical value - see documentation on DRIS.
GetSDSN	- returns the SDSN.
GetProdCode - returns the Product Code as a string.
GetDongleNumber - returns the donglenumber as a string.
GetUpdateNumber - returns the update number
GetDataAreaSize - returns the size of the data are
GetMaxAlgNum - returns the maximum algorithm number in the dongle detected
GetExecs - returns the execs left (-1 is "no limit")
GetExpDay - returns the expiry day (-1 is "no limit")
GetExpMonth - returns the expiry month (-1 is "no limit")
GetExpYear - returns the expiry year (-1 is "no limit")
GetFeatures - returns the features value.
GetNetUsers - returns the maximum number of simultaneous network user allowed by the dongle (-1 is "no lmiit")
GetAlgAnswer - returns the answer of the Algorithm (only valid if ProtCheckWithAlg previously called)
GetFDCapacity - returns the maximum capacity for the data area if an FD dongle is detected
GetFDDrive - returns the drive letter (mount name) of FD dongle detected e.g. f:\
GetDataRead - returns the read read from the dongle data area (only valid if ReadString previously called).
GetSWKeyType - returns whether a software key was detected and what type it is
GetSWKeyExpDay - software key expiry day (if a software key was detected)
GetSWKeyExpMonth - software key expiry month
GetSWKeyExpYear - software key expiry year

Visual LISP Code Example
~~~~~~~~~~~~~~~~~~~~~~~~
dpsample.lsp gives a simple example of using the Dinkey Pro/FD API from Visual LISP.
To run dpsample.lsp:

1. Enter 'vlisp' (without the quotes) on the AutoCAD command line to open the Visual LISP editor.
2. Open dpsample.lsp (and then click on the Window that contains the script to give it focus).
3. Use the toolbar or the menu 'Tools > Load Text in Editor' to load the dpsample function.
4. Enter '(dpsample)' (without the quotes) on the command line to execute the function.

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 an FD dongle has been detected then don't return the flash drive/mount name in the DRIS

Notes on Changes Made to the ActiveX Control since version previous to 7.0
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ActiveX controls we provided with versions of the SDK previous to 7.0 did not depend on
the runtime module and had to be protected directly. However, you can only register one of these
COMs per machine (renaming the file does not help in this case because it is identified by an internal
GUID which cannot be change).

This meant that you could only protect one Product per machine. These old COM controls were loaded
using "DPro.DPro.1". The new COM controls can be loaded using "DPro.DPro.2". You can register both
COM controls on one machine at the same time if you need too as they have different internal GUIDs.
