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