See:
          Description

This document is the API specification for the JNA library for simplified native library access for Java.

Top  JNA Home  API w/FRAMES 

Java Native Access (JNA)

Table of Contents

• Library Mapping
• Function Mapping
• Type Mapping
  • Primitive Types
  • Pointers
  • Strings
  • Wide (UNICODE) Strings
  • Primitive Arrays
  • Buffers/Memory Blocks
  • Callbacks/Function Pointers
  • Variable Argument Lists (Varargs)
  • Structures
  • Unions
  • Java Objects
  • Last Error
• Invocation Mapping
• Library Global Data
• VM Crash Protection
• Performance

Top

Library Mapping

// Alternative 1: interface-mapped class, dynamically load the C library
public interface CLibrary extends Library {
    CLibrary INSTANCE = (CLibrary)Native.loadLibrary("c", CLibrary.class);
}

// Alternative 2: direct-mapped class
public class CLibrary {
    static {
        Native.register("c");
    }
}

Any given native library with a unique filesystem path is represented by a single instance of NativeLibrary and obtained via NativeLibrary.getInstance(String). The native library will be unloaded when no longer referenced by any Java code.

If the library name is null, your mappings will apply to the current process instead of a separately loaded library. This may help avoid conflicts if there are several incompatible versions of a library available.

The search path for loaded native libraries may be modified by setting jna.library.path and a few other properties. See NativeLibrary for details.

Table of Contents

Function Mapping

public interface CLibrary extends Library {
    int atol(String s);
}

public class CLibrary {
    public static native int atol(String s);
}

An instance of the Function class is obtained through the NativeLibrary instance corresponding to the containing native library. This Function instance handles argument marshalling and delegation to the native function.

Table of Contents

Marshalling/Unmarshalling (Java/Native Type Conversions)

NOTES

• Unsigned values may be passed by assigning the corresponding two's-complement representation to the signed type of the same size.
• Java arrays of primitive type may be wrapped by Buffer in order to access a subset of the array (changing the effective size and/or offest).
• Java arrays of primitive type are only valid for use within the scope of a single call. If the native code keeps a reference to the memory, use Memory or Buffer instead.
• Primitive arrays and structures as members of a structure are overlaid on the parent structure memory.
• Bitfields must be manually packed into an integer type.
• All other types must eventually be converted to one of the types in the this table. Methods with arguments or return values of types other than these must either use types deriving from NativeMapped or supply type conversion information for the unsupported types.
• Type mapping behavior may be customized by providing a TypeMapper for the Library.OPTION_TYPE_MAPPER option when initializing a library interface. See W32APITypeMapper for an example which provides custom conversion of boolean and String types. You are free to use whatever types are convenient in your defined interfaces, but all custom types must provide a mapping to one of the basic or derived types listed above.
• Type mapping may also be customized on a per-class basis for user-defined types by making the user-defined type implement the NativeMapped interface.
• Structure and Union are not converted to Pointer when passed by value.

Primitive Arrays

To map a native multi-dimensional array, use a single-dimensional Java array with a number of elements equivalent to the full native array, e.g.

// Original C code
#define DIM0 2
#define DIM1 3
int array[DIM0][DIM1];
int i,j;

for (i=0;i < DIM0;i++) {
  for (j=0;j < DIM1;j++) {
    array[i][j] = i*DIM1 + j;
  }
}

// Equivalent JNA code
final int DIM0 = 2;
final int DIM1 = 3;
int[] array = new int[6];
for (int i=0;i < DIM0;i++) {
  for (int j=0;j < DIM1;j++) {
    array[i*DIM1 + j] = i*DIM1 + j;                   
  }                   
}

Pointers

Type-safe pointers may be defined by deriving from the PointerType class. Any such user-defined type will be treated the same as a Pointer.

Strings

If the native method returns char* and actually allocates memory, a return type of Pointer should be used to avoid leaking the memory. It is then up to you to take the necessary steps to free the allocated memory.

When converting Java unicode characters into an array of char, the default platform encoding is used, unless the system property jna.encoding is set to a valid encoding. This property may be set to "UTF8", for example, to ensure all native strings use that encoding.

Arrays of String passed to native code (either as a function argument or callback return value) will be converted into a NULL-terminated array of char* (or wchar_t* in the case of an array of WString.

Wide Strings

Buffers/Memory Blocks

Buffers may also be used as a memory buffer input argument; direct byte buffers can often provide much improved performance over primitive arrays. A pointer provided by native code may be converted to a Buffer by calling Pointer.getByteBuffer(long, long).

If you need to pass in a subset of a primitive array, you can do so by wrapping it in a Buffer subclass, such as ByteBuffer, using the ByteBuffer.wrap(byte[],int,int) method. Wrapping an array in a buffer also allows you to pass only a subset of a Java array to the native function.

Callbacks (Function Pointers)

If the callback returns a String or String[], the returned memory will be valid until the returned object is GC'd.

If your native code initializes function pointers within a struct, JNA will automatically generate an Callback instance matching the declared type. This enables you to easily call the function supplied by native code using proper Java syntax.

// Original C code
struct _functions {
  int (*open)(const char*,int);
  int (*close)(int);
};

// Equivalent JNA mapping
public class Functions extends Structure {
  public static interface OpenFunc extends Callback {
    int invoke(String name, int options);
  }
  public static interface CloseFunc extends Callback {
    int invoke(int fd);
  }
  public OpenFunc open;
  public CloseFunc close;
}
...
Functions funcs = new Functions();
lib.init(funcs);
int fd = funcs.open.invoke("myfile", 0);
funcs.close.invoke(fd);

// Original C code
typedef void (*sig_t)(int);
sig_t signal(int signal, sig_t sigfunc);

// Equivalent JNA mapping
public interface CLibrary extends Library {
    public interface SignalFunction extends Callback {
        void invoke(int signal);
    }
    SignalFunction signal(int signal, SignalFunction func);
}

Varargs

// Original C code
extern int printf(const char* fmt, ...);

// Equivalent JNA mapping
interface CLibrary extends Library {
    int printf(String fmt, ...);
}

Structures

Pointer-to-Structure Arguments

// Original C code
typedef struct _Point {
  int x, y;
} Point;

Point* translate(Point* pt, int dx, int dy);

// Equivalent JNA mapping
class Point extends Structure { public int x, y; }
Point translate(Point pt, int x, int y);
...
Point pt = new Point();
Point result = translate(pt, 100, 100);

Structure by Value Arguments/Return

// Original C code
typedef struct _Point {
  int x, y;
} Point;

Point translate(Point pt, int dx, int dy);

// Equivalent JNA mapping
class Point extends Structure {
    public static class ByValue extends Point implements Structure.ByValue { }
    public int x, y;
}
Point.ByValue translate(Point.ByValue pt, int x, int y);
...
Point.ByValue pt = new Point.ByValue();
Point result = translate(pt, 100, 100);

Array-of-Structure Arguments

// Original C code
void get_devices(struct Device[], int size);

// Equivalent JNA mapping
int size = ...
Device[] devices = new Device[size];
lib.get_devices(devices, devices.length);

Device dev = new Device();
// As an array of Structure
Structure[] structs = dev.toArray(size);
// As an array of Device
Device[] devices = (Device[])dev.toArray(size);

Returning an Array of struct

// Original C code
struct Display* get_displays(int* pcount);
void free_displays(struct Display* displays);

// Equivalent JNA mapping
Display get_displays(IntByReference pcount);
void free_displays(Display[] displays);
...
IntByReference pcount = new IntByReference();
Display d = lib.get_displays(pcount);
Display[] displays = (Display[])d.toArray(pcount.getValue());
...
lib.free_displays(displays);

Nested Structure Definitions

// Original C code
typedef struct _Point {
  int x, y;
} Point;

typedef struct _Line {
  Point start;
  Point end;
} Line;

// Equivalent JNA mapping
class Point extends Structure {
  public int x, y;
}

class Line extends Structure {
  public Point start;
  public Point end;
}

If you need a pointer to a structure within your structure, you can use the Structure.ByReference tagging interface to indicate the field should be treated as a pointer instead of inlining the full structure.

// Original C code
typedef struct _Line2 {
  Point* p1;
  Point* p2;
} Line2;

// Equivalent JNA mapping
class Point extends Structure {
    public static class ByReference extends Point implements Structure.ByReference { }
    public int x, y;
}
class Line2 extends Structure {
  public Point.ByReference p1;
  public Point.ByReference p2;
}

// Original C code
typedef struct _Line2 {
  Point* p1;
  Point* p2;
} Line2;

// Equivalent JNA mapping
class Line2 extends Structure {
  public Pointer p1;
  public Pointer p2;
}

Line2 line2;
Point p1, p2;
...
line2.p1 = p1.getPointer();
line2.p2 = p2.getPointer();

Nested arrays

typedef struct _Buffer {
  char buf1[32];
  char buf2[1024];
} Buffer;

class Buffer extends Structure {
  public byte[] buf1 = new byte[32];
  public byte[] buf2 = new byte[1024];
}

Variable-sized structures

// Original C code
typedef struct _Header {
  int flags;
  int buf_length;
  char buffer[1];
} Header;

// Equivalent JNA mapping
class Header extends Structure {
  public int flags;
  public int buf_length;
  public byte[] buffer;
  public Header(int bufferSize) {
    buffer = new byte[bufferSize];
    buf_length = buffer.length;
    allocateMemory();
  }
}

Volatile fields

class Data extends com.sun.jna.Structure {
  public volatile int refCount;
  public int value;
}
...
Data data = new Data();

Read-only fields

class ReadOnly extends com.sun.jna.Structure {
  // Do not initialize the field here, or the compiler will inline the value!
  public final int refCount;
  {
    // Initialize fields here, to ensure the values are not inlined
    refCount = -1;
    read();
    // refCount might now have a different value
  }
}
...
ReadOnly ro = new ReadOnly();
// Will not compile!
ro.refCount = 0;

1. All final fields should be initialized in the constructor.
2. If you call Structure.read() from anywhere but the constructor, keep in mind that the compiler and/or hotspot will be assuming field values will not change across that function call.

Unions

Obtaining "last" error

Arbitrary Java Object arguments/return values

Table of Contents

Invocation Mapping

Table of Contents

Library Global Data

Table of Contents

VM Crash Protection

NOTE: When protected mode is enabled, you should make use of the jsig library, if available (see Signal Chaining) to avoid interfering with the JVM's use of signals. In short, set the environment variable LD_PRELOAD (or LD_PRELOAD_64) to the path to libjsig.so in your JRE lib directory (usually ${java.home}/lib/${os.arch}/libjsig.so) before launching your Java application.

Table of Contents

Performance

Use direct mapping of methods

Avoid type mapping

Pointer/Array/Buffer Variants

Large Structures