com.sun.jna

Class 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 as write, read, getXXX, and setXXX, provide means to access memory underlying the native pointer.

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

Author: Sheng Liang, originator Todd Fast, suitability modifications Timothy Wall, robust library loading

See Also: Function

Field Summary
static PointerNULL
Convenience constant, same as null.
protected longpeer
Pointer value of the real native pointer.
static intSIZE
Size of a native pointer, in bytes.
Constructor Summary
Pointer()
Derived class must assign peer pointer value.
Pointer(long peer)
Create from native pointer.
Method Summary
voidclear(long size)
Zero memory for the given number of bytes.
static PointercreateConstant(long peer)
Convenience constant, equivalent to (void*)-1.
booleanequals(Object o)
Compares this Pointer to the specified object.
bytegetByte(long offset)
Indirect the native pointer as a pointer to byte.
byte[]getByteArray(long offset, int arraySize)
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 to wchar_t.
char[]getCharArray(long offset, int arraySize)
doublegetDouble(long offset)
Indirect the native pointer as a pointer to double.
double[]getDoubleArray(long offset, int arraySize)
floatgetFloat(long offset)
Indirect the native pointer as a pointer to float.
float[]getFloatArray(long offset, int arraySize)
intgetInt(long offset)
Indirect the native pointer as a pointer to int.
int[]getIntArray(long offset, int arraySize)
longgetLong(long offset)
Indirect the native pointer as a pointer to long.
long[]getLongArray(long offset, int arraySize)
NativeLonggetNativeLong(long offset)
Indirect the native pointer as a pointer to long.
PointergetPointer(long offset)
Indirect the native pointer as a pointer to pointer.
Pointer[]getPointerArray(long base)
Returns an array of Pointer.
Pointer[]getPointerArray(long offset, int arraySize)
Returns an array of Pointer of the requested size.
shortgetShort(long offset)
Indirect the native pointer as a pointer to short.
short[]getShortArray(long offset, int arraySize)
StringgetString(long offset, boolean wide)
Copy native memory to a Java String.
StringgetString(long offset)
Copy native memory to a Java String.
String[]getStringArray(long base)
Returns an array of String based on a native array of char *.
String[]getStringArray(long base, int length)
Returns an array of String based on a native array of char *, using the given array length.
String[]getStringArray(long base, boolean wide)
Returns an array of String based on a native array of char* or wchar_t* based on the wide parameter.
String[]getStringArray(long base, int length, boolean wide)
Returns an array of String based on a native array of char* or wchar_t* based on the wide parameter, using the given array length.
ObjectgetValue(long offset, Class type, Object currentValue)
inthashCode()
Returns a hashcode for the native pointer represented by this Pointer object
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.
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, 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, 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, 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, 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, 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, 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)
Set value at location being pointed to.
voidsetChar(long offset, char value)
Set value at location being pointed to.
voidsetDouble(long offset, double value)
Set value at location being pointed to.
voidsetFloat(long offset, float value)
Set value at location being pointed to.
voidsetInt(long offset, int value)
Set value at location being pointed to.
voidsetLong(long offset, long value)
Set value at location being pointed to.
voidsetMemory(long offset, long length, byte value)
Write value to the requested bank of memory.
voidsetNativeLong(long offset, NativeLong value)
Set value at location being pointed to.
voidsetPointer(long offset, Pointer value)
Set value at location being pointed to.
voidsetShort(long offset, short value)
Set value at location being pointed to.
voidsetString(long offset, String value, boolean wide)
Copy string value to the location being pointed to.
voidsetString(long offset, String value)
Copy string value to the location being pointed to.
voidsetValue(long offset, Object value, Class type)
Pointershare(long offset)
Pointershare(long offset, long sz)
Provide a view of this pointer with a different peer base.
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, short[] 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, 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, 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, double[] 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.
static void_setMemory(long addr, long length, byte value)

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.

SIZE

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

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

clear

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

createConstant

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

equals

public boolean equals(Object o)
Compares this Pointer to the specified object.

Parameters: o A Pointer instance

Returns: True if the other object is a Pointer, and the C pointers being pointed to by these objects are also equal. Returns false otherwise.

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

getByteArray

public byte[] getByteArray(long offset, int arraySize)

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,

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

getCharArray

public char[] getCharArray(long offset, int arraySize)

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

getDoubleArray

public double[] getDoubleArray(long offset, int arraySize)

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

getFloatArray

public float[] getFloatArray(long offset, int arraySize)

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

getIntArray

public int[] getIntArray(long offset, int arraySize)

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

getLongArray

public long[] getLongArray(long offset, int arraySize)

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

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;

getPointerArray

public Pointer[] getPointerArray(long base)
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.

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

getShortArray

public short[] getShortArray(long offset, int arraySize)

getString

public String getString(long offset, boolean wide)
Copy native memory to a Java String. If wide is true, access the memory as an array of wchar_t, otherwise as an array of char, using the default platform encoding.

Parameters: offset byte offset from pointer to obtain the native string v * @param wide whether to convert from a wide or standard C string

Returns: the String value being pointed to

getString

public String getString(long offset)
Copy native memory to a Java String. If the system property jna.encoding is set, uses it as the native charset when decoding the value, otherwise falls back to the default platform encoding.

Parameters: offset byte offset from pointer to obtain the native string

Returns: the String value being pointed to

getStringArray

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

getStringArray

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

getStringArray

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

getStringArray

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

getValue

Object getValue(long offset, Class type, Object currentValue)

hashCode

public int hashCode()
Returns a hashcode for the native pointer represented by this Pointer object

Returns: A hash code value for the represented native pointer

indexOf

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

read

public void read(long offset, byte[] buf, int index, int length)
Indirect the native pointer, copying from memory pointed to by native pointer, into the specified array.

Parameters: offset byte offset from pointer into which data is copied buf byte array into which data is copied index array index from which to start copying length number of elements from native pointer that must be copied

read

public void read(long offset, short[] buf, int index, int length)
Indirect the native pointer, copying from memory pointed to by native pointer, into the specified array.

Parameters: offset byte offset from pointer from which data is copied buf short array into which data is copied index array index to which data is copied length number of elements from native pointer that must be copied

read

public void read(long offset, char[] buf, int index, int length)
Indirect the native pointer, copying from memory pointed to by native pointer, into the specified array.

Parameters: offset byte offset from pointer from which data is copied buf char array into which data is copied index array index to which data is copied length number of elements from native pointer that must be copied

read

public void read(long offset, int[] buf, int index, int length)
Indirect the native pointer, copying from memory pointed to by native pointer, into the specified array.

Parameters: offset byte offset from pointer from which data is copied buf int array into which data is copied index array index to which data is copied length number of elements from native pointer that must be copied

read

public void read(long offset, long[] buf, int index, int length)
Indirect the native pointer, copying from memory pointed to by native pointer, into the specified array.

Parameters: offset byte offset from pointer from which data is copied buf long array into which data is copied index array index to which data is copied length number of elements from native pointer that must be copied

read

public void read(long offset, float[] buf, int index, int length)
Indirect the native pointer, copying from memory pointed to by native pointer, into the specified array.

Parameters: offset byte offset from pointer from which data is copied buf float array into which data is copied index array index to which data is copied length number of elements from native pointer that must be copied

read

public void read(long offset, double[] buf, int index, int length)
Indirect the native pointer, copying from memory pointed to by native pointer, into the specified array.

Parameters: offset byte offset from pointer from which data is copied buf double array into which data is copied index array index to which data is copied length number of elements from native pointer that must be copied

read

public void read(long offset, Pointer[] buf, int index, int length)
Indirect the native pointer, copying from memory pointed to by native pointer, into the specified array.

Parameters: offset byte offset from pointer from which data is copied buf Pointer array into which data is copied index array index to which data is copied length number of elements from native pointer that must be copied

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

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

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

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

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

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

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

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.

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

setString

public void setString(long offset, String value, boolean wide)
Copy string value to the location being pointed to. Copy each element in value, converted to native encoding, at an offsetfrom the location pointed to by this pointer.

Parameters: offset byte offset from pointer at which characters in value must be set value java.lang.String value to set wide whether to write the native string as an array of wchar_t. If false, writes as a NUL-terminated array of char using the default platform encoding.

setString

public void setString(long offset, String value)
Copy string value to the location being pointed to. Copy each element in value, converted to native encoding, at an offsetfrom the location pointed to by this pointer. Uses the value of the system property jna.encoding, if set, to determine the appropriate native charset in which to encode the value. If the property is not set, uses the default platform encoding.

Parameters: offset byte offset from pointer at which characters in value must be set value java.lang.String value to set

setValue

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

share

public Pointer share(long offset)

share

public Pointer share(long offset, long sz)
Provide a view of this pointer with a different peer base.

toString

public String toString()

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

_setMemory

static void _setMemory(long addr, long length, byte value)
Copyright © 2007-2009 Timothy Wall. All Rights Reserved.