Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.trolltech.qt
Class QNativePointer

    java.lang.Object
      com.trolltech.qt.QNativePointer

    public class QNativePointer

extends java.lang.Object

QNativePointer encapsulates a native C++ pointer. The class provides the functionality that you would get if you had direct access to the pointer through function calls. It is as such a low-level memory manager that should be used sparsely; its intended and legitimate use is for JNI bindings not handled by generator. Examples can be found in the generator example.

QNativePointer does type checking of pointers. Also, if the pointer is pointing to an array, you must also specify the array length; array bounds checking is enforced by QNativePointer. Any number of indirections are allowed (i.e., arrays can have any number of dimensions).

The QNativePointer will by default delete the internal pointer when being garbage collected. However, if the ownership of the pointer is given to a c++ class, you do not want this behavior. The AutoDeleteMode enum values defines the ways in which deletion of the pointer can be handled.

The data types that can be pointed to are defined by the Type enum. An allocation of an Integer pointer can, for example, be done like this:

`QNativePointer ptr = new QNativePointer(QNativePointer.Type.Int);
ptr.setIntValue(10);
`

An array of length 5 is created in the following way:

`QNativePointer ptr = new QNativePointer(QNativePointer.Type.Int, 5);
for (int i = 0; i < 5, ++i)`

        ptr.setIntAt(i, i*i);

If you are creating a multi dimensional array, you have two possibilities. You can make QNativePointers of the Pointer type or specify the number indirections of a single QNativePointer. We recommend the second alternative since it creates type safe pointers. Here is an example using the first alternative:

`QNativePointer ptr = new QNativePointer(QNativePointer.Type.Pointer, 2);
QNativePointer charArray1 = new QNativePointer(QNativePointer.Type.Char, 5);
ptr.setPointerAt(0, carArray1);`

And here is the code for the second:

`QNativePointer ptr = new QNativePointer(Type.Char, 5, 2);
ptr.setPointerAt(0, createCharPointer(myString));`

Nested Class Summary
`static class` | `QNativePointer.AutoDeleteMode` The AutoDeleteMode enum describes how garbage collection of the QNativePointer handles the deletion of the native pointer.
`static class` | `QNativePointer.Type` The Type enum describe the Java types that can be used by a QNativePointer.

Constructor Summary
`QNativePointer(QNativePointer.Type type)` Creates a native pointer of the specified `type`.
`QNativePointer(QNativePointer.Type type, int size)` Creates a native pointer to an array with `size` length of the specified `type`.
`QNativePointer(QNativePointer.Type type, int size, int indirections)` Creates a native pointer of the specified `type`.

Method Summary
`QNativePointer.AutoDeleteMode` | `autoDeleteMode()` Returns the auto-delete mode of the pointer.
`boolean` | `booleanAt(int pos)` Returns the value of the native pointer at the specified position.
`boolean` | `booleanValue()` If the native pointer is of boolean type, this function returns its value.
`byte` | `byteAt(int pos)` Returns the value of the native pointer at the specified position.
`byte` | `byteValue()` If the native pointer is of byte type, this function returns its value.
`char` | `charAt(int pos)` Returns the value of the native pointer at the specified position.
`char` | `charValue()` If the native pointer is of char type, this function returns its value.
`static QNativePointer` | `createCharPointer(java.lang.String string)` Creates a char* from the input string
`static QNativePointer` | `createCharPointerPointer(java.lang.String[] strings)` Creates a char** native pointer from the array of input strings.
`void` | `delete()` This function deletes the internal pointer.
`void` | `deleteArray()` This function deletes elements in the array of this QNativePointer.
`double` | `doubleAt(int pos)` Returns the value of the native pointer at the specified position.
`double` | `doubleValue()` If the native pointer is of double type, this function returns its value.
`protected void` | `finalize()`
`float` | `floatAt(int pos)` Returns the value of the native pointer at the specified position.
`float` | `floatValue()` If the native pointer is of float type, this function returns its value.
`void` | `free()` This function deletes the internal pointer.
`static QNativePointer` | `fromNative(long ptr, int type, int indirections)` This is an overloaded function provided for convenience.
`static QNativePointer` | `fromNative(long ptr, QNativePointer.Type type, int indirections)` This function creates a QNativePointer from an existing c++ pointer.
`int` | `indirections()` Returns the number of indirections of the pointer.
`int` | `intAt(int pos)` Returns the value of the native pointer at the specified position.
`int` | `intValue()` If the native pointer is of int type, this function returns its value.
`boolean` | `isNull()` Returns true if the native pointer is 0; otherwise false.
`long` | `longAt(int pos)` Returns the value of the native pointer at the specified position.
`long` | `longValue()` If the native pointer is of long type, this function returns its value.
`long` | `pointer()` Returns the native pointer.
`QNativePointer` | `pointerAt(int pos)` Returns the value of the native pointer at the specified position.
`QNativePointer` | `pointerValue()` If the native pointer is of pointer type, this function returns its value.
`void` | `setAutoDeleteMode(QNativePointer.AutoDeleteMode autodelete)` This function sets the auto delete mode of the QNativePointer.
`void` | `setBooleanAt(int pos, boolean value)` Sets the value of the array element at `pos` to which this native pointer points.
`void` | `setBooleanValue(boolean value)` Sets the value of this pointer to `value`.
`void` | `setByteAt(int pos, byte value)` Sets the value of the array element at `pos` to which this native pointer points.
`void` | `setByteValue(byte value)` Sets the value of this pointer to `value`.
`void` | `setCharAt(int pos, char value)` Sets the value of the array element at `pos` to which this native pointer points.
`void` | `setCharValue(char value)` Sets the value of this pointer to `value`.
`void` | `setDoubleAt(int pos, double value)` Sets the value of the array element at `pos` to which this native pointer points.
`void` | `setDoubleValue(double value)` Sets the value of this pointer to `value`.
`void` | `setFloatAt(int pos, float value)` Sets the value of the array element at `pos` to which this native pointer points.
`void` | `setFloatValue(float value)` Sets the value of this pointer to `value`.
`void` | `setIntAt(int pos, int value)` Sets the value of the array element at `pos` to which this native pointer points.
`void` | `setIntValue(int value)` Sets the value of this pointer to `value`.
`void` | `setLongAt(int pos, long value)` Sets the value of the array element at `pos` to which this native pointer points.
`void` | `setLongValue(long value)` Sets the value of this pointer to `value`.
`void` | `setPointerAt(int pos, QNativePointer value)` Sets the value of the array element at `pos` to which this native pointer points.
`void` | `setPointerValue(QNativePointer value)` Sets the value of this pointer to `value`.
`void` | `setShortAt(int pos, short value)` Sets the value of the array element at `pos` to which this native pointer points.
`void` | `setShortValue(short value)` Sets the value of this pointer to `value`.
`void` | `setStringAt(int pos, java.lang.String value)` Sets the value of the array element at `pos` to which this native pointer points.
`void` | `setStringValue(java.lang.String value)` Sets the value of this pointer to `value`.
`void` | `setVerificationEnabled(boolean a)` Sets if the any accesses should be type verified or not.
`short` | `shortAt(int pos)` Returns the value of the native pointer at the specified position.
`short` | `shortValue()` If the native pointer is of short type, this function returns its value.
`java.lang.String` | `stringAt(int pos)` Returns the value of the native pointer at the specified position.
`java.lang.String` | `stringValue()` If the native pointer is of string type, this function returns its value.
`QNativePointer.Type` | `type()` Returns the type of the native pointer.
`boolean` | `verificationEnabled()` Returns if verification is enabled or not.

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

Constructor Detail

### QNativePointer

    public QNativePointer(QNativePointer.Type type)

  Creates a native pointer of the specified `type`. The object has an indirection of 1 and the internal pointer will be deleted when the QNativePointer object is deleted.

  Parameters:
    `type` - the type of pointer to create.

### QNativePointer

    public QNativePointer(QNativePointer.Type type,
                          int size)

  Creates a native pointer to an array with `size` length of the specified `type`. The pointer will have an indirection of 1 and be deleted when the QNativePointer is garbage collected.

  Parameters:
    `type` - the type of pointer to create.
    `size` - the size of the array.

### QNativePointer

    public QNativePointer(QNativePointer.Type type,
                          int size,
                          int indirections)

  Creates a native pointer of the specified `type`. It will be an array if `size` is larger than one and have an indirection of `indirections`. For instance, the following Java statement will create a `**char` pointer with the first array dimension of length 5: `QNativePointer ptr = new QNativePointer(QNativePointer.Type.Int, 5, 2);`

  Parameters:
    `type` - the type of pointer to create.
    `size` - the length of the array.
    `indirections` - the number of indirections for the pointer.

Method Detail

### booleanValue

    public boolean booleanValue()

  If the native pointer is of boolean type, this function returns its value. If it is an array of booleans, the first element is returned.

  Returns:
    the value of the pointer.

### byteValue

    public byte byteValue()

  If the native pointer is of byte type, this function returns its value. If it is an array of bytes, the first element is returned.

  Returns:
    the value of the pointer.

### charValue

    public char charValue()

  If the native pointer is of char type, this function returns its value. If it is an array of chars, the first element is returned.

  Returns:
    the value of the pointer.

### shortValue

    public short shortValue()

  If the native pointer is of short type, this function returns its value. If it is an array of shorts, the first element is returned.

  Returns:
    the value of the pointer.

### intValue

    public int intValue()

  If the native pointer is of int type, this function returns its value. If it is an array of ints, the first element is returned.

  Returns:
    the value of the pointer.

### longValue

    public long longValue()

  If the native pointer is of long type, this function returns its value. If it is an array of longs, the first element is returned.

  Returns:
    the value of the pointer.

### floatValue

    public float floatValue()

  If the native pointer is of float type, this function returns its value. If it is an array of floats, the first element is returned.

  Returns:
    the value of the pointer.

### doubleValue

    public double doubleValue()

  If the native pointer is of double type, this function returns its value. If it is an array of doubles, the first element is returned.

  Returns:
    the value of the pointer.

### pointerValue

    public QNativePointer pointerValue()

  If the native pointer is of pointer type, this function returns its value. If it is an array of pointers, the first element is returned.

  Returns:
    the value of the pointer.

### stringValue

    public java.lang.String stringValue()

  If the native pointer is of string type, this function returns its value. If it is an array of strings, the first element is returned.

  Returns:
    the value of the pointer.

### setBooleanValue

    public void setBooleanValue(boolean value)

  Sets the value of this pointer to `value`. The type of the pointer must be boolean.

  Parameters:
    `value` - the value to which the pointer is set.

### setByteValue

    public void setByteValue(byte value)

  Sets the value of this pointer to `value`. The type of the pointer must be byte.

  Parameters:
    `value` - the value to which the pointer is set.

### setCharValue

    public void setCharValue(char value)

  Sets the value of this pointer to `value`. The type of the pointer must be char.

  Parameters:
    `value` - the value to which the pointer is set.

### setShortValue

    public void setShortValue(short value)

  Sets the value of this pointer to `value`. The type of the pointer must be short.

  Parameters:
    `value` - the value to which the pointer is set.

### setIntValue

    public void setIntValue(int value)

  Sets the value of this pointer to `value`. The type of the pointer must be int.

  Parameters:
    `value` - the value to which the pointer is set.

### setLongValue

    public void setLongValue(long value)

  Sets the value of this pointer to `value`. The type of the pointer must be long.

  Parameters:
    `value` - the value to which the pointer is set.

### setFloatValue

    public void setFloatValue(float value)

  Sets the value of this pointer to `value`. The type of the pointer must be float.

  Parameters:
    `value` - the value to which the pointer is set.

### setDoubleValue

    public void setDoubleValue(double value)

  Sets the value of this pointer to `value`. The type of the pointer must double.

  Parameters:
    `value` - the value to which the pointer is set.

### setPointerValue

    public void setPointerValue(QNativePointer value)

  Sets the value of this pointer to `value`. The pointer must be of pointer type.

  Parameters:
    `value` - the value to which the pointer is set.

### setStringValue

    public void setStringValue(java.lang.String value)

  Sets the value of this pointer to `value`. The pointer must point to a string.

  Parameters:
    `value` - the value to which the pointer is set.

### booleanAt

    public boolean booleanAt(int pos)

  Returns the value of the native pointer at the specified position. If `pos` is larger than 1, QNativePointer will check that the position is within the array bounds.

  Parameters:
    `pos` - the array index

### byteAt

    public byte byteAt(int pos)

  Returns the value of the native pointer at the specified position. If `pos` is larger than 1, QNativePointer will check that the position is within the array bounds.

  Parameters:
    `pos` - the array index

### charAt

    public char charAt(int pos)

  Returns the value of the native pointer at the specified position. If `pos` is larger than 1, QNativePointer will check that the position is within the array bounds.

  Parameters:
    `pos` - the array index

### shortAt

    public short shortAt(int pos)

  Returns the value of the native pointer at the specified position. If `pos` is larger than 1, QNativePointer will check that the position is within the array bounds.

  Parameters:
    `pos` - the array index

### intAt

    public int intAt(int pos)

  Returns the value of the native pointer at the specified position. If `pos` is larger than 1, QNativePointer will check that the position is within the array bounds.

  Parameters:
    `pos` - the array index

### longAt

    public long longAt(int pos)

  Returns the value of the native pointer at the specified position. If `pos` is larger than 1, QNativePointer will check that the position is within the array bounds.

  Parameters:
    `pos` - the array index

### floatAt

    public float floatAt(int pos)

  Returns the value of the native pointer at the specified position. If `pos` is larger than 1, QNativePointer will check that the position is within the array bounds.

  Parameters:
    `pos` - the array index

### doubleAt

    public double doubleAt(int pos)

  Returns the value of the native pointer at the specified position. If `pos` is larger than 1, QNativePointer will check that the position is within the array bounds.

  Parameters:
    `pos` - the array index

### pointerAt

    public QNativePointer pointerAt(int pos)

  Returns the value of the native pointer at the specified position. If `pos` is larger than 1, QNativePointer will check that the position is within the array bounds.

  Parameters:
    `pos` - the array index

### stringAt

    public java.lang.String stringAt(int pos)

  Returns the value of the native pointer at the specified position. If `pos` is larger than 1, QNativePointer will check that the position is within the array bounds.

  Parameters:
    `pos` - the array index

### setBooleanAt

    public void setBooleanAt(int pos,
                             boolean value)

  Sets the value of the array element at `pos` to which this native pointer points.

  Parameters:
    `pos` - the array index
    `value` - the value to set the index to

### setByteAt

    public void setByteAt(int pos,
                          byte value)

  Sets the value of the array element at `pos` to which this native pointer points.

  Parameters:
    `pos` - the array index
    `value` - the value to set the index to

### setCharAt

    public void setCharAt(int pos,
                          char value)

  Sets the value of the array element at `pos` to which this native pointer points.

  Parameters:
    `pos` - the array index
    `value` - the value to set the index to

### setShortAt

    public void setShortAt(int pos,
                           short value)

  Sets the value of the array element at `pos` to which this native pointer points.

  Parameters:
    `pos` - the array index
    `value` - the value to set the index to

### setIntAt

    public void setIntAt(int pos,
                         int value)

  Sets the value of the array element at `pos` to which this native pointer points.

  Parameters:
    `pos` - the array index
    `value` - the value to set the index to

### setLongAt

    public void setLongAt(int pos,
                          long value)

  Sets the value of the array element at `pos` to which this native pointer points.

  Parameters:
    `pos` - the array index
    `value` - the value to set the index to

### setFloatAt

    public void setFloatAt(int pos,
                           float value)

  Sets the value of the array element at `pos` to which this native pointer points.

  Parameters:
    `pos` - the array index
    `value` - the value to set the index to

### setDoubleAt

    public void setDoubleAt(int pos,
                            double value)

  Sets the value of the array element at `pos` to which this native pointer points.

  Parameters:
    `pos` - the array index
    `value` - the value to set the index to

### setPointerAt

    public void setPointerAt(int pos,
                             QNativePointer value)

  Sets the value of the array element at `pos` to which this native pointer points.

  Parameters:
    `pos` - the array index
    `value` - the value to set the index to

### setStringAt

    public void setStringAt(int pos,
                            java.lang.String value)

  Sets the value of the array element at `pos` to which this native pointer points.

  Parameters:
    `pos` - the array index
    `value` - the value to set the index to

### type

    public QNativePointer.Type type()

  Returns the type of the native pointer.

  Returns:
    the data type of the native pointer

### indirections

    public int indirections()

  Returns the number of indirections of the pointer.

  Returns:
    the number of indirections of the pointer

### isNull

    public boolean isNull()

  Returns true if the native pointer is 0; otherwise false.

  Returns:
    true if the native pointer is 0.

### autoDeleteMode

    public QNativePointer.AutoDeleteMode autoDeleteMode()

  Returns the auto-delete mode of the pointer.

  Returns:
    the auto-delete mode of this QNativePointer

### setAutoDeleteMode

    public void setAutoDeleteMode(QNativePointer.AutoDeleteMode autodelete)

  This function sets the auto delete mode of the QNativePointer. The internal pointer is deleted by default when the QNativePointer object is garbage collected, so you only need to call this function when you want to keep the pointer valid after the Java object is garbage collected.

  Parameters:
    `autodelete` - the new auto delete mode.

### free

    public void free()

  This function deletes the internal pointer. Currently, all QNativePointers should be deleted using the delete() function. After the pointer has been deleted, you cannot use the same QNativePointer to allocate further data. Note also that the pointer will by default be deleted upon garbage collection.

### delete

    public void delete()

  This function deletes the internal pointer. After the pointer has been deleted, you cannot allocate it again. The pointer is by default deleted when the QNativePointer object is garbage collected.

### deleteArray

    public void deleteArray()

  This function deletes elements in the array of this QNativePointer. After the pointer has been deleted, you cannot use this QNativePointer object again.

### pointer

    public long pointer()

  Returns the native pointer. The returned long is the `void *` value in c++.

  Returns:
    the native pointer.

### fromNative

    public static QNativePointer fromNative(long ptr,
                                            QNativePointer.Type type,
                                            int indirections)

  This function creates a QNativePointer from an existing c++ pointer. The long is the `void *` (i.e., address) value of the pointer. There are several ways of acquiring a native pointer. For instance, QNativePointer internal pointer is returned by pointer(), and QtJambiObject.nativeId() returns the c++ pointer to its Qt object.

  Parameters:
    `ptr` - the void * value of the pointer.
    `type` - the Type of the pointer
    `indirections` - the number of pointer indirections
  Returns:
    a QNativePointer object with ptr as the native pointer

### verificationEnabled

    public boolean verificationEnabled()

  Returns if verification is enabled or not.

  Returns:
    true if verification is enabled; otherwise false.

### setVerificationEnabled

    public void setVerificationEnabled(boolean a)

  Sets if the any accesses should be type verified or not. By default this value is set to true, meaning that trying to access a char pointer as an int pointer will trigger an exception. Disabling this value allows complete access, but without any safety, so incorrect usage may lead to memory corruption in the C++ implementation.

  Parameters:
    `a` - Set to true if verification should be enabled.

### fromNative

    public static QNativePointer fromNative(long ptr,
                                            int type,
                                            int indirections)

  This is an overloaded function provided for convenience.

  See Also:
    `QNativePointer.fromNative(long ptr, Type type, int indirections)`

### createCharPointerPointer

    public static QNativePointer createCharPointerPointer(java.lang.String[] strings)

  Creates a char** native pointer from the array of input strings.

  Parameters:
    `strings` - the input strings
  Returns:
    a char **

### createCharPointer

    public static QNativePointer createCharPointer(java.lang.String string)

  Creates a char* from the input string

  Parameters:
    `string` - The input string
  Returns:
    The char*

### finalize

    protected void finalize()

  Overrides:
    `finalize` in class `java.lang.Object`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD