InvocationMapper (JNA API)

com.sun.jna

## Interface InvocationMapper

-     public interface InvocationMapper

  Provide a method for overriding how a given function is invoked. An instance of this interface may be provided to `Native.loadLibrary(String, Class, java.util.Map)` as an entry in the options map with key `Library.OPTION_INVOCATION_MAPPER`.

  This is useful for implementing inlined functions, or functions which are actually C preprocessor macros. Given a native library and JNA interface method, the mapper may provide a handler which implements the desired functionality (which may or may not actually make use of a native method).

  For example, the GNU C library remaps the `stat` function into a call to `_xstat` with a slight rearrangement of arguments. A mapper for the GNU C library might look like the following:

  >      new InvocationMapper() {
  >          public InvocationHandler getInvocationHandler(NativeLibrary lib, Method m) {
  >              if (m.getName().equals("stat")) {
  >                  final Function f = lib.getFunction("_xstat");
  >                  return new InvocationHandler() {
  >                      public Object invoke(Object proxy, Method method, Object[] args) {
  >                          Object[] newArgs = new Object[args.length+1];
  >                          System.arraycopy(args, 0, newArgs, 1, args.length);
  >                          newArgs[0] = Integer.valueOf(3); // _xstat version
  >                          return f.invoke(newArgs);
  >                      }
  >                  };
  >              }
  >              return null;
  >          }
  >      }

  Another situation is where a header provides a function-like macro or inline function definition.

  >      // Original C code (macro and inline variations)
  >      #define allocblock(x) malloc(x * 1024)
  >      static inline void* allocblock(size_t x) { return malloc(x * 1024); }

  >      // Invocation mapping
  >      new InvocationMapper() {
  >          public InvocationHandler getInvocationHandler(NativeLibrary lib, Method m) {
  >              if (m.getName().equals("allocblock")) {
  >                  final Function f = lib.getFunction("malloc");
  >                  return new InvocationHandler() {
  >                      public Object invoke(Object proxy, Method method, Object[] args) {
  >                          args[0] = ((Integer)args[0]).intValue() * 1024;
  >                          return f.invoke(newArgs);
  >                      }
  >                  };
  >              }
  >              return null;
  >          }
  >      }

  Author:
    twall

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.reflect.InvocationHandler` | `getInvocationHandler(NativeLibrary lib, java.lang.reflect.Method m)` Return an `InvocationHandler` responsible for handling the invocation of the given method, or `null` if the default handling should be used.

- - ### Method Detail

    - #### getInvocationHandler

          java.lang.reflect.InvocationHandler getInvocationHandler(NativeLibrary lib,
                                                                   java.lang.reflect.Method m)

      Return an `InvocationHandler` responsible for handling the invocation of the given method, or `null` if the default handling should be used. Note that the result of a call to this method with a given library and method may be cached.
      Parameters:
        `lib` - Target library
        `m` - Original JNA interface method that was invoked.

Copyright © 2007-2016 Timothy Wall. All Rights Reserved.