JNA API 3.5.1
com.sun.jna

Class Pointer

  • Direct Known Subclasses:
    Function, Memory


    public class Pointer
    extends Object
    An abstraction for a native pointer data type. A Pointer instance represents, on the Java side, a native pointer. The native pointer could be any type of native pointer. Methods such as write, read, getXXX, and setXXX, provide means to access memory underlying the native pointer.

    The constructors are intentionally package-private, since it's not generally a good idea to be creating C pointers de novo.

    Author:
    Sheng Liang, originator, Todd Fast, suitability modifications, Timothy Wall, robust library loading
    See Also:
    Function
    • Field Summary

      Fields 
      Modifier and Type Field and Description
      static Pointer NULL
      Convenience constant, same as null.
      protected long peer
      Pointer value of the real native pointer.
      static int SIZE
      Size of a native pointer, in bytes.
    • Constructor Summary

      Constructors 
      Constructor and Description
      Pointer()
      Derived class must assign peer pointer value.
      Pointer(long peer)
      Create from native pointer.
    • Method Summary

      Methods 
      Modifier and Type Method and Description
      void clear(long size)
      Zero memory for the given number of bytes.
      static Pointer createConstant(int peer)
      Convenience constant, equivalent to (void*)CONSTANT.
      static Pointer createConstant(long peer)
      Convenience constant, equivalent to (void*)CONSTANT.
      boolean equals(Object o)
      Compares this Pointer to the specified object.
      byte getByte(long offset)
      Indirect the native pointer as a pointer to byte.
      byte[] getByteArray(long offset, int arraySize)
      Read a native array of bytes of size arraySize from the given offset from this Pointer.
      ByteBuffer getByteBuffer(long offset, long length)
      Get a ByteBuffer mapped to the memory pointed to by the pointer, ensuring the buffer uses native byte order.
      char getChar(long offset)
      Indirect the native pointer as a pointer to wchar_t.
      char[] getCharArray(long offset, int arraySize)
      Read a native array of wchar_t of size arraySize from the given offset from this Pointer.
      double getDouble(long offset)
      Indirect the native pointer as a pointer to double.
      double[] getDoubleArray(long offset, int arraySize)
      Read a native array of double of size arraySize from the given offset from this Pointer.
      float getFloat(long offset)
      Indirect the native pointer as a pointer to float.
      float[] getFloatArray(long offset, int arraySize)
      Read a native array of float of size arraySize from the given offset from this Pointer.
      int getInt(long offset)
      Indirect the native pointer as a pointer to int.
      int[] getIntArray(long offset, int arraySize)
      Read a native array of int32 of size arraySize from the given offset from this Pointer.
      long getLong(long offset)
      Indirect the native pointer as a pointer to long.
      long[] getLongArray(long offset, int arraySize)
      Read a native array of int64 of size arraySize from the given offset from this Pointer.
      NativeLong getNativeLong(long offset)
      Indirect the native pointer as a pointer to long.
      Pointer getPointer(long offset)
      Indirect the native pointer as a pointer to pointer.
      Pointer[] getPointerArray(long offset)
      Returns an array of Pointer.
      Pointer[] getPointerArray(long offset, int arraySize)
      Returns an array of Pointer of the requested size.
      short getShort(long offset)
      Indirect the native pointer as a pointer to short.
      short[] getShortArray(long offset, int arraySize)
      Read a native array of int16 of size arraySize from the given offset from this Pointer.
      String getString(long offset)
      Copy native memory to a Java String.
      String getString(long offset, boolean wide)
      Copy native memory to a Java String.
      String[] getStringArray(long offset)
      Returns an array of String based on a native array of char *.
      String[] getStringArray(long offset, boolean wide)
      Returns an array of String based on a native array of char* or wchar_t* based on the wide parameter.
      String[] getStringArray(long offset, int length)
      Returns an array of String based on a native array of char *, using the given array length.
      String[] getStringArray(long offset, int length, boolean wide)
      Returns an array of String based on a native array of char* or wchar_t* based on the wide parameter, using the given array length.
      (package private) Object getValue(long offset, Class type, Object currentValue) 
      int hashCode()
      Returns a hashcode for the native pointer represented by this Pointer object
      long indexOf(long offset, byte value)
      Returns the offset of the given value in memory from the given offset, or -1 if the value is not found.
      static long nativeValue(Pointer p)
      Read the native peer value.
      static void nativeValue(Pointer p, long value)
      Set the native peer value.
      void read(long offset, byte[] buf, int index, int length)
      Indirect the native pointer, copying from memory pointed to by native pointer, into the specified array.
      void read(long offset, char[] buf, int index, int length)
      Indirect the native pointer, copying from memory pointed to by native pointer, into the specified array.
      void read(long offset, double[] buf, int index, int length)
      Indirect the native pointer, copying from memory pointed to by native pointer, into the specified array.
      void read(long offset, float[] buf, int index, int length)
      Indirect the native pointer, copying from memory pointed to by native pointer, into the specified array.
      void read(long offset, int[] buf, int index, int length)
      Indirect the native pointer, copying from memory pointed to by native pointer, into the specified array.
      void read(long offset, long[] buf, int index, int length)
      Indirect the native pointer, copying from memory pointed to by native pointer, into the specified array.
      void read(long offset, Pointer[] buf, int index, int length)
      Indirect the native pointer, copying from memory pointed to by native pointer, into the specified array.
      void read(long offset, short[] buf, int index, int length)
      Indirect the native pointer, copying from memory pointed to by native pointer, into the specified array.
      void setByte(long offset, byte value)
      Set value at location being pointed to.
      void setChar(long offset, char value)
      Set value at location being pointed to.
      void setDouble(long offset, double value)
      Set value at location being pointed to.
      void setFloat(long offset, float value)
      Set value at location being pointed to.
      void setInt(long offset, int value)
      Set value at location being pointed to.
      void setLong(long offset, long value)
      Set value at location being pointed to.
      void setMemory(long offset, long length, byte value)
      Write value to the requested bank of memory.
      void setNativeLong(long offset, NativeLong value)
      Set value at location being pointed to.
      void setPointer(long offset, Pointer value)
      Set value at location being pointed to.
      void setShort(long offset, short value)
      Set value at location being pointed to.
      void setString(long offset, String value)
      Copy string value to the location being pointed to.
      void setString(long offset, String value, boolean wide)
      Copy string value to the location being pointed to.
      (package private) void setValue(long offset, Object value, Class type) 
      Pointer share(long offset)
      Provide a view of this memory using the given offset to calculate a new base address.
      Pointer share(long offset, long sz)
      Provide a view of this memory using the given offset to calculate a new base address, bounds-limiting the memory with the given size.
      String toString() 
      void write(long offset, byte[] buf, int index, int length)
      Indirect the native pointer, copying into memory pointed to by native pointer, from the specified array.
      void write(long offset, char[] buf, int index, int length)
      Indirect the native pointer, copying into memory pointed to by native pointer, from the specified array.
      void write(long offset, double[] buf, int index, int length)
      Indirect the native pointer, copying into memory pointed to by native pointer, from the specified array.
      void write(long offset, float[] buf, int index, int length)
      Indirect the native pointer, copying into memory pointed to by native pointer, from the specified array.
      void write(long offset, int[] buf, int index, int length)
      Indirect the native pointer, copying into memory pointed to by native pointer, from the specified array.
      void write(long offset, long[] buf, int index, int length)
      Indirect the native pointer, copying into memory pointed to by native pointer, from the specified array.
      void write(long bOff, Pointer[] buf, int index, int length)
      Write the given array of Pointer to native memory.
      void write(long offset, short[] buf, int index, int length)
      Indirect the native pointer, copying into memory pointed to by native pointer, from the specified array.
    • Field Detail

      • SIZE

        public static final int SIZE
        Size of a native pointer, in bytes.
      • NULL

        public static final Pointer NULL
        Convenience constant, same as null.
      • peer

        protected long peer
        Pointer value of the real native pointer. Use long to be 64-bit safe.
    • Constructor Detail

      • Pointer

        Pointer()
        Derived class must assign peer pointer value.
      • Pointer

        public Pointer(long peer)
        Create from native pointer. Don't use this unless you know what you're doing.
    • Method Detail

      • createConstant

        public static final Pointer createConstant(long peer)
        Convenience constant, equivalent to (void*)CONSTANT.
      • createConstant

        public static final Pointer createConstant(int peer)
        Convenience constant, equivalent to (void*)CONSTANT. This version will avoid setting any of the high bits on 64-bit systems.
      • share

        public Pointer share(long offset)
        Provide a view of this memory using the given offset to calculate a new base address.
      • share

        public Pointer share(long offset,
                    long sz)
        Provide a view of this memory using the given offset to calculate a new base address, bounds-limiting the memory with the given size.
      • clear

        public void clear(long size)
        Zero memory for the given number of bytes.
      • equals

        public boolean equals(Object o)
        Compares this Pointer to the specified object.
        Overrides:
        equals in class Object
        Parameters:
        o - A Pointer instance
        Returns:
        True if the other object is a Pointer, and the C pointers being pointed to by these objects are also equal. Returns false otherwise.
      • hashCode

        public int hashCode()
        Returns a hashcode for the native pointer represented by this Pointer object
        Overrides:
        hashCode in class Object
        Returns:
        A hash code value for the represented native pointer
      • indexOf

        public long indexOf(long offset,
                   byte value)
        Returns the offset of the given value in memory from the given offset, or -1 if the value is not found.
      • read

        public void read(long offset,
                byte[] buf,
                int index,
                int length)
        Indirect the native pointer, copying from memory pointed to by native pointer, into the specified array.
        Parameters:
        offset - byte offset from pointer into which data is copied
        buf - byte array into which data is copied
        index - array index from which to start copying
        length - number of elements from native pointer that must be copied
      • read

        public void read(long offset,
                short[] buf,
                int index,
                int length)
        Indirect the native pointer, copying from memory pointed to by native pointer, into the specified array.
        Parameters:
        offset - byte offset from pointer from which data is copied
        buf - short array into which data is copied
        index - array index to which data is copied
        length - number of elements from native pointer that must be copied
      • read

        public void read(long offset,
                char[] buf,
                int index,
                int length)
        Indirect the native pointer, copying from memory pointed to by native pointer, into the specified array.
        Parameters:
        offset - byte offset from pointer from which data is copied
        buf - char array into which data is copied
        index - array index to which data is copied
        length - number of elements from native pointer that must be copied
      • read

        public void read(long offset,
                int[] buf,
                int index,
                int length)
        Indirect the native pointer, copying from memory pointed to by native pointer, into the specified array.
        Parameters:
        offset - byte offset from pointer from which data is copied
        buf - int array into which data is copied
        index - array index to which data is copied
        length - number of elements from native pointer that must be copied
      • read

        public void read(long offset,
                long[] buf,
                int index,
                int length)
        Indirect the native pointer, copying from memory pointed to by native pointer, into the specified array.
        Parameters:
        offset - byte offset from pointer from which data is copied
        buf - long array into which data is copied
        index - array index to which data is copied
        length - number of elements from native pointer that must be copied
      • read

        public void read(long offset,
                float[] buf,
                int index,
                int length)
        Indirect the native pointer, copying from memory pointed to by native pointer, into the specified array.
        Parameters:
        offset - byte offset from pointer from which data is copied
        buf - float array into which data is copied
        index - array index to which data is copied
        length - number of elements from native pointer that must be copied
      • read

        public void read(long offset,
                double[] buf,
                int index,
                int length)
        Indirect the native pointer, copying from memory pointed to by native pointer, into the specified array.
        Parameters:
        offset - byte offset from pointer from which data is copied
        buf - double array into which data is copied
        index - array index to which data is copied
        length - number of elements from native pointer that must be copied
      • read

        public void read(long offset,
                Pointer[] buf,
                int index,
                int length)
        Indirect the native pointer, copying from memory pointed to by native pointer, into the specified array.
        Parameters:
        offset - byte offset from pointer from which data is copied
        buf - Pointer array into which data is copied
        index - array index to which data is copied
        length - number of elements from native pointer that must be copied
      • write

        public void write(long offset,
                 byte[] buf,
                 int index,
                 int length)
        Indirect the native pointer, copying into memory pointed to by native pointer, from the specified array.
        Parameters:
        offset - byte offset from pointer into which data is copied
        buf - byte array from which to copy
        index - array index from which to start copying
        length - number of elements from buf that must be copied
      • write

        public void write(long offset,
                 short[] buf,
                 int index,
                 int length)
        Indirect the native pointer, copying into memory pointed to by native pointer, from the specified array.
        Parameters:
        offset - byte offset from pointer into which data is copied
        buf - short array from which to copy
        index - array index from which to start copying
        length - number of elements from buf that must be copied
      • write

        public void write(long offset,
                 char[] buf,
                 int index,
                 int length)
        Indirect the native pointer, copying into memory pointed to by native pointer, from the specified array.
        Parameters:
        offset - byte offset from pointer into which data is copied
        buf - char array from which to copy
        index - array index from which to start copying
        length - number of elements from buf that must be copied
      • write

        public void write(long offset,
                 int[] buf,
                 int index,
                 int length)
        Indirect the native pointer, copying into memory pointed to by native pointer, from the specified array.
        Parameters:
        offset - byte offset from pointer into which data is copied
        buf - int array from which to copy
        index - array index from which to start copying
        length - number of elements from buf that must be copied
      • write

        public void write(long offset,
                 long[] buf,
                 int index,
                 int length)
        Indirect the native pointer, copying into memory pointed to by native pointer, from the specified array.
        Parameters:
        offset - byte offset from pointer into which data is copied
        buf - long array from which to copy
        index - array index from which to start copying
        length - number of elements from buf that must be copied
      • write

        public void write(long offset,
                 float[] buf,
                 int index,
                 int length)
        Indirect the native pointer, copying into memory pointed to by native pointer, from the specified array.
        Parameters:
        offset - byte offset from pointer into which data is copied
        buf - float array from which to copy
        index - array index from which to start copying
        length - number of elements from buf that must be copied
      • write

        public void write(long offset,
                 double[] buf,
                 int index,
                 int length)
        Indirect the native pointer, copying into memory pointed to by native pointer, from the specified array.
        Parameters:
        offset - byte offset from pointer into which data is copied
        buf - double array from which to copy
        index - array index from which to start copying
        length - number of elements from buf that must be copied
      • write

        public void write(long bOff,
                 Pointer[] buf,
                 int index,
                 int length)
        Write the given array of Pointer to native memory.
        Parameters:
        bOff - byte offset from pointer into which data is copied
        buf - Pointer array from which to copy
        index - array index from which to start copying
        length - number of elements from buf that must be copied
      • getByte

        public byte getByte(long offset)
        Indirect the native pointer as a pointer to byte. This is equivalent to the expression *((jbyte *)((char *)Pointer + offset)).
        Parameters:
        offset - offset from pointer to perform the indirection
        Returns:
        the byte value being pointed to
      • getChar

        public char getChar(long offset)
        Indirect the native pointer as a pointer to wchar_t. This is equivalent to the expression *((wchar_t*)((char *)Pointer + offset)).
        Parameters:
        offset - offset from pointer to perform the indirection
        Returns:
        the wchar_t value being pointed to
      • getShort

        public short getShort(long offset)
        Indirect the native pointer as a pointer to short. This is equivalent to the expression *((jshort *)((char *)Pointer + offset)).
        Parameters:
        offset - byte offset from pointer to perform the indirection
        Returns:
        the short value being pointed to
      • getInt

        public int getInt(long offset)
        Indirect the native pointer as a pointer to int. This is equivalent to the expression *((jint *)((char *)Pointer + offset)).
        Parameters:
        offset - byte offset from pointer to perform the indirection
        Returns:
        the int value being pointed to
      • getLong

        public long getLong(long offset)
        Indirect the native pointer as a pointer to long. This is equivalent to the expression *((jlong *)((char *)Pointer + offset)).
        Parameters:
        offset - byte offset from pointer to perform the indirection
        Returns:
        the long value being pointed to
      • getNativeLong

        public NativeLong getNativeLong(long offset)
        Indirect the native pointer as a pointer to long. This is equivalent to the expression *((long *)((char *)Pointer + offset)).
        Parameters:
        offset - byte offset from pointer to perform the indirection
        Returns:
        the long value being pointed to
      • getFloat

        public float getFloat(long offset)
        Indirect the native pointer as a pointer to float. This is equivalent to the expression *((jfloat *)((char *)Pointer + offset)).
        Parameters:
        offset - byte offset from pointer to perform the indirection
        Returns:
        the float value being pointed to
      • getDouble

        public double getDouble(long offset)
        Indirect the native pointer as a pointer to double. This is equivalent to the expression *((jdouble *)((char *)Pointer + offset)).
        Parameters:
        offset - byte offset from pointer to perform the indirection
        Returns:
        the double value being pointed to
      • getPointer

        public Pointer getPointer(long offset)
        Indirect the native pointer as a pointer to pointer. This is equivalent to the expression *((void **)((char *)Pointer + offset)).
        Parameters:
        offset - byte offset from pointer to perform the indirection
        Returns:
        a Pointer equivalent of the pointer value being pointed to, or null if the pointer value is NULL;
      • getByteBuffer

        public ByteBuffer getByteBuffer(long offset,
                               long length)
        Get a ByteBuffer mapped to the memory pointed to by the pointer, ensuring the buffer uses native byte order.
        Parameters:
        offset - byte offset from pointer to start the buffer
        length - Length of ByteBuffer
        Returns:
        a direct ByteBuffer that accesses the memory being pointed to,
      • getString

        public String getString(long offset,
                       boolean wide)
        Copy native memory to a Java String. If wide is true, access the memory as an array of wchar_t, otherwise as an array of char, using the default platform encoding.
        Parameters:
        offset - byte offset from pointer to obtain the native string v * @param wide whether to convert from a wide or standard C string
        Returns:
        the String value being pointed to
      • getString

        public String getString(long offset)
        Copy native memory to a Java String. If the system property jna.encoding is set, uses it as the native charset when decoding the value, otherwise falls back to the default platform encoding.
        Parameters:
        offset - byte offset from pointer to obtain the native string
        Returns:
        the String value being pointed to
      • getByteArray

        public byte[] getByteArray(long offset,
                          int arraySize)
        Read a native array of bytes of size arraySize from the given offset from this Pointer.
      • getCharArray

        public char[] getCharArray(long offset,
                          int arraySize)
        Read a native array of wchar_t of size arraySize from the given offset from this Pointer.
      • getShortArray

        public short[] getShortArray(long offset,
                            int arraySize)
        Read a native array of int16 of size arraySize from the given offset from this Pointer.
      • getIntArray

        public int[] getIntArray(long offset,
                        int arraySize)
        Read a native array of int32 of size arraySize from the given offset from this Pointer.
      • getLongArray

        public long[] getLongArray(long offset,
                          int arraySize)
        Read a native array of int64 of size arraySize from the given offset from this Pointer.
      • getFloatArray

        public float[] getFloatArray(long offset,
                            int arraySize)
        Read a native array of float of size arraySize from the given offset from this Pointer.
      • getDoubleArray

        public double[] getDoubleArray(long offset,
                              int arraySize)
        Read a native array of double of size arraySize from the given offset from this Pointer.
      • getPointerArray

        public Pointer[] getPointerArray(long offset)
        Returns an array of Pointer. The array length is determined by a NULL-valued terminating element.
      • getPointerArray

        public Pointer[] getPointerArray(long offset,
                                int arraySize)
        Returns an array of Pointer of the requested size.
      • getStringArray

        public String[] getStringArray(long offset)
        Returns an array of String based on a native array of char *. The array length is determined by a NULL-valued terminating element.
      • getStringArray

        public String[] getStringArray(long offset,
                              int length)
        Returns an array of String based on a native array of char *, using the given array length.
      • getStringArray

        public String[] getStringArray(long offset,
                              boolean wide)
        Returns an array of String based on a native array of char* or wchar_t* based on the wide parameter. The array length is determined by a NULL-valued terminating element.
      • getStringArray

        public String[] getStringArray(long offset,
                              int length,
                              boolean wide)
        Returns an array of String based on a native array of char* or wchar_t* based on the wide parameter, using the given array length.
      • setValue

        void setValue(long offset,
                    Object value,
                    Class type)
      • setMemory

        public void setMemory(long offset,
                     long length,
                     byte value)
        Write value to the requested bank of memory.
        Parameters:
        offset - byte offset from pointer to start
        length - number of bytes to write
        value - value to be written
      • setByte

        public void setByte(long offset,
                   byte value)
        Set value at location being pointed to. This is equivalent to the expression *((jbyte *)((char *)Pointer + offset)) = value.
        Parameters:
        offset - byte offset from pointer at which value must be set
        value - byte value to set
      • setShort

        public void setShort(long offset,
                    short value)
        Set value at location being pointed to. This is equivalent to the expression *((jshort *)((char *)Pointer + offset)) = value.
        Parameters:
        offset - byte offset from pointer at which value must be set
        value - short value to set
      • setChar

        public void setChar(long offset,
                   char value)
        Set value at location being pointed to. This is equivalent to the expression *((wchar_t *)((char *)Pointer + offset)) = value.
        Parameters:
        offset - byte offset from pointer at which value must be set
        value - char value to set
      • setInt

        public void setInt(long offset,
                  int value)
        Set value at location being pointed to. This is equivalent to the expression *((jint *)((char *)Pointer + offset)) = value.
        Parameters:
        offset - byte offset from pointer at which value must be set
        value - int value to set
      • setLong

        public void setLong(long offset,
                   long value)
        Set value at location being pointed to. This is equivalent to the expression *((jlong *)((char *)Pointer + offset)) = value.
        Parameters:
        offset - byte offset from pointer at which value must be set
        value - long value to set
      • setNativeLong

        public void setNativeLong(long offset,
                         NativeLong value)
        Set value at location being pointed to. This is equivalent to the expression *((long *)((char *)Pointer + offset)) = value.
        Parameters:
        offset - byte offset from pointer at which value must be set
        value - long value to set
      • setFloat

        public void setFloat(long offset,
                    float value)
        Set value at location being pointed to. This is equivalent to the expression *((jfloat *)((char *)Pointer + offset)) = value.
        Parameters:
        offset - byte offset from pointer at which value must be set
        value - float value to set
      • setDouble

        public void setDouble(long offset,
                     double value)
        Set value at location being pointed to. This is equivalent to the expression *((jdouble *)((char *)Pointer + offset)) = value.
        Parameters:
        offset - byte offset from pointer at which value must be set
        value - double value to set
      • setPointer

        public void setPointer(long offset,
                      Pointer value)
        Set value at location being pointed to. This is equivalent to the expression *((void **)((char *)Pointer + offset)) = value.
        Parameters:
        offset - byte offset from pointer at which value must be set
        value - Pointer holding the actual pointer value to set, which may be null to indicate a NULL pointer.
      • setString

        public void setString(long offset,
                     String value,
                     boolean wide)
        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.
        Parameters:
        offset - byte offset from pointer at which characters in value must be set
        value - java.lang.String value to set
        wide - whether to write the native string as an array of wchar_t. If false, writes as a NUL-terminated array of char using the default platform encoding.
      • setString

        public void setString(long offset,
                     String 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. Uses the value of the system property jna.encoding, if set, to determine the appropriate native charset in which to encode the value. If the property is not set, uses the default platform encoding.
        Parameters:
        offset - byte offset from pointer at which characters in value must be set
        value - java.lang.String value to set
      • nativeValue

        public static long nativeValue(Pointer p)
        Read the native peer value. Use with caution.
      • nativeValue

        public static void nativeValue(Pointer p,
                       long value)
        Set the native peer value. Use with caution.
JNA API 3.5.1

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