Module qtjambi
Package io.qt

Class QNativePointer

java.lang.Object
io.qt.QNativePointer
public final class QNativePointer
extends 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));

  • Constructor Details

    • 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, long 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, long 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 Details

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

    • booleanArray

      public boolean[] booleanArray()
      If the native pointer is of boolean type, this function returns its values as array.
      Returns:
      the values of the pointer.

    • byteArray

      public byte[] byteArray()
      If the native pointer is of byte type, this function returns its values as array.
      Returns:
      the values of the pointer.

    • charArray

      public char[] charArray()
      If the native pointer is of char type, this function returns its values as array.
      Returns:
      the values of the pointer.

    • shortArray

      public short[] shortArray()
      If the native pointer is of short type, this function returns its values as array.
      Returns:
      the values of the pointer.

    • intArray

      public int[] intArray()
      If the native pointer is of int type, this function returns its values as array.
      Returns:
      the values of the pointer.

    • longArray

      public long[] longArray()
      If the native pointer is of long type, this function returns its values as array.
      Returns:
      the values of the pointer.

    • floatArray

      public float[] floatArray()
      If the native pointer is of float type, this function returns its values as array.
      Returns:
      the values of the pointer.

    • doubleArray

      public double[] doubleArray()
      If the native pointer is of double type, this function returns its values as array.
      Returns:
      the values of the pointer.

    • objectArray

      public <T extends QtObjectInterface> T[] objectArray​(Class<T> valueType)
      If the native pointer is of pointer type, this function returns its value matching the given valueType.
      Parameters:
      valueType - the type of the value
      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.

    • object

      public <T extends QtObjectInterface> T object​(Class<T> valueType)
      If the native pointer is of pointer type, this function returns its value matching the given valueType. If it is an array of pointers, the first element is returned.
      Parameters:
      valueType - the type of the value
      Returns:
      the value of the pointer.

    • stringValue

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

    • stringArray

      public String[] stringArray()
      If the native pointer is of string type, this function returns its values as array.
      Returns:
      the values 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.

    • setObjectValue

      public <T extends QtObjectInterface> void setObjectValue​(T 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​(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​(long 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​(long 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​(long 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​(long 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​(long 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​(long 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​(long 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​(long 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

    • byteBuffer

      public ByteBuffer byteBuffer()

    • charBuffer

      public CharBuffer charBuffer()

    • shortBuffer

      public ShortBuffer shortBuffer()

    • intBuffer

      public IntBuffer intBuffer()

    • longBuffer

      public LongBuffer longBuffer()

    • floatBuffer

      public FloatBuffer floatBuffer()

    • doubleBuffer

      public DoubleBuffer doubleBuffer()

    • pointerAt

      public QNativePointer pointerAt​(long 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

    • objectAt

      public <T extends QtObjectInterface> T objectAt​(Class<T> valueType, long pos)
      Returns the value of the native pointer matching the given valueType at the specified position. If pos is larger than 1, QNativePointer will check that the position is within the array bounds.
      Parameters:
      valueType - the type of the value
      pos - the array index
      Returns:
      the value of the pointer.

    • stringAt

      public String stringAt​(long 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​(long 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​(long 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​(long 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​(long 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​(long 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​(long 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​(long 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​(long 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​(long 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

    • setObjectAt

      public <T extends QtObjectInterface> void setObjectAt​(long pos, T 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​(long pos, 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

    • knownSize

      public long knownSize()

    • 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, long size, int indirections, boolean readOnly)
      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

    • fromArray

      @SafeVarargs public static <T extends QtObjectInterface> QNativePointer fromArray​(T... array)

    • fromObject

      public static <T extends QtObjectInterface> QNativePointer fromObject​(T object)

    • fromBuffer

      public static QNativePointer fromBuffer​(Buffer buffer)

    • fromArray

      public static QNativePointer fromArray​(int[] data)

    • fromArray

      public static QNativePointer fromArray​(byte[] data)

    • fromArray

      public static QNativePointer fromArray​(float[] data)

    • fromArray

      public static QNativePointer fromArray​(double[] data)

    • fromArray

      public static QNativePointer fromArray​(boolean[] data)

    • fromArray

      public static QNativePointer fromArray​(char[] data)

    • fromArray

      public static QNativePointer fromArray​(long[] data)

    • fromArray

      public static QNativePointer fromArray​(short[] data)

    • fromArray

      public static QNativePointer fromArray​(Integer[] data)

    • fromArray

      public static QNativePointer fromArray​(Byte[] data)

    • fromArray

      public static QNativePointer fromArray​(Float[] data)

    • fromArray

      public static QNativePointer fromArray​(Double[] data)

    • fromArray

      public static QNativePointer fromArray​(Boolean[] data)

    • fromArray

      public static QNativePointer fromArray​(Character[] data)

    • fromArray

      public static QNativePointer fromArray​(Long[] data)

    • fromArray

      public static QNativePointer fromArray​(Short[] data)

    • fromArray

      public static QNativePointer fromArray​(String[] data)

    • verificationEnabled

      public boolean verificationEnabled()
      Returns if verification is enabled or not.
      Returns:
      true if verification is enabled; otherwise false.

    • isReadOnly

      public boolean isReadOnly()

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

    • createCharPointerPointer

      public static QNativePointer createCharPointerPointer​(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​(String string)
      Creates a char* from the input string
      Parameters:
      string - The input string
      Returns:
      The char*

    • openAsDevice

      public QIODevice openAsDevice​(QIODeviceBase.OpenModeFlag... openMode)

    • openAsDevice

      public QIODevice openAsDevice​(QIODeviceBase.OpenMode openMode)

    • invalidate

      public final void invalidate()