# Using the DinkeyChange API with MATLAB

If you are not already familiar with calling shared libraries from MATLAB code, it is strongly recommended that you read the MATLAB documentation on this topic. Depending on your version of MATLAB, you may need to install a C compiler and configure MATLAB to use it with the command `mex -setup`. Again, refer to the MATLAB documentation for further information.

See Remote Parameter Changing > DinkeyChange > DinkeyChange.dll in the user manual for information on using the DinkeyChange API. Use the `help` command to see overviews of how each M-file interface to the DinkeyChange API is used in MATLAB. Most of the DinkeyChange M-files are simple MATLAB wrappers for the shared library functions. dcgetinfo.m however is quite different to the `DCGetInfo()` function described in the user manual:

    [retCode, dongleArray] = dcgetinfo(libName, typeMask, modelMask, prodcodeMask)

The inputs `typeMask`, `modelMask` and `prodcodeMask` are used in the same way as the inputs of `DCGetInfo()`, as dcsample.m illustrates. The outputs however are grouped together as `dongleArray`, a 1-by-N vector of MATLAB structures. Each structure represents a dongle found by `dcgetinfo`'s search, and each structure has the following fields:

Field | Data Type | Description
--- | --- | ---

type

int32

The dongle's type as a numeric value. Possible values:

- 1 for Dinkey Pro dongles
- 2 for Dinkey FD dongles

type_as_string

char

The dongle's type as a string. Possible values:

- "Pro"
- "FD"

model

int32

The dongle's model as a numeric value. Possible values:

- 1 for Lite dongles
- 2 for Plus dongles
- 4 for Net dongles (5 users)
- 7 for Net dongles (unlimited users)

model_as_string

char

The dongle's model as a string. Possible values:

- "Lite"
- "Plus"
- "Net (5 users)"
- "Net (unlimited users)"

product_code | char | The dongle's product code
dongle_number | uint32 | The dongle's serial number (dongle number)
update_number | int32 | The dongle's update number

## MATLAB Example Files

- dcgetinfo.m - an M-file that provides a MATLAB interface to the `DCGetInfo()` API function.
- dcgetdiagnosticinfo.m - a MATLAB interface to the `DCGetDiagnosticInfo()` API function.
- dcdoupdatecodestring.m - a MATLAB interface to the `DCDoUpdateCodeString()` API function.
- dcdoupdatecodefromfile.m - a MATLAB interface to the `DCDoUpdateCodeFromFile()` API function.
- dcrestoredinkeyfdlite.m - a MATLAB interface to the `DCRestoreDinkeyFDLite()` API function.
- dcgetmachineid.m - a MATLAB interface to the `DCGetMachineID()` API function.
- dcdownloadtempsoftwarekey.m - a MATLAB interface to the `DCDownloadTempSoftwareKey()` API function.
- dcdownloaddemosoftwarekey.m - a MATLAB interface to the `DCDownloadDemoSoftwareKey()` API function.
- dcsample.m - examples of using these M-files.
- dinkeychangewin32proto.p - a prototype P-file that defines the signatures of the API functions for 32-bit MATLAB on Windows.
- dinkeychange32proto.p - a prototype P-file that defines the signatures of the API functions for 32-bit MATLAB on all other supported platforms.
- dinkeychange64proto.p - a prototype P-file that defines the signatures of the API functions for 64-bit MATLAB on all supported platforms.
- DinkeyChange64_thunk_pcwin64.dll - a compatibility layer required by 64-bit MATLAB to use DinkeyChange64.dll.

The appropriate prototype P-file and any M-files that you call should be included, without modification, in your own project. If you are using 64-bit MATLAB on Windows, you should also include DinkeyChange64_thunk_pcwin64.dll. If you rename DinkeyChange64.dll, you must change the DinkeyChange64 part of the thunking DLL's filename accordingly.

Our M-files and P-files are compatible with MATLAB on macOS and Linux. However, we do not currently provide the thunk files required by 64-bit MATLAB on these platforms. If you want to use the DinkeyChange API on 64-bit macOS and/or 64-bit Linux, please contact us with full details of the platform(s) and MATLAB versions that you want to use, and we can provide compatible thunk files or instruct you on how to produce these files yourself.

## Supported Versions

The MATLAB sample code provided with the Dinkey Pro/FD SDK was written and tested using MATLAB R2013a. All newer versions should be backwards compatible. The sample code may 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

dcsample.m gives a simple example of calling each of the API functions. To run dcsample.m you will need a copy of the appropriate shared library for your platform (DinkeyChange.dll for 32-bit Windows, DinkeyChange64.so for 64-bit Linux etc.). Place the library in the same folder as the example files and change MATLAB's current directory to this folder. Browse the examples in dcsample.m to see how different features can be used.

Uncomment the function calls at the top of dcsample.m to enable the examples of different features, then enter `dcsample` in the Command Window to run the examples.

dcsample.m also demonstrates loading and unloading the appropriate shared library for your platform.

Parts of the sample code 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.