Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| " 2013 FRC Java API "
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.sun.cldc.jna
Class Pointer

    java.lang.Object
      com.sun.squawk.realtime.RawMemoryAccess
          com.sun.squawk.realtime.RawMemoryFloatAccess
              com.sun.cldc.jna.Pointer

Direct Known Subclasses:
  VarPointer

    public class Pointer

extends RawMemoryFloatAccess

A pointer to native memory, based on RTSJ-like RawMemoryAccesss semantics. Otherise similar to the Memory class in JNA. All pointers have a size, so memory access through a pointer is range-checked. A pointer can either have a dedicated backing buffer of native memory (from malloc or similar), or it may be a "shared" subset of some other Pointer.

### Differences from JNA

- The backing native memory is not automically freed by finalization - No finalization in cldc.
- No getIntArray(), etc methods
  Use explicit "buf = new int[size]; geInts(offset, buf. size);" (from RTSJ)
- No read() methods, use getInts(), etc. instead (from RTSJ)
- No write() methods, use setInts(), etc. instead (from RTSJ)
- No getPointerArray() method - we need to specifiy a size for each Pointer
- No getChar(), setChar() or read or write of chars methods. (from RTSJ)
- No getByteBuffer() method - no NIO in cldc
- Some offsets are of type int instead of long (this is "Microedition", after all)
- Exception types may be different
- no support for native wide strings

Field Summary

Fields inherited from class com.sun.squawk.realtime.RawMemoryAccess
`vbase`

Constructor Summary
`Pointer(Address base, int size)` Create a pointer that refers to a memory range from [base..base+size).
`Pointer(Address base, UWord size)` Create a pointer that refers to a memory range from [base..base+size).
`Pointer(int size)` Create a pointer and allocate backing native memory of the requestsed size.
`Pointer(long base, int size)` Create a pointer that refers to a memory range from [base..base+size).

Method Summary
`Address` | `address()` Gets the virtual memory location at which the memory region is mapped.
`Pointer` | `align(int byteAlignment)` Create a new pointer that is a subset of this pointer, but is aligned to byteAlignment
`void` | `clear()` Zero memory
`void` | `clear(int size)` Zero the first "size" bytes of memory
`static void` | `copyBytes(Pointer src, int srcOffset, Pointer dst, int dstOffset, int len)` Copy `len` bytes from `src` to `dst` starting at the given offsets.
`static Pointer` | `createStringBuffer(String value)` Create a native buffer containing the C-string version of the String `vaue`.
`void` | `free()` Free the backing native memory for this pointer.
`Pointer` | `getPointer(int offset, int size)` Read a ptr value from memory at offset, and construct a new pointer representing the data stored there...
`int` | `getSize()` Gets the size of the memory
`String` | `getString(int offset)` Create a Java string from a C string pointer to by this pointer at offset
`boolean` | `isValid()`
`static String` | `NativeUnsafeGetString(Address cstr)` Create a Java string from a C string pointer
`static Pointer` | `NULL()`
`void` | `release()` Free the backing native memory for this pointer if this pointer was created by allocating memory.
`void` | `setPointer(int offset, Pointer ptr)` Set the word at `offset` from `this` pointer to the the address contained in `ptr`.
`void` | `setString(int offset, String value)` Copy string value to the location at `offset`.
`Pointer` | `share(long offset)` Create a new pointer that is a subset of this pointer, starting from offset
`Pointer` | `share(long offset, long size)` Create a new pointer that is a subset of this pointer, starting from offset
`String` | `toString()` Returns a string representation of the object.

Methods inherited from class com.sun.squawk.realtime.RawMemoryFloatAccess
`getDouble, getDoubles, getFloat, getFloats, setDouble, setDoubles, setFloat, setFloats`

Methods inherited from class com.sun.squawk.realtime.RawMemoryAccess
`checkBounds, checkMultiBounds, checkMultiRead, checkMultiWrite, getAddress, getByte, getBytes, getInt, getInts, getLong, getLongs, getMappedAddress, getShort, getShorts, invalidate, map, map, map, setByte, setBytes, setInt, setInts, setLong, setLongs, setShort, setShorts, size, wasMalloced`

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Constructor Detail

### Pointer

    public Pointer(int size)
            throws SizeOutOfBoundsException,
                   OutOfMemoryError

  Create a pointer and allocate backing native memory of the requestsed size. This backing memory can be freed later using `free()`.

  Parameters:
    `size` - the number of bytes that can be referenced from this pointer
  Throws:
    `SizeOutOfBoundsException` - if the size is negative or too large
    `OutOfMemoryError` - if the backing memory cannot be allocated

### Pointer

    public Pointer(long base,
                   int size)

  Create a pointer that refers to a memory range from [base..base+size). This pointer should NOT be freed.

  Parameters:
    `base` - the base address of the pointer
    `size` - the number of bytes that can be referenced from this pointer
  Throws:
    `SecurityException` - if the memory range intersets the Java heap
    `OffsetOutOfBoundsException` - Thrown if the address is invalid.
    `SizeOutOfBoundsException` - Thrown if the size is negative or extends into an invalid range of memory.

### Pointer

    public Pointer(Address base,
                   UWord size)

  Create a pointer that refers to a memory range from [base..base+size). This pointer should NOT be freed.

  Parameters:
    `base` - the base address of the pointer
    `size` - the number of bytes that can be referenced from this pointer
  Throws:
    `SecurityException` - if the memory range intersets the Java heap
    `OffsetOutOfBoundsException` - Thrown if the address is invalid.
    `SizeOutOfBoundsException` - Thrown if the size is negative or extends into an invalid range of memory.

### Pointer

    public Pointer(Address base,
                   int size)

  Create a pointer that refers to a memory range from [base..base+size). This pointer should NOT be freed.

  Parameters:
    `base` - the base address of the pointer
    `size` - the number of bytes that can be referenced from this pointer
  Throws:
    `SecurityException` - if the memory range intersets the Java heap
    `OffsetOutOfBoundsException` - Thrown if the address is invalid.
    `SizeOutOfBoundsException` - Thrown if the size is negative or extends into an invalid range of memory.

Method Detail

### NULL

    public static Pointer NULL()

### share

    public Pointer share(long offset)

  Create a new pointer that is a subset of this pointer, starting from offset

  Parameters:
    `offset` - offset from this pointer to start the new pointer
  Returns:
    new pointer

### share

    public Pointer share(long offset,
                         long size)

  Create a new pointer that is a subset of this pointer, starting from offset

  Parameters:
    `offset` - offset from this pointer to start the new pointer
    `size` - size of the new pointer
  Returns:
    new pointer

### align

    public Pointer align(int byteAlignment)

  Create a new pointer that is a subset of this pointer, but is aligned to byteAlignment

  Parameters:
    `byteAlignment` -
  Returns:
    new pointer
  Throws:
    `IllegalArgumentException` - if byteAlignment is not a power of 2

### toString

    public String toString()

  Description copied from class: `Object`
  Returns a string representation of the object. In general, the `toString` method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

  The `toString` method for class `Object` returns a string consisting of the name of the class of which the object is an instance, the at-sign character ``@`', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

  >      getClass().getName() + '@' + Integer.toHexString(hashCode())

  Overrides:
    `toString` in class `Object`
  Returns:
    a string representation of the object.

### address

    public final Address address()

  Gets the virtual memory location at which the memory region is mapped.

  Returns:
    The virtual address to which this is mapped (for reference purposes). Same as the base address if virtual memory is not supported.
  Throws:
    `IllegalStateException` - Thrown if the raw memory object is not in the mapped state.

### getSize

    public final int getSize()

  Gets the size of the memory

  Returns:
    the size of the native memory area

### clear

    public void clear(int size)

  Zero the first "size" bytes of memory

  Parameters:
    `size` - number of bytes

### clear

    public void clear()

  Zero memory

### getPointer

    public Pointer getPointer(int offset,
                              int size)

  Read a ptr value from memory at offset, and construct a new pointer representing the data stored there...

  Parameters:
    `offset` - offset from `this` pointer that conatins a memory location that is an address.
    `size` - the size that the new pointer should have
  Returns:
    a new pointer with e

### setPointer

    public void setPointer(int offset,
                           Pointer ptr)

  Set the word at `offset` from `this` pointer to the the address contained in `ptr`.

  Parameters:
    `offset` - offset in bytes from this pointer's base to the word to be set.
    `ptr` - the value that will be set

### getString

    public String getString(int offset)

  Create a Java string from a C string pointer to by this pointer at offset

  Parameters:
    `offset` - the byte offset of the c string from the base of this pointer
  Returns:
    a java string

### NativeUnsafeGetString

    public static String NativeUnsafeGetString(Address cstr)

  Create a Java string from a C string pointer

  Parameters:
    `cstr` -
  Returns:
    a java string

### setString

    public final void setString(int offset,
                                String value)

  Copy string value to the location at `offset`. Convert the data in `value` to a NULL-terminated C string, converted to native encoding.

  Parameters:
    `offset` - the byte offset of the c string from the base of this pointer
    `value` - the string to copy

### free

    public final void free()
                    throws IllegalStateException

  Free the backing native memory for this pointer. After freeing the pointer, all accesses to memory through this pointer will throw an exception.

  Throws:
    `IllegalStateException` - if free has already been called on this pointer.

### release

    public final void release()
                       throws IllegalStateException

  Free the backing native memory for this pointer if this pointer was created by allocating memory. If this pointer points to a subset of another buffer, or points to a "pinned" object, do nothing. After releasing the pointer, all accesses to memory through this pointer will throw an exception.

  Throws:
    `IllegalStateException` - if release has already been called on this pointer.

### isValid

    public final boolean isValid()

  Returns:
    false if the memory is the NULL pointer or has been freed.

### createStringBuffer

    public static Pointer createStringBuffer(String value)
                                      throws OutOfMemoryError

  Create a native buffer containing the C-string version of the String `vaue`. The returned pointer should be freed when not needed.

  Parameters:
    `value` - the string to copy
  Returns:
    Pointer the newly allocated memory
  Throws:
    `OutOfMemoryError` - if the underlying memory cannot be allocated

### copyBytes

    public static void copyBytes(Pointer src,
                                 int srcOffset,
                                 Pointer dst,
                                 int dstOffset,
                                 int len)
                          throws OffsetOutOfBoundsException,
                                 SizeOutOfBoundsException

  Copy `len` bytes from `src` to `dst` starting at the given offsets. Throws exception if the memory ranges specified for `src` dst `dst` stray outside the valid ranges for those `Pointers`.

  Parameters:
    `src` - Pointer to the source bytes
    `srcOffset` - offset in bytes to start copying from
    `dst` - Pointer to the destination bytes
    `dstOffset` - offset in bytes to start copying to
    `len` - number of bytes to copy
  Throws:
    `OffsetOutOfBoundsException` - Thrown if an offset is negative or greater than the size of the raw memory area. The role of the `SizeOutOfBoundsException` somewhat overlaps this exception since it is thrown if the offset is within the object but outside the mapped area.
    `SizeOutOfBoundsException` - Thrown if the object is not mapped, or if the requested memory raange falls in an invalid address range.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| " 2013 FRC Java API "
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

"
For updated information see the Java FRC site
"