Skip to content
This repository
Browse code

Started porting docs into markdown.

  • Loading branch information...
commit 92d721d9d0f4de8f1d739ba751fc19406a07a11f 1 parent 0f06d0b
Daniel Doubrovkine (dB.) @dblockdotorg authored May 23, 2011
479  CHANGES
... ...
@@ -0,0 +1,479 @@
  1
+Release 3.x.x
  2
+=============
  3
+
  4
+Features
  5
+--------
  6
+
  7
+* Facilitate `Memory</code> subclasses (jbellis).
  8
+* Allow multiple fields of the same type in Unions (Francis Barber).
  9
+* Add `platform.win32.Advapi32.AdjustTokenPrivileges</code>, `platform.win32.Advapi32.LookupPrivilegeName</code>, `platform.win32.Advapi32.LookupPrivilegeValue</code>, `platform.win32.Advapi32.ImpersonateSelf</code>.
  10
+* 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>.
  11
+* Add `platform.win32.Kernel32.DeleteFile</code> and `platform.win32.Kernel32Util.deleteFile</code>.
  12
+* Add `platform.win32.Kernel32.GetFileAttributes</code> and `platform.win32.Kernel32Util.getFileAttributes</code>.
  13
+* Add `platform.win32.Kernel32.GetTickCount</code>.
  14
+* Add Win32 Service functions to `platform.win32.Advapi32</code>.
  15
+* Add `platform.win32.W32ServiceManager</code> and `W32Service</code>.
  16
+* Add Win32 Event Logging functions to `platform.win32.Advapi32</code> and `platform.win32.Advapi32Util.EventLogIterator</code>.
  17
+* `platform.win32.Advapi32Util.registryCreateKey</code> returns `true</code> if key was created, `false</code> if it already exists.
  18
+* Add `REG_BINARY</code>, `REG_EXPAND_SZ</code> and `REG_MULTI_SZ</code> support to `platform.win32.Advapi32Util</code> registry functions.
  19
+* Reduce JNI crossings in a number of native methods, moving object creation out into pure Java code.
  20
+
  21
+Bug Fixes
  22
+---------
  23
+
  24
+* 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. 
  25
+* Fix `platform.win32.Kernel32.GetNativeSystemInfo</code> and `GetSystemInfo</code> AV on Win64.
  26
+* Fix several potential minor bugs as reported by TvT.
  27
+* Fix bug in Structure.StructureSet.toString (Blair Zajac), exposed by Tomcat ThreadLocal cleanup.
  28
+* Fix several bugs when using Structure(Pointer) ctor and array fields (Samuel Audet).
  29
+
  30
+Release 3.2.7
  31
+=============
  32
+
  33
+Features
  34
+--------
  35
+
  36
+* Add native peer value accessors for Pointer
  37
+* 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.
  38
+* `Native.loadLibrary</code> can now load `.drv</code> files.
  39
+* Refactor `com.sun.jna.platform.win32.WINBASE</code> into `WinDef</code>, `WinNT</code> and `BaseTSD</code>, matching Windows SDK headers.
  40
+* Refactor constants from `com.sun.jna.platform.win32.GDI32</code> into `WinGDI</code>, matching Windows SDK headers.
  41
+* Refactor constants from `com.sun.jna.platform.win32.User32</code> into `WinUser</code>, matching Windows SDK headers.
  42
+* Refactor `platform.win32.WinNT.LARGE_INTEGER</code> into a union.
  43
+* Add `platform.win32.ObjBase</code>, `com.sun.jna.platform.win32.Ole32.CoInitializeEx</code>, `CoUninitialize</code>, and `CoCreateInstance</code>.
  44
+* Add `platform.win32.Oleaut32.SysAllocString</code> and `SysFreeString</code>.
  45
+* Add `platform.win32.Secur32.ImpersonateSecurityContext</code> and `RevertSecurityContext</code>.
  46
+* Add `platform.win32.WinNT.WELL_KNOWN_SID_TYPE</code>, `SECURITY_MAX_SID_SIZE</code> and other related SID-related constants.
  47
+* Add `platform.win32.Advapi32.CreateWellKnownSid</code> and `IsWellKnownSid</code> and `com.sun.jna.platform.win32.Advapi32Util.isWellKnownSid</code>.
  48
+* Add `platform.win32.Kernel32.GetVersion</code>, `GetVersionEx</code>, `GetSystemInfo</code>, `GetNativeSystemInfo</code>, `GlobalMemoryStatusEx</code>, `GetLogicalDriveStrings</code> and `IsWow64Process</code>.
  49
+* Add `platform.win32.Kernel32Util.getLogicalDriveStrings</code>.
  50
+* Add `platform.win32.User32.GetSystemMetrics</code>.
  51
+* Add `platform.win32.BaseTSD.DWORD_PTR</code>.
  52
+* Add `platform.win32.WinBase.SYSTEM_INFO</code> and `MEMORYSTATUSEX</code>.
  53
+* Add `platform.win32.WinNT.OSVERSIONINFOEX</code>, `VER</code> constants.
  54
+* Add `platform.win32.WinDef.ULONGLONG</code> and `DWORDLONG</code>.
  55
+* Add `platform.win32.Shell32.SHGetDesktopFolder</code> (prep work for Com4JNA).
  56
+* Add `platform.win32.Winspool.GetPrinterInfo</code>.
  57
+* Add `platform.win32.WinspoolUtil.getPrinterInfo1</code>.
  58
+* Add `platform.win32.GDI32.GetDeviceCaps</code>.
  59
+* Add `platform.win32.GDI32.GetDIBits</code>.
  60
+
  61
+Bug Fixes
  62
+---------
  63
+
  64
+* Fix `ClassCastException</code> in `Structure.equals</code> (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=152">issue 152</a>).
  65
+* 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>).
  66
+* 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>).
  67
+* Avoid calling `UnregisterNatives</code> in native code (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=154">issue 154</a>).
  68
+* Compare unpacked library path against canonical (long) filename (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=156">issue 156</a>).
  69
+* Fix `read()</code> of uninitialized memory in `platform.win32.Advapi32Util.getTokenGroups</code> and `getTokenAccount</code>.
  70
+* Fix `com.sun.jna.platform.win32.Secur32.QuerySecurityContextToken</code> to take a `CtxtHandle</code> instead of `PSecHandle</code>.
  71
+* Fix definition of BITMAPINFO (platform/win32).
  72
+
  73
+Release 3.2.5
  74
+=============
  75
+
  76
+Features
  77
+--------
  78
+
  79
+* Split code in examples.jar into a contrib platform.jar package and individual packages for demos.
  80
+* Fix Eclipse build and added Eclipse projects for all contrib samples, import projects from jnalib and contrib.
  81
+* Ensure Structure fields correctly ordered when inherited.
  82
+* Use explicit Structure field whenever provided, regardless of whether the VM requires it.
  83
+* 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.
  84
+* 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.
  85
+* Add Win32 simplified utility interfaces Kernel32Util, Advapi32Util, Netapi32Util, Crypt32Util, NtDllUtil, Shell32Util, Ole32Util and Secur32Util to com.sun.jna.platform.win32.
  86
+* Support unicode paths in W32FileUtils.
  87
+* Fix exception during dispose in W32FileMonitor.
  88
+
  89
+Bug Fixes
  90
+---------
  91
+
  92
+* Provide String.replace for 1.4 compatibility.
  93
+* Avoid allocating memory when Structure is provided a pointer in the ctor.
  94
+* Ensure proper value returned in Pointer.getValue() for non-null, unchanged NIO Buffer values.
  95
+* Use 1.4-compatible URI generation (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=149">issue 149</a>).
  96
+
  97
+Release 3.2.4
  98
+=============
  99
+
  100
+Features
  101
+--------
  102
+
  103
+* Make Pointer ctor public.
  104
+* Provide access to Function objects for arbitrary Pointer values.
  105
+* Add linux/ia64 binaries (bpiwowar).  See <a href="https://jna.dev.java.net/issues/show_bug.cgi?id=134">issue 134 patch</a>.
  106
+
  107
+Bug Fixes
  108
+---------
  109
+
  110
+* 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>).
  111
+
  112
+Release 3.2.3
  113
+=============
  114
+
  115
+Features
  116
+--------
  117
+
  118
+* Include version information in code in case package information lost.
  119
+
  120
+Bug Fixes
  121
+---------
  122
+
  123
+* Fix WindowUtils exception on mouse over TrayIcon.
  124
+* Fix bug toggling windows transparent/opaque (win32/OSX).
  125
+* Avoid overwriting unchanged Pointer values in arrays (function calls with Pointer[] and Structure.read). 
  126
+* Ensure Structure fields marked `final</code> are never written.
  127
+* Fix bug preventing proper population Structure.ByReference fields on Structure read.
  128
+* Ensure double buffering is disabled in components added to a transparent window.
  129
+* Fix UnsatisfiedLinkError attempting to load system libraries under Web Start.
  130
+* Fix loading Web Start-provided libraries on OSX (libraries must have a .jnilib suffix under Web Start).
  131
+* Properly include sources in Maven zip file (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=129">Issue 129</a>).
  132
+
  133
+Release 3.2.2
  134
+=============
  135
+
  136
+Features
  137
+--------
  138
+
  139
+* Provide length-specified Pointer.getStringArray()
  140
+
  141
+Bug Fixes
  142
+---------
  143
+
  144
+* 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>).
  145
+* Fix case where null-valued Structure fields would get non-null values on write. 
  146
+* Synch callback Structure/Structure[] arguments on callback return.
  147
+* Fix NPE when mapping an interface to the current process.
  148
+* Automatically load proper C library version from current process on Linux (avoids crashing bug on Ubuntu with libc-i686 packages active).
  149
+* Avoid scanning structure contents in Structure.toString if contents aren't actually used.
  150
+
  151
+Release 3.2.1
  152
+==========
  153
+
  154
+Features
  155
+--------
  156
+
  157
+* Add HRESULT, LONG mapping to W32API (marc strapetz).
  158
+
  159
+
  160
+Bug Fixes
  161
+---------
  162
+
  163
+* Fix definition of HWND_BROADCAST in W32API.
  164
+* Fix memory alignment checking (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=121">Issue 121</a>).
  165
+* 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.
  166
+
  167
+Release 3.2.0
  168
+=============
  169
+
  170
+Features
  171
+--------
  172
+
  173
+* Handle String, Structure, Callback, Buffer, and primitive arrays in direct mappings.  Handle NativeMapped and TypeMapper, with optimized paths for IntegerType and PointerType.
  174
+* Optionally throw errno/GetLastError as an exception.  This is preferred to (and more efficient than) calling Native.getLastError().
  175
+* Unload/delete native library unpacked from jna.jar if Native class is garbage collected.  Only install shutdown hook if using the system class loader. 
  176
+* Auto-write contiguous Structure arrays when first element is written.
  177
+* 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>).
  178
+* Enable function lookup within current process on Windows.
  179
+
  180
+Bug Fixes
  181
+---------
  182
+
  183
+* 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>).
  184
+* Ensure Memory is not GC'd and freed if direct NIO buffers mapped to it are extant.
  185
+* Allow types derived from java.nio.Buffer as Structure fields.
  186
+
  187
+Release 3.1.0
  188
+=============
  189
+
  190
+Features
  191
+--------
  192
+
  193
+* Add raw JNI mapping of static Java methods.  Performance is about 10X that of traditional JNA interface mapping, although with less type conversion functionality. 
  194
+* Add library option to allow passing/return of Java Objects.
  195
+* Allow handling of uncaught callback exceptions (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=63">Issue 63</a>).
  196
+* Object oriented interface to X server (see contrib/x11)
  197
+* Make Memory class more accessible.
  198
+* Provide Structure ctor with Pointer argument (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=102">issue 102</a>).
  199
+* 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>).
  200
+* Open all shared libraries with RTLD_GLOBAL, if applicable.  This was the default behavior on OSX and changes the default behavior on linux.
  201
+* Allow NIO Buffer as Structure field (with limitations) (<a href="https://jna.dev.java.net/issues/show_bug.cgi?id=57">Issue 57</a>)
  202
+* Add `size_t` size.
  203
+
  204
+Bug Fixes
  205
+---------
  206
+
  207
+* 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. 
  208
+* Fix <a href="https://jna.dev.java.net/issues/show_bug.cgi?id=104">Issue 104</a>.
  209
+* Fix <a href="https://jna.dev.java.net/issues/show_bug.cgi?id=94">Issue 94</a> (Java 1.6 update 10 regression).
  210
+* Fix <a href="https://jna.dev.java.net/issues/show_bug.cgi?id=51">Issue 51</a> (Java 1.6 update 10 regression).
  211
+* Fix <a href="https://jna.dev.java.net/issues/show_bug.cgi?id=95">Issue 95</a>.
  212
+* Fix <a href="https://jna.dev.java.net/issues/show_bug.cgi?id=101">Issue 101</a>.
  213
+* Fix <a href="https://jna.dev.java.net/issues/show_bug.cgi?id=111">Issue 111</a>, memory leak with String-returning Callback.
  214
+* Fix missing storage of union type information (affects usage of struct/union by value as argument and return type).
  215
+* Remove non-functional Structure ctors requiring explicit size.
  216
+
  217
+Release 3.0.9
  218
+=============
  219
+
  220
+Bug Fixes
  221
+---------
  222
+
  223
+*  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.
  224
+
  225
+Release 3.0.8
  226
+==========
  227
+
  228
+Features
  229
+--------
  230
+
  231
+* Auto-map Pointer[]/String[]/WString[] return values.
  232
+* Provide utility functions to convert String to primitive array.
  233
+* Add jna.library.boot.path property to define the directory that the native stub library is loaded from
  234
+
  235
+Release 3.0.7
  236
+==========
  237
+
  238
+Features
  239
+--------
  240
+
  241
+* Improve Win32 loading of libraries with dependencies.
  242
+
  243
+Bug Fixes
  244
+---------
  245
+
  246
+* Fix bug reading structures with PointerType fields, introduced with Pointer field preservation fix.
  247
+
  248
+Release 3.0.6
  249
+=============
  250
+
  251
+Features
  252
+--------
  253
+
  254
+* Allow arbitrary callback method names if only one method is defined in the class which implements Callback (colinwalters).
  255
+* Allow specification of callback type mappers by using a TYPE_MAPPER field (colinwalters).
  256
+* Allow uninitialized (null-valued) boxed primitives in Structures (colinwalters).
  257
+* Add convenience methods to set active Union field and value simultaneously (xylo).
  258
+* Augment Union read/writeField to set the active field.
  259
+* Allow Structure auto-synch across native calls to be disabled.
  260
+* Win64 support.
  261
+
  262
+Bug Fixes
  263
+---------
  264
+
  265
+* Avoid overwriting unchanged Structure fields of type Pointer.
  266
+* Avoid more content dragging on OSX or warn if it's too late.
  267
+* Fix UnsatisfiedLinkError using transparent window on Win2K.
  268
+* Fix memory leak with callbacks called from native threads with no Java context (johnwallace).  
  269
+* Defer structure size calculation if type mapper not yet set, allowing type mapper to be set in derived constructors (colinwalters).
  270
+* Ensure structure memory is allocated in Structure.read/writeField.
  271
+
  272
+Release 3.0.5
  273
+=============
  274
+
  275
+Features
  276
+--------
  277
+
  278
+* Allow explicit declaration of field order for VMs which have an unpredictable field order.
  279
+* Check for w32 libraries with a "lib" prefix in addition to normal lookup.
  280
+* Allow String[]/WString[] as callback argument/return value (assume NULL-terminated array).
  281
+* Add Solaris8 compatibility to sunos-sparc build (Corey Puffalt).
  282
+* Look up libraries using web start library path, if appropriate (Corey Puffalt).
  283
+* Use constants to return integer boolean values.
  284
+
  285
+Bug Fixes
  286
+---------
  287
+
  288
+* Properly track cursor on alpha-masked windows.
  289
+* Avoid searching /lib or /usr/lib on 64-bit Linux.
  290
+* Avoid using incorrect version of a library when both 32- and 64-bit versions are found.
  291
+* Avoid transparent window events always dragging window bug on OSX.
  292
+* Fix division by zero error calculating structure size on OSX/ppc.
  293
+* Avoid overwriting initialized NativeMapped Structure fields when calculating structure size.
  294
+* Fix NPE reading back into StringArray.
  295
+
  296
+Release 3.0.4
  297
+=============
  298
+
  299
+Features
  300
+--------
  301
+
  302
+* Automatically write contents of Structure.ByReference fields on Structure.write().
  303
+* Use the actual parameter type in Function invocations if no parameter type information is available (whether method is missing or untyped varargs).
  304
+* Augmented X11 library mappings (xylo).
  305
+* Support read/write of NativeMapped arrays within Structure (notably NativeLong).
  306
+
  307
+Bug Fixes
  308
+---------
  309
+
  310
+* Fix library load error when /usr/lib32 and /usr/lib both exist (linux) (Marek Slama).
  311
+* Avoid incorrect matches against libraries named with the same prefix (e.g. libc-client.so vs libc.so) (xylo).
  312
+* Properly handle arrays of NativeMapped (e.g. NativeLong) as a Structure field (stefan endrullis).
  313
+* Ensure structure size calculated prior to setting union active type.
  314
+* XID is 64-bits on 64-bit X clients (xylo).
  315
+* Ensure proper arch name is used on Debian (amd64 instead of x86_64).
  316
+
  317
+Release 3.0.3
  318
+=============
  319
+
  320
+Features
  321
+--------
  322
+
  323
+* Enable build/run using IBM's J9 VM (leonardo).
  324
+* Make StdCallFunctionMapper attempt a leading underscore if the simpler mapping doesn't work.
  325
+* Allow Structure.read to overwrite final fields (may not work on some 1.4 VMs). 
  326
+
  327
+Bug Fixes
  328
+---------
  329
+
  330
+* Fix NPE when passing an array of Structure.ByReference.
  331
+* Compare entire linux library version when finding a match.
  332
+* Don't pass struct by value unless the method signature declares it.
  333
+* Restrict custom first element structure alignment to OSX/ppc.
  334
+* Improve performance and reduce memory footprint for window masks. Optimize polygon-based masks on w32.  Use XFillRectangles on X11.
  335
+* Fix linkage settings on sunos-amd64 to avoid relocation errors.
  336
+* Fix callback allocation code on w32, solaris, freebsd, darwin (libffi was misconfigured).
  337
+* Fix bug when NativeMapped fields are used in a Structure.ByValue instance.
  338
+* Fix NPE calling Structure.read() before memory is initialized.
  339
+* Fix NPE calling Structure.read/write with uninitialized NativeMapped fields. 
  340
+
  341
+Release 3.0.2
  342
+=============
  343
+
  344
+Features
  345
+--------
  346
+
  347
+* Attempt to force unload of jnidispatch library prior to deleting it (w32).
  348
+* Added amd64 targets for OSX, FreeBSD, and Solaris.
  349
+
  350
+Bug Fixes
  351
+---------
  352
+
  353
+* Reduce space allocated for invocation arguments.
  354
+* Fix NPE when NativeMapped type is used in a Structure.
  355
+* Fix some X11 type mappings for 64-bit.
  356
+* Fix OSX Leopard/JRE1.5+ window transparency.
  357
+* Fix window alpha compositing on X11.
  358
+* Fix loading of libraries with unicode names on OSX.
  359
+
  360
+Release 3.0.1
  361
+=============
  362
+
  363
+Features
  364
+--------
  365
+
  366
+* Improve transparent window drawing performance on w32
  367
+* Use closure allocation from libffi
  368
+
  369
+Bug Fixes
  370
+---------
  371
+
  372
+* Ensure nested structure arrays initialized with Structure.toArray use the appropriate native memory.
  373
+* Ensure structure size is calculated prior to converting to array
  374
+* Avoid creating new windows when setting a window mask
  375
+* Fix bug in Pointer.setChar.
  376
+
  377
+Release 3.0
  378
+===========
  379
+
  380
+Features
  381
+--------
  382
+
  383
+* More supported platforms, via GCC's libffi (wmeissner)
  384
+* Support struct by value as parameter and return value (duncan)
  385
+* Support struct by reference within structures
  386
+* Provide access to native peer for java.awt.Component 
  387
+* Provide access to native peer on OS X.
  388
+* Support MINGW32 builds (fullung)
  389
+* Allow per-field Structure read/write by field name
  390
+* Avoid writing Structure fields marked 'volatile'
  391
+* Read and wrap function pointers in Structure fields when read with a Java proxy to allow easy Java-side invocation (Ken Larson)
  392
+* Support array-backed Buffers as arguments (wmeissner)
  393
+* Auto-conversion of custom types (wmeissner)
  394
+* Allow pointer type-safety
  395
+* Optional VM crash protection, via Native.setProtected(boolean)
  396
+* Auto-convert WString[]
  397
+* Provide library synchronization wrapper similar to Collections.synchronizedX
  398
+* Support lookup of OSX framework libraries by name
  399
+* Explicit access to shared library global data
  400
+* Invocation interception to facilitate translation of C preprocessor macros and inline functions
  401
+* Provide utility to determine Web Start native library cache location; auto-include this path if jnidispatch is included as a &lt;nativelib&gt; (robertengels) 
  402
+* Provide access to aligned memory
  403
+* Versioning information embedded in jna.jar and native library
  404
+
  405
+Bug Fixes
  406
+---------
  407
+
  408
+* Avoid attempts to free native library if it failed to load (wmeissner)
  409
+* Explicitly check method signatures for varargs instead of heuristically guessing (wmeissner)
  410
+* Disallow declaring Pointer-derived fields in Structures (Function, Memory)
  411
+* Ensure Object.toString/hashCode/equals methods are intercepted on proxyied interfaces
  412
+* Update X11 library for 64-bit use (wmeissner)
  413
+* Properly map arrays of char*/wchar_t* under w32
  414
+* Allow Pointer[] as a Structure field and Function argument
  415
+* Fix some misleading Structure error messages
  416
+* Properly preserve/return GetLastError/errno after native calls
  417
+* Allocate executable memory on w32 to avoid errors with hardware-enforced data execution protection (DEP)
  418
+* Fix VM crash on w32 stdcall callbacks
  419
+* Use long offsets and sizes rather than ints (64-bit safe)
  420
+* Properly clean up references and release closure memory on JNI_Unload
  421
+* Use simpler AWT/JAWT library loading workaround
  422
+* Avoid changing array references within a Structure on read
  423
+
  424
+Release 2.5
  425
+===========
  426
+
  427
+Features
  428
+--------
  429
+
  430
+* Unions
  431
+* Optimized shaped windows (chris deckers & olivier chafik); instantiation time improved by about 2-3 orders of magnitude for large, mostly contiguous shapes
  432
+* Provide type mapping in callback arguments/results
  433
+* Provide access to ByteBuffer direct address as a Pointer
  434
+* Provide customization of native string encoding with jna.encoding system property 
  435
+
  436
+Bug Fixes
  437
+---------
  438
+
  439
+* Properly handle VMs with reversed Structure member storage
  440
+* Avoid making window undecorated when clearing window mask on X11
  441
+* Fix structure alignment bug on OSX/PPC when first element is > 4 bytes in size
  442
+* Clearing OSX window mask by setting to MASK_NONE now works properly
  443
+* Avoid index exceptions if native buffers are not NUL-terminated on string conversions
  444
+* Write initialized Structure[] argument memory prior to function calls
  445
+* Fix IllegalArgumentException reading WString into a Structure
  446
+* Clear memory when allocating a structure block (fixes VM crash)
  447
+* Remove versioned JAWT dependency on OSX, allowing use on 10.3/JRE1.4.
  448
+
  449
+Release 2.4
  450
+===========
  451
+
  452
+Features
  453
+--------
  454
+
  455
+* Explicitly support unaligned structures
  456
+* Auto-reallocate structure arrays
  457
+* Automatic handling of w32 UNICODE/ASCII variants
  458
+* Automatic mapping of decorated w32 stdcall function names
  459
+* Customizable, automatic type conversion of arguments and results (wmeissner)
  460
+* Support char*[] arguments as Java String[] 
  461
+* Structure supports Callback members (wmeissner)
  462
+* getByteBuffer from Pointer/Memory (wmeissner)
  463
+* Allow GC of native libraries
  464
+* Facilitate use from non-Java contexts (JRuby et al.) (wmeissner)
  465
+* Improve library path searching (wmeissner)
  466
+* Handle Structure[] arguments
  467
+* Handle native long arguments and return values
  468
+* Handle direct and array-based ByteBuffer arguments (wmeissner)
  469
+* Change default w32 build to use GCC (it's free, yo)
  470
+
  471
+Bug Fixes
  472
+---------
  473
+
  474
+* Structure.toArray failed to initialize members
  475
+* Disallow explicit free of Structure/Memory
  476
+* Ensure native libraries are only loaded once until released
  477
+* Properly handle NULL when the return value is a Structure
  478
+* Proper conversion to wchar_t on linux
  479
+* Copy full length of Java strings to C strings instead of stopping when a NUL character is encountered
0  jnalib/LICENSE.txt → LICENSE
File renamed without changes
70  README.md
Source Rendered
... ...
@@ -0,0 +1,70 @@
  1
+![JNA](https://github.com/twall/jna/raw/master/www/images/jnalogo.jpg "Java Native Access (JNA)")
  2
+
  3
+Java Native Access (JNA)
  4
+========================
  5
+
  6
+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.
  7
+
  8
+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.
  9
+
  10
+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.
  11
+
  12
+While some attention is paid to performance, correctness and ease of use take priority.
  13
+
  14
+JNA includes a platform library with many native functions already mapped as well as a set of utility interfaces that simplify native access.
  15
+
  16
+Features
  17
+========
  18
+
  19
+* Automatic mapping from Java to native functions, with simple mappings for all primitive data types
  20
+* Runs on most platforms which support Java
  21
+* Automatic conversion between C and Java strings, with customizable encoding/decoding
  22
+* Structure and Union arguments/return values, by reference and by value
  23
+* Function Pointers, (callbacks from native code to Java) as arguments and/or members of a struct
  24
+* Auto-generated Java proxies for native function pointers
  25
+* By-reference (pointer-to-type) arguments
  26
+* Java array and NIO Buffer arguments (primitive types and pointers) as pointer-to-buffer
  27
+* Nested structures and arrays
  28
+* Wide (wchar_t-based) strings
  29
+* Native long support (32- or 64-bit as appropriate)
  30
+* Demo applications
  31
+* Supported on 1.4 or later JVMs (earlier VMs may work with stubbed NIO support)
  32
+* Customizable marshalling/unmarshalling (argument and return value conversions)
  33
+* Customizable mapping from Java method to native function name, and customizable invocation to simulate C preprocessor function macros
  34
+* Support for automatic Windows ASCII/UNICODE function mappings
  35
+* Varargs support
  36
+* Type-safety for native pointers
  37
+* VM crash protection (optional)
  38
+* Optimized direct mapping for high-performance applications.
  39
+
  40
+Community
  41
+=========
  42
+
  43
+* TODO
  44
+
  45
+Using the Library
  46
+=================
  47
+
  48
+* [Getting Started](jna/tree/master/www/GettingStarted.md)
  49
+* [Mapping between Java and Native](jna/tree/master/www/Mappings.md)
  50
+* [Using Pointers and Arrays](jna/tree/master/www/PointersAndArrays.md)
  51
+* [Using Structures and Unions](jna/tree/master/www/StructuresAndUnions.md)
  52
+* [Using By-Reference Arguments](jna/tree/master/www/ByRefArguments.md)
  53
+* [Customization](jna/tree/master/www/Customization.md)
  54
+* [Callbacks/Closures](jna/tree/master/www/Callbacks.md)
  55
+* [JRuby/Jython Usage](jna/tree/master/www/JRubyJython.md)
  56
+* [Frequently Asked Questions (FAQ)](jna/tree/master/www/FAQ.md)
  57
+* [Direct Method Mapping](jna/tree/master/www/DirectMapping.md)
  58
+
  59
+Contributing 
  60
+============
  61
+
  62
+* TODO
  63
+
  64
+License
  65
+=======
  66
+
  67
+This library is provided under the LGPL, version 2.1 or later.
  68
+
  69
+*NOTE: Oracle is not sponsoring this project, even though the package name (com.sun.jna) might imply otherwise.*
  70
+
97  www/GettingStarted.md
Source Rendered
... ...
@@ -0,0 +1,97 @@
  1
+Getting Started with JNA
  2
+========================
  3
+
  4
+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.
  5
+
  6
+Begin by downloading the latest release of JNA and referencing `jna.jar` in your project's `CLASSPATH`.
  7
+
  8
+The following example maps the printf function from the standard C library and calls it. 
  9
+
  10
+    package com.sun.jna.examples;
  11
+
  12
+    import com.sun.jna.Library;
  13
+    import com.sun.jna.Native;
  14
+    import com.sun.jna.Platform;
  15
+
  16
+    /** Simple example of JNA interface mapping and usage. */
  17
+    public class HelloWorld {
  18
+
  19
+        // This is the standard, stable way of mapping, which supports extensive
  20
+        // customization and mapping of Java to native types.
  21
+
  22
+        public interface CLibrary extends Library {
  23
+            CLibrary INSTANCE = (CLibrary)
  24
+                Native.loadLibrary((Platform.isWindows() ? "msvcrt" : "c"),
  25
+                                   CLibrary.class);
  26
+
  27
+            void printf(String format, Object... args);
  28
+        }
  29
+
  30
+        public static void main(String[] args) {
  31
+            CLibrary.INSTANCE.printf("Hello, World\n");
  32
+            for (int i=0;i < args.length;i++) {
  33
+                CLibrary.INSTANCE.printf("Argument %d: %s\n", i, args[i]);
  34
+            }
  35
+        }
  36
+    }
  37
+
  38
+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.
  39
+
  40
+Make your target library available to your Java program. There are two ways to do this:
  41
+
  42
+* 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.
  43
+* 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.
  44
+
  45
+Declare a Java interface to hold the native library methods by extending the Library interface.
  46
+
  47
+Following is an example of mapping for the Windows kernel32 library.
  48
+
  49
+    package com.sun.jna.examples.win32;
  50
+
  51
+    import com.sun.jna.*;
  52
+
  53
+    // kernel32.dll uses the __stdcall calling convention (check the function
  54
+    // declaration for "WINAPI" or "PASCAL"), so extend StdCallLibrary
  55
+    // Most C libraries will just extend com.sun.jna.Library,
  56
+    public interface Kernel32 extends StdCallLibrary { 
  57
+        // Method declarations, constant and structure definitions go here
  58
+    }
  59
+
  60
+Within this interface, define an instance of the native library using the Native.loadLibrary(Class) method, providing the native library interface you defined previously.
  61
+
  62
+    Kernel32 INSTANCE = (Kernel32)
  63
+        Native.loadLibrary("kernel32", Kernel32.class);
  64
+    // Optional: wraps every call to the native library in a
  65
+    // synchronized block, limiting native calls to one at a time
  66
+    Kernel32 SYNC_INSTANCE = (Kernel32)
  67
+        Native.synchronizedLibrary(INSTANCE);
  68
+
  69
+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.
  70
+
  71
+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). 
  72
+
  73
+    public static class SYSTEMTIME extends Structure {
  74
+        public short wYear;
  75
+        public short wMonth;
  76
+        public short wDayOfWeek;
  77
+        public short wDay;
  78
+        public short wHour;
  79
+        public short wMinute;
  80
+        public short wSecond;
  81
+        public short wMilliseconds;
  82
+    }
  83
+
  84
+    void GetSystemTime(SYSTEMTIME result);
  85
+
  86
+You can now invoke methods on the library instance just like any other Java class.
  87
+
  88
+    Kernel32 lib = Kernel32.INSTANCE;
  89
+    SYSTEMTIME time = new SYSTEMTIME();
  90
+    lib.GetSystemTime(time);
  91
+
  92
+    System.out.println("Today's integer value is " + time.wDay);
  93
+
  94
+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.
  95
+
  96
+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.
  97
+
20  www/Mappings.md
Source Rendered
... ...
@@ -0,0 +1,20 @@
  1
+Default Type Mappings
  2
+=====================
  3
+
  4
+Java primitive types (and their object equivalents) map directly to the native C type of the same size.
  5
+
  6
+Native Type|Size|Java Type|Common Windows Types
  7
+char|8-bit integer|byte|BYTE, TCHAR
  8
+short|16-bit integer|short|WORD
  9
+wchar_t|16/32-bit character|char|TCHAR
  10
+int|32-bit integer|int|DWORD
  11
+int|boolean value|boolean|BOOL
  12
+long|32/64-bit integer|NativeLong|LONG
  13
+long long|64-bit integer|long|__int64
  14
+float|32-bit FP|float|
  15
+double|64-bit FP|double|
  16
+char*|C string|String|LPTCSTR
  17
+void*|pointer|Pointer|LPVOID, HANDLE, LPXXX
  18
+
  19
+Unsigned types use the same mappings as signed types. C enums are usually interchangeable with "int".
  20
+
16  www/PointersAndArrays.md
Source Rendered
... ...
@@ -0,0 +1,16 @@
  1
+Using Pointers and Arrays
  2
+=========================
  3
+
  4
+Primitive array arguments (including structs) are represented by their corresponding Java types. For example:
  5
+ 
  6
+    // Original C declarations
  7
+    void fill_buffer(int *buf, int len);
  8
+    void fill_buffer(int buf[], int len); // same thing with array syntax
  9
+
  10
+    // Equivalent JNA mapping
  11
+    void fill_buffer(int[] buf, int len);
  12
+
  13
+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.
  14
+
  15
+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.
  16
+
12  www/StructuresAndUnions.md
Source Rendered
... ...
@@ -0,0 +1,12 @@
  1
+Using Structures And Unions
  2
+===========================
  3
+
  4
+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.
  5
+
  6
+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.
  7
+
  8
+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.
  9
+
  10
+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.
  11
+
  12
+
792  www/index.html
... ...
@@ -1,792 +0,0 @@
1  
-<html>
2  
- <head>
3  
-  <link rel="stylesheet" type="text/css" href="style.css" />
4  
-  <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">
5  
-  <meta name="description" content="Java Native Access (JNA): access native libraries with pure Java code.">
6  
-  <meta name="date" content="2010-07-16">
7  
-  <title>Java Native Access (JNA): Pure Java Access to Native Libraries</title>
8  
-  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
9  
-</head>
10  
-<body>
11  
- <h2>Java Native Access (JNA)</h2>
12  
- <a name=top></a>
13  
- <img src="images/jnalogo.jpg" align="right" style="margin-right: 20px">
14  
- <ul>
15  
-  <li><a href="http://java.net/projects/jna/downloads/directory">Download</a>
16  
-  <li><a href="http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html">License (LGPLv2)</a>
17  
-  <li><a href="release-notes.html">Release Notes</a>
18  
-  <li><a href="http://java.net/projects/jna/sources/svn/show">Source Code</a>
19  
-  <li><a href="#features">Features</a>
20  
-  <li><a href="#demos">Demos</a>
21  
-  <li><a href="#platform">Platform Library</a></li>
22  
-  <li><a href="#community">Community and Support</a>
23  
-  <li><a href="#projects">Projects</a>
24  
-  <li><a href="#development">Development</a>&nbsp;&nbsp;&nbsp;
25  
-  <li><a href="#building">Building</a>
26  
-  <li><a href="#history">History</a>
27  
- </ul>
28  
- <h2>What is JNA?</h2>
29  
- <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>
30  
- <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>
31  
- <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>
32  
- <p>While some attention is paid to performance, correctness and ease of use take priority.</p>
33  
- <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>
34  
- <h2>Using the Library</h2>
35  
- <ul>
36  
-  <li><a href="#getting_started">Getting&nbsp;Started</a>
37  
-  <li><a href="javadoc/overview-summary.html">API Documentation (JavaDoc)</a>
38  
-  <li><a href="#mapping">Mapping&nbsp;between&nbsp;Java&nbsp;and&nbsp;Native</a>
39  
-  <li><a href="#pointers">Using&nbsp;Pointers&nbsp;and&nbsp;Arrays</a>
40  
-  <li><a href="#structures">Using&nbsp;Structures&nbsp;and&nbsp;Unions</a>
41  
-  <li><a href="#byref">Using&nbsp;By-reference&nbsp;Arguments</a>
42  
-  <li><a href="#customize">Customization</a>
43  
-  <li><a href="#callbacks">Callbacks/Closures</a>
44  
-  <li><a href="#dynamic">JRuby/Jython&nbsp;Usage</a>
45  
-  <li><a href="#faq">Frequently&nbsp;Asked&nbsp;Questions&nbsp;(FAQ)</a>
46  
-  <li><a href="#direct">Direct method mapping</a>
47  
- </ul>
48  
-<hr>
49  
-The <a href="http://jna.java.net/javadoc/overview-summary.html">JavaDoc is available online</a>,
50  
-which includes detailed descriptions of JNA usage in different situations.<p>
51  
-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.
52  
-<p>
53  
-<b>NOTE: Sun is <em>not</em> sponsoring this project, even though the package name (<code>com.sun.jna</code>) might imply otherwise.</b>
54  
-<hr>
55  
-<a href=#top>Top</a>
56  
-<a name=features></a>
57  
-<h3>Features</h3>
58  
-<ul>
59  
-<li>Automatic mapping from Java to native functions, with simple mappings for all primitive data types
60  
-<li>Runs on <a href="#building">most platforms which support Java</a>
61  
-<li>Automatic conversion between C and Java strings, with customizable encoding/decoding
62  
-<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
63  
-<li>Function Pointers, (callbacks from native code to Java) as arguments and/or members of a <code>struct</code>
64  
-<li>Auto-generated Java proxies for native function pointers
65  
-<li>By-reference (pointer-to-type) arguments 
66  
-<li>Java array and NIO <code>Buffer</code> arguments (primitive types and pointers) as pointer-to-buffer
67  
-<li>Nested structures and arrays
68  
-<li>Wide (<code>wchar_t</code>-based) strings
69  
-<li><a href="javadoc/com/sun/jna/NativeLong.html">Native <code>long</code></a> support (32- or 64-bit as appropriate)
70  
-<li><a href="#demos">Demo applications</a>
71  
-<li>Supported on 1.4 or later JVMs (earlier VMs may work with stubbed NIO support)
72  
-<li>Customizable marshalling/unmarshalling (argument and return value conversions)
73  
-<li>Customizable mapping from Java method to native function name, and customizable invocation to simulate C preprocessor function macros
74  
-<li>Support for automatic Windows ASCII/UNICODE function mappings
75  
-<li>Varargs support
76  
-<li><a href="javadoc/com/sun/jna/PointerType.html">Type-safety for native pointers</a>
77  
-<li><a href="javadoc/com/sun/jna/Native.html#setProtected(boolean)">VM crash protection</a> (optional)
78  
-<li>Optimized <a href='#direct'>direct mapping</a> for high-performance applications.
79  
-</ul>
80  
-<p>
81  
-
82  
-<a href=#top>Top</a>
83  
-<a name=getting_started></a>
84  
- <h3>How To Get Started Using JNA</h3>
85  
- <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>
86  
-<ol>
87  
-  <li>Download <code>jna.jar</code> from the <a href="http://jna.java.net/projects/jna/downloads">download page</a>.</li>
88  
-  <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>
89  
-<blockquote><pre><code>
90  
-package com.sun.jna.examples;
91  
-
92  
-import com.sun.jna.Library;
93  
-import com.sun.jna.Native;
94  
-import com.sun.jna.Platform;
95  
-
96  
-/** Simple example of JNA interface mapping and usage. */
97  
-public class HelloWorld {
98  
-
99  
-    // This is the standard, stable way of mapping, which supports extensive
100  
-    // customization and mapping of Java to native types.
101  
-    public interface CLibrary extends Library {
102  
-        CLibrary INSTANCE = (CLibrary)
103  
-            Native.loadLibrary((Platform.isWindows() ? "msvcrt" : "c"),
104  
-                               CLibrary.class);
105  
-    
106  
-        void printf(String format, Object... args);
107  
-    }
108  
-
109  
-    public static void main(String[] args) {
110  
-        CLibrary.INSTANCE.printf("Hello, World\n");
111  
-        for (int i=0;i < args.length;i++) {
112  
-            CLibrary.INSTANCE.printf("Argument %d: %s\n", i, args[i]);
113  
-        }
114  
-    }
115  
-}
116  
-</code></pre></blockquote>
117  
-  <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>
118  
-  <li>Make your target library available to your Java program. There are two ways to do this:
119  
-    <ul>
120  
-      <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> 
121  
-      <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>
122  
-    </ul>
123  
-  </li>
124  
-  <li>Declare a Java interface to hold the native library methods by extending
125  
-    the <a href="javadoc/com/sun/jna/Library.html"><code>Library</code></a>
126  
-    interface.<p> 
127  
-Following is an example of mapping for the Windows kernel32 library.<br>
128  
-    <blockquote><pre><code>
129  
-package com.sun.jna.examples.win32;
130  
-
131  
-import com.sun.jna.*;
132  
-
133  
-// kernel32.dll uses the __stdcall calling convention (check the function
134  
-// declaration for "WINAPI" or "PASCAL"), so extend StdCallLibrary
135  
-// Most C libraries will just extend com.sun.jna.Library,
136  
-public interface Kernel32 extends StdCallLibrary { 
137  
-    // Method declarations, constant and structure definitions go here
138  
-}</code></pre></blockquote>
139  
-  </li>
140  
-  <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>    
141  
-    <blockquote><pre><code>
142  
-    Kernel32 INSTANCE = (Kernel32)
143  
-        Native.loadLibrary("kernel32", Kernel32.class);
144  
-    // Optional: wraps every call to the native library in a
145  
-    // synchronized block, limiting native calls to one at a time
146  
-    Kernel32 SYNC_INSTANCE = (Kernel32)
147  
-        Native.synchronizedLibrary(INSTANCE);
148  
-</code></pre></blockquote><br>
149  
-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.
150  
-  </li>
151  
-  <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).
152  
-    <br>
153  
-    <blockquote><pre><code>
154  
-public static class SYSTEMTIME extends Structure {
155  
-    public short wYear;
156  
-    public short wMonth;
157  
-    public short wDayOfWeek;
158  
-    public short wDay;
159  
-    public short wHour;
160  
-    public short wMinute;
161  
-    public short wSecond;
162  
-    public short wMilliseconds;
163  
-}
164  
-
165  
-void GetSystemTime(SYSTEMTIME result);
166  
-    </code></pre></blockquote>
167  
-  </li>
168  
-  <li>You can now invoke methods on the library instance just like any other Java class. 
169  
-  	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> 
170  
-  	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.
171  
-    <br>
172  
-    <blockquote><pre><code>
173  
-Kernel32 lib = Kernel32.INSTANCE;
174  
-SYSTEMTIME time = new SYSTEMTIME();
175  
-lib.GetSystemTime(time);
176  
-System.out.println("Today's integer value is " + time.wDay);
177  
-</code></pre></blockquote>
178  
-  </li>
179  
-<li>Alternatively, you may declare a class to hold your native
180  
-    methods, declare any number of methods with the "native" qualifier,
181  
-    and invoke <code>Native.register(String)</code> in the class static
182  
-    initializer with your library's name.  See <a href='#direct'>JNA direct
183  
-    mapping</a> for an example.<p>
184  
-</li>
185  
-</ol>
186  
-If the C header files for your library are available, you can auto-generate a
187  
-library mapping by using Olivier Chafik's
188  
-excellent <a href="http://jnaerator.googlecode.com/">JNAerator</a> utility.
189  
-This is especially useful if your library uses long or complicated structures
190  
-where translating by hand can be error-prone.
191  
-<p>
192  
-See the <a href="javadoc/overview-summary.html#overview">JavaDoc overview</a> for more detailed information about JNA usage.<p>
193  
-
194  
-
195  
-<a href=#top>Top</a>
196  
-<a name=mapping></a>
197  
-<h3>Default Type Mappings</h3>
198  
-Java primitive types (and their object equivalents) map directly to the native C type of the same size.
199  
-<blockquote><table cols=4>
200  
-<thead><td>Native Type</td><td>Size</td><td>Java Type</td><td>Common Windows Types</td></thead>
201  
-<tr><td>char</td><td>8-bit integer</td><td>byte</td><td>BYTE, TCHAR</td>
202  
-<tr><td>short</td><td>16-bit integer</td><td>short</td><td>WORD</td>
203  
-<tr><td>wchar_t</td><td>16/32-bit character</td><td>char</td><td>TCHAR</td>
204  
-<tr><td>int</td><td>32-bit integer</td><td>int</td><td>DWORD</td>
205  
-<tr><td>int</td><td>boolean value</td><td>boolean</td><td>BOOL</td>
206  
-<tr><td>long</td><td>32/64-bit integer</td><td>NativeLong</td><td>LONG</td>
207  
-<tr><td>long long</td><td>64-bit integer</td><td>long</td><td>__int64</td>
208  
-<tr><td>float</td><td>32-bit FP</td><td>float</td><td></td>
209  
-<tr><td>double</td><td>64-bit FP</td><td>double</td><td></td>
210  
-<tr><td>char*</td><td>C string</td><td>String</td><td>LPTCSTR</td>
211  
-<tr><td>void*</td><td>pointer</td><td>Pointer</td><td>LPVOID, HANDLE, LP<i>XXX</i></td>
212  
-</table></blockquote>
213  
-Unsigned types use the same mappings as signed types.  C enums are usually
214  
-interchangeable with "int".  A more comprehensive list of mappings may be
215  
-found <a href="javadoc/overview-summary.html#marshalling">here</a>.   
216  
-<p>
217  
-
218  
-<a href=#top>Top</a>
219  
-<a name=pointers></a>
220  
-<h3>Using Pointers and Arrays</h3>
221  
-Primitive array arguments (including <code>struct</code>s) are represented by their corresponding Java types.  For example:
222  
-<blockquote>
223  
-    <blockquote><pre><code>
224  
-// Original C declarations
225  
-void fill_buffer(int *buf, int len);
226  
-void fill_buffer(int buf[], int len); // same thing with array syntax
227  
-
228  
-// Equivalent JNA mapping
229  
-void fill_buffer(int[] buf, int len);
230  
-</code></pre></blockquote>
231  
-</blockquote>
232  
-<p>
233  
-NOTE: if the parameter is to be used by the native function outside the
234  
-scope of the function call, you <em>must</em> use <code>Memory</code> or an
235  
-NIO Buffer.  The memory provided by a Java primitive array will only be valid
236  
-for use by the native code for the duration of the function call.
237  
-<p>
238  
-Arrays of C strings (the <code>char* argv[]</code> to the C <code>main</code>,
239  
-for example), may be represented by <code>String[]</code> in Java code.  JNA
240  
-will pass an equivalent array with a NULL final element.
241  
-<p>
242  
-
243  
-<a href=#top>Top</a>
244  
-<a name=structures></a>
245  
-<h3>Using Structures/Unions</h3>
246  
-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>
247  
-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.  
248  
-<p>
249  
-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.
250  
-<p>
251  
-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.
252  
-<p>
253  
-
254  
-<a href=#top>Top</a>
255  
-<a name=byref></a>
256  
-<h3>Using By-reference Arguments</h3>
257  
-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>
258  
-<blockquote>
259  
-    <blockquote><pre><code>
260  
-// Original C declaration
261  
-void allocate_buffer(char **bufp, int* lenp);
262  
-
263  
-// Equivalent JNA mapping
264  
-void allocate_buffer(PointerByReference bufp, IntByReference lenp);
265  
-
266  
-// Usage
267  
-PointerByReference pref = new PointerByReference();
268  
-IntByReference iref = new IntByReference();
269  
-lib.allocate_buffer(pref, iref);
270  
-Pointer p = pref.getValue();
271  
-byte[] buffer = p.getByteArray(0, iref.getValue());
272  
-    </code></pre></blockquote>
273  
-</blockquote>
274  
-
275  
-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>
276  
-
277  
-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.
278  
-<p>
279  
-Type-safe pointers may be declared by deriving from the <a href="javadoc/com/sun/jna/PointerType.html"><code>PointerType</code></a> class.
280  
-<p>
281  
-
282  
-<a href=#top>Top</a>
283  
-<a name=customize></a>
284  
-<h3>Customized Mapping from Java to Native (Types and Function Names)</h3>
285  
-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>.
286  
-<p>
287  
-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.
288  
-<p>
289  
-<a name=stdcallmapper></a>
290  
-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.
291  
-<p>
292  
-Refer to <a href="javadoc/overview-summary.html#marshalling">this table in the
293  
-overview</a> for a complete list of built-in type mappings.
294  
-<p>
295  
-
296  
-<a href=#top>Top</a>
297  
-<a name=callbacks></a>
298  
-<h3>Callbacks/Closures (Function Pointers)</h3>
299  
-Callback declarations consist of a simple interface that extends the <a href="javadoc/com/sun/jna/Callback.html">Callback</a>
300  
-interface and implements a <code>callback</code> method (or defines a single
301  
-method of arbitrary name).  Callbacks are
302  
-implemented by wrapping a Java object method in a little bit of C glue code.
303  
-The simplest usage resembles using anonymous inner classes to register event
304  
-listeners.  Following is an example of callback usage:<br> 
305  
-<blockquote>
306  
-    <blockquote><pre><code>
307  
-// Original C declarations
308  
-typedef void (*sig_t)(int);
309  
-sig_t signal(sig_t);
310  
-
311  
-// Equivalent JNA mappings
312  
-public interface CLibrary extends Library {
313  
-    int SIGUSR1 = 30;
314  
-    interface sig_t extends Callback {
315  
-        void invoke(int signal);        
316  
-    }
317  
-    sig_t signal(int sig, sig_t fn);
318  
-    int raise(int sig);
319  
-}
320  
-...
321  
-CLibrary lib = (CLibrary)Native.loadLibrary("c", CLibrary.class);
322  
-// WARNING: you must keep a reference to the callback object
323  
-// until you deregister the callback; if the callback object
324  
-// is garbage-collected, the native callback invocation will
325  
-// probably crash.
326  
-CLibrary.sig_t fn = new CLibrary.sig_t() {
327  
-    public void invoke(int sig) {
328  
-        System.out.println("signal " + sig + " was raised");
329  
-    }
330  
-};
331  
-CLibrary.sig_t old_handler = lib.signal(CLibrary.SIGUSR1, fn);
332  
-lib.raise(CLibrary.SIGUSR1);
333  
-...
334  
-</code></pre></blockquote>
335  
-</blockquote>
336  
-
337  
-Here is a more involved example, using the w32 APIs to enumerate all native windows:
338  
-<blockquote>
339  
-    <blockquote><pre><code>
340  
-// Original C declarations
341  
-typedef int (__stdcall *WNDENUMPROC)(void*,void*);
342  
-int __stdcall EnumWindows(WNDENUMPROC,void*);
343  
-
344  
-// Equivalent JNA mappings
345  
-public interface User32 extends StdCallLibrary {
346  
-    interface WNDENUMPROC extends StdCallCallback {
347  
-        /** Return whether to continue enumeration. */
348  
-        boolean callback(Pointer hWnd, Pointer arg);
349  
-    }
350  
-    boolean EnumWindows(WNDENUMPROC lpEnumFunc, Pointer arg);
351  
-}
352  
-...
353  
-User32 user32 = User32.INSTANCE;
354  
-
355  
-user32.EnumWindows(new WNDENUMPROC() {
356  
-    int count;
357  
-    public boolean callback(Pointer hWnd, Pointer userData) {
358  
-        System.out.println("Found window " + hWnd + ", total " + ++count);
359  
-        return true;
360  
-    }
361  
-}, null);
362  
-</code></pre></blockquote>
363  
-</blockquote>
364  
-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>
365  
-
366  
-Proxy wrappers are automatically generated for function pointers found within structs initialized by native code.  This facilitates calling those functions from Java.<p>
367  
-
368  
-<a href=#top>Top</a>
369  
-<a name=dynamic></a>
370  
-<h3>Invocation from Dynamically-Typed Languages</h3>
371  
-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>
372  
-Here's a brief example of using JNA from JRuby:
373  
-<blockquote>
374  
-    <blockquote><pre><code>
375  
-require 'java'
376  
-
377  
-module Libc
378  
-  @@lib = com.sun.jna.NativeLibrary.getInstance("c")
379  
-  @@ptr_funcs = [ 'fopen', 'malloc', 'calloc' ]
380  
-  def self.method_missing(meth, *args)
381  
-    if @@ptr_funcs.include?(meth.to_s)
382  
-      @@lib.getFunction(meth.to_s).invokePointer(args.to_java)
383  
-    else
384  
-      @@lib.getFunction(meth.to_s).invokeInt(args.to_java)
385  
-    end
386  
-  end
387  
-  O_RDONLY = 0
388  
-  O_WRONLY = 1
389  
-  O_RDWR = 2
390  
-end
391  
-
392  
-Libc.puts("puts from libc")
393  
-Libc.printf("Hello %s, from printf\n", "World")
394  
-
395  
-file = Libc.open("/dev/stdout", 1, Libc::O_WRONLY)
396  
-n = Libc.write(file, "Test\n", 5)
397  
-puts "Wrote #{n} bytes via Libc"
398  
-
399  
-path = "/dev/stdout"
400  
-fp = Libc.fopen(path, "w+")
401  
-Libc.fprintf(fp, "fprintf to %s via stdio\n", path)
402  
-Libc.fflush(fp)
403  
-Libc.fclose(fp)
404  
-</code></pre></blockquote></blockquote>
405  
-<p>
406  
-<a href=#top>Top</a>
407  
-<a name=platform></a>
408  
-<h3>Platform Library</h3>
409  
-<p>
410  
-JNA includes <code>platform.jar</code> that has cross-platform mappings and mappings for a number of 
411  
-commonly used platform functions, including a large number of Win32 mappings as well as a set of utility
412  
-classes that simplify native access. The code is tested and the utility interfaces ensure that
413  
-native memory management is taken care of correctly.
414  
-</p>
415  
-<p>
416  
-Before you map your own functions, check the 
417  
-<a href="javadoc/platform/overview-summary.html">platform package documentation</a> for an already mapped one.
418  
-</p>
419  
-<p>
420  
-Platform-specific structures are mapped by header. For example, <code>ShlObj.h</code> structures can
421  
-be found in <code>com.sun.jna.platform.win32.ShlObj</code>. Platform functions are mapped by 
422  
-library. For example, <code>Advapi32.dll</code> functions can be found in <code>com.sun.jna.platform.win32.Advapi32</code>. 
423  
-Simplified interfaces (wrappers) for <code>Advapi32.dll</code> functions can be found in 
424  
-<code>com.sun.jna.platform.win32.Advapi32Util</code>.
425  
-</p>
426  
-<p>
427  
-Cross-platform functions and structures are implemented in <code>com.sun.jna.platform</code>. These 
428  
-currently include the following.
429  
-<ul>
430  
- <li><code>FileMonitor</code>: a cross-platform file system watcher</li>
431  
- <li><code>FileUtils</code>: a cross-platform set of file-related functions, such as move to the recycle bin</li>
432  
- <li><code>KeyboardUtils</code>: a cross-platform set of keyboard functions, such as finding out whether a key is pressed</li>
433  
- <li><code>WindowUtils</code>: a cross-platform set of window functions, providing non-rectangular shaped and transparent windows</li>
434  
-</ul>
435  
-</p>
436  
-<a href=#top>Top</a>
437  
-<a name=faq></a>
438  
-<h3>Frequently Asked Questions (FAQ)</h3>
439  
-<ul>
440  
-<li><a href="#structure_use">Should I use Structure.ByReference, Structure.ByValue, or Structure[]?</a>
441  
-<li><a href="#char_buffer">How do I read back a string?</a>
442  
-<li><a href="#native_long">How do I map a native <code>long</code> type?</a>
443  
-<li><a href="#w32link">My library mapping causes an UnsatisfiedLinkError</a>
444  
-<li><a href="#crash">My library sometimes causes a VM crash</a>
445  
-<li><a href="#w32crash">My Windows library mapping causes a VM crash on every call</a>
446  
-<li><a href="#ptr_values">How do I get an arbitrary Pointer value?</a>
447  
-<li><a href="#struct_debug">My structure has the wrong contents.  What did I do wrong?</a>
448  
-<li><a href="#j2me">Does JNA work with J2ME/Windows Mobile?</a>
449  
-<li><a href="#performance">How does JNA performance compared to custom JNI?</a>
450  
-<li><a href="#osx">I get an UnsatisfiedLinkError on OSX trying to include my custom library via Java Web Start</a>
451  
-<li><a href="#COM">I need to use a COM/OCX/ActiveX object.  Can JNA help me?</a>
452  
-<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>
453  
-</ul>
454  
-<a name=structure_use></a>
455  
-<h4>When should I use Structure.ByReference? Structure.ByValue? Structure[]?</h4>
456  
-Find your corresponding native declaration below:
457  
-<blockquote><pre><code>
458  
-typedef struct _simplestruct {
459  
-  int myfield;
460  
-} simplestruct;
461  
-
462  
-typedef struct _outerstruct {
463  
-  simplestruct nested; // use Structure
464  
-} outerstruct;
465  
-
466  
-typedef struct _outerstruct2 {
467  
-  simplestruct *byref; // use Structure.ByReference
468  
-} outerstruct2;
469  
-
470  
-typedef struct _outerstruct3 {
471  
-  simplestruct array[4]; // use Structure[]
472  
-} outerstruct3;
473  
-
474  
-typedef struct _outerstruct4 {
475  
-  simplestruct* ptr_array[4]; // use Structure.ByReference[]
476  
-} outerstruct4;
477  
-
478  
-// Field is a pointer to an array of struct
479  
-typedef struct _outerstruct5 {
480  
-  simplestruct* ptr_to_array; // use Structure.ByReference, and use
481  
-                              // Structure.toArray() to allocate array
482  
-} outerstruct5;
483  
-
484  
-// struct pointers as return value or argument
485  
-// use Structure
486  
-outerstruct *myfunc(); 
487  
-void myfunc(outerstruct* data);
488  
-
489  
-// struct (by value) as return value or argument
490  
-// use Structure.ByValue
491  
-simplestruct myfunc();
492  
-void myfunc(simplestruct);