jna/TODO

# DESIGN GOALS/REQUIREMENTS
  o no permanent references to java objects in native code (hard to get rid of)
    this means no java object arguments to callbacks; use some sort of integer
    key instead (hashcode?) callbacks can hold local data anyway...
  o make simplest Java usage map to most common C usage
    - additional constructs provided for less-common cases
      (WString,Structure.ByValue/ByReference)
  o structure is treated as a pointer, except within a struct
  o primitive types are passed directly
  o arrays are treated as pointers, except within a struct
    - in structure (inline; otherwise pointer-to-X should be used)
    - as function argument (auto-convert to pointer via Memory)
  o pointer to type in struct should use PointerType or Structure.ByReference
  o "free" should be invisible wherever possible

# FUTURE DEMOS:
* test keyboard keys' state (needs OSX impl)
* get system process information, basic process control
* additional file utilities (meta info, free space, etc)
* enforce window minimum/maximum size (workaround java bug)

# TODO

* annotations/generics:
  o GetPrimitiveArrayCritical: use this if flagged (by annotation? method name?)
  o per-arg/return type marshalling
  o avoid casts in loadLibrary
  o wrap global variables w/type (set/get)
  o support annotations of parameters and return values w/o breaking
    1.4 compatibility (retroweaver?), e.g.
    -- retroweaver (requires retroweaver runtime classes to provide annotation
    features) not yet worth doing

    void my_function(@MarshalAs(off_t)long arg);

    trading off cruft in the interface def to avoid cruft in the usage:

    my_function(0) versus my_function(new off_t(0))
  
    this only really applies to NativeLong/IntegerType types that want to use a
    primitive value instead of creating an object instance.
  o flag string(/wstring)-returning methods which need to free their result
   to avoid leaking memory whan auto-creating strings from the result
   (since normally we don't take explicit ownership of any returned pointers)
   this is a special case for returned strings only, since other returned
   pointers are available to the user for later "freeing"
   Use a map on library creation, an iface for the library, or annotation
   NOTE: how many methods actually do this? strdup...
   Maybe make function return "Memory", which can then be converted to a
   Structure or some other type.  Then memory will free itself when no longer
   referenced. (not really common)


* eliminate type conversion contexts; these are almost entirely unused and
  more complicated than just wrapping a native mapping in a utility function
* direct non-primitive array arguments (String[], Pointer[], NativeMapped[])

* auto-generate direct mappings/bindings on a per-method basis (perform a
  method register on first call to an interface-mapped function) with
  sufficient pre-processing to convert to primitives.

* dispose memory/callbacks in Native finalizer to ensure they run first
  (use referencequeue to run them when they become unreachable)

* make direct calls call back *once* to Java where conversion is required,
  and process all arguments from there (instead of potentially swapping back
  and forth multiple times).  This also makes it easer to perform conversions
  (no native changes required).  

* ppc64 direct/raw failures (multiple)
* direct calls on ppc to varargs (callbacks) with FP args fail; avoid them for
  now 
* Callback.PostCallWrite.write() cf PostCallRead

* universal GCC build w/cross-compile (needs cross compilers...)
* return Pointer.SIZE/LONG_SIZE/WCHAR_SIZE in bits (for consistency with 1.5)
  Long.SIZE, Integer.SIZE, et al.
* interface "lvalue", which can provide a pointer to itself (reference() or
  addressOf())?
* bitfields for structs (how?)


# DONE
* combine direct and interface mapping calling code where possible
* DOCS: how to properly use W32API_DEFAULT_OPTIONS (A/W, String/WString)
* make native dll extraction from jar public, to use with user dlls packaged
  in a jar
* use consistent cpu references (x86->i386, x86_64->amd64)
* osgi for osx
* NO: make Pointer free-able (system allocates memory, client frees it); actually,
  this should probably be automatic so the user doesn't have to think about it.
  Maybe a custom type representing "function-allocated-pointer" or
  "pointer-requiring-free" (which is just Memory).  For now, leave it up to
  the user to manage the pointer, since they have to define the free method
  anyway.  use could always put a finalizer on a PointerType-derived type.
  - user can do this explicitly if needed
* NO: use libffi java raw? (deprecated)
* NO: MethodArgument/ReturnMapper: per method mapping of arguments/return type.
  Can use annotations as shorthand to initialize a map, but basically set up a
  per-NativeLibrary (or per-Function?) map of methods to mappers.

  Requires separate compilation of annotation handling.
* NO: packaging: 'types', 'convert/marshal' subpackages?
  note: marshal/unmarshal vs to/fromnative: to/fromnative is more
  explicit, since marshal/unmarshal doesn't indicate src/dst.
  o moving conversion contexts to subpackage cleans up top level
  substantially, but we probably don't want to move things like Structure and
  Pointer into a types subpackage (which would leave just a few top-level
  classes).  Javadoc is cluttered by example classes anyway.
* cache structure information per-class
* fix setFieldOrder to *always* apply if used
* Make a separate jar file for all OS-specific headers
  Maybe make interfaces per-header file (winbase, winnt, stdlib, etc),
  aggregated per-library (interface CLibrary extends stdlib, stdio, etc)
  (how useful would it really be, or is this just sorting legos?)
  o same for windowutils, fileutils, etc. (not useful)
* check Structure "final" fields; should never write back to native memory
* OSX ObjC access (see rococoa)
* do Structure.write for any callback args
* pointer.setValue(), to handle NativeMapped types and move read/writeValue
  methods out of Structure, to be used by Function w/NativeMapped[] parameter

* if method has "GetLastErrorException/ErrnoException" in its signature, use
  result codes + GetLastError/errno/errstr to auto-generate 
  runtime exceptions? (cf P/Invoke; also useful for X11 return types)
  provide annotation/custom invocation handler/hook to examine return value and
  throw an exception if the return value indicates an error

  o are error return values consistent (if so, a single handler works)?
    if null -> call GetLastError
    if nonzero ?
  o otherwise, need an ExceptionOnZero, ExceptionOnNonZero runtime, from which
  derive GetLastError/ErrnoExceptionOnZero/NZ
* verify get/set methods vs read/write for performance (Pointer)?
  (see RawTest for performance comparisons)
* Allow Buffer in Structures (and callbacks) (auto-wrap in direct byte buffer)?
  o this gets tricky when reading structs from native memory; we don't know if
  the value is already mapped to a buffer (cf CallbackReference)
* standard types for various platforms: posix/types.h, w32 (DWORD, HANDLE)

* embed version in DLL ('depends'-done)/so (symlink?)
* use libffi closure allocation/deallocation

* ensure Library options are passed to NativeFunctionHandler
  (needs getLibraryOptions(Class cls))

* handle array of Structure.ByReference as parameter/return value (cf Pointer[])
* test performance of setByte/getByte and pass pointer field directly if it
  makes sense to do so (done, halves access time to use pointer field directly,
  slight variations on 1.4/1.5/1.6).
* test callback arg/return value for callback type 
* structure by value in callback

* call native to fix up FFIType on creation (avoid multithreading problems)
  properly handle union by value (or punt; must pass union field instead)

* hash javah-generated headers; when changed, invalidate platform-specific

* add main class which spits out version information
  
* docs: split pages: FAQ
  FAQ: J2ME, new platform builds, stdcall

* struct by reference within structure
* struct by value
  (how to do struct value return (vs struct pointer) (uncommon)?)
  (how to do struct value argument (vs struct pointer) (uncommon)?) 
* use appropriate size_t and off_t sizes (use long offsets everywhere in
  Pointer) 
* Callback/function pointer as return value (e.g. signal())
* type safety between returned and passed in pointers (w32 API); advantage of
  deriving from Pointer is that type mapping can be made automatic, without an
  explicit type mapping defined.
* catch native crash/exception/faults and re-throw as java exception
  this is mostly for debugging a new mapping to avoid crashing the VM
  could do setjmp/longjmp on *nix and catch C++ exception on w32
* NativeMapped: provide interface to automatically convert custom Java
  type to/from native types. 
* update X11 libs for 64-bit
* use libffi from gcc to handle calls and callbacks?
  or move callback asm templates into dispatch_<arch>.c
* more tests for argument types (2 args, all permutations of basic data types)
   ensures native stack handling is done properly (handled by libffi)
* universal OSX build w/cross-compile (hard to do with libffi)
* use jna.encoding property to affect string encoding instead of just using
  the system default encoding.
* change/augment getWindowHandle0 to provide any heavyweight component window
* unions (copy-on-call is problematic: which member is active?) must require
  explicit write, either per member or whole object before export
* rename Argument/Result Converter to be fromNative/toNative
* split unit tests
* auto-convert struct pointers in callback args to Java Structure
  (may need a proxy wrapper around callback to avoid excessive JNI)
  use proxy for callbacks to enable auto-conversion of arguments and/or return
  value (in java-land instead of C-land). 
* review/use refactor nativelibrary/function
* auto-generate stdcall decorated symbols (try if undecorated lookup fails)
* per-library jna.library.path: many libraries have a "standard" location (or
  several); let the library author indicate what these are (X11, for example)
* return array of struct (annotation to indicate which argument has the
  length of the returned value might be nice) (this can now be done with a
  type mapper)
* callbacks need a dispose if they are to live beyond the lifetime of the
function to which they are passed; maybe a simpler callback interface for
transient callbacks, and require callback+dispose for most callbacks?
  TransientCallback: callback
  NonTransientCallback: callback+dispose
  (callback is disposed when no longer referenced; user must ensure callback
  is not GC'd until it is removed as a native callback)
* auto-convert strings in w32 functions ending in 'W'?  would this introduce
  any ambiguity?
* Dispose/unload library on GC (use ref queue)
* fix dnd on linux (no hole?) (mostly fixed, still some artifacts)
* transparent/shaped drag image
* windows handles need to be Pointer (void*), not 'int'
* other demos: move to trash, file change notification
* tests for other primitive array types
* build test dll/dispatch lib w/cygwin/gcc instead of msvc (?) under w32
* nested struct alignment (4/8 byte?  depends on first element?)
* nested structs in structs: easier to define using struct; use pointer
   if you need a pointer
   struct auto-converts to pointer as argument, should be inline in struct
   (struct should require explicit pointer, argument should require explicit
   non-pointer) (maybe use object version of basic type as "pointer" version)
* provide JNA-only search path for libraries
* callbacks
* move javah-generated files to own space
* darwin/PPC asm layer
* enable w32 build with either GCC or MSVC (GCC-built dll doesn't work yet)
* support pointer to basic type argument (int *) w/type safety - what's the
   best API from a user perspective? new Pointer(int)? new Pointer<int>?
   Base class "pointer to" gets converted to Pointer in invocation handler;
   provide a getValue() to retrieve the result; otherwise the memory is opaque

  o IntPtr, WCharPtr, CharPtr, ShortPtr, LongPtr, DoublePtr, FloatPtr, 
    Handle (PtrPtr), getValue(), getPointer()
  o add getCharArray() et al. to Pointer?

* inline arrays of primitive types
* remove debug flags (they're not useful)
* Use WString to identify return type and arg
* use interface to identify native, instead of annotation
* isolate stdcall to w32 (should be private to platform)
* generic gcc build/osx(ppc/x86)/linux
* remove generics/enable build under 1.4
* tests for structs
* test float/double
* offset placeholders for structs (explicit alignment)
* vanilla ant build file
* build native stuff from build.xml
* implement basic junit tests
* auto-align struct fields
* handle long/byte/short
* make annotations for native method names optional
// hard clip for now, alpha transparency later
// also allow ImageIcon to be used as clip (getImage())
void setWindowMask(Window w, Shape clip);
// needs:
int findNativeWindow(Window w);

#MAYBE NOT
* should structure offsets be 64-bit? technically yes, but in practice I don't
  think a structure that big actually works.
* (maybe) move all native functions into Native (limit header files, easier
  management) 
* Does it make sense to define Int16/UInt16, Int32/UInt32, etc?  Probably not
  the signed versions, but maybe the unsigned ones, to facilitate generating
  unsigned values (maybe just provide utilities to pack an unsigned int into a
  signed int).  What about size_t, off_t, et al.?  Would either need a
  bunch of native lookup functions (more accurate) or java-side conditionals
  (less robust but easier to change).
  o bounds checking is handled by IntegerType (pass in a long, get an
    exception if the value is out of bounds).
  o when used as struct fields, could allow detection of field order by order
    of initialization (requires all-or-nothing usage, though)
* StringBuffer/StringBuilder as mutable char*/wchar_t* argument
  NOTE: byte[]/char[] is probably better; it's trivial to convert to String
  and native code can't change the size anyway
* provide library load/unload hooks (Runnables in options?). Examples:
  o GetLastError (no longer needed)
  o WSAInit?
* determine X11 display name from current java program (if any); null is ok
  since it uses getenv(DISPLAY), which is what java would do
  note: DISPLAY may be available in GraphicsDevice->getIDstring