Package 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.

    While a constructor exists to create a Pointer from an integer value, it's not generally a good idea to be creating pointers that way.

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

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

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

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method 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.
      String dump​(long offset, int size)
      Dump memory for debugging purposes.
      boolean equals​(Object o)  
      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, String encoding)
      Copy native memory to a Java String using the requested encoding.
      String[] getStringArray​(long offset)
      Returns an array of String based on a native array of char *.
      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, String encoding)
      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.
      String[] getStringArray​(long offset, String encoding)
      Returns an array of String based on a native array of char *, using the requested encoding.
      (package private) Object getValue​(long offset, Class<?> type, Object currentValue)  
      String getWideString​(long offset)
      Read a wide (const wchar_t *) string from memory.
      String[] getWideStringArray​(long offset)  
      String[] getWideStringArray​(long offset, int length)  
      int hashCode()  
      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, short[] 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 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, WString value)
      Copy string value to the location being pointed to as a wide string (wchar_t*).
      void setString​(long offset, String value)
      Copy bytes out of string value to the location being pointed to, using the encoding indicated by Native.getDefaultStringEncoding().
      void setString​(long offset, String value, String encoding)
      Copy string value to the location being pointed to, using the requested encoding.
      (package private) void setValue​(long offset, Object value, Class<?> type)  
      void setWideString​(long offset, String value)
      Copy string value to the location being pointed to as a wide string (wchar_t*).
      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 offset, short[] 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.
    • Field Detail

      • 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.
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object
      • 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 from which data is copied
        buf - byte 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,
                         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,
      • getWideString

        public String getWideString​(long offset)
        Read a wide (const wchar_t *) string from memory.
      • getString

        public String getString​(long offset)
        Copy native memory to a Java String. The encoding used is obtained form Native.getDefaultStringEncoding().
        Parameters:
        offset - byte offset from pointer to start reading bytes
        Returns:
        the String value being pointed to
      • getString

        public String getString​(long offset,
                                String encoding)
        Copy native memory to a Java String using the requested encoding.
        Parameters:
        offset - byte offset from pointer to obtain the native string
        encoding - the desired encoding
        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.

        The strings are decoded using the encoding returned by Native.getDefaultStringEncoding().
      • getStringArray

        public String[] getStringArray​(long offset,
                                       String encoding)
        Returns an array of String based on a native array of char *, using the requested encoding. 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.

        The strings are decoded using the encoding returned by Native.getDefaultStringEncoding().
      • getWideStringArray

        public String[] getWideStringArray​(long offset)
      • getWideStringArray

        public String[] getWideStringArray​(long offset,
                                           int length)
      • getStringArray

        public String[] getStringArray​(long offset,
                                       int length,
                                       String encoding)
        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.
        Parameters:
        offset -
        length -
        encoding -
      • 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.
      • setWideString

        public void setWideString​(long offset,
                                  String value)
        Copy string value to the location being pointed to as a wide string (wchar_t*).
        Parameters:
        offset - byte offset from pointer at which characters in value must be set
        value - java.lang.String value to set
      • setString

        public void setString​(long offset,
                              WString value)
        Copy string value to the location being pointed to as a wide string (wchar_t*).
        Parameters:
        offset - byte offset from pointer at which characters in value must be set
        value - WString value to set
      • setString

        public void setString​(long offset,
                              String value)
        Copy bytes out of string value to the location being pointed to, using the encoding indicated by Native.getDefaultStringEncoding().
        Parameters:
        offset - byte offset from pointer at which characters in value must be set
        value - java.lang.String value to set
      • setString

        public void setString​(long offset,
                              String value,
                              String encoding)
        Copy string value to the location being pointed to, using the requested encoding.
        Parameters:
        offset - byte offset from pointer at which characters in value must be set
        value - java.lang.String value to set
        encoding - desired encoding
      • dump

        public String dump​(long offset,
                           int size)
        Dump memory for debugging purposes.
      • 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.