com.jinvoke
Annotation Type NativeImport

@Retention(value=RUNTIME)
@Target(value={METHOD,TYPE})
public @interface NativeImport

Indicates that the annotated method is imported from a native dynamic-link library(dll) or shared library(.so).

The @NativeImport annotation provides the information needed to call a function exported from a native DLL or .so.

This annotation can be applied to native methods, and classes containing native methods. When applied to a class, all native methods in the class are imported from the specified library.

In addition to annotating native methods with this annotation, the JInvoke.initialize() method must be called from from the containing class prior to invoking this method. This method can be called in the static initializer of the containing class.

If a method is annotated with this annotation, but JInvoke.initialize() is not called prior to invoking this method, J/Invoke will fail to bind it to the native method exported from the dll/so, and an UnsatisfiedLinkError will be thrown on calling the annotated method.

Example:

The following code example shows how to use the @NativeImport annotation to import the Win32 MessageBox function.

import com.jinvoke.JInvoke;
import com.jinvoke.NativeImport;

public class Example {
        @NativeImport(libname="User32")
        public static native int MessageBox(int hwnd, String text, String caption, int type);

        public static void main(String[] args) {
                JInvoke.initialize();
                MessageBox(0, "This message is being shown in a native Win32 MessageBox", "Caption", 0);
        }
}
 

Optional Element Summary

Charset	charset Indicates if String arguments are wide-character(Unicode) or single-character(Ansi).
CallingConvention	convention Indicates the calling convention of the native function.
java.lang.String	function Indicates the name of the native function to be invoked.
java.lang.String	library Indicates the name of the native library (.dll or .so) that contains the native function to be invoked.

library

public abstract java.lang.String library

Indicates the name of the native library (.dll or .so) that contains the native function to be invoked.

This library will be loaded by the J/Invoke runtime, and it should be present in the java.library.path. Alternatively, the full path to the library can be specified.

The .dll or .so suffix is not required, unless the full path is specified.

If left unspecified, the name of the containing class is used.

Default:

""

function

public abstract java.lang.String function

Indicates the name of the native function to be invoked.

A function by this name should be exported from the specified library.

J/Invoke attempts to link to the specified native function. If a function by this exact name is not exported from the native library, J/Invoke appends a 'W' to the function name and attempts to link to the Unicode version of the exported function.

If the function is exported by ordinal (a number) instead of by name, use a "#" followed by the ordinal number. e.g.:

  @NativeImport(library="Shell32", function="#61")
        public static native int SHRunDialog(int owner, int unknown1, int unknown2, String title, String description, boolean bShowLastRun);
  

If left unspecified, the method name is used.

Default:

""

convention

public abstract CallingConvention convention

Indicates the calling convention of the native function.

The default calling convention for the Win32 API is STDCALL, and for the C-runtime is CDECL.

If left unspecified, the STDCALL calling convention is used.

Default:

STDCALL

charset

public abstract Charset charset

Indicates if String arguments are wide-character(Unicode) or single-character(Ansi).

This attribute affects how arguments of type String, StringBuffer and StringBuilder are passed to the native function. When wide-character strings are used, the method name typically contains a 'w', e.g. wcslen and LPWSTR.

If left unspecified, the UNICODE charset is assumed on Windows, and ANSI on Unix platforms.

Default:

AUTO