1.1. About This Guide

This guide introduces JNIWrapper^TM, describes its design goals, concepts and principles, provides the requirements for using the product as well as sufficient information you need to know before starting to work with the product.

This document covers all platform versions of JNIWrapper. In cases where functions treat a particular platform in a specific way, or specific configuration settings are needed, these are marked accordingly.

1.2. New in This Version

New in this version (3.0) of the Programmer's Guide:

Added: Chapter 8.

1.3. Related Documents

The documents provided on the Documents page at the JNIWrapper area at TeamDev site (http://www.teamdev.com) are intended to help you understand and effectively use of the JNIWrapper technology.

To make your learning curve shorter and smoother, we suggest that you read the documentation in the following order:

• You can start with the current Programmer's Guide document describing the ideas and basics of the proposed software.

• If you plan to develop your own software effectively, proceed from this Programmer's Guide to JNIWrapper Tutorial, which provides step-by-step instructions with code samples.

• Each version of JNIWrapper is supplied with updated Release Notes. To receive the up-to-date version of specific information, be sure to check the Release Notes section inside Readme.txt file before installing JNIWrapper.

• You can also find helpful information in the Frequently Asked Questions document, which we regularly update based on the questions we get from our users. The document can be accessed online at the JNIWrapper site.

1.4. About JNIWrapper

Java^TM is a very powerful platform allowing programmers to develop state-of-the-art software. It is, however, designed to run on a variety of different platforms and therefore does not include every feature of every platform. Certain basic things like creating a symbolic link under Linux or operating with registry items under Windows® are not supported in Java^TM. Programmers willing to do this are forced to write a native library and classes interfacing with it, then debug the code using two different debuggers (Java- and native-side). These are sometimes difficult and always very time-consuming tasks. All of them can be avoided by using JNIWrapper - a Java library for calling native library functions. With JNIWrapper, you can extensively use the potential of the underlying platform (like tray icons or custom shape splash screens) with only a single native library, having the full control over the program flow on the Java side.

2.1. System Requirements

The following are general requirements to run JNIWrapper on the following supported platforms:

• Windows

  • OS: Windows 9x, Me, NT 4.0, 2000, XP and Vista

  • Java: Java 2 SDK/JRE 1.3.x and later. For CodeGen GUI, the preferred JDK is 1.4.2. or later.

• Linux

  • OS: Red Hat Linux 7.2, 9.0; Mandrake Linux 9.1, 9.2, 10.0; Mandriva 2005 LE; WhiteBox Linux; Gentoo Linux (in general, all distros on kernel 2.4.x and kernel 2.6.x)

  • Java: Java 2 SDK/JRE 1.4.x

• Mac OS X

  • OS: Mac OS X 10.3 (Panther) and later

  • Java: Java 2 SDK/JRE 1.4.x

There are no specific memory or other hardware requirements for developing an application based on JNIWrapper.

2.2. Package Contents

The JNIWrapper package consists of the following main files required for work:

• Library JAR file - jniwrap-<version>.jar, where <version> is the product version, for example "3.0".

• Native code library

  • for Windows - jniwrap.dll

  • for Linux - libjniwrap.so

  • for Mac OS X - libjniwrap.jnilib

• License file

  • jniwrap.lic

All the files need to be placed in the appropriate locations. Please see the section "Configuring Software" for more details about the product installation instructions. The package may also contain other files providing some useful information for the you, for example the Readme.txt file.

3.1. Library JAR File

The JNIWrapper JAR file should be located in the program class path. Due to the limitations of the Java native library loading mechanism, it is not recommended to load JNIWrapper in custom class loaders, unless you are sure that it will be loaded in only one such class loader.

The library file can also be placed in the boot class path or in the extension directory of Java runtime, but this is not required.

3.2. Native Code Library

The JNIWrapper native code library is loaded using the standard Java native code loading mechanism. There are no known problems with placing the native code library file on a mapped drive or even using it from the network share using a UNC path.

Do not rename the library file, or else it will not be loaded.

Even though the native code library can be placed virtually anywhere, its actual location should be determined considering the fact that Java code must find the library to load. It can be placed somewhere within the program library search path (value of the java.library.path system property, which is by default equal to the value of the system variable PATH on Windows or LD_LIBRARY_PATH on Linux).

Alternatively, you can add a search path to the default library loader used by JNIWrapper or even write a custom one that searches for native code in a predefined location. Using a default path may be preferable for development and library loader as a much better way for distributing a complete application.

Since version 3.0 it is possible to keep native libraries within a JAR file. JNIWrapper will automatically locate and install a library on demand.

You may want to install the native code library into the directories on the default system path, for example:

• on Windows - the root of Windows installation or Windows\System32

• on Linux - <java_home>/lib/i386 or <java_home>/jre/lib/i386

• on Mac OS X - /usr/lib

Note that this requires having appropriate access rights on the Windows NT/2000/XP, Linux and Mac OS X systems. Installing the native code library by using this way may be convenient, but is not a required procedure.

3.3. License File

Placing the license file is very simple: it should be located in the same folder where the native JNIWrapper library (jniwrap.dll file) resides.

Do not rename the license file, or else it will not be recognized.

Also, there is one universal way for redistribution of the runtime license file. You will just need to save this file to your application's JAR file, into its META-INF subfolder. For example, if you have some application called <application_name>.jar, the jniwrap.lic file should be located in the following folder:

    <application_name>.jar
        \META-INF
            jniwrap.lic

You may appear to have several licenses for JNIWrapper for different platforms supported. In this case, you need to put all the license key files as described above but make sure there is no file name conflict. JNIWrapper accepts multiple license files named like shown below:

• jniwrap.lic

• jniwrap.lic1

• jniwrap.lic2

• ...

• jniwrap.lic999

4.1. Finding Native Libraries

JNIWrapper accesses native libraries by name using library loaders. Library loaders are responsible for finding and loading a library by its name. You can use the supplied implementation of a path-based library loader or create your own.

The latter approach requires implementation of the com.jniwrapper.LibraryLoader interface. This interface defines two methods: findLibrary() for finding a file containing the required library by name, and loadLibrary() for loading the library (by calling System.load), also by name.

Suppose you have implemented a library loader called MyLibraryLoader. To make JNIWrapper look for the libraries using this loader, you can write something like this:

    Library.setDefaultLibraryLoader(new MyLibraryLoader());

Remember that the default loader specified this way is also used for loading the JNIWrapper native library.

Alternatively, you may use a custom loader to load a specific library only:

    myLibrary.load(new MyLibraryLoader());

4.2. Using DefaultLibraryLoader

JNIWrapper comes with a convenient default implementation of the LibraryLoader interface: DefaultLibraryLoader. It looks for the libraries in a set of directories (path). The initial search path includes all directories from the java.library.path system property.

New directories can be added to the search path using the addPath() method. DefaultLibraryLoader is a singleton and is also the one JNIWrapper uses by default.

If using the default path with some additions is sufficient, then adding directories to the search path is the only configuration needed. For example, if native libraries (or the JNIWrapper native code) are to be looked for in the bin directory relative to the program working directory, the following line should be added to the JNIWrapper initialization part of your program:

    DefaultLibraryLoader.getInstance().addPath("bin");

4.3. Loading Native Libraries

Loading of libraries does not require special attention, if only one library loader is used, i.e. when the necessary library is found and loaded using the loader set by the setDefaultLibraryLoader() method (or an instance of the DefaultLibraryLoader class, which is the initial value of that property).

If a custom library loader should be used, an explicit call to the library's load() method should be made before any function is loaded from that library.

Take a look at these examples.

Using one library loader:

    Library kernel32 = new Library("kernel32");
    // Use kernel32 here

Using a custom library loader:

    Library customLib = new Library("myCustomLib");
    LibraryLoader myCustomLoader = new MyCustomLibraryLoader();
    customLib.load(myCustomLoader);
    // Use customLib here

4.4. Getting Functions from a Native Library

Functions are represented by instances of the com.jniwrapper.Function class. A function is always part of some library and therefore, cannot be instantiated on its own. To get a function from the library, the getFunction() method should be used. For example:

    Function getLastError = kernel32.getFunction("GetLastError");

Please note that some compilers may mangle function names to include argument types or sizes. This version of JNIWrapper performs search only by the exact name, not by mangled names. Therefore, if you need to invoke a function with such a name, you should specify the full mangled name. For example:

    Function myFunc = myLibrary.getFunction("_myFunc@4");

Most libraries, however, export nice unmangled names. You can find out an exported function name by using tools such as dumpbin or Dependency Checker.

extern "C" __declspec (dllexport) int* _data = new int(123);

 // load library
 Library SAMPLE_LIB = new Library("Library_Name");

 Int result = new Int();

 // get a variable pointer
 SAMPLE_LIB.getVariable("_data", new Pointer(result));

 // read a variable value
 long variableValue = result.getValue();

4.5. Calling Conventions

There are two widespread calling conventions: cdecl used in most C/C++ programs and stdcall used, for example, in Pascal. Calling convention is a function property since a library can export functions that use different calling conventions. Use your library documentation to find out which calling convention is used by the functions you are going to invoke.

    cdeclFunction.setCallingConvention(Function.CDECL_CALLING_CONVENTION);

5.1. Primitive Types

JNIWrapper provides parameter classes for all the primitive types available in the native program: signed and unsigned integers of different sizes, floating point values, single-byte and wide characters, etc. Related types usually have a common superclass or implement a common interface.

All simple types have a no-argument constructor that initializes a parameter to the default value (usually zero or equivalent), a constructor with the initial value and a copying constructor. They also have appropriately typed getValue() and setValue() methods. Take a look at the example of using the DoubleFloat parameter:

    DoubleFloat d1 = new DoubleFloat(1.2345);
    DoubleFloat d2 = new DoubleFloat(d1);
    d1.setValue(9.876);
    System.out.println(d2.getValue());

5.2. Structures and Unions

JNIWrapper supports C-like structures and unions. Like in C, the structure and union definitions are similar. Both provide a constructor that takes an array of parameters defining the structure or union contents.

If you want to create a reusable Java class for a structure or unions, you can use a protected no-argument constructor and initialize the content by calling the init method. This method is provided for convenience, because class fields are initialized after the superclass constructor is invoked and therefore, cannot be used as constructor arguments. The structure and union member values are accessed by directly querying the parameters specified in the constructor for their values. For example:

/*
Structure definition in C:
struct SomeStruct
{
        int a;
        char b;
        double c;
}
*/
Int intField = new Int();
Char charField = new Char();
DoubleFloat doubleField = new DoubleFloat();

struct = new Structure(new Parameter[] {intField, charField, doubleField});
doubleField.setValue(10); // set struct.a value to 10
// invoke some code that modifies the structure here
System.out.println(doubleField); // prints new value of struct.c

To learn how to use linked structures, open:

<jniwrapper-3.x-win32.zip>/samples/src/LinkedStructureSample.java

private static class TestStruct extends Structure {
    public Int _int = new Int();
    public Int8 _int8 = new Int8();
    public Int16 _int16 = new Int16();
    public Int32 _int32 = new Int32();
    public Int64 _int64 = new Int64();
    public LongInt _long = new LongInt();

    public TestStruct() {
        init(new Parameter[] {
            _int, _int8, _int16, _int32, _int64, _long
        });
    }

    public TestStruct(short alignment) {
        init(new Parameter[] {
                _int, _int8, _int16, _int32, _int64, _long
            }, alignment);
    }
}

union = new Union(new Parameter[] {intField, charField, stringField, structField});
union.setActiveMember(stringField);
stringField.setValue(STRING_VALUE);
func1.invoke(result, union);
// ...
func2.invoke(union, (Parameter[])null);
union.setActiveMember(structField, true);
assertEquals(X_VALUE, structField.getX());

5.3. Pointers

JNIWrapper supports C-like pointers to all the defined types. You can create a pointer by instantiating the com.jniwrapper.Pointer class. Pointers should always refer to some object. For example:

Pointer pInt = new Pointer(new Int());

A pointer automatically allocates memory for its referenced object; it handles reads and writes requiring the referenced object to read or write its data when the pointer itself is read or written. Thus, after any native function call, all the parameters are updated even if they are referenced by several nested pointers. For example:

Int value = new Int();
Pointer ppInt = new Pointer(new Pointer(value));

// invoke func(int **i) passing ppInt as a parameter
func.invoke(null, ppInt);
System.out.println(value) // value is updated!

In cases where the referenced object is read-only or write-only, one can use the Pointer.Const or Pointer. OutOnly types, respectively. Note, however, that using these classes cannot enforce the read-only or write-only policy on the native function which may still access the data inappropriately. It is recommended that these classes are only used for performance improvements.

JNIWrapper supports pointers that refer to undefined values (void* in C) through the Pointer.Void class. Use this class when you do not care about the actual referenced object and do not need to allocate the memory a pointer points to. For example, if you need a constant (HWND)-1 you can use the following construct:

Pointer.Void HWND_TOPMOST = new Pointer.Void(-1);

Pointer.Void is not a pointer. It doesn't have a referenced object and it is not assignable to and from any other kind of pointer. The name of the type only reflects the fact that this parameter always has the same size as a platform-dependent pointer.

typedef void (*PCallbackType)(int);
PCallbackType installCallback(PCallbackType);

// Field declaration
Pointer.Void myOldCallback;
// ...
// Callback installation code
installCallback.invoke(myOldCallback, new HookCallback());

protected void callback() {
    // do some hook stuff
    myOldCallback.asFunction().invoke(null, intParam);
}

  // retrieve the pointer somewhere
  Pointer.Void handle = getHandle();

  // prepare the data pointer, assuming that it points to an integer value
  Int data = new Int();
  Pointer dataPtr = new Pointer(data);

  // cast the pointers
  handle.asTypedPointer(dataPtr); 

  // create typed pointer
  Int data = new Int(123);
  Pointer dataPtr = new Pointer(data);

  // create void pointer
  Pointer.Void handle = new Pointer.Void();

  // cast the pointers
  dataPtr.asVoidPointer(handle);

5.4. Arrays

JNIWrapper supports two types of arrays:

You can use complex arrays to store primitive values, but the primitive arrays are more efficient for this purpose.

Arrays are represented by the instance of com.jniwrapper.PrimitiveArray and com.jniwrapper.ComplexArray for the primitive and complex arrays, respectively. Arrays are represented by PrimitiveArray and ComplexArray types parametrized by parameters that represent the actual type. For example:

int i[10];  

is

PrimitiveArray i = new PrimitiveArray(Int.class, 10);

The main difference between the two types of arrays is that a primitive array is a plain data block that contains sequential data of a given type, while a complex array is a sequential storage of elements of any complexity that are all read and written whenever an array is read or written, respectively. This means that an array of pointers cannot be implemented as a primitive array because the referenced objects will not be written or read when needed. PrimitiveArray can be only of primitive types (int, char, float) and not of arrays, pointers, structures, etc. ComplexArray has no restriction on its element type.

Sometimes arrays can be specified as pointers in function signature, for example:

void foo(int *arg);

But if the actual value is a pointer to some number of integers, use array as a parameter.

The simplest method of creating an array is using a constructor specifying a sample parameter and array size. Note that the array's member type should be correctly cloneable. For example, to create an array of bytes, you can use the following construct:

PrimitiveArray val = new PrimitiveArray(new Int8(), 256);

Another method of creating an array is using a Java array of parameters that should constitute it. This is achieved by using a constructor taking a Parameter[] argument. Both primitive and complex arrays can be created this way. Here is an example of creating an array of pointers to integers:

Parameter[] members = new Parameter[10];
for(int i = 0; i < 10; i++) {
        members[i] = new Pointer(new Int(i));
}
ComplexArray result = new ComplexArray(members);

/*
C declaration:
struct s
{
        int size;
        double *data;
}
*/
Int intMember = new Int(50);
PrimitiveArray arrayMember = new PrimitiveArray(DoubleFloat.class, 50);
Structure s = new Structure(new Parameter[] {intMember,
        new Pointer(arrayMember)});

 /*
 C declaration:
 double foo(double* data, int elementsCount);
 */

 Function foo = library.getFunction("foo");
 DoubleFloat result = new DoubleFloat();
 int count = 50;
 PrimitiveArray array = new PrimitiveArray(DoubleFloat.class, count);
 foo.invoke(result, new Pointer(array), new Int(count); 

PrimitiveArray myArray = new PrimitiveArray(Int8.class, length);

Int16 len = new Int16(length);
ResizingPointer pArray = new ResizingPointer( myArray);;
Function func = getFunction("myFunction");
func.invoke(null, pArray, new Pointer(len));

length = (short)len.getValue();
pArray.readArray(length);
// use myArray here

5.5. Strings

Strings in JNIWrapper are character arrays of a predefined size with convenience methods for getting and setting string values as zero terminated strings. JNIWrapper supports two types of strings: single-byte, or ANSI strings, and Unicode strings.

All strings are defined with the maximum length that a string value can occupy. It is illegal to set a string parameter value to the value longer than its maximum length. Passing a string argument to a function that writes more data than is allocated may result in an error just like in the native programs. On the other hand, strings are safe in the way that the data is parsed until the terminating zero (of appropriate length) is found or the maximum string length is reached. Therefore, even a bad string without a terminating zero will not cause memory access failures in your program. Here are the examples of string usage:

AnsiString s = new AnsiString("Hello, World!");
WideString s2 = new WideString(20);
s2.setValue("Goodbye, World!");

Similar to arrays, strings in native code can be both pointers to string data and character arrays themselves. When using strings as structure members, use the same guidelines to determine whether a pointer wrapper should be used. When passing strings as function arguments, however, strings are always passed as pointers and JNIWrapper does pointer wrapping automatically. You should remember though that wrapping is just a convenience feature and passing a char** will require creating a new Pointer(new Pointer(new AnsiString())).

5.6. Enumerations

A C enumeration type (for example enum a {first, second, third}) can be substituted by an integer parameter, for example Int class (or any other integer parameter). In this case, new Int(0) corresponds to 'first', new Int(1) corresponds to 'second' and so on.

6.1. Calling Conventions

If you are going to use a calling convention that differs from the default one used by JNIWrapper, the calling convention must be set before a native function is first called. Failure to do so will result in an error. Here is a complete example of calling a function:

Function sprintf =
        new Library("msvcrt").getFunction("sprintf");
sprintf.setCallingConvention(
        Function.CDECL_CALLING_CONVENTION);
AnsiString result_buffer = new AnsiString();
sprintf.invoke(
        null,
        result_buffer,
        new AnsiString("Hello, %s!"),
        new AnsiString("World"));
System.out.println("result = " + result_buffer.getValue());
//Output: result = Hello, World!

This example shows that there is no problem with calling functions even with variable argument number.

JNIWrapper checks that stack is left in consistent state after the function is called and handles most of the failures by throwing a Java exception.

All exceptions descend from com.jniwrapper.FunctionExecutionException.

These error or information messages from JNIWrapper can be disabled by adding the special category for JNIWrapper classes to your log4j configuration file:

log4j.category.com.jniwrapper=FATAL

Also, it can be configured programmatically:

Category jniwrapper = Category.getInstance("com.jniwrapper");
jniwrapper.setLevel(Level.FATAL);

6.1.1. A Quick Way to Call a Function

The Function class provides a shortcut way to call a function from a library without creating Library and Function instances: the call() method. To use it, write the following:

Table 6-1.

	Function.call("user32.dll", "MessageBeep", retVal, new UInt(1));
	Function.call("/lib/libc.so.6", "printf", null, new AnsiString("Hello, World!\n"));
	Function.call("/usr/lib/libSystem.dylib", "printf", null, new AnsiString("Hello, World!\n"));

This will load a library using the default loader, look up a function and invoke it using the default calling convention.

It is not recommended to use the call() method when your program makes a lot of native function calls, because it is more resource intensive. However, it is perfectly fine to use it in simple cases like getting the current directory.

6.2. Using Callbacks

Callback is a user-defined function that is called by the library code at the appropriate time. Callbacks can have arguments and return a value. JNIWrapper supports callbacks with any kind of arguments and return values, as well as stdcall and cdecl calling conventions. Callbacks are represented by subclasses of the com.jniwrapper.Callback class.

Passing a callback as an argument is no different from passing any other value: you just need to put an instance of the Callback class as the corresponding argument. For example:

Table 6-2.

	final class EnumWindowsProc extends Callback // ... EnumWindowsProc enumWindowsProc = new EnumWindowsProc(); Function.call("user32.dll", "EnumWindows", retVal, enumWindowsProc, new Int32(57));
	class MyComparator extends Callback // ... Function.call("/lib/libc.so.6", "qsort", null, dataPointer, new Int(size), new Int(memberLen), new MyComparator());
	class MyComparator extends Callback // ... Function.call("/usr/lib/libSystem.dylib", "qsort", null, dataPointer, new Int(size), new Int(memberLen), new MyComparator());

When a callback is no longer needed, you should explicitly free the resources associated with it by invoking its dispose() method. This is the only case in JNIWrapper where resources are to be explicitly freed, because some types of the callback objects may have no references from code and still be active, for example a window procedure callback instance may be created once when the window class is registered and remain active during the entire program lifecycle.

To implement a callback, you need to subclass the Callback class implementing the callback() abstract method. The callback arguments and return value are specified in the constructor (by calling either the superclass constructor with parameters or init() method). The order of parameters is following: first go the arguments of a callback, and then a return value. Calling convention should also be set in the constructor if it is different from the default one .

When the callback() method is invoked, argument parameters contain the values of the passed arguments; after the callback() method is complete, the value of the return value parameter is returned to the caller. Here is an example of a callback that takes an integer argument and returns its value incremented by one:

/*
C callback declaration:
int callback(int);
*/
private static class IncIntCallback extends Callback {
    private Int _arg = new Int();
    private Int _result = new Int();

    public IncIntCallback() {
        init(new Parameter[] {_arg}, _result);
    }

    public void callback() {
        _result.setValue(_arg.getValue() + 1);
    }
}

7.1. Parameters

Parameters in JNIWrapper are not synchronized because synchronizing at this level is very inefficient, and performance was a high-priority goal in JNIWrapper development. Therefore, access to the parameter data should be enclosed in synchronization blocks if there is a possibility for more than one thread to access the data at a time. If you have only one parameter that is shared between threads, you can synchronize on that object's monitor:

Int32 sharedInt = new Int32();
// ...
// First thread
synchronized(sharedInt) {
    someFunction.invoke(sharedInt);
}
// ...
// Second thread
synchronized(sharedInt) {
    if (sharedInt.getValue() == 10)
        System.out.println("Value is set to 10");
// ...

7.2. Functions

Function invocation in JNIWrapper is completely thread-safe. If the called function is thread-safe, any number of threads may invoke it concurrently at any time. No synchronization is required and/or performed, and calls are executed fully concurrently as if invoking simple Java methods.

8.1. Overview

The Code Generator for JNIWrapper allows you to select C code containing the required C types and generate the corresponding Java wrappers for them. This code can be either in a C header file or in a fragment of code, which can be inserted from the clipboard or just typed as text. The resulting Java classes (Java wrappers for C types) are saved to the specified folder.

8.2. Running Code Generator for JNIWrapper

The application can be started by the appropriate file from the bin directory of JNIWrapper installation. The table below shows what file should be executed (depending on the platform) to start the applicaiton:

Table 8-1.

	Codegen.bat
	Codegen-linux.sh
	Codegen-macosx.sh

This application does not provide command-line mode.

8.3. Specifying Input Parameters and Options

The application provides an ability to specify various options for code generation. These options can be divided into the following three categories:

• Input parameters specify the input C source code in which the necessary types are defined. It can be a C header file, a folder that contains C headers files or a fragment of C code.

• Generation parameters specify the set of types to generate wrappers for, their names and base types respectively.

• Output parameters specify the destination folder to save all generated Java files to and the root package name for all generated classes.

8.4. Using Type Replacement Table

The Code Generator application imports all types that are defined in the specified source and builds a correspondence table: every imported C type is mapped to the corresponding type from the JNIWrapper library. The application provides an ability to change the name of a particular type as well as its base type (the parent type from the JNIWrapper library), in case this type was not recognized by the C parser.

Also, it is possible to define a set of types to be generated: you can just select the necessary types in the appropriate table.

8.5. Namespaces and Package Naming

The destination root package (which can be specified in the options) is actually a root for other subpackages automatically generated by the application. Also, it is possible to give a custom package name to each type (resulting class) individually.

8.6. Supported Types

The current version of the application supports the following C types:

• struct

• union

• callback

• enum

• types that are defined or redefined using the typedef keyword

Also, the application supports generation of pointers and arrays.

8.7. Known Limitations

The current version of the application does not recognize the following C preprocessor directives:

• #include

• #define

• #if

• #error

The inline functions (for example "void GetData() { return;}" should not be present in the C code either.

Nester pointer types (for example: typedef int** PPInt) are not supported yet and they are processed as usual single pointers.

Also, please keep in mind that the application just parses the given C code, but does not validate it anyhow. Therefore, before giving some C code to this application, make sure that code is compilable and valid.

To generate a more complete set of wrappers, we recommend you to precompile the input C code with a C-compiler first, and then give the resulting file to the Code Generator application. This step will help you eliminate all unresolved dependencies.

8.8. Example

Suppose you need to create a wrapper for the following C structure:

struct Sample {
  int a;
  float b;
};

which is used in the following C function:

void sample(Sample* structure);

The Code Generator application will generate the following Sample.java wrapper for this C structure:

public class Sample extends Structure {
  private Int _a = new Int();
  private SingleFloat _b = new SingleFloat();
  public Sample() {
    init(new Parameter[] {_a, _b});
  }
  ...
}

Then, this generated Sample.java file should be included to the project and compiled. And the function call can be as follows:

Library lib = ...; // library that contains 'sample' function
Function sample = lib.getFunction("sample");
Sample sample = new Sample();
function.invoke(null, new Pointer(sample));

9.1. Using JAWT Support

On the native side, all the JAWT functionality can be accessed through several structures defined in the include/jawt.h file in the JDK directory. The root structure - JAWT - is available from the GetAWT function. JNIWrapper provides the com.jniwrapper.jawt.JAWT class that implements all the functionality available through the JAWT structure. The JAWT_DrawingSurface and JAWT_DrawingSurfaceInfo classes correspond to the structures with the same names in the jawt.h file and provide the same functionality.

9.2. Accessing Native Control's Data

The most common use of the JAWT interface is to get a handle of the native control that corresponds to a given component. This data is returned in the platform-dependent structure pointed to by the platformInfo member of the jawt_DrawingSurfaceInfo structure. The contents of this structure are defined in the jawt_md.h file in the include/<platform>/ directory of the JDK installation. The correct structure needs to be passed to the constructor of the JAWT_DrawingSurfaceInfo class. A sample structure for Win32 is shown below:

public class Win32DSI extends Structure
{
    private Pointer.Void _handle = new Pointer.Void();
    private Pointer.Void _hdc = new Pointer.Void();
    private Pointer.Void _hpalette = new Pointer.Void();

    public Win32DSI()
    {
     init(new Parameter[]{_handle, _hdc, _hpalette},
            (short) 8);
    }
    /**
     * Returns target component handle (either window or
     * bitmap handle).
     */
    public Pointer.Void getHandle()
    {
        return _handle;
    }

    /**
     * Returns DC handle. This handle should be used for
     * drawing instead of handles returned * from
     * <code>GetDC</code> or <code>BeginPaint</code>.
     */
    public Pointer.Void getHdc()
    {
        return _hdc;
    }

    /**
     * Returns palette handle.
     */
    public Pointer.Void getHpalette()
    {
        return _hpalette;
    }
}

9.3. Getting HWND of a Window

Below is given an example of a code snippet that gets a Win32 window handle of an AWT window. It is very similar to the C-code required to do the same thing.

JAWT_DrawingSurface ds = JAWT.getDrawingSurface(window);
ds.lock();
Win32DSI win32DSI = new Win32DSI();
JAWT_DrawingSurfaceInfo dsi = new JAWT_DrawingSurfaceInfo(win32DSI);
Pointer pDsi = new Pointer(dsi);
ds.getDrawingSurfaceInfo(pDsi);
int result = (int) win32DSI.getHandle().getValue();
ds.freeDrawingSurfaceInfo(pDsi);
ds.unlock();
JAWT.freeDrawingSurface(ds);
return result;

In the table below you can see how to create the wrappers for Java windows on different platforms:

Table 9-1.

	// Using Wnd class from WinPack library JFrame window = new JFrame(); window.setVisible(true); //a Java window should be visible Wnd wnd = new Wnd(window);
	// Using NSWindow class from MacPack library JFrame window = new JFrame(); window.setVisible(true); // a Java window should be visible NSWindow wnd = new NSWindow(window);

9.4. JAWT Support in Different JDK Versions

When programming using the JAWT interface, you should keep in mind that JAWT is a relatively new technology. It was introduced only in JDK 1.3 with limited functionality, has had many improvements in JDK 1.4, and JAWT is intended to completely replace such native-related functions as sun.awt.windows. WToolkit.getNativeWindowHandleFromComponent. For JDK 1.3, you should expect very limited support for JAWT. For example, the argument of the getDrawingSurface() method can only be a java.awt.Canvas. JDK 1.4 introduced new functions, such as AWT locking and unlocking, as well as extended the capabilities of the existing functions.

14.1. Reporting Problems

If you find any bugs, please submit the issue to us using a special report form on the TeamDev integrated customer support and troubleshooting center at:

http://support.teamdev.com/forms/reportForm.jsf

The form will help you provide all necessary information.

14.2. Troubleshooting

To find a solution to your problem, please visit the Troubleshooting page at:

http://www.teamdev.com/jniwrapper/tshoot.jsf

This page is regularly updated using information from support requests.

If you didn't find a solution, please e-mail us at jniwrapper-support@teamdev.com or report the problem as described in the previous section.