CPtr.java

Copyright (c) 1998 Sun Microsystems, Inc. All Rights Reserved.

Sun grants you ("Licensee") a non-exclusive, royalty free, license to use,
modify and redistribute this software in source and binary code form,
provided that i) this copyright notice and license appear on all copies of
the software; and ii) Licensee does not utilize the software in a manner
which is disparaging to Sun.

This software is provided "AS IS," without a warranty of any kind. ALL
EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY
IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR
NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN AND ITS LICENSORS SHALL NOT BE
LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING
OR DISTRIBUTING THE SOFTWARE OR ITS DERIVATIVES. IN NO EVENT WILL SUN OR ITS
LICENSORS BE LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT,
INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER
CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE OF
OR INABILITY TO USE SOFTWARE, EVEN IF SUN HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.

This software is not designed or intended for use in on-line control of
aircraft, air traffic, aircraft navigation or aircraft communications; or in
the design, construction, operation or maintenance of any nuclear
facility. Licensee represents and warrants that it will not use or
redistribute the Software for such purposes.
/*
 * @(#)CPtr.java 1.8 98/03/22
 *
 * Copyright (c) 1998 Sun Microsystems, Inc. All Rights Reserved.
 *
 * See also the LICENSE file in this distribution.
 */

/**
 * An abstraction for a C pointer data type.  A CPtr instance represents, on
 * the Java side, a C pointer.  The C pointer could be any type of C
 * pointer.  Methods such as copyIn, copyOut,
 * getXXX, and setXXX, provide
 * means to indirect the underlying C pointer. 
 *
 * @author Sheng Liang
 * @see    CFunc
 */
public class CPtr {

    /**
     * The size of a C pointer on the platform this Java virtual machine is
     * running on.
     */
    public static final int SIZE;
    
    /**
     * A canonical representation of C's NULL pointer.
     */
    public static final CPtr NULL;
    
    
    /**
     * Compares this CPtr to the specified object.
     *
     * @param other a CPtr
     * @return      true if the class of this CPtr object and the
     *      class of other are exactly equal, and the C
     *      pointers being pointed to by these objects are also
     *      equal. Returns false otherwise.
     */
    public boolean equals(Object other) {
        if (other == null)
     return false;
 if (other == this)
     return true;
 if (CPtr.class != other.getClass())
     return false;
 return peer == ((CPtr)other).peer;
    }

    /**
     * Returns a hashcode for the C pointer represented by this
     * Cptr object.
     *
     * @return a hash code value for the represented C pointer.
     */
    public int hashCode() {
        return (int)((peer >>> 32) + (peer & 0xFFFFFFFF));
    }

    /**
     * Indirect the C pointer, copying into memory pointed to by C
     * pointer, from the specified array.
     *
     * @param bOff   byte offset from pointer into which data is copied
     * @param buf    byte array from which to copy
     * @param index  array index from which to start copying
     * @param length number of elements from buf that must be
     *               copied
     */
    public native void copyIn(int bOff, byte[] buf, int index, int length);

    /**
     * Indirect the C pointer, copying into memory pointed to by C
     * pointer, from the specified array.
     *
     * @param bOff   byte offset from pointer into which data is copied
     * @param buf    short array from which to copy
     * @param index  array index from which to start copying
     * @param length number of elements from buf that must be
     *               copied
     */
    public native void copyIn(int bOff, short[] buf, int index, int length);

    /**
     * Indirect the C pointer, copying into memory pointed to by C
     * pointer, from the specified array.
     *
     * @param bOff   byte offset from pointer into which data is copied
     * @param buf    char array from which to copy
     * @param index  array index from which to start copying
     * @param length number of elements from buf that must be
     *               copied
     */
    public native void copyIn(int bOff, char[] buf, int index, int length);

    /**
     * Indirect the C pointer, copying into memory pointed to by C
     * pointer, from the specified array.
     *
     * @param bOff   byte offset from pointer into which data is copied
     * @param buf    int array from which to copy
     * @param index  array index from which to start copying
     * @param length number of elements from buf that must be
     *               copied
     */
    public native void copyIn(int bOff, int[] buf, int index, int length);

    /**
     * Indirect the C pointer, copying into memory pointed to by C
     * pointer, from the specified array.
     *
     * @param bOff   byte offset from pointer into which data is copied
     * @param buf    long array from which to copy
     * @param index  array index from which to start copying
     * @param length number of elements from buf that must be
     *               copied
     */
    public native void copyIn(int bOff, long[] buf, int index, int length);

    /**
     * Indirect the C pointer, copying into memory pointed to by C
     * pointer, from the specified array.
     *
     * @param bOff   byte offset from pointer into which data is copied
     * @param buf    float array from which to copy
     * @param index  array index from which to start copying
     * @param length number of elements from buf that must be
     *               copied
     */
    public native void copyIn(int bOff, float[] buf, int index, int length);

    /**
     * Indirect the C pointer, copying into memory pointed to by C
     * pointer, from the specified array.
     *
     * @param bOff   byte offset from pointer into which data is copied
     * @param buf    double array from which to copy
     * @param index  array index from which to start copying
     * @param length number of elements from buf that must be
     *               copied
     */
    public native void copyIn(int bOff, double[] buf, int index, int length);

    /**
     * Indirect the C pointer, copying from memory pointed to by C
     * pointer, into the specified array.
     *
     * @param bOff   byte offset from pointer into which data is copied
     * @param buf    byte array into which data is copied
     * @param index  array index from which to start copying
     * @param length number of elements from C pointer that must be copied
     */
    public native void copyOut(int bOff, byte[] buf, int index, int length);

    /**
     * Indirect the C pointer, copying from memory pointed to by C
     * pointer, into the specified array.
     *
     * @param bOff   byte offset from pointer from which data is copied
     * @param buf    short array into which data is copied
     * @param index  array index to which data is copied
     * @param length number of elements from C pointer that must be copied
     */
    public native void copyOut(int bOff, short[] buf, int index, int length);

    /**
     * Indirect the C pointer, copying from memory pointed to by C
     * pointer, into the specified array.
     *
     * @param bOff   byte offset from pointer from which data is copied
     * @param buf    char array into which data is copied
     * @param index  array index to which data is copied
     * @param length number of elements from C pointer that must be copied
     */
    public native void copyOut(int bOff, char[] buf, int index, int length);

    /**
     * Indirect the C pointer, copying from memory pointed to by C
     * pointer, into the specified array.
     *
     * @param bOff   byte offset from pointer from which data is copied
     * @param buf    int array into which data is copied
     * @param index  array index to which data is copied
     * @param length number of elements from C pointer that must be copied
     */
    public native void copyOut(int bOff, int[] buf, int index, int length);

    /**
     * Indirect the C pointer, copying from memory pointed to by C
     * pointer, into the specified array.
     *
     * @param bOff   byte offset from pointer from which data is copied
     * @param buf    long array into which data is copied
     * @param index  array index to which data is copied
     * @param length number of elements from C pointer that must be copied
     */
    public native void copyOut(int bOff, long[] buf, int index, int length);

    /**
     * Indirect the C pointer, copying from memory pointed to by C
     * pointer, into the specified array.
     *
     * @param bOff   byte offset from pointer from which data is copied
     * @param buf    float array into which data is copied
     * @param index  array index to which data is copied
     * @param length number of elements from C pointer that must be copied
     */
    public native void copyOut(int bOff, float[] buf, int index, int length);

    /**
     * Indirect the C pointer, copying from memory pointed to by C
     * pointer, into the specified array.
     *
     * @param bOff   byte offset from pointer from which data is copied
     * @param buf    double array into which data is copied
     * @param index  array index to which data is copied
     * @param length number of elements from C pointer that must be copied
     */
    public native void copyOut(int bOff, double[] buf, int index, int length);

    /**
     * Indirect the C pointer as a pointer to byte.  This is
     * equivalent to the expression 
     * *((jbyte *)((char *)cptr + * offset)).
     *
     * @param offset offset from pointer to perform the indirection
     * @return the byte value being pointed to
     */
    public native byte getByte(int offset);

    /**
     * Indirect the C pointer as a pointer to short.  This is
     * equivalent to the expression
     * *((jshort *)((char *)cptr + offset)).
     *
     * @param offset byte offset from pointer to perform the indirection
     * @return the short value being pointed to
     */
    public native short getShort(int offset);

    /**
     * Indirect the C pointer as a pointer to int.  This is
     * equivalent to the expression
     * *((jint *)((char *)cptr + offset)).
     *
     * @param offset byte offset from pointer to perform the indirection
     * @return the int value being pointed to
     */
    public native int getInt(int offset);

    /**
     * Indirect the C pointer as a pointer to long.  This is
     * equivalent to the expression
     * *((jlong *)((char *)cptr + offset)).
     *
     * @param offset byte offset from pointer to perform the indirection
     * @return the long value being pointed to
     */
    public native long getLong(int offset);

    /**
     * Indirect the C pointer as a pointer to float.  This is
     * equivalent to the expression
     * *((jfloat *)((char *)cptr + offset)).
     *
     * @param offset byte offset from pointer to perform the indirection
     * @return the float value being pointed to
     */
    public native float getFloat(int offset);

    /**
     * Indirect the C pointer as a pointer to double.  This is
     * equivalent to the expression
     * *((jdouble *)((char *)cptr + offset)).
     *
     * @param offset byte offset from pointer to perform the indirection
     * @return the double value being pointed to
     */
    public native double getDouble(int offset);

    /**
     * Indirect the C pointer as a pointer to pointer.  This is equivalent to
     * the expression *((void **)((char *)cptr + offset)).
     *
     * @param offset byte offset from pointer to perform the indirection
     * @return the pointer value being pointed to
     */
    public native CPtr getCPtr(int offset);

    /**
     * Indirect the C pointer as a pointer to char *, a
     * NULL-terminated C string. Convert the C string to a
     * java.lang.String.
     *
     * @param offset byte offset from pointer to obtain the C string
     * @return the String value being pointed to 
     */
    public native String getString(int offset);

    /**
     * Set value at location being pointed to. This is equivalent
     * to the expression
     * *((jbyte *)((char *)cptr + offset)) = value.
     *
     * @param offset byte offset from pointer at which value
     *       must be set
     * @param value byte value to set
     */
    public native void setByte(int offset, byte value);

    /**
     * Set value at location being pointed to. This is equivalent
     * to the expression
     * *((jshort *)((char *)cptr + offset)) = value.
     *
     * @param offset byte offset from pointer at which value
     *       must be set
     * @param value short value to set
     */
    public native void setShort(int offset, short value);

    /**
     * Set value at location being pointed to. This is equivalent
     * to the expression
     * *((jint *)((char *)cptr + offset)) = value.
     *
     * @param offset byte offset from pointer at which value
     *       must be set
     * @param value int value to set
     */
    public native void setInt(int offset, int value);

    /**
     * Set value at location being pointed to. This is equivalent
     * to the expression
     * *((jlong *)((char *)cptr + offset)) = value.
     *
     * @param offset byte offset from pointer at which value
     *               must be set
     * @param value long value to set
     */
    public native void setLong(int offset, long value);

    /**
     * Set value at location being pointed to. This is equivalent
     * to the expression
     * *((jfloat *)((char *)cptr + offset)) = value.
     *
     * @param offset byte offset from pointer at which value
     *               must be set
     * @param value float value to set
     */
    public native void setFloat(int offset, float value);

    /**
     * Set value at location being pointed to. This is equivalent
     * to the expression
     * *((jdouble *)((char *)cptr + offset)) = value.
     *
     * @param offset byte offset from pointer at which value
     *               must be set
     * @param value double value to set
     */
    public native void setDouble(int offset, double value);

    /**
     * Set value at location being pointed to. This is equivalent
     * to the expression *((void **)((char *)cptr + offset)) = value.
     *
     * @param offset byte offset from pointer at which value 
     *               must be set
     * @param value CPtr value to set
     */
    public native void setCPtr(int offset, CPtr value);

    /**
     * Copy string value to the location being pointed to.  Copy
     * each element in value, converted to native encoding, at an
     * offsetfrom the location pointed to by this pointer.
     *
     * @param offset byte offset from pointer at which characters in
     *        value must be set
     * @param value  java.lang.String value to set 
     */
    public native void setString(int offset, String value);

    /* Initialize field and method IDs for native methods of this class. */
    private static native int initIDs(CPtr p);
    
    static {
        System.loadLibrary("disp");
 NULL = new CPtr();
        SIZE = initIDs(NULL);
    }

    /* peer and the no-args constructor are deliberately package private, so
       all classes that are abstractions of a C pointer will can only be in
       one isolated package.  */
    
    /* Pointer value of the real C pointer. Use long to be 64-bit safe. */
    long peer;

    /* No-args constructor, see comment above. */
    CPtr() {}
 
}