Skip to content


Subversion checkout URL

You can clone with
Download ZIP
100644 110 lines (78 sloc) 6.51 KB
92d721d @dblock Started porting docs into markdown.
dblock authored
1 Getting Started with JNA
2 ========================
4 Java Native Access (JNA) has a single component, `jna.jar`; the supporting native library (jnidispatch) is included in the jar file. JNA is capable of extracting and loading the native library on its own, so you don't need additional configuration. JNA falls back to extraction if the native library is not already installed on the local system somwhere accessible to `System.loadLibrary`. The native library is also available in platform-specific jar files for use with Java Web Start.
6 Begin by downloading the latest release of JNA and referencing `jna.jar` in your project's `CLASSPATH`.
8 The following example maps the printf function from the standard C library and calls it.
10 package com.sun.jna.examples;
12 import com.sun.jna.Library;
13 import com.sun.jna.Native;
14 import com.sun.jna.Platform;
16 /** Simple example of JNA interface mapping and usage. */
17 public class HelloWorld {
19 // This is the standard, stable way of mapping, which supports extensive
20 // customization and mapping of Java to native types.
22 public interface CLibrary extends Library {
23 CLibrary INSTANCE = (CLibrary)
24 Native.loadLibrary((Platform.isWindows() ? "msvcrt" : "c"),
25 CLibrary.class);
27 void printf(String format, Object... args);
28 }
30 public static void main(String[] args) {
31 CLibrary.INSTANCE.printf("Hello, World\n");
32 for (int i=0;i < args.length;i++) {
33 CLibrary.INSTANCE.printf("Argument %d: %s\n", i, args[i]);
34 }
35 }
36 }
38 Identify a native target library that you want to use. This can be any shared library with exported functions. Many examples of mappings for common system libraries, especially on Windows, may be found in the platform package.
85d8d08 @twall update docs
twall authored
40 Make your target library available to your Java program. There are several ways to do this:
92d721d @dblock Started porting docs into markdown.
dblock authored
42 * The preferred method is to set the `jna.library.path` system property to the path to your target library. This property is similar to `java.library.path`, but only applies to libraries loaded by JNA.
43 * Change the appropriate library access environment variable before launching the VM. This is `PATH` on Windows, `LD_LIBRARY_PATH` on Linux, and `DYLD_LIBRARY_PATH` on OSX.
85d8d08 @twall update docs
twall authored
44 * Make your native library available on your classpath, under the path `{OS}-{ARCH}/{LIBRARY}`, where `{OS}-{ARCH}` is JNA's canonical prefix for native libraries (e.g. `win32-x86`, `linux-amd64`, or `darwin`). If the resource is within a jar file it will be automatically extracted when loaded.
92d721d @dblock Started porting docs into markdown.
dblock authored
46 Declare a Java interface to hold the native library methods by extending the Library interface.
48 Following is an example of mapping for the Windows kernel32 library.
50 package com.sun.jna.examples.win32;
52 import com.sun.jna.*;
54 // kernel32.dll uses the __stdcall calling convention (check the function
55 // declaration for "WINAPI" or "PASCAL"), so extend StdCallLibrary
56 // Most C libraries will just extend com.sun.jna.Library,
57 public interface Kernel32 extends StdCallLibrary {
58 // Method declarations, constant and structure definitions go here
59 }
61 Within this interface, define an instance of the native library using the Native.loadLibrary(Class) method, providing the native library interface you defined previously.
63 Kernel32 INSTANCE = (Kernel32)
64 Native.loadLibrary("kernel32", Kernel32.class);
65 // Optional: wraps every call to the native library in a
66 // synchronized block, limiting native calls to one at a time
67 Kernel32 SYNC_INSTANCE = (Kernel32)
68 Native.synchronizedLibrary(INSTANCE);
70 The `INSTANCE` variable is for convenient reuse of a single instance of the library. Alternatively, you can load the library into a local variable so that it will be available for garbage collection when it goes out of scope. A Map of options may be provided as the third argument to loadLibrary to customize the library behavior; some of these options are explained in more detail below. The `SYNC_INSTANCE` is also optional; use it if you need to ensure that your native library has only one call to it at a time.
72 Declare methods that mirror the functions in the target library by defining Java methods with the same name and argument types as the native function (refer to the basic mappings below or the detailed table of type mappings). You may also need to declare native structures to pass to your native functions. To do this, create a class within the interface definition that extends Structure and add public fields (which may include arrays or nested structures).
74 public static class SYSTEMTIME extends Structure {
75 public short wYear;
76 public short wMonth;
77 public short wDayOfWeek;
78 public short wDay;
79 public short wHour;
80 public short wMinute;
81 public short wSecond;
82 public short wMilliseconds;
4721151 @twall Use `getFieldOrder()`
twall authored
83 protected List getFieldOrder() {
84 return Arrays.asList(new String[] {
85 "wYear", "wMonth", "wDayOfWeek", "wDay", "wHour", "wMinute", "wSecond", "wMilliseconds",
86 });
87 }
92d721d @dblock Started porting docs into markdown.
dblock authored
88 }
90 void GetSystemTime(SYSTEMTIME result);
92 You can now invoke methods on the library instance just like any other Java class.
94 Kernel32 lib = Kernel32.INSTANCE;
96 lib.GetSystemTime(time);
98 System.out.println("Today's integer value is " + time.wDay);
511676e @twall Update www/
twall authored
5add6b7 @twall bump versions and update repository links
twall authored
100 Several [example applications]( are available, as well as [platform-specific mappings](
92d721d @dblock Started porting docs into markdown.
dblock authored
a814936 @twall Note direct mapping and link
twall authored
102 Optimized Direct Mapping
103 ------------------------
5add6b7 @twall bump versions and update repository links
twall authored
104 JNA provides an additional method of mapping native methods, should you need extra performance. You may declare a class to hold your native methods, declare any number of methods with the `native` qualifier, and invoke `Native.register(String)` in the class static initializer with your library's name. See [JNA Direct Mapping]( for an example, as well as any of the [`DirectXXXTest`]( unit tests.
92d721d @dblock Started porting docs into markdown.
dblock authored
94ac8af @twall Update www/
twall authored
106 Automated Interface Generation
107 ------------------------------
95de1bf @PauloMigAlmeida Changed JNAerator's link to the newest one.
PauloMigAlmeida authored
108 If the C header files for your library are available, you can auto-generate a library mapping by using Olivier Chafik's excellent [JNAerator]( utility. This is especially useful if your library uses long or complicated structures where translating by hand can be error-prone.
92d721d @dblock Started porting docs into markdown.
dblock authored
Something went wrong with that request. Please try again.