Utiliser une DLL dans un programme Java

Utiliser une DLL dans un programme Java
Extrait du PoBot
http://www.pobot.org
Utiliser une DLL dans un
programme Java
- L'association - Nos réalisations - Logiciels -
Date de mise en ligne : dimanche 11 janvier 2009
Description :
Pour contrôler certaines cartes électroniques, il est nécessaire d'utiliser la bibliothèques de fonctions (library) fournie par le constructeur sous. Ici, nous allons
appeler les fonctions d'une DLL depuis un programme en Java (Processing) car c'est simple et gratuit.
PoBot
Copyright © PoBot
Page 1/8
Utiliser une DLL dans un programme Java
Sommaire
• Principe d'accès à une (...)
• Cas pratique
Parfois en robotique et encore plus souvent en électronique, les fabricants imposent d'utiliser une DLL (ou Dynamic
Linked Library) pour contrôler leur produit. Par exemple un modem radio (Ant) ou une carte d'interface entrée/sortie
pour expérimentations (kits Velleman).
Il s'agit d'un groupe de fonctions réunis dans un fichier binaire (pas de code source disponible) que notre programme
doit exécuter. Les DLL sont spécifiques à Windows (il existe aussi des bibliothèques logicielles de principe similaire
sous Linux et MaxOS, les .so ou "shared objects", .dylib ou "dynamic library", .sl ou "shared library", etc...) et
généralement on développe un programme en Basic ou en C/C++ pour les utiliser.
Dans cet article, nous allons expliquer comment appeler les fonctions d'une DLL, donc accéder aux ressources de
notre équipement électronique, depuis un programme Java, en l'occurence depuis l'environnement "Processing" qui
est vraiment très simple et très pratique (nous avons réalisé ou utilisé plusieurs applets Processing décrites sur ce
site : étude du PID, oscilloscope minimal de Sofian Audry, radar, contrôleur 3D, ...).
La carte électronique que nous utiliserons est une K8055 "VM110" de Velleman, il s'agit d'une "USB Experiment
Interface Board" qui est décrite dans un autre article de ce site.
Voici le code source du sketch d'exemple :
Sketch de test K8055
Contient la classe de wrapping pour K8055 et un example de sketch Processing.
Principe d'accès à une DLL depuis Java
Une DLL est considérée comme une ressource "native", car il s'agit d'un binaire appelant des ressources bas-niveau
du système d'exploitation, en l'occurence il s'agit ici d'exploiter les ressources HID créées par la liaison USB entre
notre ordinateur PC et la carte d'expérimentation Velleman.
La carte K8055 détectée comme HID
Java sait parler depuis longtemps à des ressources natives, via ce qu'on appelle une "Java Native Interface" ou JNI.
Il existe de nombreuses utilisations de JNI, généralement pour appeler des programmes en C/C++ recompilés pour
Copyright © PoBot
Page 2/8
Utiliser une DLL dans un programme Java
JNI puis intégrés au programme Java. Il ne s'agit pas toujours d'accéder à des ressources systèmes, mais parfois
d'exporter des algorithmes complexes pour les exécuter plus rapidement ou pour communiquer avec une application
non Java qu'il serait trop long, impossible ou inutile de migrer sous Java.
Dans notre cas (DLL fournie par un constructeur), il est impossible de recompiler le code pour indiquer qu'on
souhaite utiliser JNI. Il faut trouver une solution d'interface Java / natif qui laisse la DLL inchangée. Un article sur le
site web de Processing décrit un hack de Processing [http://processing.org/hacks/doku.php?id=hacks:jnative] basé
sur JNative, une extension open-source qui permet ce type d'accès dynamique aux fonctions d'une DLL.
Résumé des opérations à faire pour programmer l'accès
étudier la DLL cible pour connaître ses fonctions
installer la DLL dans le répertoire c :/Windows/system32
créer une classe Java basée sur JNative
écrire les opérations qui implémentent les accès à chaque fonction de la DLL
écrire de nouvelles fonctions simplifiées indépendantes de JNative
compiler le programme Java
Résumé de la chaîne d'exécution
L'application Processing utilise des opérations simplifiées qui correspondent aux fonctionnalités proposées par la
DLL.
Ces opérations traitent l'encapsulation (configuration, gestion des exceptions, changement des types de données,
call-back) en utilisant l'API JNative.
Les classes de JNative prennent la main pour appeler une DLL JNative en passant les paramètres et récupérant
les valeurs en retour.
La DLL JNative traite chacun des appels Java en gérant l'accès à la DLL cible (directement de natif à natif)
permettant ainsi de dépasser la limite de JNI qui nécessiterait une recompilation de la DLL cible.
Cas pratique
On va utiliser Processing et JNative pour écrire un programme d'accès à la carte d'expérimentation permettant de
faire des lectures et écritures sur les ports numériques et analogiques via la liaison USB.
Etude de la DLL
Deux DLL sont fournies sur le cédérom d'installation et d'exemples fourni avec le kit K8055 : "K8055D.DLL" et
"K8055D_C.DLL". La première est destinée aux programmes Visual Basic et Borland, tandis que la seconde est
destinée aux programmes Visual C++, sans autre explication... difficile surtout pour ceux qui ne veulent utiliser aucun
de ces logiciels.
Il faut tout d'abord vérifier les fonctions mises à dispostion dans chacune de ces DLL fournies par Velleman : cette
étape pourrait être superflue car des spécifications (document PDF en français) sont fournies, mais c'est l'occasion
surtout de noter le nom exact de ces fonctions tel que le compilateur utilisé par Velleman a pu les modifier. En effet,
le compilateur "décore" ("mangle" en anglais) le nom des fonctions, en ajoutant des caractères devant et derrière. On
va utiliser un petit utilitaire "dllexp" (disponible sur le site de Nirsoft
Copyright © PoBot
Page 3/8
Utiliser une DLL dans un programme Java
[http://www.nirsoft.net/utils/dll_export_viewer.html]) pour vérifier cela.
Voici ce que ça donne pour la DLL "K8055D" :
Liste des fonctions K8055
on vérifie et on note dans la première colonne le nom des fonctions que nous utiliserons.
Et voici ce que ça donne pour la DLL "K8055D_C" :
Liste des fonctions K8055 (2)
par curiosité, ce que contient la seconde DLL, K8055D_C
La première version est plus sympathique, non ? On va commencer avec elle, et éviter de se coltiner des
décorations parasites (même si elles ont certainement une utilité qui n'est pas le sujet du présent article... enfin
j'espère qu'on aura pas à chercher leur utilité pour faire fonctionner JNative).
Installation de la DLL
Il faut copier K8055D.dll dans un répertoire du système d'exploitation connu de tous les programmes. Sans faire trop
d'essais, j'ai choisi "c :/windows/system32" comme indiqué dans l'article d'origine (hack Processing en anglais).
Installation de Processing
C'est une application simple qui ne pose aucun problème. Consultez le site web : www.processing.org
[http://www.processing.org].
Installation de JNative
Il faut récupérer la dernière version de JNative : http://jnative.free.fr. On découvre au passage que c'est un projet (au
moins en partie) français. Les livrables sont disponibles sous Sourceforge. On télécharge le jar et on le copie sous
/libraries/JNative/library. On peut également extraire (à l'intérieur du jar dans la version que j'ai récupérée) le fichier
JNative.DLL et le placer à côté du fichier JNative.jar.
Copyright © PoBot
Page 4/8
Utiliser une DLL dans un programme Java
Installation de JNative
On ajoute JNative comme une "library" de Processing.
Ecriture de la classe "wrapper" des fonctions de la DLL
Dans un nouveau "sketch" Processing (manipulez un peu l'interface pour vous familiariser avec ses concepts et voir
quelques exemples d'applets), créez un fichier avec une extension .java et portant le nom (en respectant la casse,
majuscule/minuscule) de votre DLL, ici "K8055D.java". Ce n'est pas habituel car Processing utilise son propre format
".pde" car il simplifie (pas de notion de "classe" dans les sketchs ordinaires). Dans notre cas, on gardera un sketch
classique et le fichier .java est une classe secondaire donc on ne perd pas la simplicité de Processing.
Création du sketch et du wrapper java
Deux fichiers seulement : le sketch processing habituel et la classe Java qui utilisera JNative.
Ce fichier "K8055D.java" une fois ajouté à l'interface d'édition de code de Processing, on va écrire son contenu en
commençant par l'enveloppe, la "classe" à la sauce Processing :
import processing.core.*; public class K8055D extends PApplet { }
Comme cette classe implémente l'encapsulation d'appels à la DLL par JNative, il faut ajouter toutes les références
aux packages de JNative, et s'identifier comme faisant partie du package JNative :
package org.xvolks.jnative.util; import processing.core.*; ...
Pour importer les références, Processing propose un menu pour chacune des "libraries" stockées dans son
répertoire d'installation.
Copyright © PoBot
Page 5/8
Utiliser une DLL dans un programme Java
Ajout des imports nécessaires à JNative.
Tout le gros pavé d'import doit être copié en-dessous de la ligne "package" :
package org.xvolks.jnative.util; import processing.core.*; import org.xvolks.test.bug.*; import
org.xvolks.jnative.util.ole.*; import org.xvolks.jnative.util.windows.hooks.*; [... et une vingtaine de lignes comme ça ...]
public class K8055D extends PApplet { }
Maintenant que c'est fait, on va remplir la classe. D'abord en stockant en constante le nom exact de la DLL qui devra
être indiqué à chaque fois dans les appels aux fonctions JNative.
public class K8055D extends PApplet {
public static final String DLL_NAME = "K8055D.DLL"; }
Puis on va s'intéresser aux appels JNative en eux-même. Le principe est d'avoir une variable pour stocker chaque
"pont" entre Java et une fonction de la DLL. Cette variable sera initialisée la première fois que vous ferez appel à une
fonction, puis restera prête à recevoir vos invocations suivantes :
// Native-side function names private static JNative nNomDeLaFonction;
// JNative implementation of DLL
functions public static void NomDeLaFonction() throws NativeException, IllegalAccessException {
if(nNomDeLaFonction == null)
{
nNomDeLaFonction = new JNative(DLL_NAME, "NomDeLaFonction"); // The
actual "decorated" name in the DLL } nNomDeLaFonction.invoke(); // Finally, execute the native function }
Et c'est tout (dans le cas où il n'y a aucun paramètre en entrée ni en sortie). Il suffit de faire ça pour chacune des
fonctions, en remplaçant "NomDeLaFonction" par chacune des fonctions. Devant un film, ça passe vite :)
Notez bien qu'on a créé une instance d'objet JNative en passant le nom de la DLL et le "NomDeLaFonction" de la
fonction. Si on utilise la DLL avec décorations, cela donne par exemple :
nNomDeLaFonction = new JNative(DLL_NAME, "_NomDeLaFonction@4"); // The actual "decorated" name in the
DLL
La gestion des paramètres
Prenons un exemple concret : ouvrir la connexion avec la carte. Il s'agit de la fonction OpenDevice qui prend en
argument l'adresse de la carte selon la configuration des cavaliers SK5 et SK6 et qui retourne 1 si c'est réussi et 0 si
ça ne fonctionne pas.
Copyright © PoBot
Page 6/8
Utiliser une DLL dans un programme Java
On va ajouter une ligne dans l'initialisation de l'instance JNative pour indiquer le type de la donnée de retour. Pas
besoin de spécifier le type d'argument, il suffit d'ajouter sa valeur lors de l'invocation. Enfin la troisième ligne
supplémentaire consiste à récupérer la valeur de retour selon le type concerné pour la retourner à notre tour.
/** * */ public static int OpenDevice(int address) throws NativeException, IllegalAccessException {
if(nOpenDevice == null)
{
nOpenDevice = new JNative(DLL_NAME, "OpenDevice"); // The actual "decorated"
name in the DLL
nOpenDevice.setRetVal(Type.INT);
} nOpenDevice.setParameter(0, address);
nOpenDevice.invoke(); // Finally, execute the native function
return nOpenDevice.getRetValAsInt(); // get native
call's return value }
Il suffit maintenant de compléter chacune des opérations Java en fonction des paramètres et valeurs de retour
indiquées dans la documentation des fonctions de la DLL et le tour est joué.
Simplification des appels depuis le sketch Processing
Comme on le voit dans les exemples de code ci-dessus, les opérations ne gèrent pas les exceptions de JNative et
les renvoient pour traitement ultérieur. Si on appelait ces fonctions depuis le sketch Processing, il faudrait tout un tas
de code "try... catch..." et plein d'imports des classes de la bibliothèque JNative... pas très "Processing" tout ça.
On va donc simplifier grandement en écrivant des fonctions intermédiaires. En plus, on va choisir des noms
d'opérations et des types de données indépendant de ce que nous impose la carte K8055. J'ai choisi d'implémenter
les opérations d'accès aux ports d'entrées/sorties numériques et analogiques "à la sauce Arduino" :
digitalRead(pin)
digitalWrite(pin, value)
/** * Write a high or low value to a digital pin (or channel as K8055 refers to) * @arg pin : channel from 1 to 5 *
@arg value : true or false for HIGH or LOW */ public static void digitalWrite(int pin, boolean value) { try {
if
(value) {
SetDigitalChannel(pin);
}
else {
ClearDigitalChannel(pin);
}
}
catch
(NativeException ne) {
println("Error ! "+ne.toString());
} catch (IllegalAccessException e) {
println("Error ! "+e.toString());
} } /** * Reads the value from a specified digital pin (or channel as K8055
refers to) * @arg pin : channel from 1 to 5 * @return boolean value (true for HIGH and false for LOW) */ public
static boolean digitalRead(int pin) { try {
return (ReadDigitalChannel(pin) == 1); }
catch (NativeException
ne) {
println("Error ! "+ne.toString());
} catch (IllegalAccessException e) {
println("Error !
"+e.toString());
} return false; }
Et c'est fini. Dans le code du sketch, à part l'import de la classe que vous venez d'écrire, rien de plus. Voici ce que ça
donne pour faire clignoter une led toutes les secondes pendant une demi-seconde :
import org.xvolks.jnative.util.K8055D; void setup() { K8055D.initCard(0); } void draw() {
K8055D.digitalWrite(1,true); delay(500); K8055D.digitalWrite(1,false); delay(500); }
Simple, n'est-il pas ? Voici les sources pour que vous puissiez continuer à implémenter toutes les fonctions de la
DLL (je me suis peut être arrêté en route...) et faire tout ce que vous voulez avec !
Copyright © PoBot
Page 7/8
Utiliser une DLL dans un programme Java
Sketch de test K8055
Contient la classe de wrapping pour K8055 et un example de sketch Processing.
Copyright © PoBot
Page 8/8