org.cinvoke
Class CInvoke

java.lang.Object
  extended byorg.cinvoke.CInvoke

public final class CInvoke
extends java.lang.Object

Provides interfaces and related utility methods for calling C libraries. The CInvoke class is the main public class in the C/Invoke Java binding. In addition to the load() methods, which connect Java interfaces to native shared libraries, it contains methods which can marshal parameters or return values in situations where the library cannot determine the correct marshaling behavior on its own.


Nested Class Summary
 class CInvoke.CC
          An enumeration of values representing different calling conventions.
 class CInvoke.ENC
          An enumeration which determines the encoding to use when marshalling strings.
 
Constructor Summary
CInvoke()
           
 
Method Summary
static int getSize(java.lang.Class type)
          Utility method which returns the number of bytes required to hold an instance of the given marshalable type.
static int getSize(java.lang.Object obj)
          Utility method which returns the number of bytes required to hold the given marshalable value.
static java.lang.Object load(java.lang.String libname, java.lang.Class iface)
          Loads a native C library and attaches it to the given Java interface.
static java.lang.Object load(java.lang.String libname, java.lang.Class iface, int callconv)
          Loads a native C library and attaches it to the given Java interface.
static java.lang.Object load(java.lang.String libname, java.lang.Class iface, int callconv, int encoding)
          Loads a native C library and attaches it to the given Java interface.
static java.lang.Object[] ptrToArray(Ptr ptr, java.lang.Class eltype, int num)
          Converts a pointer to a native array to a Java array value.
static java.lang.String ptrToString(Ptr ptr, int numchars, int encoding)
          Converts a pointer to an unmanaged buffer to a Java string value.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

CInvoke

public CInvoke()
Method Detail

load

public static java.lang.Object load(java.lang.String libname,
                                    java.lang.Class iface)
Loads a native C library and attaches it to the given Java interface. See the documentation for the load(String, Class, int, int) overload for more information. Using this overload calls functions with the default calling convention and the UTF-8 string encoding.

Parameters:
libname - The platform-specific name of the library to load.
iface - The interface to attach to the library.
Returns:
An object instance which implements the given interface. This object acts a proxy to the native C library.

load

public static java.lang.Object load(java.lang.String libname,
                                    java.lang.Class iface,
                                    int callconv)
Loads a native C library and attaches it to the given Java interface. See the documentation for the load(String, Class, int, int) overload for more information. Using this overload calls functions with the UTF-8 string encoding.

Parameters:
libname - The platform-specific name of the library to load.
iface - The interface to attach to the library.
callconv - The calling convention to use on functions in this library, from the CInvoke.CC enumeration.
Returns:
An object instance which implements the given interface. This object acts a proxy to the native C library.

load

public static java.lang.Object load(java.lang.String libname,
                                    java.lang.Class iface,
                                    int callconv,
                                    int encoding)
Loads a native C library and attaches it to the given Java interface. Each method in the given interface should correspond to a function symbol in the given library. However, individual symbols are not resolved until their corresponding methods are called for the first time. The signature of the interface method determines how parameters and return values are marshaled to and from C. The following types are allowed in method signatures:
  • byte, Byte: Marshaled as a C 'char' type.
  • short, Short: Marshaled as a 2-byte integer.
  • int, Integer: Marshaled as a 4-byte integer.
  • long, Long: Marshaled as an 8-byte integer.
  • float, Float: Marshaled as a C 'float' type.
  • double, Double: Marshaled as a C 'double' type.
  • NativeShort: Marshaled as a C 'short' type.
  • NativeInt: Marshaled as a C 'int' type.
  • NativeLong: Marshaled as a C 'long' type.
  • NativeLongLong: Marshaled as a C 'long long' type.
  • Ptr: Marshaled a C pointer value (i.e. a void*, or any other pointer of the same size).
  • String: Marshaled as a constant string pointer, with either UTF-8 or Unicode encoding. When used as a return value, marshaling continues up until the first 0 character.
  • Any Interface: If an interface type is specified for a parameter, then an instance of the interface will be marshaled as a function pointer. The interface specified should have one method defined. This method will be called back when unmanaged code calls the function pointer. Therefore, the prototype of this method should match the callback protoype. Arrays and callbacks cannot be used as parameter types in callback prototypes, and Strings cannot be used as parameters or as the return type. Callbacks are currently only supported when all the calls to a callback are made from within the calling function. Passing a managed function pointer to a C function which stores the value and calls it later in another thread may result in undefined behavior. Interfaces cannot be used as return types.
  • Any Array Type: Arrays of any other valid type are marshaled as pointers to C array values. Arrays, unlike Strings, are mutable; their elements are writable by unmanaged code, and after a C function returns, any value written to an array element is marshaled back to a corresponding Java value. This means you can use arrays whenever pointer or pass-by-reference semantics are required. However, arrays of interfaces or Strings are not supported, and using an array as a return type is not supported (use ptrToString or ptrToArray instead).
  • Any Class: Class types other than those listed above are marshaled as C structures, with each public field of a class corresponding to a structure member. Unfortunately, there is a twist to declaring classes which are compatible with C structures: in C, the order of the structure members is very important, but Java provides no method of determining the order class fields are declared in. Thus, in order to correctly marshal C structures, classes should be declared with the names of the fields in the alphabetical order which matches the order in the c struct. For example, to marshal the following structure definition:
    struct st {
            short mys;
            int myi
            float myfl;
    };
     
    the Java class should be declared:
    class st {
            public NativeShort a_mys;
            public NativeInt b_myi;
            public float c_myf;
    }
     
    The prefixes on the members ensure that the alphabetic order of the class fields corresponds to the C structure member order.

    Structures cannot contain members that are arrays, Strings, or interfaces. Members which have class types are treated as embedded structure values. Structures can never be passed or returned by value, only inside arrays. To pass a pointer to a structure to a function, pass an array with a length of 1. To return a pointer to a function, return a Ptr value and convert it to an array of structures with ptrToArray.

    Parameters:
    libname - The platform-specific name of the library to load. This is usually the name of a file containing the shared object file, i.e. mylib.dll or /lib/libmylib.so. The search path for library files is also implementation and system-defined; specifying the full path to a library file usually yields the most portable behavior.
    iface - The interface to attach to the library. The returned object implements this interface.
    callconv - The calling convention to use on functions in this library, from the CInvoke.CC enumeration.
    encoding - The encoding to use when marshaling strings in and out of this library, from the CInvoke.ENC enumeration.
    Returns:
    An object instance which implements the given interface. This object acts a proxy to the native C library. When a method in the given interface is called on this object, the name of the method is used as a symbol name to be looked up in the library. The parameters to the method are translated to their C equivalents, the C function is called, and the return value (and any array values) are translated back to Java objects.

  • ptrToString

    public static java.lang.String ptrToString(Ptr ptr,
                                               int numchars,
                                               int encoding)
    Converts a pointer to an unmanaged buffer to a Java string value.

    Parameters:
    ptr - A pointer value which points to an array of bytes or Unicode characters.
    numchars - The number of characters in the string. Specify a negative value to stop conversion at the first 0 character. This parameter is ignored when using the UTF-8 encoding, which always stops at the first 0 byte.
    encoding - The encoding to use, must be one of the values from the CInvoke.ENC enumeration.
    Returns:
    The completed String value.

    ptrToArray

    public static java.lang.Object[] ptrToArray(Ptr ptr,
                                                java.lang.Class eltype,
                                                int num)
    Converts a pointer to a native array to a Java array value.

    Parameters:
    ptr - A pointer value which points to a contiguous array of unmanaged values.
    eltype - The type of the elements of the array to create. Must be either a class with public fields (marshalled as a C structure) or a "basic" type (Byte, Short, Int, Long, Float, Double, NativeShort, NativeInt, NativeLong, NativeLongLong, or Ptr).
    num - The number of elements in the array.
    Returns:
    The completed Java array, cast to the Object[] type.

    getSize

    public static int getSize(java.lang.Class type)
    Utility method which returns the number of bytes required to hold an instance of the given marshalable type.

    Parameters:
    type - The type to retrieve the size of.
    Returns:
    The number of bytes of unmanaged memory required to hold an instance of the specified type.

    getSize

    public static int getSize(java.lang.Object obj)
    Utility method which returns the number of bytes required to hold the given marshalable value. If the value is an array, the size returned will be the combined size of all array elements.

    Parameters:
    obj - The object to retrieve the size of.
    Returns:
    The number of bytes of unmanaged memory required to hold the object.