com.kenai.jffi
Class MemoryIO

java.lang.Object
  extended by com.kenai.jffi.MemoryIO

public abstract class MemoryIO
extends java.lang.Object

Provides facilities to access native memory from java.


Method Summary
 long allocateMemory(long size, boolean clear)
          Allocates native memory.
abstract  void copyMemory(long src, long dst, long size)
          Copies contents of a native memory location to another native memory location.
 void freeMemory(long address)
          Releases memory allocated via allocateMemory back to the system.
abstract  long getAddress(long address)
          Reads a native memory address from a native memory location.
abstract  byte getByte(long address)
          Reads an 8 bit integer from a native memory location.
 void getByteArray(long address, byte[] data, int offset, int length)
          Reads a java byte array from native memory.
 void getCharArray(long address, char[] data, int offset, int length)
          Reads a java char array from native memory.
 long getDirectBufferAddress(java.nio.Buffer buffer)
          Gets the native memory address of a direct ByteBuffer
abstract  double getDouble(long address)
          Reads a 64 bit floating point value from a native memory location.
 void getDoubleArray(long address, double[] data, int offset, int length)
          Reads a java double array from native memory.
abstract  float getFloat(long address)
          Reads a 32 bit floating point value from a native memory location.
 void getFloatArray(long address, float[] data, int offset, int length)
          Reads a java float array from native memory.
static MemoryIO getInstance()
          Gets an instance of MemoryIO that can be used to access native memory.
abstract  int getInt(long address)
          Reads a 32 bit integer from a native memory location.
 void getIntArray(long address, int[] data, int offset, int length)
          Reads a java int array from native memory.
abstract  long getLong(long address)
          Reads a 64 bit integer from a native memory location.
 void getLongArray(long address, long[] data, int offset, int length)
          Reads a java long array from native memory.
abstract  short getShort(long address)
          Reads a 16 bit integer from a native memory location.
 void getShortArray(long address, short[] data, int offset, int length)
          Reads a java short array from native memory.
 long getStringLength(long address)
          Gets the length of a native ascii or utf-8 string.
 byte[] getZeroTerminatedByteArray(long address)
          Reads a byte array from native memory, stopping when a zero byte is found.
 byte[] getZeroTerminatedByteArray(long address, int maxlen)
          Reads a byte array from native memory, stopping when a zero byte is found, or the maximum length is reached.
 byte[] getZeroTerminatedByteArray(long address, long maxlen)
          Deprecated. 
 long indexOf(long address, byte value)
          Finds the location of a byte value in a native memory region.
 long indexOf(long address, byte value, int maxlen)
          Finds the location of a byte value in a native memory region.
 java.nio.ByteBuffer newDirectByteBuffer(long address, int capacity)
          Creates a new Direct ByteBuffer for a native memory region.
abstract  void putAddress(long address, long value)
          Writes a native memory address value to a native memory location.
abstract  void putByte(long address, byte value)
          Writes an 8 bit integer value to a native memory location.
 void putByteArray(long address, byte[] data, int offset, int length)
          Writes a java byte array to native memory.
 void putCharArray(long address, char[] data, int offset, int length)
          Writes a java char array to native memory.
abstract  void putDouble(long address, double value)
          Writes a 64 bit floating point value to a native memory location.
 void putDoubleArray(long address, double[] data, int offset, int length)
          Writes a java double array to native memory.
abstract  void putFloat(long address, float value)
          Writes a 32 bit floating point value to a native memory location.
 void putFloatArray(long address, float[] data, int offset, int length)
          Writes a java double array to native memory.
abstract  void putInt(long address, int value)
          Writes a 32 bit integer value to a native memory location.
 void putIntArray(long address, int[] data, int offset, int length)
          Writes a java int array to native memory.
abstract  void putLong(long address, long value)
          Writes a 64 bit integer value to a native memory location.
 void putLongArray(long address, long[] data, int offset, int length)
          Writes a java long array to native memory.
abstract  void putShort(long address, short value)
          Writes a 16 bit integer value to a native memory location.
 void putShortArray(long address, short[] data, int offset, int length)
          Writes a java short array to native memory.
 void putZeroTerminatedByteArray(long address, byte[] data, int offset, int length)
          Copies a java byte array to native memory and appends a NUL terminating byte.
abstract  void setMemory(long address, long size, byte value)
          Sets a region of native memory to a specific byte value.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getInstance

public static MemoryIO getInstance()
Gets an instance of MemoryIO that can be used to access native memory.

Returns:
A MemoryIO instance.

getByte

public abstract byte getByte(long address)
Reads an 8 bit integer from a native memory location.

Parameters:
address - The memory location to get the value from.
Returns:
A byte containing the value.

getShort

public abstract short getShort(long address)
Reads a 16 bit integer from a native memory location.

Parameters:
address - The memory location to get the value from.
Returns:
A short containing the value.

getInt

public abstract int getInt(long address)
Reads a 32 bit integer from a native memory location.

Parameters:
address - The memory location to get the value from.
Returns:
An int containing the value.

getLong

public abstract long getLong(long address)
Reads a 64 bit integer from a native memory location.

Parameters:
address - The memory location to get the value from.
Returns:
A long containing the value.

getFloat

public abstract float getFloat(long address)
Reads a 32 bit floating point value from a native memory location.

Parameters:
address - The memory location to get the value from.
Returns:
A float containing the value.

getDouble

public abstract double getDouble(long address)
Reads a 64 bit floating point value from a native memory location.

Parameters:
address - The memory location to get the value from.
Returns:
A double containing the value.

getAddress

public abstract long getAddress(long address)
Reads a native memory address from a native memory location.

Parameters:
address - The memory location to get the value from.
Returns:
A long containing the value.

putByte

public abstract void putByte(long address,
                             byte value)
Writes an 8 bit integer value to a native memory location.

Parameters:
address - The memory location to put the value.
value - The value to write to memory.

putShort

public abstract void putShort(long address,
                              short value)
Writes a 16 bit integer value to a native memory location.

Parameters:
address - The memory location to put the value.
value - The value to write to memory.

putInt

public abstract void putInt(long address,
                            int value)
Writes a 32 bit integer value to a native memory location.

Parameters:
address - The memory location to put the value.
value - The value to write to memory.

putLong

public abstract void putLong(long address,
                             long value)
Writes a 64 bit integer value to a native memory location.

Parameters:
address - The memory location to put the value.
value - The value to write to memory.

putFloat

public abstract void putFloat(long address,
                              float value)
Writes a 32 bit floating point value to a native memory location.

Parameters:
address - The memory location to put the value.
value - The value to write to memory.

putDouble

public abstract void putDouble(long address,
                               double value)
Writes a 64 bit floating point value to a native memory location.

Parameters:
address - The memory location to put the value.
value - The value to write to memory.

putAddress

public abstract void putAddress(long address,
                                long value)
Writes a native memory address value to a native memory location.

Parameters:
address - The memory location to put the value.
value - The value to write to memory.

copyMemory

public abstract void copyMemory(long src,
                                long dst,
                                long size)
Copies contents of a native memory location to another native memory location.

Parameters:
src - The source memory address.
dst - The destination memory address.
size - The number of bytes to copy.

setMemory

public abstract void setMemory(long address,
                               long size,
                               byte value)
Sets a region of native memory to a specific byte value.

Parameters:
address - The address of start of the native memory.
size - The number of bytes to set.
value - The value to set the native memory to.

putByteArray

public final void putByteArray(long address,
                               byte[] data,
                               int offset,
                               int length)
Writes a java byte array to native memory.

Parameters:
address - The native memory address to copy the array to.
data - The java array to copy.
offset - The offset within the array to start copying from.
length - The number of array elements to copy.

getByteArray

public final void getByteArray(long address,
                               byte[] data,
                               int offset,
                               int length)
Reads a java byte array from native memory.

Parameters:
address - The native memory address to copy the array from.
data - The java array to copy.
offset - The offset within the array to start copying to.
length - The number of array elements to copy.

putCharArray

public final void putCharArray(long address,
                               char[] data,
                               int offset,
                               int length)
Writes a java char array to native memory.

Parameters:
address - The native memory address to copy the array to.
data - The java array to copy.
offset - The offset within the array to start copying from.
length - The number of array elements to copy.

getCharArray

public final void getCharArray(long address,
                               char[] data,
                               int offset,
                               int length)
Reads a java char array from native memory.

Parameters:
address - The native memory address to copy the array from.
data - The java array to copy.
offset - The offset within the array to start copying to.
length - The number of array elements to copy.

putShortArray

public final void putShortArray(long address,
                                short[] data,
                                int offset,
                                int length)
Writes a java short array to native memory.

Parameters:
address - The native memory address to copy the array to.
data - The java array to copy.
offset - The offset within the array to start copying from.
length - The number of array elements to copy.

getShortArray

public final void getShortArray(long address,
                                short[] data,
                                int offset,
                                int length)
Reads a java short array from native memory.

Parameters:
address - The native memory address to copy the array from.
data - The java array to copy.
offset - The offset within the array to start copying to.
length - The number of array elements to copy.

putIntArray

public final void putIntArray(long address,
                              int[] data,
                              int offset,
                              int length)
Writes a java int array to native memory.

Parameters:
address - The native memory address to copy the array to.
data - The java array to copy.
offset - The offset within the array to start copying from.
length - The number of array elements to copy.

getIntArray

public final void getIntArray(long address,
                              int[] data,
                              int offset,
                              int length)
Reads a java int array from native memory.

Parameters:
address - The native memory address to copy the array from.
data - The java array to copy.
offset - The offset within the array to start copying to.
length - The number of array elements to copy.

putLongArray

public final void putLongArray(long address,
                               long[] data,
                               int offset,
                               int length)
Writes a java long array to native memory.

Parameters:
address - The native memory address to copy the array to.
data - The java array to copy.
offset - The offset within the array to start copying from.
length - The number of array elements to copy.

getLongArray

public final void getLongArray(long address,
                               long[] data,
                               int offset,
                               int length)
Reads a java long array from native memory.

Parameters:
address - The native memory address to copy the array from.
data - The java array to copy.
offset - The offset within the array to start copying to.
length - The number of array elements to copy.

putFloatArray

public final void putFloatArray(long address,
                                float[] data,
                                int offset,
                                int length)
Writes a java double array to native memory.

Parameters:
address - The native memory address to copy the array to.
data - The java array to copy.
offset - The offset within the array to start copying from.
length - The number of array elements to copy.

getFloatArray

public final void getFloatArray(long address,
                                float[] data,
                                int offset,
                                int length)
Reads a java float array from native memory.

Parameters:
address - The native memory address to copy the array from.
data - The java array to copy.
offset - The offset within the array to start copying to.
length - The number of array elements to copy.

putDoubleArray

public final void putDoubleArray(long address,
                                 double[] data,
                                 int offset,
                                 int length)
Writes a java double array to native memory.

Parameters:
address - The native memory address to copy the array to.
data - The java array to copy.
offset - The offset within the array to start copying from.
length - The number of array elements to copy.

getDoubleArray

public final void getDoubleArray(long address,
                                 double[] data,
                                 int offset,
                                 int length)
Reads a java double array from native memory.

Parameters:
address - The native memory address to copy the array from.
data - The java array to copy.
offset - The offset within the array to start copying to.
length - The number of array elements to copy.

allocateMemory

public final long allocateMemory(long size,
                                 boolean clear)
Allocates native memory.

Parameters:
size - The number of bytes of memory to allocate
clear - Whether the memory should be cleared (each byte set to zero).
Returns:
The native address of the allocated memory.

freeMemory

public final void freeMemory(long address)
Releases memory allocated via allocateMemory back to the system.

Parameters:
address - The address of the memory to release.

getStringLength

public final long getStringLength(long address)
Gets the length of a native ascii or utf-8 string.

Parameters:
address - The native address of the string.
Returns:
The length of the string, in bytes.

getZeroTerminatedByteArray

public final byte[] getZeroTerminatedByteArray(long address)
Reads a byte array from native memory, stopping when a zero byte is found. This can be used to read ascii or utf-8 strings from native memory.

Parameters:
address - The address to read the data from.
Returns:
The byte array containing a copy of the native data. Any zero byte is stripped from the end.

getZeroTerminatedByteArray

public final byte[] getZeroTerminatedByteArray(long address,
                                               int maxlen)
Reads a byte array from native memory, stopping when a zero byte is found, or the maximum length is reached. This can be used to read ascii or utf-8 strings from native memory.

Parameters:
address - The address to read the data from.
maxlen - The limit of the memory area to scan for a zero byte.
Returns:
The byte array containing a copy of the native data. Any zero byte is stripped from the end.

getZeroTerminatedByteArray

@Deprecated
public final byte[] getZeroTerminatedByteArray(long address,
                                                          long maxlen)
Deprecated. 


putZeroTerminatedByteArray

public final void putZeroTerminatedByteArray(long address,
                                             byte[] data,
                                             int offset,
                                             int length)
Copies a java byte array to native memory and appends a NUL terminating byte. Note A total of length + 1 bytes is written to native memory.

Parameters:
address - The address to copy to.
data - The byte array to copy to native memory
offset - The offset within the byte array to begin copying from
length - The number of bytes to copy to native memory

indexOf

public final long indexOf(long address,
                          byte value)
Finds the location of a byte value in a native memory region.

Parameters:
address - The native memory address to start searching from.
value - The value to search for.
Returns:
The memory location of the value, if found, else -1 (minus one).

indexOf

public final long indexOf(long address,
                          byte value,
                          int maxlen)
Finds the location of a byte value in a native memory region.

Parameters:
address - The native memory address to start searching from.
value - The value to search for.
maxlen - The maximum number of bytes to search.
Returns:
The memory location of the value, if found, else -1 (minus one).

newDirectByteBuffer

public final java.nio.ByteBuffer newDirectByteBuffer(long address,
                                                     int capacity)
Creates a new Direct ByteBuffer for a native memory region.

Parameters:
address - The start of the native memory region.
capacity - The size of the native memory region.
Returns:
A ByteBuffer representing the native memory region.

getDirectBufferAddress

public final long getDirectBufferAddress(java.nio.Buffer buffer)
Gets the native memory address of a direct ByteBuffer

Parameters:
buffer - A direct ByteBuffer to get the address of.
Returns:
The native memory address of the buffer contents, or null if not a direct buffer.