WinRun4J

Overview

The launcher provides the ability to bind Windows API functions to java native methods without the need to write any native code. This is best described with a simple example:

package org.boris.winrun4j.test;

import org.boris.winrun4j.PInvoke;
import org.boris.winrun4j.PInvoke.DllImport;
import org.boris.winrun4j.PInvoke.UIntPtr;

public class BindingExample1
{
    static {
        PInvoke.bind(BindingExample1.class);
    }

    @DllImport("kernel32")
    public static native boolean GetComputerName(StringBuilder lpBuffer, UIntPtr lpnSize);
    
    public static void main(String[] args) throws Exception {
        StringBuilder name = new StringBuilder();
        UIntPtr size = new UIntPtr(100);
        if (GetComputerName(name, size)) {
            System.out.println(name);
        }
    }
}

When the class is loaded the PInvoke method will bind all java methods with the DllImport to a native function. When the native method is invoked the java arguments will be automatically converted into native values. Native memory will be managed automatically.

The example above is equivalent to the information/instructions provided on PINVOKE.NET for GetComputerName. The only extra step required is the PInvoke.bind call in the static constructor.

The "lpnSize" parameter tells the native binder how much space to allocate to the "lpBuffer" string.

The goal of the native binder is to be as compatible with PINVOKE.NET as possible so that it can be used as the reference. Some differences do exist due to language constraints, such as:

The native methods must be manually bound by using the PInvoke.bind method. The simplest approach is use a static constructor as above.
The java "long" primitive type should be used where an [in] pointer or handle is required. It is interpreted by the native binder to mean the native pointer size (ie. it will work on both 32-bit and 64-bit VMs).

Binding Structs

The native binding supports C-structs using java classes with equivalent data members. The java clas must implement the Struct marker interface. A simple example is as follows:

package org.boris.winrun4j.test;

import org.boris.winrun4j.PInvoke;
import org.boris.winrun4j.PInvoke.DllImport;
import org.boris.winrun4j.PInvoke.MarshalAs;
import org.boris.winrun4j.PInvoke.Struct;

public class BindingExample2
{
    static {
        PInvoke.bind(BindingExample2.class, "kernel32");
    }

    @DllImport
    public static native boolean GetVersionEx(OSVERSIONINFOEX version);

    public static class OSVERSIONINFOEX implements Struct
    {
        public int sizeOf = PInvoke.sizeOf(OSVERSIONINFOEX.class, true);
        public int majorVersion;
        public int minorVersion;
        public int buildNumber;
        public int platformId;
        @MarshalAs(sizeConst = 128)
        public String csdVersion;
        public short servicePackMajor;
        public short servicePackMinor;
        public short suiteMask;
        public byte productType;
        public byte reserved;
    }
    
    public static void main(String[] args) throws Exception {
        OSVERSIONINFOEX ver = new OSVERSIONINFOEX();
        if (GetVersionEx(ver)) {
            System.out.println(ver.majorVersion);
            System.out.println(ver.minorVersion);
            System.out.println(ver.csdVersion);
        }
    }
}

Unicode/Multi-byte Character Support

The native binder defaults to unicode or wide-character format and will automatically look for a native method named like the java native method with a "W" at the end (eg. GetVersionExW). To use the ANSI version of the method use the wideChar attribute of the DllImport annotation, like:

    @DllImport(lib = "kernel32.dll", wideChar = false)
    public static native boolean GetVersionEx(OSVERSIONINFOEX version);

Note that the native library to bind to can be specified as an argument to the PInvoke.bind method. This is useful when you need to bind multiple methods to the same library.

Callbacks

The native binding supports callbacks using java interfaces. The java clas must implement the Callback marker interface and have only 1 method defined.

A simple example is as follows:

package org.boris.winrun4j.test;

import org.boris.winrun4j.PInvoke;
import org.boris.winrun4j.PInvoke.Callback;
import org.boris.winrun4j.PInvoke.DllImport;
import org.boris.winrun4j.PInvoke.IntPtr;

public class BindingExample3
{
    static {
        PInvoke.bind(BindingExample3.class, "user32");
    }

    @DllImport
    public static native boolean EnumWindows(WindowEnumProc enumFunc, IntPtr lParam);

    public interface WindowEnumProc extends Callback
    {
        boolean windowEnum(long hWnd, IntPtr lParam) throws Exception;
    }
    
    public static void main(String[] args) throws Exception {
        IntPtr count = new IntPtr();

        WindowEnumProc callback = new WindowEnumProc() {
            public boolean windowEnum(long hWnd, IntPtr lParam) throws Exception {
                System.out.println(hWnd);
                System.out.println(lParam);
                lParam.value++;
                return true;
            }
        };

        EnumWindows(callback, count);

        System.out.println(count.value);
    }    
}