public abstract class Pointer extends Object
isDirect()
for more information.Modifier | Constructor and Description |
---|---|
protected |
Pointer(Runtime runtime,
long address,
boolean direct) |
Modifier and Type | Method and Description |
---|---|
long |
address()
Gets the native address of this memory object (optional operation).
|
abstract Object |
array()
Returns the array that backs this pointer.
|
abstract int |
arrayLength()
Returns the length of this pointer's backing array that is used by this pointer.
|
abstract int |
arrayOffset()
Returns the offset within this pointer's backing array of the first element.
|
abstract void |
checkBounds(long offset,
long length)
Checks that the memory region is within the bounds of this memory object
|
abstract void |
get(long offset,
byte[] dst,
int idx,
int len)
Bulk get method for multiple
byte values. |
abstract void |
get(long offset,
double[] dst,
int idx,
int len)
Bulk get method for multiple
double values. |
abstract void |
get(long offset,
float[] dst,
int idx,
int len)
Bulk get method for multiple
float values. |
abstract void |
get(long offset,
int[] dst,
int idx,
int len)
Bulk get method for multiple
int values. |
abstract void |
get(long offset,
long[] dst,
int idx,
int len)
Bulk get method for multiple
long values. |
void |
get(long offset,
Pointer[] dst,
int idx,
int len)
Bulk get method for multiple
Pointer values. |
abstract void |
get(long offset,
short[] dst,
int idx,
int len)
Bulk get method for multiple
short values. |
abstract long |
getAddress(long offset)
Reads a native memory address value at the given offset.
|
abstract byte |
getByte(long offset)
Reads an
byte (8 bit) value at the given offset. |
abstract double |
getDouble(long offset)
Reads a
double (64 bit) value at the given offset. |
abstract float |
getFloat(long offset)
Reads a
float (32 bit) value at the given offset. |
abstract int |
getInt(long offset)
Reads an
int (32 bit) value at the given offset. |
abstract long |
getInt(Type type,
long offset)
Reads an integer value of the given type, at the given offset.
|
abstract long |
getLong(long offset)
Reads a
long (64 bit) value at the given offset. |
abstract long |
getLongLong(long offset)
Reads a
long (64 bit) value at the given offset. |
abstract long |
getNativeLong(long offset)
Reads a native
long value at the given offset. |
Pointer[] |
getNullTerminatedPointerArray(long offset) |
String[] |
getNullTerminatedStringArray(long offset) |
abstract Pointer |
getPointer(long offset)
Reads an
Pointer value at the given offset. |
abstract Pointer |
getPointer(long offset,
long size)
Reads an
Pointer value at the given offset. |
Runtime |
getRuntime()
Gets the
Runtime this Pointer instance belongs to. |
abstract short |
getShort(long offset)
Reads a
short (16 bit) value at the given offset. |
abstract String |
getString(long offset)
Reads an
String value at the given offset. |
abstract String |
getString(long offset,
int maxLength,
Charset cs)
Reads a
String value at the given offset, using a specific Charset |
abstract boolean |
hasArray()
Indicates whether this Pointer instance is backed by an array.
|
abstract int |
indexOf(long offset,
byte value)
Returns the location of a byte value within the memory area represented by this
Pointer . |
abstract int |
indexOf(long offset,
byte value,
int maxlen)
Returns the location of a byte value within the memory area represented by this
Pointer . |
boolean |
isDirect()
Indicates whether or not this memory object represents a native memory address.
|
static Pointer |
newIntPointer(Runtime runtime,
long address)
Wraps an integer value in an opaque
Pointer instance. |
abstract void |
put(long offset,
byte[] src,
int idx,
int len)
Bulk put method for multiple
byte values. |
abstract void |
put(long offset,
double[] src,
int idx,
int len)
Bulk put method for multiple
double values. |
abstract void |
put(long offset,
float[] src,
int idx,
int len)
Bulk put method for multiple
float values. |
abstract void |
put(long offset,
int[] src,
int idx,
int len)
Bulk put method for multiple
int values. |
abstract void |
put(long offset,
long[] src,
int idx,
int len)
Bulk put method for multiple
long values. |
void |
put(long offset,
Pointer[] src,
int idx,
int len)
Bulk put method for multiple
Pointer values. |
abstract void |
put(long offset,
short[] src,
int idx,
int len)
Bulk put method for multiple
short values. |
abstract void |
putAddress(long offset,
Address value)
Writes a native memory address value at the given offset.
|
abstract void |
putAddress(long offset,
long value)
Writes a native memory address value at the given offset.
|
abstract void |
putByte(long offset,
byte value)
Writes a
byte (8 bit) value at the given offset. |
abstract void |
putDouble(long offset,
double value)
Writes a
double (64 bit, double precision) value at the given offset. |
abstract void |
putFloat(long offset,
float value)
Writes a
float (32 bit, single precision) value at the given offset. |
abstract void |
putInt(long offset,
int value)
Writes an
int (32 bit) value at the given offset. |
abstract void |
putInt(Type type,
long offset,
long value)
Writes an integer of a specific type, at the given offset.
|
abstract void |
putLong(long offset,
long value)
Writes a
native long value at the given offset. |
abstract void |
putLongLong(long offset,
long value)
Writes a
long (64 bit) value at the given offset. |
abstract void |
putNativeLong(long offset,
long value)
Writes a native
long value at the given offset. |
abstract void |
putPointer(long offset,
Pointer value)
Writes a
Pointer value at the given offset. |
abstract void |
putShort(long offset,
short value)
Writes a
short (16 bit) value at the given offset. |
abstract void |
putString(long offset,
String string,
int maxLength,
Charset cs)
Writes a
String value at the given offset, using a specific Charset |
abstract void |
setMemory(long offset,
long size,
byte value)
Sets the value of each byte in the memory area represented by this
Pointer . |
abstract long |
size()
Gets the size of this memory object in bytes (optional operation).
|
abstract Pointer |
slice(long offset)
Creates a new
Pointer representing a sub-region of the memory
referred to by this Pointer . |
abstract Pointer |
slice(long offset,
long size)
Creates a new
Pointer representing a sub-region of the memory
referred to by this Pointer . |
String |
toString() |
abstract void |
transferFrom(long offset,
Pointer src,
long srcOffset,
long count)
Bulk data transfer from one memory location to another.
|
abstract void |
transferTo(long offset,
Pointer dst,
long dstOffset,
long count)
Bulk data transfer from one memory location to another.
|
static Pointer |
wrap(Runtime runtime,
ByteBuffer buffer)
Wraps an existing ByteBuffer in a
Pointer implementation so it can
be used as a parameter to native functions. |
static Pointer |
wrap(Runtime runtime,
long address)
Wraps a native address in a
Pointer instance. |
static Pointer |
wrap(Runtime runtime,
long address,
long size)
Wraps a native address in a
Pointer instance. |
protected Pointer(Runtime runtime, long address, boolean direct)
public static Pointer wrap(Runtime runtime, long address)
Pointer
instance.runtime
- the Runtime
of the pointer.address
- the address
to wrap in a Pointer instance.Pointer
instance.public static Pointer wrap(Runtime runtime, long address, long size)
Pointer
instance.runtime
- the Runtime
of the pointer.address
- the address
to wrap in a Pointer instance.size
- the size of the native memory region.Pointer
instance.public static Pointer wrap(Runtime runtime, ByteBuffer buffer)
Pointer
implementation so it can
be used as a parameter to native functions.
Wrapping a ByteBuffer is only neccessary if the native function parameter
was declared as a Pointer
. The if the method will always be used
with ByteBuffer
parameters, then the parameter type can just be declared
as ByteBuffer
and the conversion will be performed automatically.
runtime
- the Runtime
the wrapped ByteBuffer
will
be used with.buffer
- the ByteBuffer
to wrap.Pointer
instance that will proxy all accesses to the ByteBuffer contents.public static Pointer newIntPointer(Runtime runtime, long address)
Pointer
instance. This is a Pointer instance that
throws errors when any of the memory access methods are used, but can be otherwise used interchangeably
with a real Pointer.runtime
- the Runtime
of the pointer.address
- the address
to wrap in a Pointer instance.Pointer
instance.public final boolean isDirect()
Memory objects can be either direct (representing native memory), or non-direct (representing java heap memory).
Non-direct memory objects can still be passed to native functions as pointer (void *, char *, etc) parameters, but the java memory will first be copied to a temporary native memory area. The temporary memory area will then be used as the parameter value for the call. If needed, the java memory will be automatically reloaded from the temporary native memory after the native function returns.
Note: the transient nature of the temporary memory allocated for non-direct memory means native functions which store the address value passed to them will fail in unpredictable ways when using non-direct memory. You will need to explicitly allocate direct memory to use those types of functions.
public final long address()
public final Runtime getRuntime()
Runtime
this Pointer
instance belongs to.Runtime
instance of this Pointer
.public abstract long size()
Pointer
points to. If
the size is unknown, Long.MAX_VALUE
is returned}.public abstract boolean hasArray()
public abstract Object array()
UnsupportedOperationException
- if this pointer does not have a backing array.public abstract int arrayOffset()
UnsupportedOperationException
- if this pointer does not have a backing arraypublic abstract int arrayLength()
UnsupportedOperationException
- if this pointer does not have a backing arraypublic abstract byte getByte(long offset)
byte
(8 bit) value at the given offset.offset
- The offset from the start of the memory this Pointer
represents at which the value will be read.byte
value at the offset.public abstract short getShort(long offset)
short
(16 bit) value at the given offset.offset
- The offset from the start of the memory this Pointer
represents at which the value will be read.short
value at the offset.public abstract int getInt(long offset)
int
(32 bit) value at the given offset.offset
- The offset from the start of the memory this Pointer
represents at which the value will be read.int
value contained in the memory at the offset.public abstract long getLong(long offset)
long
(64 bit) value at the given offset.offset
- The offset from the start of the memory this Pointer
represents at which the value will be read.long
value at the offset.public abstract long getLongLong(long offset)
long
(64 bit) value at the given offset.offset
- The offset from the start of the memory this Pointer
represents at which the value will be read.long
value at the offset.public abstract float getFloat(long offset)
float
(32 bit) value at the given offset.offset
- The offset from the start of the memory this Pointer
represents at which the value will be read.float
value at the offset.public abstract double getDouble(long offset)
double
(64 bit) value at the given offset.offset
- The offset from the start of the memory this Pointer
represents at which the value will be read.double
value at the offset.public abstract long getNativeLong(long offset)
long
value at the given offset.
A native long
can be either 32 or 64 bits in size, depending
on the cpu architecture, and the C ABI in use.
For windows, a long is always 32 bits (4 bytes) in size, but on unix systems, a long on a 32bit system is 32 bits, and on a 64bit system, is 64 bits.
offset
- The offset from the start of the memory this Pointer
represents at which the value will be read.long
value at the offset.NativeLong
public abstract long getInt(Type type, long offset)
type
- Type of integer to read.offset
- The offset from the start of the memory this Pointer
represents at which the value will be read.int
value contained in the memory at the offset.public abstract void putByte(long offset, byte value)
byte
(8 bit) value at the given offset.offset
- The offset from the start of the memory this Pointer
represents at which the value will be written.value
- the byte
value to be written.public abstract void putShort(long offset, short value)
short
(16 bit) value at the given offset.offset
- The offset from the start of the memory this Pointer
represents at which the value will be written.value
- the short
value to be written.public abstract void putInt(long offset, int value)
int
(32 bit) value at the given offset.offset
- The offset from the start of the memory this Pointer
represents at which the value will be written.value
- the int
value to be written.public abstract void putLong(long offset, long value)
native long
value at the given offset.offset
- The offset from the start of the memory this Pointer
represents at which the value will be written.value
- the long
value to be written.public abstract void putLongLong(long offset, long value)
long
(64 bit) value at the given offset.offset
- The offset from the start of the memory this Pointer
represents at which the value will be written.value
- the long
value to be written.public abstract void putFloat(long offset, float value)
float
(32 bit, single precision) value at the given offset.offset
- The offset from the start of the memory this Pointer
represents at which the value will be written.value
- the float
value to be written.public abstract void putDouble(long offset, double value)
double
(64 bit, double precision) value at the given offset.offset
- The offset from the start of the memory this Pointer
represents at which the value will be written.value
- the double
value to be written.public abstract void putNativeLong(long offset, long value)
long
value at the given offset.
A native long
can be either 32 or 64 bits in size, depending
on the cpu architecture, and the C ABI in use.
For windows, a long is always 32 bits (4 bytes) in size, but on unix systems, a long on a 32bit system is 32 bits, and on a 64bit system, is 64 bits.
offset
- The offset from the start of the memory this Pointer
represents at which the value will be written.value
- the native long
value to be written.public abstract void putInt(Type type, long offset, long value)
type
- The integer type.offset
- The offset from the start of the memory this Pointer
represents at which the value will be written.value
- the int
value to be written.public abstract long getAddress(long offset)
A native address can be either 32 or 64 bits in size, depending on the cpu architecture.
offset
- The offset from the start of the memory this Pointer
represents at which the value will be read.Address
public abstract void putAddress(long offset, long value)
A native address can be either 32 or 64 bits in size, depending on the cpu architecture.
offset
- The offset from the start of the memory this Pointer
represents at which the value will be written.value
- The native address value to be written.Address
public abstract void putAddress(long offset, Address value)
A native address can be either 32 or 64 bits in size, depending on the cpu architecture.
offset
- The offset from the start of the memory this Pointer
represents at which the value will be written.value
- The native address value to be written.Address
public abstract void get(long offset, byte[] dst, int idx, int len)
byte
values.
This method reads multiple byte
values from consecutive addresses,
beginning at the given offset, and stores them in an array.offset
- the offset from the start of the memory this Pointer
represents at which the first value will be read.dst
- the array into which values are to be stored.idx
- the start index in the dst
array to begin storing the values.len
- the number of values to be read.public abstract void put(long offset, byte[] src, int idx, int len)
byte
values.
This method writes multiple byte
values to consecutive addresses,
beginning at the given offset, from an array.offset
- the offset from the start of the memory this Pointer
represents at which the first value will be written.src
- the array to get values from.idx
- the start index in the dst
array to begin reading values.len
- the number of values to be written.public abstract void get(long offset, short[] dst, int idx, int len)
short
values.
This method reads multiple short
values from consecutive addresses,
beginning at the given offset, and stores them in an array.offset
- The offset from the start of the memory this Pointer
represents at which the first value will be read.dst
- The array into which values are to be stored.idx
- the start index in the dst
array to begin storing the values.len
- the number of values to be read.public abstract void put(long offset, short[] src, int idx, int len)
short
values.
This method writes multiple short
values to consecutive addresses,
beginning at the given offset, from an array.offset
- the offset from the start of the memory this Pointer
represents at which the first value will be written.src
- the array to get values from.idx
- the start index in the dst
array to begin reading values.len
- the number of values to be written.public abstract void get(long offset, int[] dst, int idx, int len)
int
values.
This method reads multiple int
values from consecutive addresses,
beginning at the given offset, and stores them in an array.offset
- The offset from the start of the memory this Pointer
represents at which the first value will be read.dst
- The array into which values are to be stored.idx
- the start index in the dst
array to begin storing the values.len
- the number of values to be read.public abstract void put(long offset, int[] src, int idx, int len)
int
values.
This method writes multiple int
values to consecutive addresses,
beginning at the given offset, from an array.offset
- the offset from the start of the memory this Pointer
represents at which the first value will be written.src
- the array to get values from.idx
- the start index in the dst
array to begin reading values.len
- the number of values to be written.public abstract void get(long offset, long[] dst, int idx, int len)
long
values.
This method reads multiple long
values from consecutive addresses,
beginning at the given offset, and stores them in an array.offset
- The offset from the start of the memory this Pointer
represents at which the first value will be read.dst
- The array into which values are to be stored.idx
- the start index in the dst
array to begin storing the values.len
- the number of values to be read.public abstract void put(long offset, long[] src, int idx, int len)
long
values.
This method writes multiple long
values to consecutive addresses,
beginning at the given offset, from an array.offset
- the offset from the start of the memory this Pointer
represents at which the first value will be written.src
- the array to get values from.idx
- the start index in the dst
array to begin reading values.len
- the number of values to be written.public abstract void get(long offset, float[] dst, int idx, int len)
float
values.
This method reads multiple float
values from consecutive addresses,
beginning at the given offset, and stores them in an array.offset
- The offset from the start of the memory this Pointer
represents at which the first value will be read.dst
- The array into which values are to be stored.idx
- the start index in the dst
array to begin storing the values.len
- the number of values to be read.public abstract void put(long offset, float[] src, int idx, int len)
float
values.
This method writes multiple float
values to consecutive addresses,
beginning at the given offset, from an array.offset
- the offset from the start of the memory this Pointer
represents at which the first value will be written.src
- the array to get values from.idx
- the start index in the dst
array to begin reading values.len
- the number of values to be written.public abstract void get(long offset, double[] dst, int idx, int len)
double
values.
This method reads multiple double
values from consecutive addresses,
beginning at the given offset, and stores them in an array.offset
- The offset from the start of the memory this Pointer
represents at which the first value will be read.dst
- The array into which values are to be stored.idx
- the start index in the dst
array to begin storing the values.len
- the number of values to be read.public abstract void put(long offset, double[] src, int idx, int len)
double
values.
This method writes multiple double
values to consecutive addresses,
beginning at the given offset, from an array.offset
- the offset from the start of the memory this Pointer
represents at which the first value will be written.src
- the array to get values from.idx
- the start index in the dst
array to begin reading values.len
- the number of values to be written.public abstract Pointer getPointer(long offset)
Pointer
value at the given offset.offset
- the offset from the start of the memory this Pointer
represents at which the value will be read.Pointer
value read from memory.public abstract Pointer getPointer(long offset, long size)
Pointer
value at the given offset.offset
- the offset from the start of the memory this Pointer
represents at which the value will be read.size
- the maximum size of the memory location the returned Pointer
represents.Pointer
value read from memory.public abstract void putPointer(long offset, Pointer value)
Pointer
value at the given offset.offset
- The offset from the start of the memory this Pointer
represents at which the value will be written.value
- the Pointer
value to be written to memory.public abstract String getString(long offset)
String
value at the given offset.offset
- the offset from the start of the memory this Pointer
represents at which the value will be read.String
value read from memory.public abstract String getString(long offset, int maxLength, Charset cs)
String
value at the given offset, using a specific Charset
offset
- the offset from the start of the memory this Pointer
represents at which the value will be read.maxLength
- the maximum size of memory to search for a NUL byte.cs
- the Charset
to use to decode the string.String
value read from memory.public abstract void putString(long offset, String string, int maxLength, Charset cs)
String
value at the given offset, using a specific Charset
offset
- the offset from the start of the memory this Pointer
represents at which the value will be written.string
- the string to be written.maxLength
- the maximum size of memory to use to store the string.cs
- the Charset
to use to decode the string.public abstract Pointer slice(long offset)
Pointer
representing a sub-region of the memory
referred to by this Pointer
.offset
- the offset from the start of the memory this Pointer
represents at which the new Pointer
will start.Pointer
instance representing the new sub-region.public abstract Pointer slice(long offset, long size)
Pointer
representing a sub-region of the memory
referred to by this Pointer
.offset
- the offset from the start of the memory this Pointer
represents at which the new Pointer
will start.size
- the maximum size of the memory sub-region.Pointer
instance representing the new sub-region.public abstract void transferTo(long offset, Pointer dst, long dstOffset, long count)
offset
- the offset from the start of the memory location this Pointer
represents to begin copying from.dst
- the destination memory location to transfer data to.dstOffset
- the offset from the start of the memory location the destination Pointer
represents to begin copying to.count
- the number of bytes to transfer.public abstract void transferFrom(long offset, Pointer src, long srcOffset, long count)
offset
- the offset from the start of the memory location this Pointer
represents to begin copying to.src
- the destination memory location to transfer data from.srcOffset
- the offset from the start of the memory location the destination Pointer
represents to begin copying from.count
- the number of bytes to transfer.public abstract void checkBounds(long offset, long length)
offset
- the starting point within this memory region.length
- the length of the memory region in bytesIndexOutOfBoundsException
- if the memory region is not within the bounds.public abstract void setMemory(long offset, long size, byte value)
Pointer
.
to a specified value.offset
- the offset from the start of the memory location this Pointer
represents to begin writing to.size
- the number of bytes to set to the value.value
- the value to set each byte to.public abstract int indexOf(long offset, byte value)
Pointer
.offset
- the offset from the start of the memory location this Pointer
represents to begin searching.value
- the byte
value to locate.public abstract int indexOf(long offset, byte value, int maxlen)
Pointer
.offset
- the offset from the start of the memory location this Pointer
represents to begin searching.value
- the byte
value to locate.maxlen
- the maximum number of bytes to search for the desired value.public void get(long offset, Pointer[] dst, int idx, int len)
Pointer
values.
This method reads multiple Pointer
values from consecutive addresses,
beginning at the given offset, and stores them in an array.offset
- The offset from the start of the memory this Pointer
represents at which the first value will be read.dst
- The array into which values are to be stored.idx
- the start index in the dst
array to begin storing the values.len
- the number of values to be read.public void put(long offset, Pointer[] src, int idx, int len)
Pointer
values.
This method writes multiple Pointer
values to consecutive addresses,
beginning at the given offset, from an array.offset
- the offset from the start of the memory this Pointer
represents at which the first value will be written.src
- the array to get values from.idx
- the start index in the src
array to begin reading values.len
- the number of values to be written.public String[] getNullTerminatedStringArray(long offset)
public Pointer[] getNullTerminatedPointerArray(long offset)
Copyright © 2017. All rights reserved.