JNative

Overview

Package

Class

Tree

Deprecated

Index

Help

JNative project : see http://jnative.sf.net

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.xvolks.jnative
Class JNative

java.lang.Object
  org.xvolks.jnative.JNative

public class JNative
extends java.lang.Object
extends java.lang.Object

JNative this is the main class for calling native functions.
$Id: JNative.java,v 1.8 2006/01/12 21:35:45 mdenty Exp $;
To do so you have to :

create a new JNative object (JNative messageBox = new JNative("User32.dll", "MessageBoxA");
set its return type (messageBox.setRetVal(Type.INT);
pass some parameters (messageBox.setParameter(0, Type.INT, "0");
pass some parameters (messageBox.setParameter(1, Type.STRING, "message");
pass some parameters (messageBox.setParameter(2, Type.STRING, "caption");
pass some parameters (messageBox.setParameter(3, Type.INT, "" + 0);
then invoke the function (messageBox.invoke();
you can get its return value (messageBox.getRetVal();
dispose native resources when they no more needed (messageBox.dispose();

So simple :)
if you have to deal with pointers you can create some, here is a sample, it uses one pointer but could have be done with 3 (one per PULARGE_INTEGER)

The C function to call

 BOOL GetDiskFreeSpaceEx(
   LPCTSTR lpDirectoryName,
   PULARGE_INTEGER lpFreeBytesAvailable,
   PULARGE_INTEGER lpTotalNumberOfBytes,
   PULARGE_INTEGER lpTotalNumberOfFreeBytes
);

The implementation in Java with JNative

        public static final FreeDiskSpace getDiskFreeSpaceEx(String drive) throws NativeException, IllegalAccessException {
           if(drive == null) throw new NullPointerException("The drive name cannot be null !");
           Pointer lpFreeBytesAvailable = new Pointer(24);
           int i = 0;
           JNative fs = new JNative("Kernel32.dll", "GetDiskFreeSpaceExA");
           fs.setRetVal(Type.INT);
           fs.setParameter(i++, Type.STRING, drive);
           fs.setParameter(i++, lpFreeBytesAvailable.getPointer(), 8);
           fs.setParameter(i++, lpFreeBytesAvailable.getPointer() + 8, 8);
           fs.setParameter(i++, lpFreeBytesAvailable.getPointer() + 16 , 8);
           fs.invoke();
           FreeDiskSpace dsp = new FreeDiskSpace(drive, lpFreeBytesAvailable);
           lpFreeBytesAvailable.dispose();
           return dsp;
        }

mémo : pour créer le .h -> "%JAVA_HOME%\bin\javah.exe" -classpath %BIN_DIR% org.xvolks.jnative.JNative

Constructor Summary
`JNative(java.lang.String dllName, java.lang.String functionName)` Constructor exact call of new JNative(dllName, functionName, false); Creates a function without debug output
`JNative(java.lang.String dllName, java.lang.String functionName, boolean nativeDebug)` Constructor

Method Summary
`static int`	`allocMemory(int size)` Method allocMemory allocates native block of memory : don't forget to free it with `freeMemory(int)`!!!!
`void`	`dispose()` Method dispose free native pointers and memory internally used by the jnative dll No more calls to this dll can be done when dispose is called !!
`boolean`	`equals(java.lang.Object obj)` Indicates whether some other object is "equal to" this one.
`protected void`	`finalize()` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
`static void`	`freeMemory(int pointer)` Method freeMemory try to free the block of memory pointed by `pointer` No checks are done to see if the pointer is valid (TODO ?)
`static int`	`getCurrentModule()` Method getCurrentModule
`static java.lang.String[]`	`getDLLFileExports(java.lang.String dllFile)` Method getDLLFileExports gets all the names of the functions exported by a library
`java.lang.String`	`getDLLName()` Method getDLLName
`java.lang.String`	`getFunctionName()` Method getFunctionName
`static byte[]`	`getMemory(int pointer, int size)` Method getMemory
`static java.lang.String`	`getMemoryAsString(int pointer, int size)` Method getMemoryAsString
`java.lang.String`	`getParameter(int pos)` Method getParameter
`java.lang.String`	`getRetVal()` Method getRetVal gets the value returned by the function, should be verified to avoid invalid pointers when getting out values
`void`	`invoke()` Method invoke calls the function
`static int`	`registerWindowProc(int hwnd, WindowProc proc)` Method registerWindowProc register a WindowProc for the Window `hwnd`
`static void`	`setMemory(int pointer, byte[] buffer)` Method setMemory fills the native memory with the content of `buffer` Be aware that buffer overflows are no checked !!!!
`static void`	`setMemory(int pointer, byte[] buffer, int offset, int len)` Method setMemory fills the native memory with the content of `buffer` Be aware that buffer overflows are no checked !!!!
`static void`	`setMemory(int pointer, java.lang.String buffer)` Method setMemory fills the native memory with the content of `buffer` Be aware that buffer overflows are no checked !!!!
`void`	`setParameter(int pos, int pointer, int size)` Method setParameter Sets the parameter at index `pos`
`void`	`setParameter(int pos, Pointer p)` Method setParameter Sets the parameter at index `pos`
`void`	`setParameter(int pos, Type type, byte[] value)` Method setParameter Sets the parameter at index `pos`
`void`	`setParameter(int pos, Type type, java.lang.String value)` Method setParameter Sets the parameter at index `pos`
`void`	`setRetVal(Type type)` Method setRetVal fixes the return type of this function.

Methods inherited from class java.lang.Object
`clone, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

JNative

public JNative(java.lang.String dllName,
               java.lang.String functionName)
        throws NativeException

Constructor exact call of new JNative(dllName, functionName, false);
Creates a function without debug output

Parameters:: dllName - the name of library file; functionName - the decorated name of the function (MessageBoxA instead of MessageBox)
Throws:: NativeException - if the dll was not found, function name is incorrect...
See Also:: getDLLFileExports(String)

JNative

public JNative(java.lang.String dllName,
               java.lang.String functionName,
               boolean nativeDebug)
        throws NativeException

Constructor

Parameters:: dllName - a String the name of the library; that DLL must be in the library.path; functionName - a String the name of the function this is the decorated name (@see org.xvolks.jnative.JNative#getDLLFileExports(String)); nativeDebug - a boolean if true the dll logs output on stdout (beware this is shared between all instances of JNative)
Throws:: NativeException - if the dll was not found, function name is incorrect...
See Also:: getDLLFileExports(String)

Method Detail

setParameter

public void setParameter(int pos,
                         Type type,
                         java.lang.String value)
                  throws NativeException,
                         java.lang.IllegalAccessException

Method setParameter
Sets the parameter at index pos

Parameters:: pos - the offset of the parameter; type - one of the enum entry (INT, STRING...); value - the parameter in its String representation
Throws:: NativeException; java.lang.IllegalAccessException

setParameter

public void setParameter(int pos,
                         Type type,
                         byte[] value)
                  throws NativeException,
                         java.lang.IllegalAccessException

Method setParameter
Sets the parameter at index pos

Parameters:: pos - the offset of the parameter; type - one of the enum entry (INT, STRING...); value - the parameter in its byte[] representation
Throws:: NativeException; java.lang.IllegalAccessException

setParameter

public void setParameter(int pos,
                         int pointer,
                         int size)
                  throws NativeException,
                         java.lang.IllegalAccessException

Method setParameter
Sets the parameter at index pos

Parameters:: pos - the offset of the parameter; pointer - the address of a pointer; size - the size of the reserved memory at address pointer
Throws:: NativeException; java.lang.IllegalAccessException - if dispose() have already been called.

setParameter

public void setParameter(int pos,
                         Pointer p)
                  throws NativeException,
                         java.lang.IllegalAccessException

Method setParameter
Sets the parameter at index pos

Parameters:: pos - the offset of the parameter; p - a pointer object representing an address
Throws:: NativeException; java.lang.IllegalAccessException - if dispose() have already been called.

setRetVal

public void setRetVal(Type type)
               throws NativeException,
                      java.lang.IllegalAccessException

Method setRetVal fixes the return type of this function.

Parameters:: type - a Type generally VOID or INT, if VOID it is not necessary to call this function
Throws:: NativeException; java.lang.IllegalAccessException - if dispose() have already been called.

getRetVal

public java.lang.String getRetVal()
                           throws NativeException,
                                  java.lang.IllegalAccessException

Method getRetVal gets the value returned by the function, should be verified to avoid invalid pointers when getting out values

Returns:: the value returned by this function in its String representation
BOOL functions return int values
Throws:: NativeException; java.lang.IllegalAccessException - if dispose() have already been called.

getParameter

public java.lang.String getParameter(int pos)
                              throws NativeException,
                                     java.lang.IllegalAccessException

Method getParameter

Parameters:: pos - an int
Returns:: the parameter at index pos
Throws:: NativeException; java.lang.IllegalAccessException - if dispose() have already been called.

invoke

public void invoke()
            throws NativeException,
                   java.lang.IllegalAccessException

Method invoke calls the function

Throws:: NativeException; java.lang.IllegalAccessException - if dispose() have already been called.

dispose

public final void dispose()
                   throws NativeException,
                          java.lang.IllegalAccessException

Method dispose free native pointers and memory internally used by the jnative dll

No more calls to this dll can be done when dispose is called !!

Throws:: NativeException; java.lang.IllegalAccessException - if dispose() have already been called.

finalize

protected void finalize()
                 throws java.lang.Throwable

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. A subclass overrides the finalize method to dispose of system resources or to perform other cleanup.

The general contract of finalize is that it is invoked if and when the Java^TM virtual machine has determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, except as a result of an action taken by the finalization of some other object or class which is ready to be finalized. The finalize method may take any action, including making this object available again to other threads; the usual purpose of finalize, however, is to perform cleanup actions before the object is irrevocably discarded. For example, the finalize method for an object that represents an input/output connection might perform explicit I/O transactions to break the connection before the object is permanently discarded.

The finalize method of class Object performs no special action; it simply returns normally. Subclasses of Object may override this definition.

The Java programming language does not guarantee which thread will invoke the finalize method for any given object. It is guaranteed, however, that the thread that invokes finalize will not be holding any user-visible synchronization locks when finalize is invoked. If an uncaught exception is thrown by the finalize method, the exception is ignored and finalization of that object terminates.

After the finalize method has been invoked for an object, no further action is taken until the Java virtual machine has again determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, including possible actions by other objects or classes which are ready to be finalized, at which point the object may be discarded.

The finalize method is never invoked more than once by a Java virtual machine for any given object.

Any exception thrown by the finalize method causes the finalization of this object to be halted, but is otherwise ignored.

This one calls dispose() but all Throwable are catched

Overrides:: finalize in class java.lang.Object

Throws:: java.lang.Throwable - the Exception raised by this method

getFunctionName

public final java.lang.String getFunctionName()

Method getFunctionName

Returns:: the name of this function

getDLLName

public final java.lang.String getDLLName()

Method getDLLName

Returns:: the name of this DLL

equals

public boolean equals(java.lang.Object obj)

Indicates whether some other object is "equal to" this one.

Overrides:: equals in class java.lang.Object

allocMemory

public static int allocMemory(int size)
                       throws NativeException

Method allocMemory allocates native block of memory : don't forget to free it with freeMemory(int)!!!!

Parameters:: size - the size of the memory block to reserve in bytes
Returns:: the address of the reserved memory (a pointer)
Throws:: NativeException - if the memory cannot be reserved

freeMemory

public static void freeMemory(int pointer)
                       throws NativeException

Method freeMemory try to free the block of memory pointed by pointer
No checks are done to see if the pointer is valid (TODO ?)

Parameters:: pointer - the address of a memory block to free
Throws:: NativeException - if the memory cannon be freed

setMemory

public static void setMemory(int pointer,
                             java.lang.String buffer)
                      throws NativeException

Method setMemory fills the native memory with the content of buffer
Be aware that buffer overflows are no checked !!!!

Parameters:: pointer - the address of the native memory; buffer - a String to memcpy
Throws:: NativeException

setMemory

public static void setMemory(int pointer,
                             byte[] buffer)
                      throws NativeException

Method setMemory fills the native memory with the content of buffer
Be aware that buffer overflows are no checked !!!!

Parameters:: pointer - the address of the native memory; buffer - a byte[] to memcpy
Throws:: NativeException

setMemory

public static void setMemory(int pointer,
                             byte[] buffer,
                             int offset,
                             int len)
                      throws NativeException

Method setMemory fills the native memory with the content of buffer
Be aware that buffer overflows are no checked !!!!

Parameters:: pointer - the address of the native memory; buffer - a byte[] to memcpy; offset - the offset of the native side; len - the number of bytes to copy
Throws:: NativeException

getMemory

public static byte[] getMemory(int pointer,
                               int size)
                        throws NativeException

Method getMemory

Parameters:: pointer - the address of the native memory; size - number of bytes to copy
Returns:: a copy of the memory at address pointer
Throws:: NativeException

getMemoryAsString

public static java.lang.String getMemoryAsString(int pointer,
                                                 int size)
                                          throws NativeException

Method getMemoryAsString

Parameters:: pointer - the address of the native char*; size - number of bytes to copy
Returns:: a String copy of the memory at address pointer limited by a NULL terminator if the char* is lower than size characters
Throws:: NativeException

registerWindowProc

public static int registerWindowProc(int hwnd,
                                     WindowProc proc)
                              throws NativeException

Method registerWindowProc register a WindowProc for the Window hwnd

Parameters:: hwnd - the HANDLE of the window; proc - a WindowProc object that be called by native events
Returns:: the previous function pointer used as a WindowProc for this window.
Throws:: NativeException - if the SetWindowLongPtr fails or somthing weird happens (can crash too ;) )...

getCurrentModule

public static int getCurrentModule()
                            throws NativeException

Method getCurrentModule

Returns:: the HMODULE associated with the jnative DLL
Throws:: NativeException

getDLLFileExports

public static java.lang.String[] getDLLFileExports(java.lang.String dllFile)
                                            throws NativeException,
                                                   java.lang.IllegalAccessException

Method getDLLFileExports gets all the names of the functions exported by a library

Parameters:: dllFile - the name of a library
Returns:: a String[] the names of the functions
Throws:: NativeException; java.lang.IllegalAccessException

Overview

Package

Class

Tree

Deprecated

Index

Help

JNative project : see http://jnative.sf.net

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.xvolks.jnative Class JNative

JNative

JNative

setParameter

setParameter

setParameter

setParameter

setRetVal

getRetVal

getParameter

invoke

dispose

finalize

getFunctionName

getDLLName

equals

allocMemory

freeMemory

setMemory

setMemory

setMemory

getMemory

getMemoryAsString

registerWindowProc

getCurrentModule

getDLLFileExports

org.xvolks.jnative
Class JNative