JNA API 3.3.0

## com.sun.jna
Class Pointer

    java.lang.Object
      com.sun.jna.Pointer

Direct Known Subclasses:
  Function, Memory

    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 Pointer` | `NULL` Convenience constant, same as `null`.
`protected long` | `peer` Pointer value of the real native pointer.
`static int` | `SIZE` 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
`void` | `clear(long size)` Zero memory for the given number of bytes.
`static Pointer` | `createConstant(int peer)` Convenience constant, equivalent to `(void*)CONSTANT`.
`static Pointer` | `createConstant(long peer)` Convenience constant, equivalent to `(void*)CONSTANT`.
`boolean` | `equals(Object o)` Compares this `Pointer` to the specified object.
`byte` | `getByte(long offset)` Indirect the native pointer as a pointer to `byte`.
`byte[]` | `getByteArray(long offset, int arraySize)`
`ByteBuffer` | `getByteBuffer(long offset, long length)` Get a ByteBuffer mapped to the memory pointed to by the pointer, ensuring the buffer uses native byte order.
`char` | `getChar(long offset)` Indirect the native pointer as a pointer to `wchar_t`.
`char[]` | `getCharArray(long offset, int arraySize)`
`double` | `getDouble(long offset)` Indirect the native pointer as a pointer to `double`.
`double[]` | `getDoubleArray(long offset, int arraySize)`
`float` | `getFloat(long offset)` Indirect the native pointer as a pointer to `float`.
`float[]` | `getFloatArray(long offset, int arraySize)`
`int` | `getInt(long offset)` Indirect the native pointer as a pointer to `int`.
`int[]` | `getIntArray(long offset, int arraySize)`
`long` | `getLong(long offset)` Indirect the native pointer as a pointer to `long`.
`long[]` | `getLongArray(long offset, int arraySize)`
`NativeLong` | `getNativeLong(long offset)` Indirect the native pointer as a pointer to `long`.
`Pointer` | `getPointer(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.
`short` | `getShort(long offset)` Indirect the native pointer as a pointer to `short`.
`short[]` | `getShortArray(long offset, int arraySize)`
`String` | `getString(long offset)` Copy native memory to a Java String.
`String` | `getString(long offset, boolean wide)` 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, 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)` Returns an array of `String` based on a native array of `char *`, using the given array length.
`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.
`(package private) Object` | `getValue(long offset, Class type, Object currentValue)`
`int` | `hashCode()` Returns a hashcode for the native pointer represented by this `Pointer` object
`long` | `indexOf(long offset, byte value)` Returns the offset of the given value in memory from the given offset, or -1 if the value is not found.
`static long` | `nativeValue(Pointer p)` Read the native peer value.
`static void` | `nativeValue(Pointer p, long value)` Set the native peer value.
`void` | `read(long offset, byte[] buf, int index, int length)` Indirect the native pointer, copying from memory pointed to by native pointer, into the specified array.
`void` | `read(long offset, char[] buf, int index, int length)` Indirect the native pointer, copying from memory pointed to by native pointer, into the specified array.
`void` | `read(long offset, double[] buf, int index, int length)` Indirect the native pointer, copying from memory pointed to by native pointer, into the specified array.
`void` | `read(long offset, float[] buf, int index, int length)` Indirect the native pointer, copying from memory pointed to by native pointer, into the specified array.
`void` | `read(long offset, int[] buf, int index, int length)` Indirect the native pointer, copying from memory pointed to by native pointer, into the specified array.
`void` | `read(long offset, long[] buf, int index, int length)` Indirect the native pointer, copying from memory pointed to by native pointer, into the specified array.
`void` | `read(long offset, Pointer[] buf, int index, int length)` Indirect the native pointer, copying from memory pointed to by native pointer, into the specified array.
`void` | `read(long offset, short[] buf, int index, int length)` Indirect the native pointer, copying from memory pointed to by native pointer, into the specified array.
`void` | `setByte(long offset, byte value)` Set `value` at location being pointed to.
`void` | `setChar(long offset, char value)` Set `value` at location being pointed to.
`void` | `setDouble(long offset, double value)` Set `value` at location being pointed to.
`void` | `setFloat(long offset, float value)` Set `value` at location being pointed to.
`void` | `setInt(long offset, int value)` Set `value` at location being pointed to.
`void` | `setLong(long offset, long value)` Set `value` at location being pointed to.
`void` | `setMemory(long offset, long length, byte value)` Write `value` to the requested bank of memory.
`void` | `setNativeLong(long offset, NativeLong value)` Set `value` at location being pointed to.
`void` | `setPointer(long offset, Pointer value)` Set `value` at location being pointed to.
`void` | `setShort(long offset, short value)` Set `value` at location being pointed to.
`void` | `setString(long offset, String value)` Copy string `value` to the location being pointed to.
`void` | `setString(long offset, String value, boolean wide)` Copy string `value` to the location being pointed to.
`(package private) void` | `setValue(long offset, Object value, Class type)`
`Pointer` | `share(long offset)`
`Pointer` | `share(long offset, long sz)` Provide a view of this pointer with a different peer base.
`String` | `toString()`
`void` | `write(long offset, byte[] buf, int index, int length)` Indirect the native pointer, copying into memory pointed to by native pointer, from the specified array.
`void` | `write(long offset, char[] buf, int index, int length)` Indirect the native pointer, copying into memory pointed to by native pointer, from the specified array.
`void` | `write(long offset, double[] buf, int index, int length)` Indirect the native pointer, copying into memory pointed to by native pointer, from the specified array.
`void` | `write(long offset, float[] buf, int index, int length)` Indirect the native pointer, copying into memory pointed to by native pointer, from the specified array.
`void` | `write(long offset, int[] buf, int index, int length)` Indirect the native pointer, copying into memory pointed to by native pointer, from the specified array.
`void` | `write(long offset, long[] buf, int index, int length)` Indirect the native pointer, copying into memory pointed to by native pointer, from the specified array.
`void` | `write(long bOff, Pointer[] buf, int index, int length)` Write the given array of Pointer to native memory.
`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.

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

Field Detail

### SIZE

    public static final int SIZE

  Size of a native pointer, in bytes.

### 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.

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

### createConstant

    public static final Pointer createConstant(long peer)

  Convenience constant, equivalent to `(void*)CONSTANT`.

### createConstant

    public static final Pointer createConstant(int peer)

  Convenience constant, equivalent to `(void*)CONSTANT`. This version will avoid setting any of the high bits on 64-bit systems.

### share

    public Pointer share(long offset)

### share

    public Pointer share(long offset,
                         long sz)

  Provide a view of this pointer with a different peer base.

### clear

    public void clear(long size)

  Zero memory for the given number of bytes.

### equals

    public boolean equals(Object o)

  Compares this `Pointer` to the specified object.

  Overrides:
    `equals` in class `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.

### hashCode

    public int hashCode()

  Returns a hashcode for the native pointer represented by this `Pointer` object

  Overrides:
    `hashCode` in class `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

### 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

### getValue

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

### 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

### 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

### 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

### 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

### 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

### 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

### 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

### 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

### 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`;

### 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,

### 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

### getByteArray

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

### getCharArray

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

### getShortArray

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

### getIntArray

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

### getLongArray

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

### getFloatArray

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

### getDoubleArray

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

### getPointerArray

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

### 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.

### setValue

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

### 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

### 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

### 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

### 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

### 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

### 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

### 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

### 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

### 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.

### 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 `offset`from 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 `offset`from 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

### toString

    public String toString()

  Overrides:
    `toString` in class `Object`

### nativeValue

    public static long nativeValue(Pointer p)

  Read the native peer value. Use with caution.

### nativeValue

    public static void nativeValue(Pointer p,
                                   long value)

  Set the native peer value. Use with caution.

JNA API 3.3.0

Copyright © 2007-2010 Timothy Wall. All Rights Reserved.