Package com.sun.jna
Class Pointer
java.lang.Object
com.sun.jna.Pointer
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:
-
Field Summary
Fields -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionvoidclear(long size) Zero memory for the given number of bytes.static final PointercreateConstant(int peer) Convenience constant, equivalent to(void*)CONSTANT.static final PointercreateConstant(long peer) Convenience constant, equivalent to(void*)CONSTANT.dump(long offset, int size) Dump memory for debugging purposes.booleanbytegetByte(long offset) Indirect the native pointer as a pointer tobyte.byte[]getByteArray(long offset, int arraySize) getByteBuffer(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) getNativeLong(long offset) Indirect the native pointer as a pointer tolong.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 ofPointerof the requested size.shortgetShort(long offset) Indirect the native pointer as a pointer toshort.short[]getShortArray(long offset, int arraySize) getString(long offset) Copy native memory to a Java String.Copy native memory to a Java String using the requested encoding.String[]getStringArray(long offset) Returns an array ofStringbased on a native array ofchar *.String[]getStringArray(long offset, int length) Returns an array ofStringbased on a native array ofchar *, using the given array length.String[]getStringArray(long offset, int length, String encoding) Returns an array ofStringbased on a native array ofchar*orwchar_t*based on thewideparameter, using the given array length.String[]getStringArray(long offset, String encoding) Returns an array ofStringbased on a native array ofchar *, using the requested encoding.(package private) ObjectgetWideString(long offset) Read a wide (const wchar_t *) string from memory.String[]getWideStringArray(long offset) 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 longRead 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.voidIndirect 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.voidCopy stringvalueto the location being pointed to as a wide string (wchar_t*).voidCopy bytes out of stringvalueto the location being pointed to, using the encoding indicated byNative.getDefaultStringEncoding().voidCopy stringvalueto the location being pointed to, using the requested encoding.(package private) voidvoidsetWideString(long offset, String value) Copy stringvalueto the location being pointed to as a wide string (wchar_t*).share(long offset) Provide a view of this memory using the given offset to calculate a new base address.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.toString()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 the given array of Pointer to native memory.
-
Field Details
-
NULL
Convenience constant, same asnull. -
peer
protected long peerPointer value of the real native pointer. Use long to be 64-bit safe.
-
-
Constructor Details
-
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 Details
-
createConstant
Convenience constant, equivalent to(void*)CONSTANT. -
createConstant
Convenience constant, equivalent to(void*)CONSTANT. This version will avoid setting any of the high bits on 64-bit systems. -
clear
public void clear(long size) Zero memory for the given number of bytes. -
equals
-
hashCode
public int hashCode() -
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
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
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
-
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
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
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
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
Read a wide (const wchar_t *) string from memory. -
getString
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
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
Returns an array ofPointer. The array length is determined by a NULL-valued terminating element. -
getPointerArray
Returns an array ofPointerof the requested size. -
getStringArray
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
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
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
-
getWideStringArray
-
getStringArray
Returns an array ofStringbased on a native array ofchar*orwchar_t*based on thewideparameter, using the given array length.- Parameters:
offset-length-encoding-
-
setValue
-
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
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
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
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
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
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
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
Dump memory for debugging purposes. -
toString
-
nativeValue
Read the native peer value. Use with caution. -
nativeValue
Set the native peer value. Use with caution.
-