How to call a DLL function from java? (Calling C/C++ native function from Java)

Java code and Java Runtime

Java JAVAC, JRE, JDK, JVM

Java is a platform independent programming language. An application written in Java does not require recompilation for running in different platforms. Java compiler never compiles the code to native platform instructions binaries which is often seen with C, C++ programming languages. Java compiler (JAVAC) takes .java source files and compiles them into object files. These object files are in the form of JAVA byte code. To run these object codes JAVA setup provides JAVA runtime Environment (JRE). JAVA runtime Environment consists of a program running tool as JAVA and a couple of libraries and run time binaries. These are platform dependent. JAVA makes JRE for each platforms. JRE for Windows, Linux, Android are different kind of binaries and they are native to platfrom architectures like x86, x86_64, ARM, ARM64 etc. JAVA byte codes are interpreted by the runtime binary to translate to native instructions and then they run as native code.

Java Native Interface/JNI

Java call C uing JNI

JAVA is good for writing codes without much knowledge of the platform on which it will be running. However system applications may need to access some of the system resources which are strictly platform dependent. C, C++ are the languages which can access OS resources and low level interfaces. Java cannot access this directly from java context. However there is a provision in Java to interface with native binaries. This interface is well known as Java Native Interface or JNI in short. JNI in the gateway between JAVA and native binaries, written in C/C++/VB or any other compiled languages. Most of the system applications are developed in two parts. One part which is tightly coupled to OS and low layer calls are written with C,C++. These binaries exposes native calls to JAVA environment. The other halves of the JAVA code calls these native interfaces.

Java Code

public class MyJNI {
  static {
    try{
      /* MyJNI.dll (Windows) or libMyJNI.so (Linux) */
      System.loadLibrary("MyJNI");
    } catch(java.lang.UnsatisfiedLinkError err){
      /* Error output when native binary not present */
      System.out.println("Unable to load MyJNI library");
      System.exit(0);
    }
  }
  private boolean z;
  private byte    b;
  private char    c;
  private short   s;
  private int     i;
  private long    j;
  private float   f;
  private double  d;
  private String  str;

  /* JNI simple interface take no arguments and no returns */
  private native void HelloWorld();
  /* JNI Call by Value */
  private native int CallC (boolean z,
                            byte    b,
                            char    c,
                            short   s,
                            int     i,
                            long    j,
                            float   f,
                            double  d,
                            String  str);
  /* JNI Call by Value */
  private native void SetMembers();
 
  public static void main(String[] args) {
    MyJNI myjni = new MyJNI();
    myjni.HelloWorld();
    System.out.println("Calling by Value");
    myjni.CallC (true,
                 (byte)'J',
                 'K',
                 (short)10,
                 100,
                 (long)1000,
                 (float)1.2,
                 1.5,
                 "Hello From Java!");
      myjni.z = true;
      myjni.b = (byte)'C';
      myjni.c = 'D';
      myjni.s = 20;
      myjni.i = 200;
      myjni.j = 2000;
      myjni.f = (float)2.2;
      myjni.d = 2.5;
      myjni.str = "Hello from Java!";
      System.out.println("Calling by Reference");
      myjni.SetMembers();
      System.out.println("End of Calling by Reference");
      System.out.println("Java Members (changed)");
      System.out.println("z (boolean) = " + myjni.z);
      System.out.println("b (byte) = " + (char)myjni.b);
      System.out.println("c (char) = " + (char)myjni.c);
      System.out.println("s (short) = " + (short)myjni.s);
      System.out.println("i (int) = " + myjni.i);
      System.out.println("l (long) = " + myjni.j);
      System.out.println("f (float) = " + myjni.f);
      System.out.println("d (double) = " + myjni.d);
      System.out.println("str (string) = " + myjni.str);
   }
}

Above code has three functions which are declared with native keyword. Native keyword informs Java Compiler that the function can be linked even if the definition of HelloWorld(), CallC() and SetMembers() do not exist. This is similar to importing a function from DLL/SO file. Java compiler puts these interfaces in import table or checks import table of DLL/so during runtime linking.

JNI library error

At this point if we try to execute this code we will get error as Java runtime will fail to load import library MyJNI.dll or libMyJNI.so. 

>javac MyJNI.java
>java MyJNI
Unable to load MyJNI library

So the java side of the application is ready but the native implementation part is missing here. Let us see what are the things we need here.

  1. C/C++ header file contains the native function prototypes or declarations
  2. C/C++ source file contains definitions of the routines
  3. Native DLL binary which will be loaded and executed.

Native DLL binary will be generated by compiling and linking the header and source files. We will see how these three files will be generated in this tutorial.

JAVAH & Interface generation

We need a tool called JAVAH which generates this interface. JAVAH comes with JDK and no additional installation or setup is required. Javah can be executed in the same way as we execute comiler javac or java. Javah takes byte code file name (without .class extension) as argument. It process than binary and generates a C/C++ header file in the same name. 

>javah MyJNI

JNI header file

Note carefully javah has generated three function prototype in C/C++. JNIEXPORT macro tells C/C++ compiler to export these functions from DLL/SO library so that java run time can import these calls. Additionally there are two extra arguments for each functions. First argument is of type JNIEnv which gives a pointer to Java Runtime Environment. JNIEnv provides many interfaces which native binary can utilize. Next argument is of type jobject which represents the object itself or the "this" pointer. We can access members of the object through this arguments. Next arguments are same as declared in java. jboolean, jbyte, jchar, jshort, jlong, jfloat, jdouble are type definition of unsigned char, signed char, signed short, short, int, long, float and double in C/C++. Now java treats strings as UNICODE thus jstring is not directly char * but conversions are possible in both the ways.

  1. Java_MyJNI_HelloWorld() is the equivalent JNI prototype of HelloWorld() in java.
  2. Java_MyJNI_CallC() is the equivalent JNI prototype of CallC() in java. It is calling all arguments by value.
  3. Java_MyJNI_SetMembers() is the equivalent JNI prototype of SetMembers() in java.

Call by reference in java is not possible but this is equivalent of Call by reference in java. Java_MyJNI_SetMembers access and modify member variables of MyJNI class object and thus can be treated as the equivalent of call by reference.

/* DO NOT EDIT THIS FILE - it is machine generated */
#include <jni.h>
/* Header for class MyJNI */

#ifndef _Included_MyJNI
#define _Included_MyJNI
#ifdef __cplusplus
extern "C" {
#endif
/* * Class: MyJNI * Method: HelloWorld * Signature: ()V */
JNIEXPORT void JNICALL Java_MyJNI_HelloWorld
  (JNIEnv *, jobject);

/* * Class: MyJNI * Method: CallC * Signature: (ZBCSIJFDLjava/lang/String;)I */
JNIEXPORT jint JNICALL Java_MyJNI_CallC
  (JNIEnv *, jobject, jboolean, jbyte, jchar, jshort, jint, jlong, jfloat, jdouble, jstring);

/* * Class: MyJNI * Method: SetJMembers * Signature: ()V */
JNIEXPORT void JNICALL Java_MyJNI_SetMembers
  (JNIEnv *, jobject);

#ifdef __cplusplus
}
#endif
#endif

Implement Native C/C++ Code

Now we will implement these interfaces in a dynamic link library in Windows or in a shared library in Linux. We need to create a C/C++ source file and may need to copy this header file to the same folder. Here we created MyJNI.c in the same folder where MyJNI.h is located. We should include this file and implement the definitions.

jchar, jshort, jlong, jfloat, jdouble are type definition of char, short, long, float and double in C/C++ thus we can used these directly. But this is not true for the strings. Java treats strings char char as UNICODE. There are two bytes for each characters. First character contains ASCII value and next one contains language id. jstring can be converted to UTF char* and vice versa. GetStringUTFChars() can be used to extract char* from Java strings. NewStringUTF() is used to allocate a new UNICODE string from UTF char*. ReleaseStringUTFChars() is used to release existing buffer.

Here in Java_MyJNI_CallC(), we are simply printing the values passed from Java in C/C++ context and directly returning to Java context. Java_MyJNI_SetMembers() is not taking arguments. Every C++/Java function has inherent member called this pointer. This function uses this object to access all member variables. JNI can access and modify all the members. These are the steps to access/modify Java members.

  • GetObjectClass() returns the class reference
  • GetFieldID() returns field ID of the member from class reference
  • GetXXXXField()/GetObjectField returns an instance of the member variable from object
  • SetXXXXField()/SetObjectField can be used to set the member value

This is only a demo however in practical situation where system applications need to access system resources can open device files and can call mmap/ioctls/sysctl etc to interface deeper inside into system side.

/* MyJNI.cpp : Defines the entry point for the DLL application. */
#include <stdio.h>
#include "MyJNI.h"
BOOL APIENTRY DllMain ( HANDLE hModule, 
                        DWORD  ul_reason_for_call, 
                        LPVOID lpReserved
                      )
{
    return TRUE;
}

JNIEXPORT void JNICALL Java_MyJNI_HelloWorld (JNIEnv *,
                                              jobject)
{
  printf ("Hello World!\n");

}

JNIEXPORT jint JNICALL Java_MyJNI_CallC (JNIEnv * env,
                                         jobject  jobj,
                                         jboolean z,
                                         jbyte    b,
                                         jchar    c,
                                         jshort   s,
                                         jint     i,
                                         jlong    j,
                                         jfloat   f,
                                         jdouble  d,
                                         jstring  str)
{

  printf ("Arguments from Java \n");
  printf ("z (boolean) = %s\n", b ? "true" : "false");
  printf ("b (byte) = %c\n", b);
  printf ("c (char) = %c\n", c);
  printf ("s (short) = %d\n", (int)s);
  printf ("i (int) = %d\n", i);
  printf ("l (long) = %ld\n",j);
  printf ("f (float) = %f\n", f);
  printf ("d (double) = %f\n", d);
  printf ("str (string) = %s\n", env->GetStringUTFChars( str, NULL));
  return 0;
}

JNIEXPORT void JNICALL Java_MyJNI_SetMembers (JNIEnv * env,
                                              jobject jobj)
{

  jfieldID fidnum;
  printf ("Java members (from C)\n");

   /* Get a reference to this object's class */
   jclass thisclass = env->GetObjectClass(jobj);
 
  /* ============== Boolean ================= */
  /* Boolean Get the Field ID of the instance */
  fidnum = env->GetFieldID(thisclass, "z", "Z");
  if (NULL == fidnum) {
    return;
  }
  /* Get the boolean given the Field ID */
  jboolean z = env->GetBooleanField(jobj, fidnum);
  printf ("z (boolean) = %s\n", z ? "true" : "false");
 
  /* Change the variable */
  z = false;
  env->SetBooleanField(jobj, fidnum, z);

  /* ============== Byte ================= */
  /* Byte Get the Field ID of the instance */
  fidnum = env->GetFieldID(thisclass, "b", "B");
  if (NULL == fidnum) {
    return;
  }
  /* Get the byte given the Field ID */
  jbyte b = env->GetByteField(jobj, fidnum);
  printf ("b (byte) = %c\n", b);
 
  /* Change the variable */
  b += 1;
  env->SetByteField(jobj, fidnum, b);
  
  /* ============== Char ================= */
  /* Char Get the Field ID of the instance */
  fidnum = env->GetFieldID(thisclass, "c", "C");
  if (NULL == fidnum) {
    return;
  }
  /* Get the char given the Field ID */
  jchar c = env->GetCharField(jobj, fidnum);
  printf ("c (char) = %c\n", c);
 
  /* Change the variable */
  c += 1;
  env->SetCharField(jobj, fidnum, c);

  /* ============== Short ================= */
  /* Short Get the Field ID of the instance */
  fidnum = env->GetFieldID(thisclass, "s", "S");
  if (NULL == fidnum) {
    return;
  }
  /* Get the short given the Field ID */
  jshort s = env->GetShortField(jobj, fidnum);
  printf ("s (short) = %d\n", s);
 
  /* Change the variable */
  s = 10;
  env->SetShortField(jobj, fidnum, s);

  /* ============== Int ================= */
  /* Int Get the Field ID of the instance */
  fidnum = env->GetFieldID(thisclass, "i", "I");
  if (NULL == fidnum) {
    return;
  }
  /* Get the int given the Field ID */
  jint i = env->GetIntField(jobj, fidnum);
  printf ("i (int) = %d\n", i);
 
  /* Change the variable */
  i = 100;
  env->SetIntField(jobj, fidnum, i);

  /* ============== Long ================= */
  /* Long Get the Field ID of the instance */
  fidnum = env->GetFieldID(thisclass, "j", "J");
  if (NULL == fidnum) {
    return;
  }
  /* Get the long given the Field ID */
  jlong j = env->GetLongField(jobj, fidnum);
  printf ("l (long) = %ld\n", j);
 
  /* Change the variable */
  j = 1000;
  env->SetLongField(jobj, fidnum, j);

  /* ============== Float ================= */
  /* Float Get the Field ID of the instance */
  fidnum = env->GetFieldID(thisclass, "f", "F");
  if (NULL == fidnum) {
    return;
  }
  /* Get the float given the Field ID */
  jfloat f = env->GetFloatField(jobj, fidnum);
  printf ("f (float) = %f\n", f);
 
  /* Change the variable */
  f = (float)1.2;
  env->SetFloatField(jobj, fidnum, f);

  /* ============== Double ================= */
  /* Double Get the Field ID of the instance */
  fidnum = env->GetFieldID(thisclass, "d", "D");
  if (NULL == fidnum) {
    return;
  }
  /* Get the Double given the Field ID */
  jdouble d = env->GetDoubleField(jobj, fidnum);
  printf ("d (double) = %f\n", d);
 
  /* Change the variable */
  d = 1.5;
  env->SetDoubleField(jobj, fidnum, d);

  /* ============== String ================= */
  /* String Get the Field ID of the instance */
   fidnum = env->GetFieldID(thisclass, "str", "Ljava/lang/String;");
  if (NULL == fidnum) {
    return;
  }
  /* Get the String given the Field ID */
  jstring str = (jstring)env->GetObjectField(jobj, fidnum);
  printf ("str (string) = %s\n", env->GetStringUTFChars(str, NULL));

  /* Change the variable */
  env->ReleaseStringUTFChars(str, "str");
  str = env->NewStringUTF ((const char *) "Hello form C!");
  env->SetObjectField(jobj, fidnum, str);

}

JNI Block Diagram

JNI Block Diagram

JNI Execution

Now we need to place this native library in the same folder where our Java Class binary located and can run. If we have more than one class We can also place this in the Java Runtime binary folder jre\bin if we want to access this from more than one java class located in different folder. 

:>java MyJNI
Hello World!
Calling by Value
Arguments from Java
z (boolean)  = true
b (byte)     = J
c (char)     = K
s (short)    = 10
i (int)      = 100
l (long)     = 1000
f (float)    = 1.200000
d (double)   = 1.500000
str (string) = Hello From Java!
Calling by Reference
Java members (from C)
z (boolean)  = true
b (byte)     = C
c (char)     = D
s (short)    = 20
i (int)      = 200
l (long)     = 2000
f (float)    = 2.200000
d (double)   = 2.500000
str (string) = Hello from Java!
End of Calling by Reference
Java Members (changed)
z (boolean)  = false
b (byte)     = D
c (char)     = E
s (short)    = 10
i (int)      = 100
l (long)     = 1000
f (float)    = 1.2
d (double)   = 1.5
str (string) = Hello form C!

About our authors: Team EQA

You have viewed 1 page out of 27. Your DLL learning is 0.00% complete. Login to check your learning progress.

‹ # ›

Questions index C Questions C++ Questions Win32 MFC COM/DCOM DLL Questions