Package com.sun.cldc.jna

See:
          Description

Package com.sun.cldc.jna Description

The CLDC/JNA package contains classes that help import native data structures and functions from Java code without writing C code.

Overview

Unlike JNA, there is currently no automatic support for generating wrapper methods or structures serialization code, so there is more boiler-plate code to write in order to import C functions and structures. But using C functions and structures is about as easy in CLDC/JNA as in JNA. Or easier.

Memory

A Pointer is a pointer to a region of native memory, based on RTSJ-like RawMemoryAccesss semantics. Otherwise it is similar to the Memory class in JNA. All Pointers have a size, so memory access through a Pointer is range-checked. There are a full set of getters and setters (such as getByte(offset), or setInt(offset, value)) to data within the range referred to by the Pointer.

A pointer can either have a dedicated backing buffer of native memory (from malloc or similar), or it may be a "shared" subset of some other pointer.

Functions

The main steps to making a C function callable from Java are to:

1. Create a class (or add methods to an existing class) to contain the method calling code
2. Get a Function pointer object that refers to the C function
3. Create a Java method with the same name and parameters as the C function, which calls the C function using the function pointer.
   Note that sometimes it make more sense to alter the API slightly for the convieince of the Java code that will call this method.

Example 1: Importing C function taking primitive types

    int close (int fildes);

public class LibC {

    ...other definitions...

    private static final Function closePtr = Function.getFunction("close");

    /**
     * delete a descriptor
     * 
     * @param fd a descriptor to be operated on by cmd
     * @return Upon successful completion, a value of 0 is returned.  Otherwise, a value of -1 is returned
     *         and the global integer variable errno is set to indicate the error.
     */
    public static int close(int fd) {
        return closePtr.call1(fd);
    }
    
}  

Example 2: Importing C function taking a string

    /*
     * File status flags: these are used by open(2), fcntl(2).
     * They are also used (indirectly) in the kernel file structure f_flags,
     * which is a superset of the open/fcntl flags.  Open flags and f_flags
     * are inter-convertible using OFLAGS(fflags) and FFLAGS(oflags).
     * Open/fcntl flags begin with O_; kernel-internal flags begin with F.
     */
    /* open-only flags */
    public final static int     O_RDONLY        = 0x0000;               /* open for reading only */
    public final static int     O_WRONLY        = 0x0001;               /* open for writing only */
    public final static int     O_RDWR          = 0x0002;               /* open for reading and writing */
    public final static int     O_ACCMODE       = 0x0003;               /* mask for above modes */
    
    /**
     * open or create a file for reading or writing
     * 
     * @param name String
     * @param oflag
     * @return If successful, returns a non-negative integer, termed a file descriptor.  Returns
     *         -1 on failure, and sets errno to indicate the error.
     */
    public static int open(String name, int oflag) {
        Pointer name0 = Pointer.createStringBuffer(name);
        int result = openPtr.call2(name0, oflag);
        name0.free();
        return result;
    }

Example 3: Calling simple C functions

    public void test() {
        int fd = LibC.open("foo", LibC.O_RDONLY); // defined in Example 2.
        if (fd >= 0) {
            System.out.println("It worked!");
            LibC.close(fd);
        }
    }

Differences from JNA

• No reflection in CLDC means that operations such as function invocation and the reading and writing of Structure fields to native buffers has to be done explicitly, not handled automatically. A future version may be able to generate this code automatically though.
• No NIO buffers
• The Pointer type is modeled after the RawMemoryFloatAccess class from RTSJ (JSRT 1).
• Throws RuntimeExceptions instead of UnsatisfiedLinkErrors. Are link errors really "unrecoverable"? Platform independant code might want to work around missing functions.
• Calling conventions unimplemented
• no finalization in cldc
• No classes representing types (IntegerType, PointerType, etc)
• No support for TypeMapper, TypeConverter, FunctionMapper, InvocationMapper, etc.
• No support for Callbacks