Package com.sun.jna
Class Pointer
- java.lang.Object
-
- com.sun.jna.Pointer
-
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 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 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 tobyte
.byte[]
getByteArray(long offset, int arraySize)
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 towchar_t
.char[]
getCharArray(long offset, int arraySize)
double
getDouble(long offset)
Indirect the native pointer as a pointer todouble
.double[]
getDoubleArray(long offset, int arraySize)
float
getFloat(long offset)
Indirect the native pointer as a pointer tofloat
.float[]
getFloatArray(long offset, int arraySize)
int
getInt(long offset)
Indirect the native pointer as a pointer toint
.int[]
getIntArray(long offset, int arraySize)
long
getLong(long offset)
Indirect the native pointer as a pointer tolong
.long[]
getLongArray(long offset, int arraySize)
NativeLong
getNativeLong(long offset)
Indirect the native pointer as a pointer tolong
.Pointer
getPointer(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 ofPointer
of the requested size.short
getShort(long offset)
Indirect the native pointer as a pointer toshort
.short[]
getShortArray(long offset, int arraySize)
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 ofString
based on a native array ofchar *
.String[]
getStringArray(long offset, int length)
Returns an array ofString
based on a native array ofchar *
, using the given array length.String[]
getStringArray(long offset, int length, String encoding)
Returns an array ofString
based on a native array ofchar*
orwchar_t*
based on thewide
parameter, using the given array length.String[]
getStringArray(long offset, String encoding)
Returns an array ofString
based on a native array ofchar *
, 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)
Setvalue
at location being pointed to.void
setChar(long offset, char value)
Setvalue
at location being pointed to.void
setDouble(long offset, double value)
Setvalue
at location being pointed to.void
setFloat(long offset, float value)
Setvalue
at location being pointed to.void
setInt(long offset, int value)
Setvalue
at location being pointed to.void
setLong(long offset, long value)
Setvalue
at location being pointed to.void
setMemory(long offset, long length, byte value)
Writevalue
to the requested bank of memory.void
setNativeLong(long offset, NativeLong value)
Setvalue
at location being pointed to.void
setPointer(long offset, Pointer value)
Setvalue
at location being pointed to.void
setShort(long offset, short value)
Setvalue
at location being pointed to.void
setString(long offset, WString value)
Copy stringvalue
to the location being pointed to as a wide string (wchar_t*
).void
setString(long offset, String value)
Copy bytes out of stringvalue
to the location being pointed to, using the encoding indicated byNative.getDefaultStringEncoding()
.void
setString(long offset, String value, String encoding)
Copy stringvalue
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 stringvalue
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 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.
-
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
-byte
array 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
-short
array 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
-char
array 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
-int
array 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
-long
array 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
-float
array 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
-double
array 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
-Pointer
array 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
-byte
array from which to copyindex
- array index from which to start copyinglength
- number of elements frombuf
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 copiedbuf
-short
array from which to copyindex
- array index from which to start copyinglength
- number of elements frombuf
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 copiedbuf
-char
array from which to copyindex
- array index from which to start copyinglength
- number of elements frombuf
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 copiedbuf
-int
array from which to copyindex
- array index from which to start copyinglength
- number of elements frombuf
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 copiedbuf
-long
array from which to copyindex
- array index from which to start copyinglength
- number of elements frombuf
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 copiedbuf
-float
array from which to copyindex
- array index from which to start copyinglength
- number of elements frombuf
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 copiedbuf
-double
array from which to copyindex
- array index from which to start copyinglength
- number of elements frombuf
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 copiedbuf
-Pointer
array from which to copyindex
- array index from which to start copyinglength
- number of elements frombuf
that must be copied
-
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
byte
value 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_t
value 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
short
value 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
int
value 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
long
value 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
long
value 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
float
value 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
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, ornull
if the pointer value isNULL
;
-
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 bufferlength
- 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 formNative.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 stringencoding
- the desired encoding- Returns:
- the
String
value 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 ofPointer
of the requested size.
-
getStringArray
public String[] getStringArray(long offset)
Returns an array of
The strings are decoded using the encoding returned byString
based on a native array ofchar *
. The array length is determined by a NULL-valued terminating element.Native.getDefaultStringEncoding()
.
-
getStringArray
public String[] getStringArray(long offset, String encoding)
Returns an array ofString
based on a native array ofchar *
, 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
The strings are decoded using the encoding returned byString
based on a native array ofchar *
, using the given array length.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 ofString
based on a native array ofchar*
orwchar_t*
based on thewide
parameter, using the given array length.- Parameters:
offset
-length
-encoding
-
-
setMemory
public void setMemory(long offset, long length, byte value)
Writevalue
to 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)
Setvalue
at location being pointed to. This is equivalent to the expression*((jbyte *)((char *)Pointer + offset)) = value
.- Parameters:
offset
- byte offset from pointer at whichvalue
must be setvalue
-byte
value to set
-
setShort
public void setShort(long offset, short value)
Setvalue
at location being pointed to. This is equivalent to the expression*((jshort *)((char *)Pointer + offset)) = value
.- Parameters:
offset
- byte offset from pointer at whichvalue
must be setvalue
-short
value to set
-
setChar
public void setChar(long offset, char value)
Setvalue
at location being pointed to. This is equivalent to the expression*((wchar_t *)((char *)Pointer + offset)) = value
.- Parameters:
offset
- byte offset from pointer at whichvalue
must be setvalue
-char
value to set
-
setInt
public void setInt(long offset, int value)
Setvalue
at location being pointed to. This is equivalent to the expression*((jint *)((char *)Pointer + offset)) = value
.- Parameters:
offset
- byte offset from pointer at whichvalue
must be setvalue
-int
value to set
-
setLong
public void setLong(long offset, long value)
Setvalue
at location being pointed to. This is equivalent to the expression*((jlong *)((char *)Pointer + offset)) = value
.- Parameters:
offset
- byte offset from pointer at whichvalue
must be setvalue
-long
value to set
-
setNativeLong
public void setNativeLong(long offset, NativeLong value)
Setvalue
at location being pointed to. This is equivalent to the expression*((long *)((char *)Pointer + offset)) = value
.- Parameters:
offset
- byte offset from pointer at whichvalue
must be setvalue
-long
value to set
-
setFloat
public void setFloat(long offset, float value)
Setvalue
at location being pointed to. This is equivalent to the expression*((jfloat *)((char *)Pointer + offset)) = value
.- Parameters:
offset
- byte offset from pointer at whichvalue
must be setvalue
-float
value to set
-
setDouble
public void setDouble(long offset, double value)
Setvalue
at location being pointed to. This is equivalent to the expression*((jdouble *)((char *)Pointer + offset)) = value
.- Parameters:
offset
- byte offset from pointer at whichvalue
must be setvalue
-double
value to set
-
setPointer
public void setPointer(long offset, Pointer value)
Setvalue
at location being pointed to. This is equivalent to the expression*((void **)((char *)Pointer + offset)) = value
.- Parameters:
offset
- byte offset from pointer at whichvalue
must be setvalue
-Pointer
holding the actual pointer value to set, which may benull
to indicate aNULL
pointer.
-
setWideString
public void setWideString(long offset, String value)
Copy stringvalue
to the location being pointed to as a wide string (wchar_t*
).- Parameters:
offset
- byte offset from pointer at which characters invalue
must be setvalue
-java.lang.String
value to set
-
setString
public void setString(long offset, WString value)
Copy stringvalue
to the location being pointed to as a wide string (wchar_t*
).- Parameters:
offset
- byte offset from pointer at which characters invalue
must be setvalue
-WString
value to set
-
setString
public void setString(long offset, String value)
Copy bytes out of stringvalue
to the location being pointed to, using the encoding indicated byNative.getDefaultStringEncoding()
.- Parameters:
offset
- byte offset from pointer at which characters invalue
must be setvalue
-java.lang.String
value to set
-
setString
public void setString(long offset, String value, String encoding)
Copy stringvalue
to the location being pointed to, using the requested encoding.- Parameters:
offset
- byte offset from pointer at which characters invalue
must be setvalue
-java.lang.String
value to setencoding
- 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.
-
-