Package com.sun.jna
Class Pointer
- java.lang.Object
-
- com.sun.jna.Pointer
-
public class Pointer extends java.lang.ObjectAn 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 aswrite,read,getXXX, andsetXXX, 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
-
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description voidclear(long size)Zero memory for the given number of bytes.static PointercreateConstant(int peer)Convenience constant, equivalent to(void*)CONSTANT.static PointercreateConstant(long peer)Convenience constant, equivalent to(void*)CONSTANT.java.lang.Stringdump(long offset, int size)Dump memory for debugging purposes.booleanequals(java.lang.Object o)bytegetByte(long offset)Indirect the native pointer as a pointer tobyte.byte[]getByteArray(long offset, int arraySize)java.nio.ByteBuffergetByteBuffer(long offset, long length)Get a ByteBuffer mapped to the memory pointed to by the pointer, ensuring the buffer uses native byte order.chargetChar(long offset)Indirect the native pointer as a pointer towchar_t.char[]getCharArray(long offset, int arraySize)doublegetDouble(long offset)Indirect the native pointer as a pointer todouble.double[]getDoubleArray(long offset, int arraySize)floatgetFloat(long offset)Indirect the native pointer as a pointer tofloat.float[]getFloatArray(long offset, int arraySize)intgetInt(long offset)Indirect the native pointer as a pointer toint.int[]getIntArray(long offset, int arraySize)longgetLong(long offset)Indirect the native pointer as a pointer tolong.long[]getLongArray(long offset, int arraySize)NativeLonggetNativeLong(long offset)Indirect the native pointer as a pointer tolong.PointergetPointer(long offset)Indirect the native pointer as a pointer to pointer.Pointer[]getPointerArray(long offset)Returns an array ofPointer.Pointer[]getPointerArray(long offset, int arraySize)Returns an array ofPointerof the requested size.shortgetShort(long offset)Indirect the native pointer as a pointer toshort.short[]getShortArray(long offset, int arraySize)java.lang.StringgetString(long offset)Copy native memory to a Java String.java.lang.StringgetString(long offset, java.lang.String encoding)Copy native memory to a Java String using the requested encoding.java.lang.String[]getStringArray(long offset)Returns an array ofStringbased on a native array ofchar *.java.lang.String[]getStringArray(long offset, int length)Returns an array ofStringbased on a native array ofchar *, using the given array length.java.lang.String[]getStringArray(long offset, int length, java.lang.String encoding)Returns an array ofStringbased on a native array ofchar*orwchar_t*based on thewideparameter, using the given array length.java.lang.String[]getStringArray(long offset, java.lang.String encoding)Returns an array ofStringbased on a native array ofchar *, using the requested encoding.(package private) java.lang.ObjectgetValue(long offset, java.lang.Class<?> type, java.lang.Object currentValue)java.lang.StringgetWideString(long offset)Read a wide (const wchar_t *) string from memory.java.lang.String[]getWideStringArray(long offset)java.lang.String[]getWideStringArray(long offset, int length)inthashCode()longindexOf(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 longnativeValue(Pointer p)Read the native peer value.static voidnativeValue(Pointer p, long value)Set the native peer value.voidread(long offset, byte[] buf, int index, int length)Indirect the native pointer, copying from memory pointed to by native pointer, into the specified array.voidread(long offset, char[] buf, int index, int length)Indirect the native pointer, copying from memory pointed to by native pointer, into the specified array.voidread(long offset, double[] buf, int index, int length)Indirect the native pointer, copying from memory pointed to by native pointer, into the specified array.voidread(long offset, float[] buf, int index, int length)Indirect the native pointer, copying from memory pointed to by native pointer, into the specified array.voidread(long offset, int[] buf, int index, int length)Indirect the native pointer, copying from memory pointed to by native pointer, into the specified array.voidread(long offset, long[] buf, int index, int length)Indirect the native pointer, copying from memory pointed to by native pointer, into the specified array.voidread(long offset, short[] buf, int index, int length)Indirect the native pointer, copying from memory pointed to by native pointer, into the specified array.voidread(long offset, Pointer[] buf, int index, int length)Indirect the native pointer, copying from memory pointed to by native pointer, into the specified array.voidsetByte(long offset, byte value)Setvalueat location being pointed to.voidsetChar(long offset, char value)Setvalueat location being pointed to.voidsetDouble(long offset, double value)Setvalueat location being pointed to.voidsetFloat(long offset, float value)Setvalueat location being pointed to.voidsetInt(long offset, int value)Setvalueat location being pointed to.voidsetLong(long offset, long value)Setvalueat location being pointed to.voidsetMemory(long offset, long length, byte value)Writevalueto the requested bank of memory.voidsetNativeLong(long offset, NativeLong value)Setvalueat location being pointed to.voidsetPointer(long offset, Pointer value)Setvalueat location being pointed to.voidsetShort(long offset, short value)Setvalueat location being pointed to.voidsetString(long offset, WString value)Copy stringvalueto the location being pointed to as a wide string (wchar_t*).voidsetString(long offset, java.lang.String value)Copy bytes out of stringvalueto the location being pointed to, using the encoding indicated byNative.getDefaultStringEncoding().voidsetString(long offset, java.lang.String value, java.lang.String encoding)Copy stringvalueto the location being pointed to, using the requested encoding.(package private) voidsetValue(long offset, java.lang.Object value, java.lang.Class<?> type)voidsetWideString(long offset, java.lang.String value)Copy stringvalueto the location being pointed to as a wide string (wchar_t*).Pointershare(long offset)Provide a view of this memory using the given offset to calculate a new base address.Pointershare(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.java.lang.StringtoString()voidwrite(long offset, byte[] buf, int index, int length)Indirect the native pointer, copying into memory pointed to by native pointer, from the specified array.voidwrite(long offset, char[] buf, int index, int length)Indirect the native pointer, copying into memory pointed to by native pointer, from the specified array.voidwrite(long offset, double[] buf, int index, int length)Indirect the native pointer, copying into memory pointed to by native pointer, from the specified array.voidwrite(long offset, float[] buf, int index, int length)Indirect the native pointer, copying into memory pointed to by native pointer, from the specified array.voidwrite(long offset, int[] buf, int index, int length)Indirect the native pointer, copying into memory pointed to by native pointer, from the specified array.voidwrite(long offset, long[] buf, int index, int length)Indirect the native pointer, copying into memory pointed to by native pointer, from the specified array.voidwrite(long offset, short[] buf, int index, int length)Indirect the native pointer, copying into memory pointed to by native pointer, from the specified array.voidwrite(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 asnull.
-
peer
protected long peer
Pointer value of the real native pointer. Use long to be 64-bit safe.
-
-
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(java.lang.Object o)
- Overrides:
equalsin classjava.lang.Object
-
hashCode
public int hashCode()
- Overrides:
hashCodein classjava.lang.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 copiedbuf-bytearray into which data is copiedindex- array index to which data is copiedlength- 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 copiedbuf-shortarray into which data is copiedindex- array index to which data is copiedlength- 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 copiedbuf-chararray into which data is copiedindex- array index to which data is copiedlength- 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 copiedbuf-intarray into which data is copiedindex- array index to which data is copiedlength- 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 copiedbuf-longarray into which data is copiedindex- array index to which data is copiedlength- 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 copiedbuf-floatarray into which data is copiedindex- array index to which data is copiedlength- 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 copiedbuf-doublearray into which data is copiedindex- array index to which data is copiedlength- 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 copiedbuf-Pointerarray into which data is copiedindex- array index to which data is copiedlength- 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 copiedbuf-bytearray from which to copyindex- array index from which to start copyinglength- number of elements frombufthat 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 copiedbuf-shortarray from which to copyindex- array index from which to start copyinglength- number of elements frombufthat 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 copiedbuf-chararray from which to copyindex- array index from which to start copyinglength- number of elements frombufthat 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 copiedbuf-intarray from which to copyindex- array index from which to start copyinglength- number of elements frombufthat 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 copiedbuf-longarray from which to copyindex- array index from which to start copyinglength- number of elements frombufthat 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 copiedbuf-floatarray from which to copyindex- array index from which to start copyinglength- number of elements frombufthat 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 copiedbuf-doublearray from which to copyindex- array index from which to start copyinglength- number of elements frombufthat 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 copiedbuf-Pointerarray from which to copyindex- array index from which to start copyinglength- number of elements frombufthat must be copied
-
getValue
java.lang.Object getValue(long offset, java.lang.Class<?> type, java.lang.Object currentValue)
-
getByte
public byte getByte(long offset)
Indirect the native pointer as a pointer tobyte. This is equivalent to the expression*((jbyte *)((char *)Pointer + offset)).- Parameters:
offset- offset from pointer to perform the indirection- Returns:
- the
bytevalue being pointed to
-
getChar
public char getChar(long offset)
Indirect the native pointer as a pointer towchar_t. This is equivalent to the expression*((wchar_t*)((char *)Pointer + offset)).- Parameters:
offset- offset from pointer to perform the indirection- Returns:
- the
wchar_tvalue being pointed to
-
getShort
public short getShort(long offset)
Indirect the native pointer as a pointer toshort. This is equivalent to the expression*((jshort *)((char *)Pointer + offset)).- Parameters:
offset- byte offset from pointer to perform the indirection- Returns:
- the
shortvalue being pointed to
-
getInt
public int getInt(long offset)
Indirect the native pointer as a pointer toint. This is equivalent to the expression*((jint *)((char *)Pointer + offset)).- Parameters:
offset- byte offset from pointer to perform the indirection- Returns:
- the
intvalue being pointed to
-
getLong
public long getLong(long offset)
Indirect the native pointer as a pointer tolong. This is equivalent to the expression*((jlong *)((char *)Pointer + offset)).- Parameters:
offset- byte offset from pointer to perform the indirection- Returns:
- the
longvalue being pointed to
-
getNativeLong
public NativeLong getNativeLong(long offset)
Indirect the native pointer as a pointer tolong. This is equivalent to the expression*((long *)((char *)Pointer + offset)).- Parameters:
offset- byte offset from pointer to perform the indirection- Returns:
- the
longvalue being pointed to
-
getFloat
public float getFloat(long offset)
Indirect the native pointer as a pointer tofloat. This is equivalent to the expression*((jfloat *)((char *)Pointer + offset)).- Parameters:
offset- byte offset from pointer to perform the indirection- Returns:
- the
floatvalue being pointed to
-
getDouble
public double getDouble(long offset)
Indirect the native pointer as a pointer todouble. This is equivalent to the expression*((jdouble *)((char *)Pointer + offset)).- Parameters:
offset- byte offset from pointer to perform the indirection- Returns:
- the
doublevalue 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
Pointerequivalent of the pointer value being pointed to, ornullif the pointer value isNULL;
-
getByteBuffer
public java.nio.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 bufferlength- Length of ByteBuffer- Returns:
- a direct ByteBuffer that accesses the memory being pointed to,
-
getWideString
public java.lang.String getWideString(long offset)
Read a wide (const wchar_t *) string from memory.
-
getString
public java.lang.String getString(long offset)
Copy native memory to a Java String. The encoding used is obtained formNative.getDefaultStringEncoding().- Parameters:
offset- byte offset from pointer to start reading bytes- Returns:
- the
Stringvalue being pointed to
-
getString
public java.lang.String getString(long offset, java.lang.String encoding)Copy native memory to a Java String using the requested encoding.- Parameters:
offset- byte offset from pointer to obtain the native stringencoding- the desired encoding- Returns:
- the
Stringvalue being pointed to
-
getByteArray
public byte[] getByteArray(long offset, int arraySize)
-
getCharArray
public char[] getCharArray(long offset, int arraySize)
-
getShortArray
public short[] getShortArray(long offset, int arraySize)
-
getIntArray
public int[] getIntArray(long offset, int arraySize)
-
getLongArray
public long[] getLongArray(long offset, int arraySize)
-
getFloatArray
public float[] getFloatArray(long offset, int arraySize)
-
getDoubleArray
public double[] getDoubleArray(long offset, int arraySize)
-
getPointerArray
public Pointer[] getPointerArray(long offset)
Returns an array ofPointer. The array length is determined by a NULL-valued terminating element.
-
getPointerArray
public Pointer[] getPointerArray(long offset, int arraySize)
Returns an array ofPointerof the requested size.
-
getStringArray
public java.lang.String[] getStringArray(long offset)
Returns an array of
The strings are decoded using the encoding returned byStringbased on a native array ofchar *. The array length is determined by a NULL-valued terminating element.Native.getDefaultStringEncoding().
-
getStringArray
public java.lang.String[] getStringArray(long offset, java.lang.String encoding)Returns an array ofStringbased on a native array ofchar *, using the requested encoding. The array length is determined by a NULL-valued terminating element.
-
getStringArray
public java.lang.String[] getStringArray(long offset, int length)Returns an array of
The strings are decoded using the encoding returned byStringbased on a native array ofchar *, using the given array length.Native.getDefaultStringEncoding().
-
getWideStringArray
public java.lang.String[] getWideStringArray(long offset)
-
getWideStringArray
public java.lang.String[] getWideStringArray(long offset, int length)
-
getStringArray
public java.lang.String[] getStringArray(long offset, int length, java.lang.String encoding)Returns an array ofStringbased on a native array ofchar*orwchar_t*based on thewideparameter, using the given array length.- Parameters:
offset-length-encoding-
-
setValue
void setValue(long offset, java.lang.Object value, java.lang.Class<?> type)
-
setMemory
public void setMemory(long offset, long length, byte value)Writevalueto the requested bank of memory.- Parameters:
offset- byte offset from pointer to startlength- number of bytes to writevalue- value to be written
-
setByte
public void setByte(long offset, byte value)Setvalueat location being pointed to. This is equivalent to the expression*((jbyte *)((char *)Pointer + offset)) = value.- Parameters:
offset- byte offset from pointer at whichvaluemust be setvalue-bytevalue to set
-
setShort
public void setShort(long offset, short value)Setvalueat location being pointed to. This is equivalent to the expression*((jshort *)((char *)Pointer + offset)) = value.- Parameters:
offset- byte offset from pointer at whichvaluemust be setvalue-shortvalue to set
-
setChar
public void setChar(long offset, char value)Setvalueat location being pointed to. This is equivalent to the expression*((wchar_t *)((char *)Pointer + offset)) = value.- Parameters:
offset- byte offset from pointer at whichvaluemust be setvalue-charvalue to set
-
setInt
public void setInt(long offset, int value)Setvalueat location being pointed to. This is equivalent to the expression*((jint *)((char *)Pointer + offset)) = value.- Parameters:
offset- byte offset from pointer at whichvaluemust be setvalue-intvalue to set
-
setLong
public void setLong(long offset, long value)Setvalueat location being pointed to. This is equivalent to the expression*((jlong *)((char *)Pointer + offset)) = value.- Parameters:
offset- byte offset from pointer at whichvaluemust be setvalue-longvalue to set
-
setNativeLong
public void setNativeLong(long offset, NativeLong value)Setvalueat location being pointed to. This is equivalent to the expression*((long *)((char *)Pointer + offset)) = value.- Parameters:
offset- byte offset from pointer at whichvaluemust be setvalue-longvalue to set
-
setFloat
public void setFloat(long offset, float value)Setvalueat location being pointed to. This is equivalent to the expression*((jfloat *)((char *)Pointer + offset)) = value.- Parameters:
offset- byte offset from pointer at whichvaluemust be setvalue-floatvalue to set
-
setDouble
public void setDouble(long offset, double value)Setvalueat location being pointed to. This is equivalent to the expression*((jdouble *)((char *)Pointer + offset)) = value.- Parameters:
offset- byte offset from pointer at whichvaluemust be setvalue-doublevalue to set
-
setPointer
public void setPointer(long offset, Pointer value)Setvalueat location being pointed to. This is equivalent to the expression*((void **)((char *)Pointer + offset)) = value.- Parameters:
offset- byte offset from pointer at whichvaluemust be setvalue-Pointerholding the actual pointer value to set, which may benullto indicate aNULLpointer.
-
setWideString
public void setWideString(long offset, java.lang.String value)Copy stringvalueto the location being pointed to as a wide string (wchar_t*).- Parameters:
offset- byte offset from pointer at which characters invaluemust be setvalue-java.lang.Stringvalue to set
-
setString
public void setString(long offset, WString value)Copy stringvalueto the location being pointed to as a wide string (wchar_t*).- Parameters:
offset- byte offset from pointer at which characters invaluemust be setvalue-WStringvalue to set
-
setString
public void setString(long offset, java.lang.String value)Copy bytes out of stringvalueto the location being pointed to, using the encoding indicated byNative.getDefaultStringEncoding().- Parameters:
offset- byte offset from pointer at which characters invaluemust be setvalue-java.lang.Stringvalue to set
-
setString
public void setString(long offset, java.lang.String value, java.lang.String encoding)Copy stringvalueto the location being pointed to, using the requested encoding.- Parameters:
offset- byte offset from pointer at which characters invaluemust be setvalue-java.lang.Stringvalue to setencoding- desired encoding
-
dump
public java.lang.String dump(long offset, int size)Dump memory for debugging purposes.
-
toString
public java.lang.String toString()
- Overrides:
toStringin classjava.lang.Object
-
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.
-
-