Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| " 2013 FRC Java API "
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES

## Package com.sun.cldc.jna

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

See:
Description

Interface Summary
Includes | NOT YET IMPLEMENTED The Includes annotation can be applied to the top-level interface declarations in a JNA Library declaration to indicate the C include files that contain the relevent #defines and structure definitions for that library Example: @Includes( "", "", "") public interface LibC extends LibraryImport { ...
JNAPlatform | This class imports some constants that are used by the JNA itself
Library | Library is the interface that all Library interface definitions (automatically generated by JNAGen) should extend

Class Summary
BlockingFunction | BlockingFunction allows Java code to call C function that block.
DynamicStructure | A DynamicStructure is a structure with support for getting the field offsets for a particular platform from native code.
Function | A pointer to a native function that can be called from Java.
JNAPlatformImpl |
Native | Generic machinery to support access to native code.
NativeLibrary | Represents a handle to a runtime library (for example, as returned by the POSIX function "dlopen" http://www.opengroup.org/onlinepubs/009695399/functions/dlopen.html
OpaqueStructure | This is a "Structure" that we'll never look at the fields of.
Platform | Provide simplified platform information
Pointer | A pointer to native memory, based on RTSJ-like RawMemoryAccesss semantics.
PointerType | Superclass of types representing native pointers
Posix |
PrivatePointer | Utilities used by JNA generated Java code.
Spot |
Structure | Abstract class for proxies to native structure types.
TaskExecutor | A TaskExecutor is a native thread that can be used to run native functions.
VarPointer | A pointer to a native variable that can be read/wrote from Java.
Windows |

## 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

The classes names were chosen to resemble the Java Native Access (JNA) APIs, to the extent that this made sense on CLDC, and time allowed.

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

The CLDC/JNA package provides low-level access to native (non-Java heap) memory using the `Pointer` class. In many cases you will use higher level abstractions such as `Structure`s, but to refer to raw memory you can use the Pointer class.

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

Using CLDC/JNA you can create methods that call out to C functions. Most functions that are exported from a library may be called (as if by dlsym()). Functions that pass pointers to structures are more complicated, and will be described after the Structures section.

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

In this example we will create a wrapper for calling the standard C function "close". It is defined as:

        int close (int fildes);

Yes, we've side-stepped the issue of getting a file descriptor by calling open, because that API is slightly (only slightly) more complicated. Now we create a class, create a Function pointer, and create a wrapper method.

    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

Importing C function that take C strings as arguments is a little harder. Also note that this API uses a set of constants that we had to hand-translate from C to Java:

        /*
         * 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

After the C functions have been imported it's then simple to call them from other Java code:

        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

There are specific differences listed for each class, but here are the major differences:

- 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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| " 2013 FRC Java API "
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES

"
For updated information see the Java FRC site
"