Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Started porting docs into markdown.

  • Loading branch information...
commit 92d721d9d0f4de8f1d739ba751fc19406a07a11f 1 parent 0f06d0b
@dblock dblock authored
View
479 CHANGES
@@ -0,0 +1,479 @@
+Release 3.x.x
+=============
+
+Features
+--------
+
+* Facilitate `Memory</code> subclasses (jbellis).
+* Allow multiple fields of the same type in Unions (Francis Barber).
+* Add `platform.win32.Advapi32.AdjustTokenPrivileges</code>, `platform.win32.Advapi32.LookupPrivilegeName</code>, `platform.win32.Advapi32.LookupPrivilegeValue</code>, `platform.win32.Advapi32.ImpersonateSelf</code>.
+* Add `platform.win32.Advapi32.DuplicateTokenEx</code>, `platform.win32.Advapi32.CreateProcessAsUser</code>, `platform.win32.Kernel32.GetExitCodeProcess</code>, `platform.win32.Kernel32.TerminateProcess</code>, `platform.win32.Kernel32.ReadFile</code>, `platform.win32.Kernel32.CreatePipe</code>, `platform.win32.Kernel32.SetHandleInformation</code> and related constants / structures in `platform.win32.WinBase</code> and `platform.win32.WinNT</code>. Please note that the `SECURITY_ATTRIBUTES</code> structure has been moved from `platform.win32.WinNT</code> to `platform.win32.WinBase</code>.
+* Add `platform.win32.Kernel32.DeleteFile</code> and `platform.win32.Kernel32Util.deleteFile</code>.
+* Add `platform.win32.Kernel32.GetFileAttributes</code> and `platform.win32.Kernel32Util.getFileAttributes</code>.
+* Add `platform.win32.Kernel32.GetTickCount</code>.
+* Add Win32 Service functions to `platform.win32.Advapi32</code>.
+* Add `platform.win32.W32ServiceManager</code> and `W32Service</code>.
+* Add Win32 Event Logging functions to `platform.win32.Advapi32</code> and `platform.win32.Advapi32Util.EventLogIterator</code>.
+* `platform.win32.Advapi32Util.registryCreateKey</code> returns `true</code> if key was created, `false</code> if it already exists.
+* Add `REG_BINARY</code>, `REG_EXPAND_SZ</code> and `REG_MULTI_SZ</code> support to `platform.win32.Advapi32Util</code> registry functions.
+* Reduce JNI crossings in a number of native methods, moving object creation out into pure Java code.
+
+Bug Fixes
+---------
+
+* Move all native functions into `com.sun.jna.Native</code>, to ensure that all dependent classes must be disposed before the `Native</code> class is unloaded.
+* Fix `platform.win32.Kernel32.GetNativeSystemInfo</code> and `GetSystemInfo</code> AV on Win64.
+* Fix several potential minor bugs as reported by TvT.
+* Fix bug in Structure.StructureSet.toString (Blair Zajac), exposed by Tomcat ThreadLocal cleanup.
+* Fix several bugs when using Structure(Pointer) ctor and array fields (Samuel Audet).
+
+Release 3.2.7
+=============
+
+Features
+--------
+
+* Add native peer value accessors for Pointer
+* The `jna.library.path</code> property is now re-evaluated whenever a native library is loaded. Previously this value was cached when the JNA classes loaded.
+* `Native.loadLibrary</code> can now load `.drv</code> files.
+* Refactor `com.sun.jna.platform.win32.WINBASE</code> into `WinDef</code>, `WinNT</code> and `BaseTSD</code>, matching Windows SDK headers.
+* Refactor constants from `com.sun.jna.platform.win32.GDI32</code> into `WinGDI</code>, matching Windows SDK headers.
+* Refactor constants from `com.sun.jna.platform.win32.User32</code> into `WinUser</code>, matching Windows SDK headers.
+* Refactor `platform.win32.WinNT.LARGE_INTEGER</code> into a union.
+* Add `platform.win32.ObjBase</code>, `com.sun.jna.platform.win32.Ole32.CoInitializeEx</code>, `CoUninitialize</code>, and `CoCreateInstance</code>.
+* Add `platform.win32.Oleaut32.SysAllocString</code> and `SysFreeString</code>.
+* Add `platform.win32.Secur32.ImpersonateSecurityContext</code> and `RevertSecurityContext</code>.
+* Add `platform.win32.WinNT.WELL_KNOWN_SID_TYPE</code>, `SECURITY_MAX_SID_SIZE</code> and other related SID-related constants.
+* Add `platform.win32.Advapi32.CreateWellKnownSid</code> and `IsWellKnownSid</code> and `com.sun.jna.platform.win32.Advapi32Util.isWellKnownSid</code>.
+* Add `platform.win32.Kernel32.GetVersion</code>, `GetVersionEx</code>, `GetSystemInfo</code>, `GetNativeSystemInfo</code>, `GlobalMemoryStatusEx</code>, `GetLogicalDriveStrings</code> and `IsWow64Process</code>.
+* Add `platform.win32.Kernel32Util.getLogicalDriveStrings</code>.
+* Add `platform.win32.User32.GetSystemMetrics</code>.
+* Add `platform.win32.BaseTSD.DWORD_PTR</code>.
+* Add `platform.win32.WinBase.SYSTEM_INFO</code> and `MEMORYSTATUSEX</code>.
+* Add `platform.win32.WinNT.OSVERSIONINFOEX</code>, `VER</code> constants.
+* Add `platform.win32.WinDef.ULONGLONG</code> and `DWORDLONG</code>.
+* Add `platform.win32.Shell32.SHGetDesktopFolder</code> (prep work for Com4JNA).
+* Add `platform.win32.Winspool.GetPrinterInfo</code>.
+* Add `platform.win32.WinspoolUtil.getPrinterInfo1</code>.
+* Add `platform.win32.GDI32.GetDeviceCaps</code>.
+* Add `platform.win32.GDI32.GetDIBits</code>.
+
+Bug Fixes
+---------
+
+* Fix `ClassCastException</code> in `Structure.equals</code> (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=152">issue 152</a>).
+* Fix bug initializing a structure object from existing memory when the structure has initialized fields (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=133">issue 133</a>).
+* Fix NPE reading an array of string from a pointer when an element of the array is `NULL</code> (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=151">issue 151</a>).
+* Avoid calling `UnregisterNatives</code> in native code (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=154">issue 154</a>).
+* Compare unpacked library path against canonical (long) filename (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=156">issue 156</a>).
+* Fix `read()</code> of uninitialized memory in `platform.win32.Advapi32Util.getTokenGroups</code> and `getTokenAccount</code>.
+* Fix `com.sun.jna.platform.win32.Secur32.QuerySecurityContextToken</code> to take a `CtxtHandle</code> instead of `PSecHandle</code>.
+* Fix definition of BITMAPINFO (platform/win32).
+
+Release 3.2.5
+=============
+
+Features
+--------
+
+* Split code in examples.jar into a contrib platform.jar package and individual packages for demos.
+* Fix Eclipse build and added Eclipse projects for all contrib samples, import projects from jnalib and contrib.
+* Ensure Structure fields correctly ordered when inherited.
+* Use explicit Structure field whenever provided, regardless of whether the VM requires it.
+* Add Win32 mappings for two dozen functions from Kernel32.dll, Advapi32.dll, Netapi32.dll, Secur32.dll, NtDll.dll, Ole32.dll, Shell32.dll and Crypt32.dll to com.sun.jna.platform.win32.
+* Port parts of WinError.h, WinNT.h, LMAccess.h, LMCons.h, LMErr.h, LMJoin.h, NTStatus.h, ShlObj.h, WinDef.h, ShellApi.h, Wdm.h, WinReg.h, WinCrypt.h, Sspi.h, Guid.h, NtSecApi.h and DsGetDc.h.
+* Add Win32 simplified utility interfaces Kernel32Util, Advapi32Util, Netapi32Util, Crypt32Util, NtDllUtil, Shell32Util, Ole32Util and Secur32Util to com.sun.jna.platform.win32.
+* Support unicode paths in W32FileUtils.
+* Fix exception during dispose in W32FileMonitor.
+
+Bug Fixes
+---------
+
+* Provide String.replace for 1.4 compatibility.
+* Avoid allocating memory when Structure is provided a pointer in the ctor.
+* Ensure proper value returned in Pointer.getValue() for non-null, unchanged NIO Buffer values.
+* Use 1.4-compatible URI generation (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=149">issue 149</a>).
+
+Release 3.2.4
+=============
+
+Features
+--------
+
+* Make Pointer ctor public.
+* Provide access to Function objects for arbitrary Pointer values.
+* Add linux/ia64 binaries (bpiwowar). See <a href="https://jna.dev.java.net/issues/show_bug.cgi?id=134">issue 134 patch</a>.
+
+Bug Fixes
+---------
+
+* Use a more robust method to decode a file-based URL (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=135">issue 135</a>).
+
+Release 3.2.3
+=============
+
+Features
+--------
+
+* Include version information in code in case package information lost.
+
+Bug Fixes
+---------
+
+* Fix WindowUtils exception on mouse over TrayIcon.
+* Fix bug toggling windows transparent/opaque (win32/OSX).
+* Avoid overwriting unchanged Pointer values in arrays (function calls with Pointer[] and Structure.read).
+* Ensure Structure fields marked `final</code> are never written.
+* Fix bug preventing proper population Structure.ByReference fields on Structure read.
+* Ensure double buffering is disabled in components added to a transparent window.
+* Fix UnsatisfiedLinkError attempting to load system libraries under Web Start.
+* Fix loading Web Start-provided libraries on OSX (libraries must have a .jnilib suffix under Web Start).
+* Properly include sources in Maven zip file (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=129">Issue 129</a>).
+
+Release 3.2.2
+=============
+
+Features
+--------
+
+* Provide length-specified Pointer.getStringArray()
+
+Bug Fixes
+---------
+
+* Fix crash with direct mapping if NULL struct* used (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=125">Issue 125</a>).
+* Fix case where null-valued Structure fields would get non-null values on write.
+* Synch callback Structure/Structure[] arguments on callback return.
+* Fix NPE when mapping an interface to the current process.
+* Automatically load proper C library version from current process on Linux (avoids crashing bug on Ubuntu with libc-i686 packages active).
+* Avoid scanning structure contents in Structure.toString if contents aren't actually used.
+
+Release 3.2.1
+==========
+
+Features
+--------
+
+* Add HRESULT, LONG mapping to W32API (marc strapetz).
+
+
+Bug Fixes
+---------
+
+* Fix definition of HWND_BROADCAST in W32API.
+* Fix memory alignment checking (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=121">Issue 121</a>).
+* Fix Structure <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/lang/Object.html#equals(java.lang.Object)">equals/hashCode</a> implementation, based on current Java fields rather than strictly native memory contents. Avoid using equals/hashCode when avoiding recursive reads/writes.
+
+Release 3.2.0
+=============
+
+Features
+--------
+
+* Handle String, Structure, Callback, Buffer, and primitive arrays in direct mappings. Handle NativeMapped and TypeMapper, with optimized paths for IntegerType and PointerType.
+* Optionally throw errno/GetLastError as an exception. This is preferred to (and more efficient than) calling Native.getLastError().
+* Unload/delete native library unpacked from jna.jar if Native class is garbage collected. Only install shutdown hook if using the system class loader.
+* Auto-write contiguous Structure arrays when first element is written.
+* Support NativeMapped[] as function arguments for interface-mapped libraries (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=90">Issue 90</a>).
+* Enable function lookup within current process on Windows.
+
+Bug Fixes
+---------
+
+* Restrict recursive structure reads/writes by thread instead of globally. This avoids potentially missed reads/writes with concurrent access (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=120">Issue 120</a>).
+* Ensure Memory is not GC'd and freed if direct NIO buffers mapped to it are extant.
+* Allow types derived from java.nio.Buffer as Structure fields.
+
+Release 3.1.0
+=============
+
+Features
+--------
+
+* Add raw JNI mapping of static Java methods. Performance is about 10X that of traditional JNA interface mapping, although with less type conversion functionality.
+* Add library option to allow passing/return of Java Objects.
+* Allow handling of uncaught callback exceptions (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=63">Issue 63</a>).
+* Object oriented interface to X server (see contrib/x11)
+* Make Memory class more accessible.
+* Provide Structure ctor with Pointer argument (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=102">issue 102</a>).
+* Allow implicit library access to current process on linux (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=98">issue 98</a>).
+* Open all shared libraries with RTLD_GLOBAL, if applicable. This was the default behavior on OSX and changes the default behavior on linux.
+* Allow NIO Buffer as Structure field (with limitations) (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=57">Issue 57</a>)
+* Add `size_t` size.
+
+Bug Fixes
+---------
+
+* Run tests with <a href="http://java.sun.com/j2se/1.4.2/docs/guide/vm/signal-chaining.html">libjsig.so</a>, if available, which fixes some crashes when running tests on 64-bit platforms.
+* Fix <a href="https://jna.dev.java.net/issues/show_bug.cgi?id=104">Issue 104</a>.
+* Fix <a href="https://jna.dev.java.net/issues/show_bug.cgi?id=94">Issue 94</a> (Java 1.6 update 10 regression).
+* Fix <a href="https://jna.dev.java.net/issues/show_bug.cgi?id=51">Issue 51</a> (Java 1.6 update 10 regression).
+* Fix <a href="https://jna.dev.java.net/issues/show_bug.cgi?id=95">Issue 95</a>.
+* Fix <a href="https://jna.dev.java.net/issues/show_bug.cgi?id=101">Issue 101</a>.
+* Fix <a href="https://jna.dev.java.net/issues/show_bug.cgi?id=111">Issue 111</a>, memory leak with String-returning Callback.
+* Fix missing storage of union type information (affects usage of struct/union by value as argument and return type).
+* Remove non-functional Structure ctors requiring explicit size.
+
+Release 3.0.9
+=============
+
+Bug Fixes
+---------
+
+* Fix <a href="https://jna.dev.java.net/issues/show_bug.cgi?id=93">issue 93</a> by only manually searching jna.library.path, then falling back to passing the mapped library name to dlopen/LoadLibrary. This fixes an <a href="http://jira.codehaus.org/browse/JRUBY-3084">issue in JRUBY</a> where the incorrect libc.so.6 was being loaded.
+
+Release 3.0.8
+==========
+
+Features
+--------
+
+* Auto-map Pointer[]/String[]/WString[] return values.
+* Provide utility functions to convert String to primitive array.
+* Add jna.library.boot.path property to define the directory that the native stub library is loaded from
+
+Release 3.0.7
+==========
+
+Features
+--------
+
+* Improve Win32 loading of libraries with dependencies.
+
+Bug Fixes
+---------
+
+* Fix bug reading structures with PointerType fields, introduced with Pointer field preservation fix.
+
+Release 3.0.6
+=============
+
+Features
+--------
+
+* Allow arbitrary callback method names if only one method is defined in the class which implements Callback (colinwalters).
+* Allow specification of callback type mappers by using a TYPE_MAPPER field (colinwalters).
+* Allow uninitialized (null-valued) boxed primitives in Structures (colinwalters).
+* Add convenience methods to set active Union field and value simultaneously (xylo).
+* Augment Union read/writeField to set the active field.
+* Allow Structure auto-synch across native calls to be disabled.
+* Win64 support.
+
+Bug Fixes
+---------
+
+* Avoid overwriting unchanged Structure fields of type Pointer.
+* Avoid more content dragging on OSX or warn if it's too late.
+* Fix UnsatisfiedLinkError using transparent window on Win2K.
+* Fix memory leak with callbacks called from native threads with no Java context (johnwallace).
+* Defer structure size calculation if type mapper not yet set, allowing type mapper to be set in derived constructors (colinwalters).
+* Ensure structure memory is allocated in Structure.read/writeField.
+
+Release 3.0.5
+=============
+
+Features
+--------
+
+* Allow explicit declaration of field order for VMs which have an unpredictable field order.
+* Check for w32 libraries with a "lib" prefix in addition to normal lookup.
+* Allow String[]/WString[] as callback argument/return value (assume NULL-terminated array).
+* Add Solaris8 compatibility to sunos-sparc build (Corey Puffalt).
+* Look up libraries using web start library path, if appropriate (Corey Puffalt).
+* Use constants to return integer boolean values.
+
+Bug Fixes
+---------
+
+* Properly track cursor on alpha-masked windows.
+* Avoid searching /lib or /usr/lib on 64-bit Linux.
+* Avoid using incorrect version of a library when both 32- and 64-bit versions are found.
+* Avoid transparent window events always dragging window bug on OSX.
+* Fix division by zero error calculating structure size on OSX/ppc.
+* Avoid overwriting initialized NativeMapped Structure fields when calculating structure size.
+* Fix NPE reading back into StringArray.
+
+Release 3.0.4
+=============
+
+Features
+--------
+
+* Automatically write contents of Structure.ByReference fields on Structure.write().
+* Use the actual parameter type in Function invocations if no parameter type information is available (whether method is missing or untyped varargs).
+* Augmented X11 library mappings (xylo).
+* Support read/write of NativeMapped arrays within Structure (notably NativeLong).
+
+Bug Fixes
+---------
+
+* Fix library load error when /usr/lib32 and /usr/lib both exist (linux) (Marek Slama).
+* Avoid incorrect matches against libraries named with the same prefix (e.g. libc-client.so vs libc.so) (xylo).
+* Properly handle arrays of NativeMapped (e.g. NativeLong) as a Structure field (stefan endrullis).
+* Ensure structure size calculated prior to setting union active type.
+* XID is 64-bits on 64-bit X clients (xylo).
+* Ensure proper arch name is used on Debian (amd64 instead of x86_64).
+
+Release 3.0.3
+=============
+
+Features
+--------
+
+* Enable build/run using IBM's J9 VM (leonardo).
+* Make StdCallFunctionMapper attempt a leading underscore if the simpler mapping doesn't work.
+* Allow Structure.read to overwrite final fields (may not work on some 1.4 VMs).
+
+Bug Fixes
+---------
+
+* Fix NPE when passing an array of Structure.ByReference.
+* Compare entire linux library version when finding a match.
+* Don't pass struct by value unless the method signature declares it.
+* Restrict custom first element structure alignment to OSX/ppc.
+* Improve performance and reduce memory footprint for window masks. Optimize polygon-based masks on w32. Use XFillRectangles on X11.
+* Fix linkage settings on sunos-amd64 to avoid relocation errors.
+* Fix callback allocation code on w32, solaris, freebsd, darwin (libffi was misconfigured).
+* Fix bug when NativeMapped fields are used in a Structure.ByValue instance.
+* Fix NPE calling Structure.read() before memory is initialized.
+* Fix NPE calling Structure.read/write with uninitialized NativeMapped fields.
+
+Release 3.0.2
+=============
+
+Features
+--------
+
+* Attempt to force unload of jnidispatch library prior to deleting it (w32).
+* Added amd64 targets for OSX, FreeBSD, and Solaris.
+
+Bug Fixes
+---------
+
+* Reduce space allocated for invocation arguments.
+* Fix NPE when NativeMapped type is used in a Structure.
+* Fix some X11 type mappings for 64-bit.
+* Fix OSX Leopard/JRE1.5+ window transparency.
+* Fix window alpha compositing on X11.
+* Fix loading of libraries with unicode names on OSX.
+
+Release 3.0.1
+=============
+
+Features
+--------
+
+* Improve transparent window drawing performance on w32
+* Use closure allocation from libffi
+
+Bug Fixes
+---------
+
+* Ensure nested structure arrays initialized with Structure.toArray use the appropriate native memory.
+* Ensure structure size is calculated prior to converting to array
+* Avoid creating new windows when setting a window mask
+* Fix bug in Pointer.setChar.
+
+Release 3.0
+===========
+
+Features
+--------
+
+* More supported platforms, via GCC's libffi (wmeissner)
+* Support struct by value as parameter and return value (duncan)
+* Support struct by reference within structures
+* Provide access to native peer for java.awt.Component
+* Provide access to native peer on OS X.
+* Support MINGW32 builds (fullung)
+* Allow per-field Structure read/write by field name
+* Avoid writing Structure fields marked 'volatile'
+* Read and wrap function pointers in Structure fields when read with a Java proxy to allow easy Java-side invocation (Ken Larson)
+* Support array-backed Buffers as arguments (wmeissner)
+* Auto-conversion of custom types (wmeissner)
+* Allow pointer type-safety
+* Optional VM crash protection, via Native.setProtected(boolean)
+* Auto-convert WString[]
+* Provide library synchronization wrapper similar to Collections.synchronizedX
+* Support lookup of OSX framework libraries by name
+* Explicit access to shared library global data
+* Invocation interception to facilitate translation of C preprocessor macros and inline functions
+* Provide utility to determine Web Start native library cache location; auto-include this path if jnidispatch is included as a &lt;nativelib&gt; (robertengels)
+* Provide access to aligned memory
+* Versioning information embedded in jna.jar and native library
+
+Bug Fixes
+---------
+
+* Avoid attempts to free native library if it failed to load (wmeissner)
+* Explicitly check method signatures for varargs instead of heuristically guessing (wmeissner)
+* Disallow declaring Pointer-derived fields in Structures (Function, Memory)
+* Ensure Object.toString/hashCode/equals methods are intercepted on proxyied interfaces
+* Update X11 library for 64-bit use (wmeissner)
+* Properly map arrays of char*/wchar_t* under w32
+* Allow Pointer[] as a Structure field and Function argument
+* Fix some misleading Structure error messages
+* Properly preserve/return GetLastError/errno after native calls
+* Allocate executable memory on w32 to avoid errors with hardware-enforced data execution protection (DEP)
+* Fix VM crash on w32 stdcall callbacks
+* Use long offsets and sizes rather than ints (64-bit safe)
+* Properly clean up references and release closure memory on JNI_Unload
+* Use simpler AWT/JAWT library loading workaround
+* Avoid changing array references within a Structure on read
+
+Release 2.5
+===========
+
+Features
+--------
+
+* Unions
+* Optimized shaped windows (chris deckers & olivier chafik); instantiation time improved by about 2-3 orders of magnitude for large, mostly contiguous shapes
+* Provide type mapping in callback arguments/results
+* Provide access to ByteBuffer direct address as a Pointer
+* Provide customization of native string encoding with jna.encoding system property
+
+Bug Fixes
+---------
+
+* Properly handle VMs with reversed Structure member storage
+* Avoid making window undecorated when clearing window mask on X11
+* Fix structure alignment bug on OSX/PPC when first element is > 4 bytes in size
+* Clearing OSX window mask by setting to MASK_NONE now works properly
+* Avoid index exceptions if native buffers are not NUL-terminated on string conversions
+* Write initialized Structure[] argument memory prior to function calls
+* Fix IllegalArgumentException reading WString into a Structure
+* Clear memory when allocating a structure block (fixes VM crash)
+* Remove versioned JAWT dependency on OSX, allowing use on 10.3/JRE1.4.
+
+Release 2.4
+===========
+
+Features
+--------
+
+* Explicitly support unaligned structures
+* Auto-reallocate structure arrays
+* Automatic handling of w32 UNICODE/ASCII variants
+* Automatic mapping of decorated w32 stdcall function names
+* Customizable, automatic type conversion of arguments and results (wmeissner)
+* Support char*[] arguments as Java String[]
+* Structure supports Callback members (wmeissner)
+* getByteBuffer from Pointer/Memory (wmeissner)
+* Allow GC of native libraries
+* Facilitate use from non-Java contexts (JRuby et al.) (wmeissner)
+* Improve library path searching (wmeissner)
+* Handle Structure[] arguments
+* Handle native long arguments and return values
+* Handle direct and array-based ByteBuffer arguments (wmeissner)
+* Change default w32 build to use GCC (it's free, yo)
+
+Bug Fixes
+---------
+
+* Structure.toArray failed to initialize members
+* Disallow explicit free of Structure/Memory
+* Ensure native libraries are only loaded once until released
+* Properly handle NULL when the return value is a Structure
+* Proper conversion to wchar_t on linux
+* Copy full length of Java strings to C strings instead of stopping when a NUL character is encountered
View
0  jnalib/LICENSE.txt → LICENSE
File renamed without changes
View
70 README.md
@@ -0,0 +1,70 @@
+![JNA](https://github.com/twall/jna/raw/master/www/images/jnalogo.jpg "Java Native Access (JNA)")
+
+Java Native Access (JNA)
+========================
+
+JNA provides Java programs easy access to native shared libraries (DLLs on Windows) without writing anything but Java code—no JNI or native code is required. This functionality is comparable to Windows' Platform/Invoke and Python's ctypes. Access is dynamic at runtime without code generation.
+
+JNA allows you to call directly into native functions using natural Java method invocation. The Java call looks just like it does in native code. Most calls require no special handling or configuration; no boilerplate or generated code is required.
+
+The JNA library uses a small native library stub to dynamically invoke native code. The developer uses a Java interface to describe functions and structures in the target native library. This makes it quite easy to take advantage of native platform features without incurring the high overhead of configuring and building JNI code for multiple platforms.
+
+While some attention is paid to performance, correctness and ease of use take priority.
+
+JNA includes a platform library with many native functions already mapped as well as a set of utility interfaces that simplify native access.
+
+Features
+========
+
+* Automatic mapping from Java to native functions, with simple mappings for all primitive data types
+* Runs on most platforms which support Java
+* Automatic conversion between C and Java strings, with customizable encoding/decoding
+* Structure and Union arguments/return values, by reference and by value
+* Function Pointers, (callbacks from native code to Java) as arguments and/or members of a struct
+* Auto-generated Java proxies for native function pointers
+* By-reference (pointer-to-type) arguments
+* Java array and NIO Buffer arguments (primitive types and pointers) as pointer-to-buffer
+* Nested structures and arrays
+* Wide (wchar_t-based) strings
+* Native long support (32- or 64-bit as appropriate)
+* Demo applications
+* Supported on 1.4 or later JVMs (earlier VMs may work with stubbed NIO support)
+* Customizable marshalling/unmarshalling (argument and return value conversions)
+* Customizable mapping from Java method to native function name, and customizable invocation to simulate C preprocessor function macros
+* Support for automatic Windows ASCII/UNICODE function mappings
+* Varargs support
+* Type-safety for native pointers
+* VM crash protection (optional)
+* Optimized direct mapping for high-performance applications.
+
+Community
+=========
+
+* TODO
+
+Using the Library
+=================
+
+* [Getting Started](jna/tree/master/www/GettingStarted.md)
+* [Mapping between Java and Native](jna/tree/master/www/Mappings.md)
+* [Using Pointers and Arrays](jna/tree/master/www/PointersAndArrays.md)
+* [Using Structures and Unions](jna/tree/master/www/StructuresAndUnions.md)
+* [Using By-Reference Arguments](jna/tree/master/www/ByRefArguments.md)
+* [Customization](jna/tree/master/www/Customization.md)
+* [Callbacks/Closures](jna/tree/master/www/Callbacks.md)
+* [JRuby/Jython Usage](jna/tree/master/www/JRubyJython.md)
+* [Frequently Asked Questions (FAQ)](jna/tree/master/www/FAQ.md)
+* [Direct Method Mapping](jna/tree/master/www/DirectMapping.md)
+
+Contributing
+============
+
+* TODO
+
+License
+=======
+
+This library is provided under the LGPL, version 2.1 or later.
+
+*NOTE: Oracle is not sponsoring this project, even though the package name (com.sun.jna) might imply otherwise.*
+
View
97 www/GettingStarted.md
@@ -0,0 +1,97 @@
+Getting Started with JNA
+========================
+
+Java Native Access (JNA) has a single component, `jna.jar`; the supporting native library (jnidispatch) is included in the jar file. JNA is capable of extracting and loading the native library on its own, so you don't need additional configuration. JNA falls back to extraction if the native library is not already installed on the local system somwhere accessible to `System.loadLibrary`. The native library is also available in platform-specific jar files for use with Java Web Start.
+
+Begin by downloading the latest release of JNA and referencing `jna.jar` in your project's `CLASSPATH`.
+
+The following example maps the printf function from the standard C library and calls it.
+
+ package com.sun.jna.examples;
+
+ import com.sun.jna.Library;
+ import com.sun.jna.Native;
+ import com.sun.jna.Platform;
+
+ /** Simple example of JNA interface mapping and usage. */
+ public class HelloWorld {
+
+ // This is the standard, stable way of mapping, which supports extensive
+ // customization and mapping of Java to native types.
+
+ public interface CLibrary extends Library {
+ CLibrary INSTANCE = (CLibrary)
+ Native.loadLibrary((Platform.isWindows() ? "msvcrt" : "c"),
+ CLibrary.class);
+
+ void printf(String format, Object... args);
+ }
+
+ public static void main(String[] args) {
+ CLibrary.INSTANCE.printf("Hello, World\n");
+ for (int i=0;i < args.length;i++) {
+ CLibrary.INSTANCE.printf("Argument %d: %s\n", i, args[i]);
+ }
+ }
+ }
+
+Identify a native target library that you want to use. This can be any shared library with exported functions. Many examples of mappings for common system libraries, especially on Windows, may be found in the platform package.
+
+Make your target library available to your Java program. There are two ways to do this:
+
+* The preferred method is to set the `jna.library.path` system property to the path to your target library. This property is similar to `java.library.path`, but only applies to libraries loaded by JNA.
+* Change the appropriate library access environment variable before launching the VM. This is `PATH` on Windows, `LD_LIBRARY_PATH` on Linux, and `DYLD_LIBRARY_PATH` on OSX.
+
+Declare a Java interface to hold the native library methods by extending the Library interface.
+
+Following is an example of mapping for the Windows kernel32 library.
+
+ package com.sun.jna.examples.win32;
+
+ import com.sun.jna.*;
+
+ // kernel32.dll uses the __stdcall calling convention (check the function
+ // declaration for "WINAPI" or "PASCAL"), so extend StdCallLibrary
+ // Most C libraries will just extend com.sun.jna.Library,
+ public interface Kernel32 extends StdCallLibrary {
+ // Method declarations, constant and structure definitions go here
+ }
+
+Within this interface, define an instance of the native library using the Native.loadLibrary(Class) method, providing the native library interface you defined previously.
+
+ Kernel32 INSTANCE = (Kernel32)
+ Native.loadLibrary("kernel32", Kernel32.class);
+ // Optional: wraps every call to the native library in a
+ // synchronized block, limiting native calls to one at a time
+ Kernel32 SYNC_INSTANCE = (Kernel32)
+ Native.synchronizedLibrary(INSTANCE);
+
+The `INSTANCE` variable is for convenient reuse of a single instance of the library. Alternatively, you can load the library into a local variable so that it will be available for garbage collection when it goes out of scope. A Map of options may be provided as the third argument to loadLibrary to customize the library behavior; some of these options are explained in more detail below. The `SYNC_INSTANCE` is also optional; use it if you need to ensure that your native library has only one call to it at a time.
+
+Declare methods that mirror the functions in the target library by defining Java methods with the same name and argument types as the native function (refer to the basic mappings below or the detailed table of type mappings). You may also need to declare native structures to pass to your native functions. To do this, create a class within the interface definition that extends Structure and add public fields (which may include arrays or nested structures).
+
+ public static class SYSTEMTIME extends Structure {
+ public short wYear;
+ public short wMonth;
+ public short wDayOfWeek;
+ public short wDay;
+ public short wHour;
+ public short wMinute;
+ public short wSecond;
+ public short wMilliseconds;
+ }
+
+ void GetSystemTime(SYSTEMTIME result);
+
+You can now invoke methods on the library instance just like any other Java class.
+
+ Kernel32 lib = Kernel32.INSTANCE;
+ SYSTEMTIME time = new SYSTEMTIME();
+ lib.GetSystemTime(time);
+
+ System.out.println("Today's integer value is " + time.wDay);
+
+Alternatively, you may declare a class to hold your native methods, declare any number of methods with the `native` qualifier, and invoke `Native.register(String)` in the class static initializer with your library's name. See [JNA Direct Mapping](DirectMapping.md) for an example.
+
+If the C header files for your library are available, you can auto-generate a library mapping by using Olivier Chafik's excellent [JNAerator](http://jnaerator.googlecode.com/) utility. This is especially useful if your library uses long or complicated structures where translating by hand can be error-prone.
+
View
20 www/Mappings.md
@@ -0,0 +1,20 @@
+Default Type Mappings
+=====================
+
+Java primitive types (and their object equivalents) map directly to the native C type of the same size.
+
+Native Type|Size|Java Type|Common Windows Types
+char|8-bit integer|byte|BYTE, TCHAR
+short|16-bit integer|short|WORD
+wchar_t|16/32-bit character|char|TCHAR
+int|32-bit integer|int|DWORD
+int|boolean value|boolean|BOOL
+long|32/64-bit integer|NativeLong|LONG
+long long|64-bit integer|long|__int64
+float|32-bit FP|float|
+double|64-bit FP|double|
+char*|C string|String|LPTCSTR
+void*|pointer|Pointer|LPVOID, HANDLE, LPXXX
+
+Unsigned types use the same mappings as signed types. C enums are usually interchangeable with "int".
+
View
16 www/PointersAndArrays.md
@@ -0,0 +1,16 @@
+Using Pointers and Arrays
+=========================
+
+Primitive array arguments (including structs) are represented by their corresponding Java types. For example:
+
+ // Original C declarations
+ void fill_buffer(int *buf, int len);
+ void fill_buffer(int buf[], int len); // same thing with array syntax
+
+ // Equivalent JNA mapping
+ void fill_buffer(int[] buf, int len);
+
+NOTE: If the parameter is to be used by the native function outside the scope of the function call, you must use Memory or an NIO Buffer. The memory provided by a Java primitive array will only be valid for use by the native code for the duration of the function call.
+
+Arrays of C strings (the `char* argv[]` to the C `main`, for example), may be represented by `String[]` in Java code. JNA will automatically pass an equivalent array with a `NULL` final element.
+
View
12 www/StructuresAndUnions.md
@@ -0,0 +1,12 @@
+Using Structures And Unions
+===========================
+
+When a function requires a pointer to a struct, a Java Structure should be used. If the struct is passed or returned by value, you need only make minor modifications to the parameter or return type class declaration.
+
+Typically you define a public static class derived from `Structure` within your library interface definition. This allows the structure to share any options (like custom type mapping) defined for the library interface.
+
+If a function requires an array of struct (allocated contiguously in memory), a Java `Structure[]` may be used. When passing in an array of `Structure`, it is not necessary to initialize the array elements (the function call will allocate, zero memory, and assign the elements for you). If you do need to initialize the array, you should use the `Structure.toArray` method to obtain an array of Structure elements contiguous in memory, which you can then initialize as needed.
+
+Unions are generally interchangeable with Structures, but require that you indicate which union field is active with the `setType` method before it can be properly passed to a function call.
+
+
View
792 www/index.html
@@ -1,792 +0,0 @@
-<html>
- <head>
- <link rel="stylesheet" type="text/css" href="style.css" />
- <meta name="keywords" content="java,jna,jni,c,c++,native,method,function,call,ctypes,ffi,foreign function interface,jdirect,jinvoke,pinvoke,platform invoke,native library access,native access,call native from java,java c library,easy jni,call c from java,avoid jni,jni alternative,jni replacement,legacy,call from java,replace jni">
- <meta name="description" content="Java Native Access (JNA): access native libraries with pure Java code.">
- <meta name="date" content="2010-07-16">
- <title>Java Native Access (JNA): Pure Java Access to Native Libraries</title>
- <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
-</head>
-<body>
- <h2>Java Native Access (JNA)</h2>
- <a name=top></a>
- <img src="images/jnalogo.jpg" align="right" style="margin-right: 20px">
- <ul>
- <li><a href="http://java.net/projects/jna/downloads/directory">Download</a>
- <li><a href="http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html">License (LGPLv2)</a>
- <li><a href="release-notes.html">Release Notes</a>
- <li><a href="http://java.net/projects/jna/sources/svn/show">Source Code</a>
- <li><a href="#features">Features</a>
- <li><a href="#demos">Demos</a>
- <li><a href="#platform">Platform Library</a></li>
- <li><a href="#community">Community and Support</a>
- <li><a href="#projects">Projects</a>
- <li><a href="#development">Development</a>&nbsp;&nbsp;&nbsp;
- <li><a href="#building">Building</a>
- <li><a href="#history">History</a>
- </ul>
- <h2>What is JNA?</h2>
- <p>JNA provides Java programs easy access to native shared libraries (DLLs on Windows) without writing anything but Java code&#8212;no JNI or native code is required. This functionality is comparable to Windows' Platform/Invoke and Python's ctypes. Access is dynamic at runtime without code generation.</p>
- <p>JNA allows you to call directly into native functions using natural Java method invocation. The Java call looks just like it does in native code. Most calls require no special handling or configuration; no boilerplate or generated code is required.</p>
- <p>The JNA library uses a small native library stub to dynamically invoke native code. The developer uses a Java interface to describe functions and structures in the target native library. This makes it quite easy to take advantage of native platform features without incurring the high overhead of configuring and building JNI code for multiple platforms.</p>
- <p>While some attention is paid to performance, correctness and ease of use take priority.</p>
- <p>JNA includes a platform library with many native functions already mapped as well as a set of utility interfaces that simplify native access.</p>
- <h2>Using the Library</h2>
- <ul>
- <li><a href="#getting_started">Getting&nbsp;Started</a>
- <li><a href="javadoc/overview-summary.html">API Documentation (JavaDoc)</a>
- <li><a href="#mapping">Mapping&nbsp;between&nbsp;Java&nbsp;and&nbsp;Native</a>
- <li><a href="#pointers">Using&nbsp;Pointers&nbsp;and&nbsp;Arrays</a>
- <li><a href="#structures">Using&nbsp;Structures&nbsp;and&nbsp;Unions</a>
- <li><a href="#byref">Using&nbsp;By-reference&nbsp;Arguments</a>
- <li><a href="#customize">Customization</a>
- <li><a href="#callbacks">Callbacks/Closures</a>
- <li><a href="#dynamic">JRuby/Jython&nbsp;Usage</a>
- <li><a href="#faq">Frequently&nbsp;Asked&nbsp;Questions&nbsp;(FAQ)</a>
- <li><a href="#direct">Direct method mapping</a>
- </ul>
-<hr>
-The <a href="http://jna.java.net/javadoc/overview-summary.html">JavaDoc is available online</a>,
-which includes detailed descriptions of JNA usage in different situations.<p>
-This library is provided under the <a href="http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html">LGPL</a>, version 2.1 or later.
-<p>
-<b>NOTE: Sun is <em>not</em> sponsoring this project, even though the package name (<code>com.sun.jna</code>) might imply otherwise.</b>
-<hr>
-<a href=#top>Top</a>
-<a name=features></a>
-<h3>Features</h3>
-<ul>
-<li>Automatic mapping from Java to native functions, with simple mappings for all primitive data types
-<li>Runs on <a href="#building">most platforms which support Java</a>
-<li>Automatic conversion between C and Java strings, with customizable encoding/decoding
-<li><a href="javadoc/com/sun/jna/Structure.html">Structure</a> and <a href="javadoc/com/sun/jna/Union.html">Union</a> arguments/return values, by reference and by value
-<li>Function Pointers, (callbacks from native code to Java) as arguments and/or members of a <code>struct</code>
-<li>Auto-generated Java proxies for native function pointers
-<li>By-reference (pointer-to-type) arguments
-<li>Java array and NIO <code>Buffer</code> arguments (primitive types and pointers) as pointer-to-buffer
-<li>Nested structures and arrays
-<li>Wide (<code>wchar_t</code>-based) strings
-<li><a href="javadoc/com/sun/jna/NativeLong.html">Native <code>long</code></a> support (32- or 64-bit as appropriate)
-<li><a href="#demos">Demo applications</a>
-<li>Supported on 1.4 or later JVMs (earlier VMs may work with stubbed NIO support)
-<li>Customizable marshalling/unmarshalling (argument and return value conversions)
-<li>Customizable mapping from Java method to native function name, and customizable invocation to simulate C preprocessor function macros
-<li>Support for automatic Windows ASCII/UNICODE function mappings
-<li>Varargs support
-<li><a href="javadoc/com/sun/jna/PointerType.html">Type-safety for native pointers</a>
-<li><a href="javadoc/com/sun/jna/Native.html#setProtected(boolean)">VM crash protection</a> (optional)
-<li>Optimized <a href='#direct'>direct mapping</a> for high-performance applications.
-</ul>
-<p>
-
-<a href=#top>Top</a>
-<a name=getting_started></a>
- <h3>How To Get Started Using JNA</h3>
- <p>Java Native Access (JNA) has a single component, <code>jna.jar</code>; the supporting native library (<code>jnidispatch</code>) is included in the jar file. JNA is capable of extracting and loading the native library on its own, so you don't need additional configuration. JNA falls back to extraction if the native library is not already installed on the local system somewhere accessible to <code>System.loadLibrary</code> (see <a href="javadoc/com/sun/jna/Native.html#library_loading">information on library loading</a>). The native library is also available in platform-specific jar files for use with Java Web Start.</p>
-<ol>
- <li>Download <code>jna.jar</code> from the <a href="http://jna.java.net/projects/jna/downloads">download page</a>.</li>
- <li>Compile and run this short example, which maps the <code>printf</code> function from the standard C library and calls it. Be sure to include jna.jar in the classpath:<br>
-<blockquote><pre><code>
-package com.sun.jna.examples;
-
-import com.sun.jna.Library;
-import com.sun.jna.Native;
-import com.sun.jna.Platform;
-
-/** Simple example of JNA interface mapping and usage. */
-public class HelloWorld {
-
- // This is the standard, stable way of mapping, which supports extensive
- // customization and mapping of Java to native types.
- public interface CLibrary extends Library {
- CLibrary INSTANCE = (CLibrary)
- Native.loadLibrary((Platform.isWindows() ? "msvcrt" : "c"),
- CLibrary.class);
-
- void printf(String format, Object... args);
- }
-
- public static void main(String[] args) {
- CLibrary.INSTANCE.printf("Hello, World\n");
- for (int i=0;i < args.length;i++) {
- CLibrary.INSTANCE.printf("Argument %d: %s\n", i, args[i]);
- }
- }
-}
-</code></pre></blockquote>
- <li>Identify a native <em>target library</em> that you want to use. This can be any shared library with exported functions. Many examples of mappings for common system libraries may be found in the <a href="#platform">platform</a> package.</li>
- <li>Make your target library available to your Java program. There are two ways to do this:
- <ul>
- <li>The preferred method is to set the <code>jna.library.path</code> system property to the path to your target library. This property is similar to <code>java.library.path</code> but only applies to libraries loaded by JNA.</li>
- <li>Change the appropriate library access environment variable before launching the VM. This is PATH on Windows, LD_LIBRARY_PATH on Linux, and DYLD_LIBRARY_PATH on OSX.</li>
- </ul>
- </li>
- <li>Declare a Java interface to hold the native library methods by extending
- the <a href="javadoc/com/sun/jna/Library.html"><code>Library</code></a>
- interface.<p>
-Following is an example of mapping for the Windows kernel32 library.<br>
- <blockquote><pre><code>
-package com.sun.jna.examples.win32;
-
-import com.sun.jna.*;
-
-// kernel32.dll uses the __stdcall calling convention (check the function
-// declaration for "WINAPI" or "PASCAL"), so extend StdCallLibrary
-// Most C libraries will just extend com.sun.jna.Library,
-public interface Kernel32 extends StdCallLibrary {
- // Method declarations, constant and structure definitions go here
-}</code></pre></blockquote>
- </li>
- <li>Within this interface, define an instance of the native library using the <code>Native.loadLibrary(Class)</code> method, providing the native library interface you defined in step (5).<br>
- <blockquote><pre><code>
- Kernel32 INSTANCE = (Kernel32)
- Native.loadLibrary("kernel32", Kernel32.class);
- // Optional: wraps every call to the native library in a
- // synchronized block, limiting native calls to one at a time
- Kernel32 SYNC_INSTANCE = (Kernel32)
- Native.synchronizedLibrary(INSTANCE);
-</code></pre></blockquote><br>
-The INSTANCE variable is for convenient reuse of a single instance of the library. Alternatively, you can load the library into a local variable so that it will be available for garbage collection when it goes out of scope. A <code>Map</code> of options may be provided as the third argument to <code>loadLibrary</code> to customize the library behavior; some of these options are explained in more detail below. The SYNC_INSTANCE is also optional; use it if you need to ensure that your native library has only one call to it at a time.
- </li>
- <li>Declare methods that mirror the functions in the target library by defining Java methods with the same name and argument types as the native function (refer to the <a href="#mapping">basic mappings</a> below or <a href="javadoc/overview-summary.html#marshalling">the detailed table of type mappings</a>). You may also need to declare native structures to pass to your native functions. To do this, create a class within the interface definition that extends <a href="javadoc/com/sun/jna/Structure.html"><code>Structure</code></a> and add public fields (which may include arrays or nested structures).
- <br>
- <blockquote><pre><code>
-public static class SYSTEMTIME extends Structure {
- public short wYear;
- public short wMonth;
- public short wDayOfWeek;
- public short wDay;
- public short wHour;
- public short wMinute;
- public short wSecond;
- public short wMilliseconds;
-}
-
-void GetSystemTime(SYSTEMTIME result);
- </code></pre></blockquote>
- </li>
- <li>You can now invoke methods on the library instance just like any other Java class.
- For a more extensive example, see the <a href="http://java.net/projects/jna/sources/svn/content/trunk/jnalib/contrib/platform/src/com/sun/jna/platform/WindowUtils.java">WindowUtils</a>
- and <a href="http://java.net/projects/jna/sources/svn/content/trunk/jnalib/contrib/shapedwindowdemo/com/sun/jna/contrib/demo/ShapedWindowDemo.java">ShapedWindowDemo</a> classes.
- <br>
- <blockquote><pre><code>
-Kernel32 lib = Kernel32.INSTANCE;
-SYSTEMTIME time = new SYSTEMTIME();
-lib.GetSystemTime(time);
-System.out.println("Today's integer value is " + time.wDay);
-</code></pre></blockquote>
- </li>
-<li>Alternatively, you may declare a class to hold your native
- methods, declare any number of methods with the "native" qualifier,
- and invoke <code>Native.register(String)</code> in the class static
- initializer with your library's name. See <a href='#direct'>JNA direct
- mapping</a> for an example.<p>
-</li>
-</ol>
-If the C header files for your library are available, you can auto-generate a
-library mapping by using Olivier Chafik's
-excellent <a href="http://jnaerator.googlecode.com/">JNAerator</a> utility.
-This is especially useful if your library uses long or complicated structures
-where translating by hand can be error-prone.
-<p>
-See the <a href="javadoc/overview-summary.html#overview">JavaDoc overview</a> for more detailed information about JNA usage.<p>
-
-
-<a href=#top>Top</a>
-<a name=mapping></a>
-<h3>Default Type Mappings</h3>
-Java primitive types (and their object equivalents) map directly to the native C type of the same size.
-<blockquote><table cols=4>
-<thead><td>Native Type</td><td>Size</td><td>Java Type</td><td>Common Windows Types</td></thead>
-<tr><td>char</td><td>8-bit integer</td><td>byte</td><td>BYTE, TCHAR</td>
-<tr><td>short</td><td>16-bit integer</td><td>short</td><td>WORD</td>
-<tr><td>wchar_t</td><td>16/32-bit character</td><td>char</td><td>TCHAR</td>
-<tr><td>int</td><td>32-bit integer</td><td>int</td><td>DWORD</td>
-<tr><td>int</td><td>boolean value</td><td>boolean</td><td>BOOL</td>
-<tr><td>long</td><td>32/64-bit integer</td><td>NativeLong</td><td>LONG</td>
-<tr><td>long long</td><td>64-bit integer</td><td>long</td><td>__int64</td>
-<tr><td>float</td><td>32-bit FP</td><td>float</td><td></td>
-<tr><td>double</td><td>64-bit FP</td><td>double</td><td></td>
-<tr><td>char*</td><td>C string</td><td>String</td><td>LPTCSTR</td>
-<tr><td>void*</td><td>pointer</td><td>Pointer</td><td>LPVOID, HANDLE, LP<i>XXX</i></td>
-</table></blockquote>
-Unsigned types use the same mappings as signed types. C enums are usually
-interchangeable with "int". A more comprehensive list of mappings may be
-found <a href="javadoc/overview-summary.html#marshalling">here</a>.
-<p>
-
-<a href=#top>Top</a>
-<a name=pointers></a>
-<h3>Using Pointers and Arrays</h3>
-Primitive array arguments (including <code>struct</code>s) are represented by their corresponding Java types. For example:
-<blockquote>
- <blockquote><pre><code>
-// Original C declarations
-void fill_buffer(int *buf, int len);
-void fill_buffer(int buf[], int len); // same thing with array syntax
-
-// Equivalent JNA mapping
-void fill_buffer(int[] buf, int len);
-</code></pre></blockquote>
-</blockquote>
-<p>
-NOTE: if the parameter is to be used by the native function outside the
-scope of the function call, you <em>must</em> use <code>Memory</code> or an
-NIO Buffer. The memory provided by a Java primitive array will only be valid
-for use by the native code for the duration of the function call.
-<p>
-Arrays of C strings (the <code>char* argv[]</code> to the C <code>main</code>,
-for example), may be represented by <code>String[]</code> in Java code. JNA
-will pass an equivalent array with a NULL final element.
-<p>
-
-<a href=#top>Top</a>
-<a name=structures></a>
-<h3>Using Structures/Unions</h3>
-When a function requires a pointer to a <code>struct</code>, a Java <a href="javadoc/com/sun/jna/Structure.html">Structure</a> should be used. If the <code>struct</code> is passed or returned by value, you need only make <a href="javadoc/overview-summary.html#byvalue">minor modifications</a> to the parameter or return type class declaration.<p>
-Typically you define a <code>public static</code> class derived from <code>Structure</code> within your library interface definition. This allows the structure to share any options (like custom type mapping) defined for the library interface.
-<p>
-If a function requires an array of <code>struct</code> (allocated contiguously in memory), a Java <code>Structure[]</code> may be used. When passing in an array of <code>Structure</code>, it is not necessary to initialize the array elements (the function call will allocate, zero memory, and assign the elements for you). If you <em>do</em> need to initialize the array, you should use the <code>Structure.toArray</code> method to obtain an array of <code>Structure</code> elements contiguous in memory, which you can then initialize as needed.
-<p>
-Unions are generally interchangeable with <code>Structure</code>s, but require that you indicate which union field is active with the <code>setType</code> method before it can be properly passed to a function call.
-<p>
-
-<a href=#top>Top</a>
-<a name=byref></a>
-<h3>Using By-reference Arguments</h3>
-When a function accepts a pointer-to-type argument you can use one of the <a href="javadoc/com/sun/jna/ptr/ByReference.html"><code>ByReference</code></a> types to capture the returned value, or subclass your own. For example:<br>
-<blockquote>
- <blockquote><pre><code>
-// Original C declaration
-void allocate_buffer(char **bufp, int* lenp);
-
-// Equivalent JNA mapping
-void allocate_buffer(PointerByReference bufp, IntByReference lenp);
-
-// Usage
-PointerByReference pref = new PointerByReference();
-IntByReference iref = new IntByReference();
-lib.allocate_buffer(pref, iref);
-Pointer p = pref.getValue();
-byte[] buffer = p.getByteArray(0, iref.getValue());
- </code></pre></blockquote>
-</blockquote>
-
-Alternatively, you could use a Java array with a single element of the desired type, but the <code>ByReference</code> convention better conveys the intent of the code.<p>
-
-The <a href="javadoc/com/sun/jna/Pointer.html"><code>Pointer</code></a> class provides a number of accessor methods in addition to <a href="javadoc/com/sun/jna/Pointer.html#getByteArray"><code>getByteArray()</code></a> which effectively function as a typecast onto the memory.
-<p>
-Type-safe pointers may be declared by deriving from the <a href="javadoc/com/sun/jna/PointerType.html"><code>PointerType</code></a> class.
-<p>
-
-<a href=#top>Top</a>
-<a name=customize></a>
-<h3>Customized Mapping from Java to Native (Types and Function Names)</h3>
-The <a href="javadoc/com/sun/jna/TypeMapper.html">TypeMapper</a> class and related interfaces provide for converting any Java type used as an argument, return value, or structure member to be converted to or from a native type. The example w32 API interfaces use a type mapper to convert Java boolean into the w32 <code>BOOL</code> type. A <code>TypeMapper</code> instance is passed as the value for the <a href="javadoc/com/sun/jna/Library#OPTION_TYPE_MAPPER">TYPE_MAPPER</a> key in the options map passed to <code>Native.loadLibrary</code>.
-<p>
-Alternatively, user-defined types may implement the <a href="javadoc/com/sun/jna/win32/NativeMapped.html">NativeMapped</a> interface, which determines conversion to and from native types on a class-by-class basis.
-<p>
-<a name=stdcallmapper></a>
-You may also customize the mapping of Java method names to the corresponding native function name. The <a href="javadoc/com/sun/jna/win32/StdCallFunctionMapper.html">StdCallFunctionMapper</a> is one implementation which automatically generates <code>stdcall</code>-decorated function names from a Java interface method signature. The mapper should be passed as the value for the <a href="javadoc/com/sun/jna/Library#OPTION_FUNCTION_MAPPER">OPTION_FUNCTION_MAPPER</a> key in the options map passed to the <code>Native.loadLibrary</code> call.
-<p>
-Refer to <a href="javadoc/overview-summary.html#marshalling">this table in the
-overview</a> for a complete list of built-in type mappings.
-<p>
-
-<a href=#top>Top</a>
-<a name=callbacks></a>
-<h3>Callbacks/Closures (Function Pointers)</h3>
-Callback declarations consist of a simple interface that extends the <a href="javadoc/com/sun/jna/Callback.html">Callback</a>
-interface and implements a <code>callback</code> method (or defines a single
-method of arbitrary name). Callbacks are
-implemented by wrapping a Java object method in a little bit of C glue code.
-The simplest usage resembles using anonymous inner classes to register event
-listeners. Following is an example of callback usage:<br>
-<blockquote>
- <blockquote><pre><code>
-// Original C declarations
-typedef void (*sig_t)(int);
-sig_t signal(sig_t);
-
-// Equivalent JNA mappings
-public interface CLibrary extends Library {
- int SIGUSR1 = 30;
- interface sig_t extends Callback {
- void invoke(int signal);
- }
- sig_t signal(int sig, sig_t fn);
- int raise(int sig);
-}
-...
-CLibrary lib = (CLibrary)Native.loadLibrary("c", CLibrary.class);
-// WARNING: you must keep a reference to the callback object
-// until you deregister the callback; if the callback object
-// is garbage-collected, the native callback invocation will
-// probably crash.
-CLibrary.sig_t fn = new CLibrary.sig_t() {
- public void invoke(int sig) {
- System.out.println("signal " + sig + " was raised");
- }
-};
-CLibrary.sig_t old_handler = lib.signal(CLibrary.SIGUSR1, fn);
-lib.raise(CLibrary.SIGUSR1);
-...
-</code></pre></blockquote>
-</blockquote>
-
-Here is a more involved example, using the w32 APIs to enumerate all native windows:
-<blockquote>
- <blockquote><pre><code>
-// Original C declarations
-typedef int (__stdcall *WNDENUMPROC)(void*,void*);
-int __stdcall EnumWindows(WNDENUMPROC,void*);
-
-// Equivalent JNA mappings
-public interface User32 extends StdCallLibrary {
- interface WNDENUMPROC extends StdCallCallback {
- /** Return whether to continue enumeration. */
- boolean callback(Pointer hWnd, Pointer arg);
- }
- boolean EnumWindows(WNDENUMPROC lpEnumFunc, Pointer arg);
-}
-...
-User32 user32 = User32.INSTANCE;
-
-user32.EnumWindows(new WNDENUMPROC() {
- int count;
- public boolean callback(Pointer hWnd, Pointer userData) {
- System.out.println("Found window " + hWnd + ", total " + ++count);
- return true;
- }
-}, null);
-</code></pre></blockquote>
-</blockquote>
-If your callback needs to live beyond the method invocation where it is used, make sure you keep a reference to it or the native code will call back to an empty stub after the callback object is garbage collected.<p>
-
-Proxy wrappers are automatically generated for function pointers found within structs initialized by native code. This facilitates calling those functions from Java.<p>
-
-<a href=#top>Top</a>
-<a name=dynamic></a>
-<h3>Invocation from Dynamically-Typed Languages</h3>
-Languages such as <a href=http://www.jython.org>Jython</a> or <a href=http://jruby.sf.net>JRuby</a> may find it more convenient to access the NativeLibrary and Function classes directly rather than establishing a dedicated interface.<p>
-Here's a brief example of using JNA from JRuby:
-<blockquote>
- <blockquote><pre><code>
-require 'java'
-
-module Libc
- @@lib = com.sun.jna.NativeLibrary.getInstance("c")
- @@ptr_funcs = [ 'fopen', 'malloc', 'calloc' ]
- def self.method_missing(meth, *args)
- if @@ptr_funcs.include?(meth.to_s)
- @@lib.getFunction(meth.to_s).invokePointer(args.to_java)
- else
- @@lib.getFunction(meth.to_s).invokeInt(args.to_java)
- end
- end
- O_RDONLY = 0
- O_WRONLY = 1
- O_RDWR = 2
-end
-
-Libc.puts("puts from libc")
-Libc.printf("Hello %s, from printf\n", "World")
-
-file = Libc.open("/dev/stdout", 1, Libc::O_WRONLY)
-n = Libc.write(file, "Test\n", 5)
-puts "Wrote #{n} bytes via Libc"
-
-path = "/dev/stdout"
-fp = Libc.fopen(path, "w+")
-Libc.fprintf(fp, "fprintf to %s via stdio\n", path)
-Libc.fflush(fp)
-Libc.fclose(fp)
-</code></pre></blockquote></blockquote>
-<p>
-<a href=#top>Top</a>
-<a name=platform></a>
-<h3>Platform Library</h3>
-<p>
-JNA includes <code>platform.jar</code> that has cross-platform mappings and mappings for a number of
-commonly used platform functions, including a large number of Win32 mappings as well as a set of utility
-classes that simplify native access. The code is tested and the utility interfaces ensure that
-native memory management is taken care of correctly.
-</p>
-<p>
-Before you map your own functions, check the
-<a href="javadoc/platform/overview-summary.html">platform package documentation</a> for an already mapped one.
-</p>
-<p>
-Platform-specific structures are mapped by header. For example, <code>ShlObj.h</code> structures can
-be found in <code>com.sun.jna.platform.win32.ShlObj</code>. Platform functions are mapped by
-library. For example, <code>Advapi32.dll</code> functions can be found in <code>com.sun.jna.platform.win32.Advapi32</code>.
-Simplified interfaces (wrappers) for <code>Advapi32.dll</code> functions can be found in
-<code>com.sun.jna.platform.win32.Advapi32Util</code>.
-</p>
-<p>
-Cross-platform functions and structures are implemented in <code>com.sun.jna.platform</code>. These
-currently include the following.
-<ul>
- <li><code>FileMonitor</code>: a cross-platform file system watcher</li>
- <li><code>FileUtils</code>: a cross-platform set of file-related functions, such as move to the recycle bin</li>
- <li><code>KeyboardUtils</code>: a cross-platform set of keyboard functions, such as finding out whether a key is pressed</li>
- <li><code>WindowUtils</code>: a cross-platform set of window functions, providing non-rectangular shaped and transparent windows</li>
-</ul>
-</p>
-<a href=#top>Top</a>
-<a name=faq></a>
-<h3>Frequently Asked Questions (FAQ)</h3>
-<ul>
-<li><a href="#structure_use">Should I use Structure.ByReference, Structure.ByValue, or Structure[]?</a>
-<li><a href="#char_buffer">How do I read back a string?</a>
-<li><a href="#native_long">How do I map a native <code>long</code> type?</a>
-<li><a href="#w32link">My library mapping causes an UnsatisfiedLinkError</a>
-<li><a href="#crash">My library sometimes causes a VM crash</a>
-<li><a href="#w32crash">My Windows library mapping causes a VM crash on every call</a>
-<li><a href="#ptr_values">How do I get an arbitrary Pointer value?</a>
-<li><a href="#struct_debug">My structure has the wrong contents. What did I do wrong?</a>
-<li><a href="#j2me">Does JNA work with J2ME/Windows Mobile?</a>
-<li><a href="#performance">How does JNA performance compared to custom JNI?</a>
-<li><a href="#osx">I get an UnsatisfiedLinkError on OSX trying to include my custom library via Java Web Start</a>
-<li><a href="#COM">I need to use a COM/OCX/ActiveX object. Can JNA help me?</a>
-<li><a href="#shutdown">I'm using a shutdown hook on Windows to make some native calls (with direct mapping). Why does the calls sometimes fail?</a>
-</ul>
-<a name=structure_use></a>
-<h4>When should I use Structure.ByReference? Structure.ByValue? Structure[]?</h4>
-Find your corresponding native declaration below:
-<blockquote><pre><code>
-typedef struct _simplestruct {
- int myfield;
-} simplestruct;
-
-typedef struct _outerstruct {
- simplestruct nested; // use Structure
-} outerstruct;
-
-typedef struct _outerstruct2 {
- simplestruct *byref; // use Structure.ByReference
-} outerstruct2;
-
-typedef struct _outerstruct3 {
- simplestruct array[4]; // use Structure[]
-} outerstruct3;
-
-typedef struct _outerstruct4 {
- simplestruct* ptr_array[4]; // use Structure.ByReference[]
-} outerstruct4;
-
-// Field is a pointer to an array of struct
-typedef struct _outerstruct5 {
- simplestruct* ptr_to_array; // use Structure.ByReference, and use
- // Structure.toArray() to allocate array
-} outerstruct5;
-
-// struct pointers as return value or argument
-// use Structure
-outerstruct *myfunc();
-void myfunc(outerstruct* data);
-
-// struct (by value) as return value or argument
-// use Structure.ByValue
-simplestruct myfunc();
-void myfunc(simplestruct);
-</code></pre></blockquote>
-
-If you need a ByValue or ByReference class, define them within your main Structure definition like this:
-<blockquote><pre><code>
-public class MyStructure extends Structure {
- public static class ByValue extends MyStructure implements Structure.ByValue { }
- public static class ByReference extends MyStructure implements Structure.ByReference { }
-}
-</code></pre></blockquote>
-
-<a name=char_buffer></a>
-<h4>How do I read back a function's string result?</h4>
-Suppose you have a function:<br>
-<blockquote><pre><code>
-// Returns the number of characters written to the buffer
-int getString(char* buffer, int bufsize);
-</code></pre></blockquote>
-The native code is expecting a fixed-size buffer, which it will fill in with the requested data. A Java <code>String</code> is not appropriate here, since <code>String</code>s are immutable. Nor is a Java <code>StringBuffer</code>, since the native code only fills the buffer and does not change its size. The appropriate argument type would be either <code>byte[]</code>, <code>Memory</code>, or an NIO <code>Buffer</code>, with the size of the object passed as the second argument. The method <a href="javadoc/com/sun/jna/Native#toString(byte[])">Native.toString(byte[])</a> may then be used to convert the array of byte into a Java <code>String</code>.
-
-<a name=native_long></a>
-<h4>How do I map a native <code>long</code> type?</h4>
-Actually, no one ever asks this question, but they <em>really</em> need the answer. <font color='red'><em>Do not</em> use Java <code>long</code>!</font><p>
-
-On Windows, you can use a Java <code>int</code>, since the native <code>long</code> type is always 32 bits. On any other platform, the type may be 32 or 64 bits, so you should use the <a href="javadoc/com/sun/jna/NativeLong.html">NativeLong</a> type to ensure the proper size is used.
-
-
-<a name=w32link></a>
-<h4>My library mapping causes an UnsatisfiedLinkError</h4>
-Use a dump utility to examine the names of your exported functions to make sure they match (<a href="http://linux.die.net/man/1/nm">nm</a> on linux, <a href="http://www.dependencywalker.com">depends</a> on Windows). On Windows, if the functions have a suffix of the form "@NN", you need to pass a StdCallFunctionMapper as an option when initializing your library interface (<a href="#stdcallmapper">see here</a>). In general, you can use a function mapper (<a href="javadoc/com/sun/jna/FunctionMapper.html">FunctionMapper</a>) to change the name of the looked-up method, or an invocation mapper (<a href="javadoc/com/sun/jna/InvocationMapper.html">InvocationMapper</a>) for more extensive control over the method invocation.
-
-<a name=crash></a>
-<h4>My library sometimes causes a VM crash</h4>
-Double check the signature of the method causing the crash to ensure all arguments are of the appropriate size and type. Be especially careful with native pointer variations. See also <a href="#struct_debug">information on debugging structure definitions</a>.
-
-<a name=w32crash></a>
-<h4>My Windows library mapping causes a VM crash on every call</h4>
-If your library uses the <code>stdcall</code> calling convention, your interface should extend the <code>StdCallLibrary</code> interface. Using the wrong calling convention for a library will usually cause a VM crash.<p>
-
-<a name=ptr_values></a>
-<h4>How do I get an arbitrary Pointer value?</h4>
-First, you probably don't actually want an <em>arbitrary</em> value. Ask yourself what you're really trying to do. Remember, type safety is your friend.
-<ul>
-<li>Pointer.createConstant() should be used when you need a special value that is not really a pointer (NULL usually serves this purpose, but some C programmers like to check pointers for special integer values instead). The Pointer produced by this function can't actually be used to access memory.
-<li>Pointer.share() can be used to generate a new Pointer as an offset from an existing one
-<li>java.nio.Buffer can be used to wrap a Java array with a different offset and length than the original.
-<li>Clean up the sloppy C code by declaring an appropriate function interface. If your function in C takes either a Pointer or an integer type, simply declare both method signatures in your JNA interface. They will both invoke the same function, but you get the added benefit of type checking on the arguments.
-</ul>
-If you <em>really</em>, <em>really</em>, <em>HAVE</em> to convert an integer
-value into a Pointer, you can do something like this:<br>
-<code>new IntByReference(value).getPointer().getPointer(0)</code>
-
-<a name=struct_debug></a>
-<h4>Debugging Structure Definitions</h4>
-Normally when you invoke <code>toString</code> on a <code>Structure</code>, it will print each defined field with its calculated memory offset. If when launching the VM, you pass it "-Djna.dump_memory=true", <code>toString</code> will also dump the contents of the corresponding native memory. This is useful to determine if you've added or omitted a field, or chosen an incorrect size. Viewing the memory as bytes usually makes it clear where field boundaries should be, assuming the memory has been initialized by native code.
-
-<a name=j2me></a>
-<h4>Does JNA work with J2ME/Windows Mobile?</h4>
-There is an <a href="http://java.net/jira/browse/JNA-108">implementation</a> available, but it has not yet been integrated into the standard build.<p>
-
-<a name=COM></a>
-<h4>I need to use a COM/OCX/ActiveX object. Can JNA do that?</h4>
-Not really. Try <a href="http://sourceforge.net/projects/jacob-project/develop">JACOB</a> or <a href="http://com4j.dev.java.net/">com4j</a>, both of which
-can parse a COM interface definition and generate a Java object to match it.
-
-<a name=shutdown></a>
-<h4>Why does the VM sometimes crash in my shutdown hook on Windows?</h4>
-If you are using direct mapping, make sure you keep a reference to the JNA
-class com.sun.jna.Native until your shutdown hook completes. If you are using
-interface mapping, your library proxy will be keeping a reference internally,
-so an explicit reference is not required.
-<p>
-If JNA unpacks its native code from its own jar file, it saves it in a
-temporary location and attempts to remove it when the Native class is
-finalized (which may or may not happen as the VM exits). In order to
-do so, it must first unload its native library from memory.
-<p>
-Alternatively, if the jnidispatch.dll native library
-is found in the system library load path, JNA will not attempt to unload it,
-although your shutdown hook must still ensure that the JNA classes you wish to
-use have not been GC'd.
-
-<a name=osx></a>
-<h4>I get an UnsatisfiedLinkError on OSX when I provide my native library via Java Web Start</h4>
-Libraries loaded via the JNLP class loader on OSX must be named with a .jnilib
-suffix. The class loader won't find resources included with
-the <code>&lt;nativelib&gt;</code> tag if they have a .dylib suffix.<p>
-
-<a name=performance></a>
-<h4>How does JNA performance compare to custom JNI?</h4>
-<p>
-<a href='#direct'>JNA direct mapping</a> can provide performance near that
-of custom JNI. Nearly all the type mapping features of interface mapping are
-available, although automatic type conversion will likely incur some overhead.
-<p>
-The calling overhead for a single native call using JNA interface mapping can
-be an order of magnitude (~10X) greater time than equivalent custom JNI
-(whether it actually does in the context of your application is a different
-question). In raw terms, the calling overhead is on the order of hundreds of
-microseconds instead of tens of microseconds. Note that that's the <em>call
-overhead</em>, <b>not</b> the <em>total call time</em>.
-This magnitude is typical of the difference between systems using
-dynamically-maintained type information and systems where type information is
-statically compiled. JNI hard-codes type information in the method
-invocation, where JNA interface mapping dynamically determines type
-information at runtime.
-<p>
-You might expect a speedup of about an order of magnitude moving to JNA direct
-mapping, and a factor of two or three moving from there to custom JNI.
-The actual difference will vary depending on usage and function
-signatures. As with any optimization process, you should determine
-first <em>where</em> you need a speed increase, and then see how much
-difference there is by performing targeted optimizations. The ease of
-programming everything in Java usually outweighs small performance gains when
-using custom JNI.
-<p>
-See the JavaDoc for
-<a href="javadoc/com/sun/jna/overview-summary.html#performance">performance
-tips</a> related to different types of type mapping.
-<p>
-<a href=#top>Top</a>
-<a name=direct></a>
-<h3>JNA Direct Mapping</h3>
-JNA supports a direct mapping method which can improve performance
-substantially, approaching that of custom JNI. Method signatures are the same
-as they would be in a JNA interface mapping, but they can be any static or
-object methods. You only need register them within the static initializer of
-the defining class, as in the example below.
-The <code>Native.register()</code> method takes the name of your native
-library, the same as <code>Native.loadLibrary()</code> would.<p>
-
-<blockquote><pre><code>
-import com.sun.jna.*;
-
-/** Simple example of JNA direct mapping.
- */
-public class HelloWorld {
-
- static {
- Native.register(Platform.isWindows() ? "msvcrt" : "m");
- }
-
- public static native double cos(double);
- public static native double sin(double);
-
- public static void main(String[] args) {
- System.out.println("cos(0)=" + cos(0));
- System.out.println("sin(0)=" + sin(0));
- }
-}
-</code></pre></blockquote>
-<p>
-As of version 3.2.0, direct mapping supports the same type mappings as
-interface mapping, except for arrays of Pointer/String/WString/NativeMapped as
-function arguments. You can easily convert from
-interface mapping to direct mapping by creating a direct mapping class which
-implements your library interface, with all methods defined as native methods.
-Then your library instance variable can be assigned an instance of this new
-class instead of the object returned by <code>Native.loadLibrary()</code>.<p>
-
-<a href=#top>Top</a>
-<a name=demos></a>
-<h3>Examples</h3>
-<p>
-There're several good examples for using the JNA library In the <code>jnacontrib</code> distribution folder.
-These are pretty nifty utilities in and of themselves as well.
-</p>
-<p>
-You can see some live demos here.
-<ul>
-<li><a href="demo/BalloonManagerDemo.jnlp">Demo</a> |
-<a href="http://java.net/projects/jna/sources/svn/content/trunk/jnalib/contrib/balloonmanagerdemo/com/sun/jna/contrib/demo/BalloonManagerDemo.java">BaloonManagerDemo.java Source</a>
-: Speech-balloon windows (a la Google Maps)
-</li>
-<li><a href="demo/ShapedWindowDemo.jnlp">Demo</a> |
-<a href="http://java.net/projects/jna/sources/svn/content/trunk/jnalib/contrib/shapedwindowdemo/com/sun/jna/contrib/demo/ShapedWindowDemo.java">ShapedWindowDemo.java Source</a>
-: Non-rectangular windows (a circular clock)
-</li>
-</ul>
-</p>
-<p>
-<a href=#top>Top</a>
-<a name=community></a>
- <h3>Community</h3>
- <ul>
- <li><a href="http://java.net/jira/browse/JNA">Issues Bugs (JIRA)</a>
- <li><a href="http://java.net/projects/jna/lists/users/archive">Mailing List (Users)</a>
- <li><a href="http://java.net/projects/jna/sources/svn/show">Source Code (Subversion)</a>
- </ul>
- <p>Please use the <a href="mailto:users@jna.java.net">mailing list</a> to ask for help, suggest ideas, etc.
- Report bugs in <a href="http://java.net/jira/browse/JNA">JIRA</a>.
- When asking about how to do a library mapping, be sure to include C API definitions and example usage, as well as whatever Java mapping you've already tried.</p>
- <ul>
- <li><a href="http://java.net/projects/jna/lists/users/archive">Usage Questions and Discussion</a>
- <li><a href="http://java.net/projects/jna/lists/dev/archive">Development Discussion</a>
- </ul>
-<p>
-You're encouraged to contribute to JNA. Get the source code from <a href="http://java.net/projects/jna/sources/svn/show">Subversion</a> and upload patches to <a href="http://java.net/jira/browse/JNA">JIRA</a>. To check-out source code from subversion use the <code>https://svn.java.net/svn/jna~svn/trunk</code> url.
-<p>
-If you are interested in paid support, feel free to say so on one of the JNA mailing lists. Most simple questions will be answered on the list, but more complicated work, new features or target platforms can be negotiated with any of the JNA developers (this is how several of JNA's features came into being). You may even encounter other users with the same need and be able to cost share the new development.
-<p>
-
-<a href=#top>Top</a>
-<a name=projects></a>
- <h3>Projects Using JNA</h3>
- <p>
- JNA is a mature and stable library with dozens of contributors and hundreds of commercial and non-commercial projects that use it.
- The list of the companies would be too long to mention here.
- </p>
-<p>
-<a href=#top>Top</a>
-<a name=development></a>
- <h3>Development Tasks</h3>
- <p>The library works fairly well now, but there are a number of tasks with which we'd appreciate help:</p>
- <ul>
- <li>Build the <code>jnidispatch</code> library backend on new platforms (it should mostly work out of the box if we can just get access to the appropriate build platform).</li>
- <li>More comprehensive documentation on using JNA, including examples of Java to native conversions of data types, function usage, and proper memory management.</li>
- <li>Tips and recommended usage of JNA: Likely danger areas, failure modes, best practices, multithreading, etc.</li>
- <li>Native library definitions in <code>platform.jar</code> for the more useful libraries on various platforms and native utility interfaces; for example, <code>User32.dll</code> on Windows.
- This is important for both having an exhaustive library definition and to illustrate all the different ways a native library may need to be mapped.</li>
- <li>Testing on various JDK versions and platforms (linux flavors!).</li>
- <li>See the TODO file in the project directory for more up-to-date items.</li>
- </ul>
-<p>
-
-<a href=#top>Top</a>
-<a name=building></a>
-<h3>Building and Multi-platform support</h3>
-Check out source code from <code>https://svn.java.net/svn/jna~svn/trunk</code>.
-<p>
-JNA has been built and tested on OSX (ppc, x86, x86_64), linux (x86, amd64),
-FreeBSD/OpenBSD (x86, amd64), Solaris (x86, amd64, sparc, sparcv9) and Windows
-(x86, amd64). It has also been built for windows/mobile and Linux/ppc64,
-although those platforms are not included in the distribution. The ant build
-script's test target will build and run the test suite, which has decent
-coverage and is a quick way to determine if your environment is set up
-correctly.
-<p>
-If you want to do a build yourself, you'll need <a
-href="http://ant.apache.org">ANT</a>, <a
-href="http://directory.fsf.org/make.html">GNU make</a> and <a
-href="http://gcc.gnu.org">GCC</a>. On windows, you will need either <a
-href="http://www.cygwin.com">cygwin GCC (3.4.4)</a> (the build is not yet
-configured properly to use GCC 4) or the MINGW32 version
-(MSVC is used to build the win64 target, so you could probably use it for
-win32 as well, but I doubt it's worth the effort). To
-rebuild <code>jna.jar</code>, and run the unit tests, do<br>
-<blockquote><pre><code>
-% ant dist test
-</code></pre></blockquote>
-<p>
-If JNA has not yet been built on for your platform, you may need to tweak the build.xml and native/Makefile build configurations so that your platform is recognized.
-<p>
-The project also includes <a href="http://netbeans.org">NetBeans</a> and <a href="http://www.eclipse.org">Eclipse</a> project configurations, if you're so inclined.<p>
-
-<a href=#top>Top</a>
-<a name=history></a>
-<h3>History</h3>
-<p>Fragments of this project date back to a small shared stubs library originally written by Sheng Liang of the Sun JNI team and demoed at JavaOne circa 1999. <p>
-Todd Fast (also of Sun) first published JNA on dev.java.net in the fall of 2006, which allowed calls with primitive type parameters and partial struct support (that code is still available in the SVN repo under the <a href="https://jna.dev.java.net/svn/jna/tags/CVS%20HEAD">CVS HEAD</a> tag). From the original project announcement:
-<blockquote><pre>
-Headline Initial JNA code checked in
-Date Nov 30, 2006
-Contributed by toddfast
-</pre>
-Announcement<p>
-
-Thanks everyone for your interest in the Java Native Access (JNA) project! I've just checked in the initial code. I've worked on this little project off-and-on for the better part of 6-7 years, and this release comes about a year after I last looked at it. Therefore, I'm only just now getting familiar with it again after refactoring and redesigning for JDK 5 last year, so there may be any number of issues or shortcomings leftover since my last time with it. Please look through the code and get involved!<p>
-
-The Java library code is contained in a NetBeans 5.x project. If you want to build it, please use NetBeans or use the Ant build script in the root of the jnalib/ directory. I will upload a binary at some point to make it a bit easier to get started.<p>
-
-I've checked in binaries of the jnidispatch library and the testlib library for Win32 (.dll's), but don't have convenient access to build these for other platforms. I would greatly appreciate help from others to compile and test versions for other platforms, particularly Mac OS.<p>
-
-To get an idea how to use JNA, please refer to the JUnit tests in the test/ directory. These are crufty and not meant to be examples, but will have to suffice until real samples are available (I would definitely appreciate community help with those as well). Note that you will need to modify your java.library.path system property to include the jnidispatch binary (and possibly the testlib binary) in order to use JNA or run the unit tests. For example:
-java -Djava.library.path=./native/testlib/Debug;./native/jnidispatch/Debug ...
-</blockquote>
-
-<p>Timothy Wall rebooted the project in February of 2007, introducing a number of critical features, adding linux and OSX ports, and making the library usable with more than just rudimentary functions. I was looking for a way to experiment with native libraries without having to carve out a new Makefile and build process (those of you who've never built multi-lingual projects involving C don't know what you're missing). Specifically I wanted some shaped windows and better file system access. After a few proof-of-concept tests, I scouted around for existing projects from which I could bootstrap (see the OTHERS file for some of the projects that are out there). JNA had the simplest, most straightforward architecture (as did <a href="http://nlink.dev.java.net">NLINK</a>, which likely had the same roots). It was also the least problematic to make work cross-platform with a consistent build process.<p>
-
-Wayne Meissner has contributed enormously ("a metric buttload of hard work") in getting libffi and the various additional native libraries working. His work on a Java interface to the gstreamer library has contributed a number of critical features to JNA.<p>
-
-<script src="https://ssl.google-analytics.com/urchin.js" type="text/javascript">
-</script>
-<script type="text/javascript">
-_uacct = "UA-1166339-4";
-urchinTracker();
-</script>
-<div name="meta-info" style="visibility:hidden;display:none;">
-java,jna,jni,c,c++,native,method,function,call,ctypes,ffi,foreign function interface,jdirect,jinvoke,pinvoke,platform invoke,native library access,native access,call native from java,java c library,easy jni,call c from java,avoid jni,jni alternative,jni replacement,legacy,call from java,replace jni
-</div>
-</body>
-</html>
-<!--
-Local variables:
-eval: (add-hook 'write-file-hooks 'time-stamp)
-time-stamp-start: "<meta name=\"date\" content=\""
-time-stamp-format: "%:y-%02m-%02d"
-time-stamp-end: "\">"
-End:
--->
-
View
436 www/release-notes.html
@@ -1,436 +0,0 @@
-<a name="top"></a>
-<h2>Release 3.x.x</h2>
-<h3>Features</h3>
-<ul>
-<li>Facilitate <code>Memory</code> subclasses (jbellis).
-<li>Allow multiple fields of the same type in Unions (Francis Barber).
-<li>Add <code>platform.win32.Advapi32.AdjustTokenPrivileges</code>, <code>platform.win32.Advapi32.LookupPrivilegeName</code>, <code>platform.win32.Advapi32.LookupPrivilegeValue</code>, <code>platform.win32.Advapi32.ImpersonateSelf</code>.
-<li>Add <code>platform.win32.Advapi32.DuplicateTokenEx</code>, <code>platform.win32.Advapi32.CreateProcessAsUser</code>,
-<code>platform.win32.Kernel32.GetExitCodeProcess</code>, <code>platform.win32.Kernel32.TerminateProcess</code>, <code>platform.win32.Kernel32.ReadFile</code>,
-<code>platform.win32.Kernel32.CreatePipe</code>, <code>platform.win32.Kernel32.SetHandleInformation</code> and related constants / structures in <code>platform.win32.WinBase</code>
-and <code>platform.win32.WinNT</code>. Please note that the <code>SECURITY_ATTRIBUTES</code> structure has been moved from <code>platform.win32.WinNT</code> to <code>platform.win32.WinBase</code>.
-<li>Add <code>platform.win32.Kernel32.DeleteFile</code> and <code>platform.win32.Kernel32Util.deleteFile</code>.
-<li>Add <code>platform.win32.Kernel32.GetFileAttributes</code> and <code>platform.win32.Kernel32Util.getFileAttributes</code>.
-<li>Add <code>platform.win32.Kernel32.GetTickCount</code>.
-<li>Add Win32 Service functions to <code>platform.win32.Advapi32</code>.
-<li>Add <code>platform.win32.W32ServiceManager</code> and <code>W32Service</code>.
-<li>Add Win32 Event Logging functions to <code>platform.win32.Advapi32</code> and <code>platform.win32.Advapi32Util.EventLogIterator</code>.
-<li><code>platform.win32.Advapi32Util.registryCreateKey</code> returns <code>true</code> if key was created, <code>false</code> if it already exists.
-<li>Add <code>REG_BINARY</code>, <code>REG_EXPAND_SZ</code> and <code>REG_MULTI_SZ</code> support to <code>platform.win32.Advapi32Util</code> registry functions.
-<li>Reduce JNI crossings in a number of native methods, moving object creation out into pure Java code.
-</ul>
-<h3>Bug Fixes</h3>
-<ul>
-<li>Move all native functions into <code>com.sun.jna.Native</code>, to ensure that all dependent classes must be disposed before the <code>Native</code> class is unloaded.
-<li>Fix <code>platform.win32.Kernel32.GetNativeSystemInfo</code> and <code>GetSystemInfo</code> AV on Win64.
-<li>Fix several potential minor bugs as reported by TvT.
-<li>Fix bug in Structure.StructureSet.toString (Blair Zajac), exposed by Tomcat ThreadLocal cleanup.
-<li>Fix several bugs when using Structure(Pointer) ctor and array fields (Samuel Audet).
-</ul>
-
-<h2>Release 3.2.7</h2>
-<h3>Features</h3>
-<ul>
-<li>Add native peer value accessors for Pointer
-<li>The <code>jna.library.path</code> property is now re-evaluated whenever a native library is loaded. Previously this value was cached when the JNA classes loaded.
-<li><code>Native.loadLibrary</code> can now load <code>.drv</code> files.
-<li>Refactor <code>com.sun.jna.platform.win32.WINBASE</code> into <code>WinDef</code>, <code>WinNT</code> and <code>BaseTSD</code>, matching Windows SDK headers.
-<li>Refactor constants from <code>com.sun.jna.platform.win32.GDI32</code> into <code>WinGDI</code>, matching Windows SDK headers.
-<li>Refactor constants from <code>com.sun.jna.platform.win32.User32</code> into <code>WinUser</code>, matching Windows SDK headers.
-<li>Refactor <code>platform.win32.WinNT.LARGE_INTEGER</code> into a union.
-<li>Add <code>platform.win32.ObjBase</code>, <code>com.sun.jna.platform.win32.Ole32.CoInitializeEx</code>, <code>CoUninitialize</code>, and <code>CoCreateInstance</code>.
-<li>Add <code>platform.win32.Oleaut32.SysAllocString</code> and <code>SysFreeString</code>.
-<li>Add <code>platform.win32.Secur32.ImpersonateSecurityContext</code> and <code>RevertSecurityContext</code>.
-<li>Add <code>platform.win32.WinNT.WELL_KNOWN_SID_TYPE</code>, <code>SECURITY_MAX_SID_SIZE</code> and other related SID-related constants.
-<li>Add <code>platform.win32.Advapi32.CreateWellKnownSid</code> and <code>IsWellKnownSid</code> and <code>com.sun.jna.platform.win32.Advapi32Util.isWellKnownSid</code>.
-<li>Add <code>platform.win32.Kernel32.GetVersion</code>, <code>GetVersionEx</code>, <code>GetSystemInfo</code>, <code>GetNativeSystemInfo</code>, <code>GlobalMemoryStatusEx</code>, <code>GetLogicalDriveStrings</code> and <code>IsWow64Process</code>.
-<li>Add <code>platform.win32.Kernel32Util.getLogicalDriveStrings</code>.
-<li>Add <code>platform.win32.User32.GetSystemMetrics</code>.
-<li>Add <code>platform.win32.BaseTSD.DWORD_PTR</code>.
-<li>Add <code>platform.win32.WinBase.SYSTEM_INFO</code> and <code>MEMORYSTATUSEX</code>.
-<li>Add <code>platform.win32.WinNT.OSVERSIONINFOEX</code>, <code>VER</code> constants.
-<li>Add <code>platform.win32.WinDef.ULONGLONG</code> and <code>DWORDLONG</code>.
-<li>Add <code>platform.win32.Shell32.SHGetDesktopFolder</code> (prep work for Com4JNA).
-<li>Add <code>platform.win32.Winspool.GetPrinterInfo</code>.
-<li>Add <code>platform.win32.WinspoolUtil.getPrinterInfo1</code>.
-<li>Add <code>platform.win32.GDI32.GetDeviceCaps</code>.
-<li>Add <code>platform.win32.GDI32.GetDIBits</code>.
-</ul>
-<h3>BugFixes</h3>
-<ul>
-<li>Fix <code>ClassCastException</code> in <code>Structure.equals</code> (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=152">issue 152</a>).
-<li>Fix bug initializing a structure object from existing memory when the
- structure has initialized fields (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=133">issue 133</a>).
-<li>Fix NPE reading an array of string from a pointer when an element of the
- array is <code>NULL</code> (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=151">issue 151</a>).
-<li>Avoid calling <code>UnregisterNatives</code> in native code (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=154">issue 154</a>).
-<li>Compare unpacked library path against canonical (long) filename (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=156">issue 156</a>).
-<li>Fix <code>read()</code> of uninitialized memory in <code>platform.win32.Advapi32Util.getTokenGroups</code> and <code>getTokenAccount</code>.
-<li>Fix <code>com.sun.jna.platform.win32.Secur32.QuerySecurityContextToken</code> to take a <code>CtxtHandle</code> instead of <code>PSecHandle</code>.
-<li>Fix definition of BITMAPINFO (platform/win32).
-</ul>
-<h2>Release 3.2.5</h2>
-<h3>Features</h3>
-<ul>
-<li>Split code in examples.jar into a contrib platform.jar package and individual packages for demos.
-<li>Fix Eclipse build and added Eclipse projects for all contrib samples, import projects from jnalib and contrib.
-<li>Ensure Structure fields correctly ordered when inherited.
-<li>Use explicit Structure field whenever provided, regardless of whether the VM requires it.
-<li>Add Win32 mappings for two dozen functions from Kernel32.dll, Advapi32.dll, Netapi32.dll, Secur32.dll, NtDll.dll, Ole32.dll, Shell32.dll and Crypt32.dll to com.sun.jna.platform.win32.
-<li>Port parts of WinError.h, WinNT.h, LMAccess.h, LMCons.h, LMErr.h, LMJoin.h, NTStatus.h, ShlObj.h, WinDef.h, ShellApi.h, Wdm.h, WinReg.h, WinCrypt.h, Sspi.h, Guid.h, NtSecApi.h and DsGetDc.h.
-<li>Add Win32 simplified utility interfaces Kernel32Util, Advapi32Util, Netapi32Util, Crypt32Util, NtDllUtil, Shell32Util, Ole32Util and Secur32Util to com.sun.jna.platform.win32.
-<li>Support unicode paths in W32FileUtils.
-<li>Fix exception during dispose in W32FileMonitor.
-</ul>
-<h3>Bug Fixes</h3>
-<ul>
-<li>Provide String.replace for 1.4 compatibility.
-<li>Avoid allocating memory when Structure is provided a pointer in the ctor.
-<li>Ensure proper value returned in Pointer.getValue() for non-null, unchanged
-NIO Buffer values.
-<li>Use 1.4-compatible URI generation (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=149">issue 149</a>).
-</ul>
-<h2>Release 3.2.4</h2>
-<h3>Features</h3>
-<ul>
-<li>Make Pointer ctor public.
-<li>Provide access to Function objects for arbitrary Pointer values.
-<li>Add linux/ia64 binaries (bpiwowar). See <a href="https://jna.dev.java.net/issues/show_bug.cgi?id=134">issue 134 patch</a>.
-</ul>
-<h3>Bug Fixes</h3>
-<ul>
-<li>Use a more robust method to decode a file-based URL (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=135">issue 135</a>).
-</ul>
-<h2>Release 3.2.3</h2>
-<h3>Features</h3>
-<ul>
-<li>Include version information in code in case package information lost.
-</ul>
-<h3>Bug Fixes</h3>
-<ul>
-<li>Fix WindowUtils exception on mouse over TrayIcon.
-<li>Fix bug toggling windows transparent/opaque (win32/OSX).
-<li>Avoid overwriting unchanged Pointer values in arrays (function calls with Pointer[] and Structure.read).
-<li>Ensure Structure fields marked <code>final</code> are never written.
-<li>Fix bug preventing proper population Structure.ByReference fields on Structure read.
-<li>Ensure double buffering is disabled in components added to a transparent window.
-<li>Fix UnsatisfiedLinkError attempting to load system libraries under Web Start.
-<li>Fix loading Web Start-provided libraries on OSX (libraries must have a .jnilib suffix under Web Start).
-<li>Properly include sources in Maven zip file (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=129">Issue 129</a>).
-</ul>
-<h2>Release 3.2.2</h2>
-<h3>Features</h3>
-<ul>
-<li>Provide length-specified Pointer.getStringArray()
-</ul>
-<h3>Bug Fixes</h3>
-<ul>
-<li>Fix crash with direct mapping if NULL struct* used (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=125">Issue 125</a>).
-<li>Fix case where null-valued Structure fields would get non-null values on
- write.
-<li>Synch callback Structure/Structure[] arguments on callback return.
-<li>Fix NPE when mapping an interface to the current process.
-<li>Automatically load proper C library version from current process on Linux
- (avoids crashing bug on Ubuntu with libc-i686 packages active).
-<li>Avoid scanning structure contents in Structure.toString if contents aren't
- actually used.
-</ul>
-<h2>Release 3.2.1</h2>
-<h3>Features</h3>
-<ul>
-<li>Add HRESULT, LONG mapping to W32API (marc strapetz).
-</ul>
-<h3>Bug Fixes</h3>
-<ul>
-<li>Fix definition of HWND_BROADCAST in W32API.
-<li>Fix memory alignment checking (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=121">Issue 121</a>).
-<li>Fix
- Structure <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/lang/Object.html#equals(java.lang.Object)">equals/hashCode</a>
- implementation, based on current Java fields rather than strictly native
- memory contents. Avoid using equals/hashCode when avoiding recursive
- reads/writes.
-</ul>
-<h2>Release 3.2.0</h2>
-<h3>Features</h3>
-<ul>
-<li>Handle String, Structure, Callback, Buffer, and primitive arrays in direct
- mappings. Handle NativeMapped and TypeMapper, with optimized paths for
- IntegerType and PointerType.
-<li>Optionally throw errno/GetLastError as an exception. This is preferred to
- (and more efficient than) calling Native.getLastError().
-<li>Unload/delete native library unpacked from jna.jar if Native class is garbage collected. Only install shutdown hook if using the system class loader.
-<li>Auto-write contiguous Structure arrays when first element is written.
-<li>Support NativeMapped[] as function arguments for interface-mapped
- libraries (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=90">Issue 90</a>).
-<li>Enable function lookup within current process on Windows.
-</ul>
-<h3>Bug Fixes</h3>
-<ul>
-<li>Restrict recursive structure reads/writes by thread instead of globally.
- This avoids potentially missed reads/writes with concurrent access (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=120">Issue 120</a>).
-<li>Ensure Memory is not GC'd and freed if direct NIO buffers mapped to it are extant.
-<li>Allow types derived from java.nio.Buffer as Structure fields.
-</ul>
-<h2>Release 3.1.0</h2>
-<h3>Features</h3>
-<ul>
-<li>Add raw JNI mapping of static Java methods. Performance is about 10X that of traditional JNA interface mapping, although with less type conversion functionality.
-<li>Add library option to allow passing/return of Java Objects.
-<li>Allow handling of uncaught callback exceptions (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=63">Issue 63</a>).
-<li>Object oriented interface to X server (see contrib/x11)
-<li>Make Memory class more accessible.
-<li>Provide Structure ctor with Pointer argument (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=102">issue 102</a>).
-<li>Allow implicit library access to current process on linux (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=98">issue 98</a>).
-<li>Open all shared libraries with RTLD_GLOBAL, if applicable. This was the
- default behavior on OSX and changes the default behavior on linux.
-<li>Allow NIO Buffer as Structure field (with limitations) (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=57">Issue 57</a>)
-<li>Add <code>size_t</code> size.
-</ul>
-<b>Bug Fixes</b>
-<ul>
-<li>Run tests with <a href="http://java.sun.com/j2se/1.4.2/docs/guide/vm/signal-chaining.html">libjsig.so</a>, if available, which fixes some crashes when running tests on 64-bit platforms.
-<li>Fix <a href="https://jna.dev.java.net/issues/show_bug.cgi?id=104">Issue 104</a>.
-<li>Fix <a href="https://jna.dev.java.net/issues/show_bug.cgi?id=94">Issue 94</a> (Java 1.6 update 10 regression).
-<li>Fix <a href="https://jna.dev.java.net/issues/show_bug.cgi?id=51">Issue 51</a> (Java 1.6 update 10 regression).
-<li>Fix <a href="https://jna.dev.java.net/issues/show_bug.cgi?id=95">Issue 95</a>.
-<li>Fix <a href="https://jna.dev.java.net/issues/show_bug.cgi?id=101">Issue 101</a>.
-<li>Fix <a href="https://jna.dev.java.net/issues/show_bug.cgi?id=111">Issue 111</a>, memory leak with String-returning Callback.
-<li>Fix missing storage of union type information (affects usage of struct/union by value as argument and return type).
-<li>Remove non-functional Structure ctors requiring explicit size.
-</ul>
-<h2>Release 3.0.9</h2>
-<b>Bug Fixes</b>
-<ul>
-<li> Fix <a href="https://jna.dev.java.net/issues/show_bug.cgi?id=93">issue 93</a> by only manually searching jna.library.path, then falling back to passing the mapped library name to dlopen/LoadLibrary. This fixes an <a href="http://jira.codehaus.org/browse/JRUBY-3084">issue in JRUBY</a> where the incorrect libc.so.6 was being loaded.
-</ul>
-<h2>Release 3.0.8</h2>
-<h3>Features</h3>
-<ul>
-<li>Auto-map Pointer[]/String[]/WString[] return values.
-<li>Provide utility functions to convert String to primitive array.
-<li>Add jna.library.boot.path property to define the directory that the native stub library is loaded from
-</ul>
-<h2>Release 3.0.7</h2>
-<h3>Features</h3>
-<ul>
-<li>Improve win32 loading of libraries with dependencies.
-</ul>
-<h3>Bug Fixes</h3>
-<ul>
-<li>Fix bug reading structures with PointerType fields, introduced with Pointer field preservation fix.
-</ul>
-<h2>Release 3.0.6</h2>
-<h3>Features</h3>
-<ul>
-<li>Allow arbitrary callback method names if only one method is defined in the class which implements Callback (colinwalters).
-<li>Allow specification of callback type mappers by using a TYPE_MAPPER field (colinwalters).
-<li>Allow uninitialized (null-valued) boxed primitives in Structures (colinwalters).
-<li>Add convenience methods to set active Union field and value simultaneously (xylo).
-<li>Augment Union read/writeField to set the active field.
-<li>Allow Structure auto-synch across native calls to be disabled.
-<li>Win64 support.
-</ul>
-<h3>Bug Fixes</h3>
-<ul>
-<li>Avoid overwriting unchanged Structure fields of type Pointer.
-<li>Avoid more content dragging on OSX or warn if it's too late.
-<li>Fix UnsatisfiedLinkError using transparent window on Win2K.
-<li>Fix memory leak with callbacks called from native threads with no Java context (johnwallace).
-<li>Defer structure size calculation if type mapper not yet set, allowing type mapper to be set in derived constructors (colinwalters).
-<li>Ensure structure memory is allocated in Structure.read/writeField.
-</ul>
-<h2>Release 3.0.5</h2>
-<h3>Features</h3>
-<ul>
-<li>Allow explicit declaration of field order for VMs which have an unpredictable field order.
-<li>Check for w32 libraries with a "lib" prefix in addition to normal lookup.
-<li>Allow String[]/WString[] as callback argument/return value (assume NULL-terminated array).
-<li>Add Solaris8 compatibility to sunos-sparc build (Corey Puffalt).
-<li>Look up libraries using web start library path, if appropriate (Corey Puffalt).
-<li>Use constants to return integer boolean values.
-</ul>
-<h3>Bug Fixes</h3>
-<ul>
-<li>Properly track cursor on alpha-masked windows.
-<li>Avoid searching /lib or /usr/lib on 64-bit Linux.
-<li>Avoid using incorrect version of a library when both 32- and 64-bit versions are found.
-<li>Avoid transparent window events always dragging window bug on OSX.
-<li>Fix division by zero error calculating structure size on OSX/ppc.
-<li>Avoid overwriting initialized NativeMapped Structure fields when calculating structure size.
-<li>Fix NPE reading back into StringArray.
-</ul>
-<h2>Release 3.0.4</h2>
-<h3>Features</h3>
-<ul>
-<li>Automatically write contents of Structure.ByReference fields on Structure.write().
-<li>Use the actual parameter type in Function invocations if no parameter type information is available (whether method is missing or untyped varargs).
-<li>Augmented X11 library mappings (xylo).
-<li>Support read/write of NativeMapped arrays within Structure (notably NativeLong).
-</ul>
-<h3>Bug Fixes</h3>
-<ul>
-<li>Fix library load error when /usr/lib32 and /usr/lib both exist (linux) (Marek Slama).
-<li>Avoid incorrect matches against libraries named with the same prefix
- (e.g. libc-client.so vs libc.so) (xylo).
-<li>Properly handle arrays of NativeMapped (e.g. NativeLong) as a Structure field (stefan endrullis).
-<li>Ensure structure size calculated prior to setting union active type.
-<li>XID is 64-bits on 64-bit X clients (xylo).
-<li>Ensure proper arch name is used on Debian (amd64 instead of x86_64).
-</ul>
-<h2>Release 3.0.3</h2>
-<h3>Features</h3>
-<ul>
-<li>Enable build/run using IBM's J9 VM (leonardo).
-<li>Make StdCallFunctionMapper attempt a leading underscore if the simpler mapping doesn't work.
-<li>Allow Structure.read to overwrite final fields (may not work on some 1.4 VMs).
-</ul>
-<h3>Bug Fixes</h3>
-<ul>
-<li>Fix NPE when passing an array of Structure.ByReference.
-<li>Compare entire linux library version when finding a match.
-<li>Don't pass struct by value unless the method signature declares it.
-<li>Restrict custom first element structure alignment to OSX/ppc.
-<li>Improve performance and reduce memory footprint for window masks.
- Optimize polygon-based masks on w32. Use XFillRectangles on X11.
-<li>Fix linkage settings on sunos-amd64 to avoid relocation errors.
-<li>Fix callback allocation code on w32, solaris, freebsd, darwin (libffi was misconfigured).
-<li>Fix bug when NativeMapped fields are used in a Structure.ByValue instance.
-<li>Fix NPE calling Structure.read() before memory is initialized.
-<li>Fix NPE calling Structure.read/write with uninitialized NativeMapped fields.
-</ul>
-
-<h2>Release 3.0.2</h2>
-<h3>Features</h3>
-<ul>
-<li>Attempt to force unload of jnidispatch library prior to deleting it (w32).
-<li>Added amd64 targets for OSX, FreeBSD, and Solaris.
-</ul>
-<h3>Bug Fixes</h3>
-<ul>
-<li>Reduce space allocated for invocation arguments.
-<li>Fix NPE when NativeMapped type is used in a Structure.
-<li>Fix some X11 type mappings for 64-bit.
-<li>Fix OSX Leopard/JRE1.5+ window transparency.
-<li>Fix window alpha compositing on X11.
-<li>Fix loading of libraries with unicode names on OSX.
-</ul>
-
-<h2>Release 3.0.1</h2>
-<h3>Features</h3>
-<ul>
-<li>Improve transparent window drawing performance on w32
-<li>Use closure allocation from libffi
-</ul>
-<h3>Bug Fixes</h3>
-<ul>
-<li>Ensure nested structure arrays initialized with Structure.toArray use the
- appropriate native memory.
-<li>Ensure structure size is calculated prior to converting to array
-<li>Avoid creating new windows when setting a window mask
-<li>Fix bug in Pointer.setChar.
-</ul>
-
-<h2>Release 3.0</h2>
-<h3>Features</h3>
-<ul>
-<li>More supported platforms, via GCC's libffi (wmeissner)
-<li>Support struct by value as parameter and return value (duncan)
-<li>Support struct by reference within structures
-<li>Provide access to native peer for java.awt.Component
-<li>Provide access to native peer on OS X.
-<li>Support MINGW32 builds (fullung)
-<li>Allow per-field Structure read/write by field name
-<li>Avoid writing Structure fields marked 'volatile'
-<li>Read and wrap function pointers in Structure fields when read with a Java
- proxy to allow easy Java-side invocation (Ken Larson)
-<li>Support array-backed Buffers as arguments (wmeissner)
-<li>Auto-conversion of custom types (wmeissner)
-<li>Allow pointer type-safety
-<li>Optional VM crash protection, via Native.setProtected(boolean)
-<li>Auto-convert WString[]
-<li>Provide library synchronization wrapper similar to Collections.synchronizedX
-<li>Support lookup of OSX framework libraries by name
-<li>Explicit access to shared library global data
-<li>Invocation interception to facilitate translation of C preprocessor macros
- and inline functions
-<li>Provide utility to determine Web Start native library cache location;
- auto-include this path if jnidispatch is included as a &lt;nativelib&gt;
- (robertengels)
-<li>Provide access to aligned memory
-<li>Versioning information embedded in jna.jar and native library
-</ul>
-<h3>Bug Fixes</h3>
-<ul>
-<li>Avoid attempts to free native library if it failed to load (wmeissner)
-<li>Explicitly check method signatures for varargs instead of heuristically
- guessing (wmeissner)
-<li>Disallow declaring Pointer-derived fields in Structures (Function, Memory)
-<li>Ensure Object.toString/hashCode/equals methods are intercepted on proxyied
- interfaces
-<li>Update X11 library for 64-bit use (wmeissner)
-<li>Properly map arrays of char*/wchar_t* under w32
-<li>Allow Pointer[] as a Structure field and Function argument
-<li>Fix some misleading Structure error messages
-<li>Properly preserve/return GetLastError/errno after native calls
-<li>Allocate executable memory on w32 to avoid errors with hardware-enforced
- data execution protection (DEP)
-<li>Fix VM crash on w32 stdcall callbacks
-<li>Use long offsets and sizes rather than ints (64-bit safe)
-<li>Properly clean up references and release closure memory on JNI_Unload
-<li>Use simpler AWT/JAWT library loading workaround
-<li>Avoid changing array references within a Structure on read
-</ul>
-<h2>Release 2.5</h2>
-<h3>Features</h3>
-<ul>
-<li>Unions
-<li>Optimized shaped windows (chris deckers & olivier chafik); instantiation time
-improved by about 2-3 orders of magnitude for large, mostly contiguous shapes
-<li>Provide type mapping in callback arguments/results
-<li>Provide access to ByteBuffer direct address as a Pointer
-<li>Provide customization of native string encoding with jna.encoding system property
-</ul>
-
-<h3>Bug Fixes</h3>
-<ul>
-<li>Properly handle VMs with reversed Structure member storage
-<li>Avoid making window undecorated when clearing window mask on X11
-<li>Fix structure alignment bug on OSX/PPC when first element is > 4 bytes in size
-<li>Clearing OSX window mask by setting to MASK_NONE now works properly
-<li>Avoid index exceptions if native buffers are not NUL-terminated on string conversions
-<li>Write initialized Structure[] argument memory prior to function calls
-<li>Fix IllegalArgumentException reading WString into a Structure
-<li>Clear memory when allocating a structure block (fixes VM crash)
-<li>Remove versioned JAWT dependency on OSX, allowing use on 10.3/JRE1.4.
-</ul>
-
-<h2>Release 2.4</h2>
-<h3>Features</h3>
-<ul>
-<li>Explicitly support unaligned structures
-<li>Auto-reallocate structure arrays
-<li>Automatic handling of w32 UNICODE/ASCII variants
-<li>Automatic mapping of decorated w32 stdcall function names
-<li>Customizable, automatic type conversion of arguments and results (wmeissner)
-<li>Support char*[] arguments as Java String[]
-<li>Structure supports Callback members (wmeissner)
-<li>getByteBuffer from Pointer/Memory (wmeissner)
-<li>Allow GC of native libraries
-<li>Facilitate use from non-Java contexts (JRuby et al.) (wmeissner)
-<li>Improve library path searching (wmeissner)
-<li>Handle Structure[] arguments
-<li>Handle native long arguments and return values
-<li>Handle direct and array-based ByteBuffer arguments (wmeissner)
-<li>Change default w32 build to use GCC (it's free, yo)
-</ul>
-
-<h3>Bug Fixes</h3>
-<ul>
-<li>Structure.toArray failed to initialize members
-<li>Disallow explicit free of Structure/Memory
-<li>Ensure native libraries are only loaded once until released
-<li>Properly handle NULL when the return value is a Structure
-<li>Proper conversion to wchar_t on linux
-<li>Copy full length of Java strings to C strings instead of stopping when a NUL
-character is encountered
-</ul>
View
13 www/style.css
@@ -1,13 +0,0 @@
-body { color: #000000; font-family: Verdana, Arial; font-size: 0.8em; }
-body p { margin-top: 5px; }
-a { font-family: Arial; text-decoration: none; }
-body h1 { font-size: 1.8em; padding-top: 5px; margin-bottom: 5px;}
-body h2 { font-size: 1.6em; padding-top: 5px; margin-bottom: 5px;}
-body h3 { font-size: 1.5em; padding-top: 5px; margin-bottom: 5px;}
-body h4 { font-weight: bold; padding-top: 5px; margin-bottom: 5px;}
-body h1, h2, h3, h4 { border-bottom: 1px solid #AAA; font-weight: normal; }
-body table { border: 1pt solid black }
-body tr td { font-size: 10pt; font-family: Verdana, Arial; border: 1pt solid silver; }
-body code { font-size: 10pt }
-body pre { font-size: 10pt }
-body ul { margin-top: 5px; margin-bottom: 5px }
Please sign in to comment.
Something went wrong with that request. Please try again.