com.jniwrapper
Class Pointer

java.lang.Object
  com.jniwrapper.Parameter
      com.jniwrapper.Pointer

All Implemented Interfaces:

PointerParameter

Direct Known Subclasses:

ArithmeticalPointer, ExternalArrayPointer, Pointer.Const, Pointer.OutOnly, ResizingPointer

public class Pointer
extends Parameter
implements PointerParameter

This class represents a pointer to object in terms of C language.

Pointer type is defined by its referenced object. For example, an int pointer (int *) is a Pointer to Int.

 Int value = new Int();
 Pointer pValue = new Pointer(value); // this is int*
 

Nested Class Summary

static class	Pointer.Const Represents a pointer to constant object.
static class	Pointer.OutOnly Represents a pointer to object with undefined initial value.
static class	Pointer.Void Represents a void *.

Field Summary

static int

POINTER_LENGTH

Fields inherited from class com.jniwrapper.Parameter

LICENSE_TYPE, V

Constructor Summary

Pointer(java.lang.Class parameterClass)
Constructs a new typified pointer.

Pointer(Parameter ref)
Constructs a new pointer to a given object.

Pointer(Parameter ref, boolean isNull)
Constructs a new pointer to a given object.

Method Summary

protected void	acceptIOPerformer(IOPerformer performer, DataBuffer source, int initialOffset, boolean isReadOperation, boolean invokedByCallback) Implementation of a Visitor pattern for parameter IO.
void	asTypedPointer(Pointer target) Deprecated. use castTo(com.jniwrapper.Pointer) instead.
void	asVoidPointer(Pointer.Void target) Deprecated. use castTo(com.jniwrapper.Pointer.Void) instead.
void	castTo(Pointer.Void target) Casts this pointer to the given void pointer.
void	castTo(Pointer target) Assigns this pointer value to the typed pointer.
protected void	checkMemHandleLength() Checks that the memory block referred to by this pointer is big enough to hold the referenced object and allocates a new one if required.
java.lang.Object	clone()
boolean	equals(java.lang.Object obj) Compares this Parameter object to a given object.
java.lang.String	getDebugInfo() Return debug info for JNIWrapper parameter.
int	getLength() Returns the length of the parameter in memory.
java.lang.Class	getParameterClass() Returns the parameter type of this pointer object.
protected long	getPointerHandle() Returns the value of pointer as used by the native side.
Parameter	getReferencedObject() Returns the referenced object of this pointer.
boolean	isNull() Tests if this pointer is null.
void	pop(DataBuffer stackBuffer, int offset, boolean invokedByCallback) Default implementation that does nothing because most primitive types do nothing on pop.
void	push(DataBuffer stackBuffer, int offset, boolean invokedByCallback) Writes a parameter to a function stacks.
void	read(byte[] arr, int offset) Reads the parameter value from a byte array.
void	read(DataBuffer stackBuffer, int offset, boolean invokedByCallback) Reads this parameter from a specified data source.
protected void	readPointer(DataBuffer stackBuffer, int offset) Reads this pointer handle part (not the referenced object) from the given data buffer.
protected void	readReferencedObject(boolean invokedByCallback) Reads the referenced object only.
protected void	setExternalSource(long newHandle, int length) Makes this pointer use external (unmanaged) memory area.
void	setNull(boolean isNull) Sets a pointer null value.
void	setReferencedObject(Parameter ref) Changes the pointer referenced object.
void	setReferencedObject(Parameter ref, boolean isNull) Changes the pointer referenced object.
void	write(byte[] arr, int offset) Writes the parameter value to a byte array.
void	write(DataBuffer stackBuffer, int offset, boolean invokedByCallback) Writes this parameter to a specified data source.
protected void	writePointer(DataBuffer stackBuffer, int offset) Writes this pointer handle part (not the referenced object) to a given data buffer.
protected void	writeReferencedObject(boolean invokedByCallback) Writes the referenced object only.

Methods inherited from class com.jniwrapper.Parameter

asReturnValue, dataBufferAssigned, getAlignedLength, getAlignmentRequirement, getDataBuffer, getDataBufferOffset, hashCode, indent, read, setDataBuffer, toByteArray

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

POINTER_LENGTH

public static final int POINTER_LENGTH

Constructor Detail

Pointer

public Pointer(Parameter ref)

Constructs a new pointer to a given object. The constructed pointer is a non-null pointer parameter that points to the given object.

Parameters:

ref - referenced object.

Pointer

public Pointer(Parameter ref,
               boolean isNull)

Constructs a new pointer to a given object. The constructed pointer may be null, in which case a referenced object value is not used or updated until the pointer value is changed to non-null by native function.

Parameters:

ref - referenced object

isNull - if true the constructed pointer is null.

Pointer

public Pointer(java.lang.Class parameterClass)

Constructs a new typified pointer. Initially the referenced object is null, but the specified class what instance to create when this pointer is assigned on the native side.

Parameters:

parameterClass - defines the parameter type.

Method Detail

asTypedPointer

public void asTypedPointer(Pointer target)

Deprecated. use castTo(com.jniwrapper.Pointer) instead.

Assigns this pointer value to the typed pointer.

Parameters:

target - typed pointer.

castTo

public void castTo(Pointer target)

Assigns this pointer value to the typed pointer.

Parameters:

target - typed pointer.

getReferencedObject

public Parameter getReferencedObject()

Returns the referenced object of this pointer.

setReferencedObject

public void setReferencedObject(Parameter ref)

Changes the pointer referenced object.

setReferencedObject

public void setReferencedObject(Parameter ref,
                                boolean isNull)

Changes the pointer referenced object.

Parameters:

ref - new referenced object.

isNull - if true this pointer becomes null.

isNull

public final boolean isNull()

Tests if this pointer is null.

Specified by:

isNull in interface PointerParameter

Returns:

true if this pointer is null; false otherwise

setNull

public final void setNull(boolean isNull)

Sets a pointer null value. Setting this to true makes the pointer to be null, setting to false makes it to reference its referenced object.

getLength

public int getLength()

Description copied from class: Parameter

Returns the length of the parameter in memory. This method is similar to C sizeof() operator.

Specified by:

getLength in class Parameter

write

public void write(byte[] arr,
                  int offset)

Description copied from class: Parameter

Writes the parameter value to a byte array.

Overrides:

write in class Parameter

read

public void read(byte[] arr,
                 int offset)

Description copied from class: Parameter

Reads the parameter value from a byte array.

Overrides:

read in class Parameter

clone

public java.lang.Object clone()

Specified by:

clone in class Parameter

getPointerHandle

protected long getPointerHandle()

Returns the value of pointer as used by the native side.

write

public void write(DataBuffer stackBuffer,
                  int offset,
                  boolean invokedByCallback)
           throws MemoryAccessViolationException

Description copied from class: Parameter

Writes this parameter to a specified data source.

Specified by:

write in class Parameter

Throws:

MemoryAccessViolationException

writePointer

protected void writePointer(DataBuffer stackBuffer,
                            int offset)
                     throws MemoryAccessViolationException

Writes this pointer handle part (not the referenced object) to a given data buffer. This method checks if enough memory is allocated to store the referenced object and reallocates it if necessary.

Throws:

MemoryAccessViolationException

read

public void read(DataBuffer stackBuffer,
                 int offset,
                 boolean invokedByCallback)
          throws MemoryAccessViolationException

Description copied from class: Parameter

Reads this parameter from a specified data source.

Specified by:

read in class Parameter

Throws:

MemoryAccessViolationException

readPointer

protected void readPointer(DataBuffer stackBuffer,
                           int offset)
                    throws MemoryAccessViolationException

Reads this pointer handle part (not the referenced object) from the given data buffer. This method checks if the read handle is the same as the previously written one and also adjusts null status accordingly. If the pointer handle was changed by the native code, the new memory is considered external and is not freed by JNIWrapper.

Throws:

MemoryAccessViolationException

asVoidPointer

public void asVoidPointer(Pointer.Void target)

Deprecated. use castTo(com.jniwrapper.Pointer.Void) instead.

Assigns this pointer value to the void pointer.

Parameters:

target - target void pointer

castTo

public void castTo(Pointer.Void target)

Casts this pointer to the given void pointer.

Parameters:

target - the target void pointer

setExternalSource

protected void setExternalSource(long newHandle,
                                 int length)

Makes this pointer use external (unmanaged) memory area.

Parameters:

newHandle - memory handle

length - known allocated length

Since:

1.1

push

public void push(DataBuffer stackBuffer,
                 int offset,
                 boolean invokedByCallback)

Description copied from class: Parameter

Writes a parameter to a function stacks.

Overrides:

push in class Parameter

pop

public void pop(DataBuffer stackBuffer,
                int offset,
                boolean invokedByCallback)
         throws MemoryAccessViolationException

Description copied from class: Parameter

Default implementation that does nothing because most primitive types do nothing on pop. Reads a parameter from a function stack.

Overrides:

pop in class Parameter

Throws:

MemoryAccessViolationException

checkMemHandleLength

protected void checkMemHandleLength()

Checks that the memory block referred to by this pointer is big enough to hold the referenced object and allocates a new one if required. If this pointer is set to be null, no action is taken.

acceptIOPerformer

protected void acceptIOPerformer(IOPerformer performer,
                                 DataBuffer source,
                                 int initialOffset,
                                 boolean isReadOperation,
                                 boolean invokedByCallback)

Description copied from class: Parameter

Implementation of a Visitor pattern for parameter IO. A performer is responsible for reading and writing the parameter. Users implementing a complex parameter from scratch (i.e. not by extending a pre-existing class such as Structure or Pointer) may wish to override this method to make a performer visit object internal parts.

Overrides:

acceptIOPerformer in class Parameter

Parameters:

performer - a visitor responsible for I/Oing the parameter.

source - data buffer for I/O operation.

initialOffset - I/O operation offset of this parameter in the buffer.

writeReferencedObject

protected void writeReferencedObject(boolean invokedByCallback)

Writes the referenced object only. No checking is performed for memory block size or even location validity.

readReferencedObject

protected void readReferencedObject(boolean invokedByCallback)

Reads the referenced object only. No checking is performed for memory block size or even location validity.

equals

public boolean equals(java.lang.Object obj)

Description copied from class: Parameter

Compares this Parameter object to a given object. Two Parameter objects are considered equal if their byte representations are equal and they are of the same type. Subclasses may override this method as appropriate.

Overrides:

equals in class Parameter

Parameters:

obj - a value to compare this object to.

Returns:

true if two objects are equal.

getDebugInfo

public java.lang.String getDebugInfo()

Description copied from class: Parameter

Return debug info for JNIWrapper parameter.

Specified by:

getDebugInfo in class Parameter

Returns:

debug info

getParameterClass

public java.lang.Class getParameterClass()

Returns the parameter type of this pointer object.

Returns:

parameter class