<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Using the DinkeyChange API with Java</title>
<style>
body {
color: black;
font-family: Verdana, Arial, Helvetica, sans-serif;
font-size: 13px;
margin: 25px auto;
max-width: 800px;
}
p, ul, ol, table {
margin-top: 0;
margin-bottom: 15px;
}
ul.contents a {
text-decoration: none;
}
h1,h2,h3,h4,h5,h6 {
margin-top: 25px;
margin-bottom: 15px;
}
h2 {
border-top: 1px solid gray;
}
table {
margin-left: auto;
margin-right: auto;
border-collapse: collapse;
}
th, td {
border: 1px solid black;
padding: 0.5em;
text-align: left;
}
.ui_element
{ /* Use for things like program options and menu items */
color: #008000;
font-style: italic;
}
.filepath
{ /* Use for paths and filenames */
font-family: monospace;
font-size: 13px;
font-weight: bold;
}
.manual
{ /* Use when referring to user manual sections/chapters */
font-style: italic;
}
.alert
{
border: 1px solid black;
padding: 15px 15px 15px 58px;
font-weight: bold;
background-repeat: no-repeat;
background-position: 5px 15px;
margin-bottom: 15px;
}
.important
{
background-color: #FFFDD0;
background-image: url('data:image/png;base64,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');
}
.information
{
background-color: #EBF8FF;
background-image: url('data:image/png;base64,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');
}
.alert > p:last-child, .alert > ul:last-child, .alert > ol:last-child
{
/* Cancel double space at bottom of alert caused by above rule */
margin-bottom: 0;
}
.important .filepath, .information .filepath {
/* Make filepaths stand out in sections that are already bold */
font-weight: normal;
}
div.col_wrapper
{
clear: both;
overflow: hidden;
}
div.two_col
{
width: 50%;
float: left;
}
code {
color: gray;
white-space: nowrap;
}
pre {
padding: 15px;
background-color: #EEEEEE;
}
pre > code { /* Block level code snippets */
white-space: pre; /* Override nowrap used for inline code */
color: inherit;
}
code .comment
{
color: green;
}
code .keyword
{
font-weight: bold;
color: blue;
}
code .string
{
color: #A00000;
}
code .constant
{
font-weight: bold;
}
</style>
</head>
<body>
<h1>Using the DinkeyChange API with Java</h1>
<p>
The DinkeyChange API allows you apply secure update codes to modify the information
stored in Dinkey Pro and FD dongles directly from your Java application.
The API also allows you to view the information needed to create these codes, and produce
encrypted diagnostic files to help you troubleshoot any dongle-related problems your users might have.
</p>
<p>
The <code>DinkeyChange</code> class provides a Java wrapper around the API, which is implemented by native libraries.
If you are not familiar with calling native libraries, it is recommended that you read the Java documentation on the subject,
especially the documentation for <code>System.loadLibrary()</code>,
and how Java uses the system property <code>java.library.path</code> to locate native libraries.
</p>
<p>
The native libraries and the classes described below are part of the <code>uk.microcosm.dinkeydongle</code> package.
See the documentation for your development environment for details of how to include and reference this package in your project.
<span class="filepath">dinkeydongle.jar</span> provides all of the Java classes in the <code>uk.microcosm.dinkeydongle</code> package in a single JAR file.
This allows you to import the package much more easily in many Java IDEs. Note that the native libraries are <strong>not</strong> included in the JAR file.
You will need to distribute with your software the native libraries for every platform that your software supports.
</p>
<h2>The DinkeyChange Class</h2>
<p>
This class exposes the DinkeyChange API to Java programs.
It contains only static methods and fields, and cannot be instantiated.
</p>
<h3>Fields</h3>
<p>
Useful constants you can use in your code:
</p>
<ul>
<li><code>static final int MAX_USB_DEVICES</code> - maximum number of dongles that the API can return information about.</li>
<li><code>static final int MAX_PRODCODE_LEN</code> - maximum length of a product code string.</li>
</ul>
<p>
Possible values to use as the <code>typeMask</code> parameter of <code>DinkeyChange.getDongles()</code>:
</p>
<ul>
<li><code>static final int TYPE_MASK_PRO</code> - search for Dinkey Pro dongles only.</li>
<li><code>static final int TYPE_MASK_FD</code> - search for Dinkey FD dongles only.</li>
<li><code>static final int TYPE_MASK_ALL</code> - search for both Dinkey Pro and FD dongles.</li>
</ul>
<p>
Possible values to use as the <code>modelMask</code> parameter of <code>DinkeyChange.getDongles()</code>:
</p>
<ul>
<li><code>static final int MODEL_MASK_LITE</code> - search for Lite dongles only.</li>
<li><code>static final int MODEL_MASK_PLUS</code> - search for Plus dongles only.</li>
<li><code>static final int MODEL_MASK_NET</code> - search for Net dongles only.</li>
<li><code>static final int MODEL_MASK_ALL</code> - search for all models of dongle.</li>
<li><code>static final int MODEL_MASK_DEFAULT</code> - search only for models that can be modified using update codes (i.e. ignore Lite dongles.)</li>
</ul>
<p>
Possible values to use as the <code>model</code> parameter of <code>DinkeyChange.downloadDemoSoftwareKey()</code>:
</p>
<ul>
<li><code>static final int SWKEY_MODEL_DEFAULT </code> - download the default model (valid only if exactly one model is set in the demo key template).</li>
<li><code>static final int SWKEY_MODEL_PRO_LITE </code> - download a Pro Lite demo software key.</li>
<li><code>static final int SWKEY_MODEL_PRO_PLUS</code> - download a Pro Plus demo software key.</li>
<li><code>static final int SWKEY_MODEL_PRO_NET</code> - download a Pro Net demo software key.</li>
<li><code>static final int SWKEY_MODEL_FD_LITE </code> - download an FD Lite demo software key.</li>
<li><code>static final int SWKEY_MODEL_FD_PLUS</code> - download an FD Plus demo software key.</li>
<li><code>static final int SWKEY_MODEL_FD_NET</code> - download an FD Net demo software key.</li>
</ul>
<h3>Methods</h3>
<p>
All methods in this class throw a <code>DinkeyChangeException</code> if the underlying native API call fails.
The <code>DinkeyChangeException</code> contains the error code and extended error code returned by the native API function.
</p>
<h4>static DongleToChange[] getDongles(int typeMask, int modelMask, String productCodeMask)</h4>
<p>
Returns a list of the dongles attached to this computer that match the search criteria specified by the method's arguments.
<code>typeMask</code> and <code>modelMask</code> should be set to one of the possible values listed above.
If <code>productCodeMask</code> is specified, only dongles with a product code that exactly matches (case is not important) this string will be returned.
In most cases this string will be the product code of your protected application.
Use <code>null</code> or the empty string as this parameter to search for dongles with any product code.
</p>
<h4>static String writeDiagnosticsToFile(String filename)</h4>
<p>
Writes diagnostic information about all dongles connnected to this computer to the file specified by <code>filename</code>.
The output file is encrypted, and its contents can only be viewed using DinkeyLook.
The path to the file can be absolute, or relative to the current working directory.
If the filename does not end in ".dlpf" this extension will be added automatically.
This method returns the absolute path to the file created.
</p>
<h4>static String writeDiagnosticsToFile(java.io.File file)</h4>
<p>
Writes diagnostic information about all dongles connnected to this computer to the file represented by <code>file</code>.
The output file is encrypted, and its contents can only be viewed using DinkeyLook.
The path to the file can be absolute, or relative to the current working directory.
If the filename does not end in ".dlpf" this extension will be added automatically.
This method returns the absolute path to the file created.
</p>
<h4>static int applyUpdate(String updateCode)</h4>
<p>
Applies a short secure update code to a dongle connected to this computer.
Returns the confirmation code for this update.
</p>
<h4>static int applyUpdate(java.io.File updateFile)</h4>
<p>
Applies the secure update code in the file represented by <code>updateFile</code> to a dongle connected to this computer.
Returns the confirmation code for this update.
</p>
<h4>static void restoreDinkeyFDLite()</h4>
<p>
Restores the hidden <span class="filepath">.DO NOT DELETE.dat</span> on a Dinkey FD Lite dongle.
</p>
<h4>static long getmachineID()</h4>
<p>
Returns the machine ID required to generate a temporary software key for this computer.
</p>
<h4>static void downloadTempSoftwareKey()</h4>
<p>
Downloads and installs a temporary software key that was created by DinkeyAdd.
</p>
<h4>static void downloadDemoSoftwareKey(String productCode, int model)</h4>
<p>
Downloads and installs a demo software key from a demo template that was created by DinkeyAdd.
<code>productCode</code> specifies the product code of the demo template to download the key from.
<code>model</code> specifies the model of demo key to download, and should be set to one of the values listed above.
</p>
<h2>The DongleToChange Class</h2>
<p>
An instance of <code>DongleToChange</code> represents one dongle found by <code>DinkeyChange.getDongles()</code>.
</p>
<h3>Fields</h3>
<p>
Possible values for <code>type</code>:
</p>
<ul>
<li><code>static final int TYPE_PRO</code> - a Dinkey Pro dongle.</li>
<li><code>static final int TYPE_FD</code> - a Dinkey FD dongle.</li>
</ul>
<p>
Possible values for <code>mask</code>:
</p>
<ul>
<li><code>static final int MODEL_LITE</code> - a Lite dongle.</li>
<li><code>static final int MODEL_PLUS</code> - a Plus dongle.</li>
<li><code>static final int MODEL_NET5</code> - a Net dongle (5 users).</li>
<li><code>static final int MODEL_NETU</code> - a Net dongle (unlimited users).</li>
</ul>
<p>
Fields that provide information needed to create an update code for this dongle:
</p>
<ul>
<li><code>final int type</code> - integer representation of the dongle type.</li>
<li><code>final String typeAsString</code> - string representation of the dongle type.</li>
<li><code>final int model</code> - integer representation of the dongle model.</li>
<li><code>final String modelAsString</code> - string representation of the dongle model.</li>
<li><code>final String productCode</code> - the dongle's product code.</li>
<li><code>final long dongleNumber</code> - the dongle's dongle number (sometimes called dongle serial number).</li>
<li><code>final int updateNumber</code> - the dongle's update number.</li>
</ul>
<h2>The DinkeyChangeException Class</h2>
<p>
An instance of this <code>Exception</code> subclass is thrown if a call to the DinkeyChange API fails.
The usual <code>getMessage()</code> method returns a string providing general information about the error.
If the problem occurred in Java code, <code>getCause()</code> will return the Java exception that caused the <code>DinkeyChangeException</code>.
</p>
<h3>Methods</h3>
<p>
<code>DinkeyChangeException</code>'s methods provide further details about the error that occurred.
It is strongly recommended that you display this information in the event of an error,
to help both you and us troubleshoot a recurring problem.
More information about Dinkey Pro/FD error numbers can be found in the user manual chapter <span class="manual">Error Codes</span>
and online in our <a href="http://www.microcosm.co.uk/kb">knowledge base</a>.
</p>
<h4>int getError()</h4>
<p>
Returns an error code indicating the cause of the error.
</p>
<h4>int getExtendedError()</h4>
<p>
Returns an extended error code providing additional information about the error.
</p>
<h2>Java Example Files</h2>
<ul>
<li><span class="filepath">DCSample.java</span> - various examples of using the DinkeyChange classes.</li>
</ul>
<h2>Supported Versions</h2>
<p>
All parts of the <code>uk.microcosm.dinkeydongle</code> package support Java platforms version 5 and newer.
</p>
<h2>Try It Yourself</h2>
<p>
<span class="filepath">DCSample.java</span> gives a simple example of calling each of the API functions.
To run the DCSample program you will need a copy of the appropriate shared library for your platform
(<span class="filepath">DinkeyChange.dll</span> for 32-bit Windows, <span class="filepath">DinkeyChange64.so</span> for 64-bit Linux etc.).
Place the library in one of the paths specified by your Java environment's <code>java.library.path</code> system property.
Browse the examples in <code>DCSample.java</code> to see how different features can be used.
</p>
</body>
</html>
