# Using Dinkey Pro/FD with Excel

The Shell protection method supports Windows executables produced by the DoneEx XCell Compiler.

API protection checks in Excel are implemented by adding Visual Basic for Applications (VBA) code to your workbook. The VBA module DinkeyPro.bas is used to communicate with the dongle via the appropriate API DLL (dpwin32.dll on 32-bit Windows, dpwin64.dll on 64-bit Windows). You should lock these DLLs with the API method using DinkeyAdd as described in the user manual, and distribute the locked DLLs with your software.

Using the DoneEx XCell Compiler and the Shell method is the preferred option for most Excel users, as it does not require you to write any VBA macro code, and so is easier to implement.

## XCell Compiler and the Shell Method

The DoneEx XCell Compiler converts an Excel workbook into an executable file (a program). All of your data, formulas and VBA macro code are stored encrypted, which makes this method very secure. XCell Compiler is a separate tool that must be purchased separately. A free trial is available to allow you to evaluate its functionality before buying.

There are a few things that you should be aware of when protecting your workbook with XCell Compiler and Dinkey Pro/FD:

- You must use the XCell Compiler option Save into external storage (XSTG file). This option means that your protected workbook's data is encrypted and securely stored in a separate file, not in the executable. This is necessary to allow changes to your workbook to be saved, as Shell-protected executables cannot be modified.

- If you use the Shell method background check (recommended and enabled by default), if a background protection check fails then your protected workbook will be immediately closed without any warning messages, and any unsaved changes will be lost.

- When a user closes your protected workbook, Excel will always ask the user if they want to save changes, even if no changes have been made.

## VBA Code and the API Method

For a good level of security, your workbook should rely heavily on VBA code (macros). See below for more information.

Before you distribute your protected workbook, you must protect your VBA code against modification. To do this:

1. Open your project in the Visual Basic Editor.
2. Go to Tools > VBAProject Properties in the menu.
3. Select the Protection tab.
4. Enable Lock project for viewing and enter a strong password, then click OK.

Now the workbook's VBA code cannot be viewed or modified without entering the password.

Even if you have never written code before, you will probably be familiar with macros: sequences of commands and functions that you can use to automate tasks in Excel. Excel macros are stored in modules that contain sequences of instructions in a code language known as Visual Basic for Applications, or VBA. The terms macros and VBA are often used interchangeably.

VBA code is a powerful and flexible tool with many uses. Unfortunately, the power of VBA means that macros created with malicious intentions can cause harm to your documents or your system. As a result, Excel makes it possible for users to open and use workbooks with macros disabled, and to only allow the VBA code to be executed if the user trusts the owner of the workbook. Obviously, this also prevents dongle checking code from running. To prevent someone using this safety feature to work around the dongle protection, you should ensure that the functionality of your workbook relies heavily on macros. That way if your workbook is opened with macros disabled, its functionality will be severely limited.

Legitimate users of your workbook may be concerned about executing the VBA code in your workbook. Excel allows you to certify your macros with a digital signature so that users can verify that they are from a trustworthy source (i.e. you), and that the code has not been modified since you wrote it. See the Excel documentation for more information.

### Excel Example Files

- DinkeyPro.bas - a module that provides a VBA interface to the Dinkey Pro/FD API.
- DPSample.xls - various examples of using DinkeyPro.bas.

DinkeyPro.bas should be used, without modification, in your own project. Use File > Import File in the Visual Basic Editor to add DinkeyPro.bas to your VBA code.

### Supported Versions

The Excel sample workbook and VBA code provided with the Dinkey Pro/FD SDK was created using Excel 2007, and tested using Excel 2007 (32-bit) and Excel 2013 (64-bit). All newer versions should be backwards compatible. The sample code should also work with older versions, but no guarantees can be made, and support for older versions is likely to be very limited.

### Try It Yourself

The sample code is designed to teach you how to use the Dinkey Pro/FD API in Excel workbooks. Do not copy the examples verbatim into your own code. Experiment with the sample code to understand how the API works, and read the chapter Increasing Your Protection in the user manual for many suggestions on how to make the best use of the API features.

DPSample.xls gives simple examples of performing a protection check, as well as using various other features of Dinkey Pro/FD. To use DPSample.xls you will first need to use DinkeyAdd to produce a locked copy of the DLL for your platform, and program a dongle (if you are using Plus or Net dongles). Place the locked DLL in the same folder as the example files.

Open DPSample.xls in Excel, then open the Visual Basic Editor by pressing ALT+F11. Browse the examples in the DPSample module to see how different features can be used. All the examples follow the same basic pattern:

1. Set up the `DRIS` structure with the relevant information.
2. Call the API.
3. Use the information returned in the `DRIS`.

Uncomment the function calls in the `RunExampleButton_Click()` procedure in the DPSample module to enable the examples of different features, then click the Run Example button on Sheet1 of the workbook to run the examples.

The DPSample module also demonstrates loading the appropriate DLL for your platform.

Parts of the sample code are marked with `!!!!` must be customised with your own functions or values for some features to work correctly. Not all features are supported by all dongle models. See the user manual for more information.