Chapter   5

KNI Functions

This chapter specifies the KNI functions. For each KNI function, we provide the following information:

function prototype,
a detailed description, including parameters, return values, and potential exceptions.

Note that since KNI is an implementation-level interface, the interface places some important restrictions and expectations on the programmer.

We use the adverb must to describe restrictions and conventions that the KNI programmer is expected to adhere to. For instance, when some KNI function must receive a non-null object as a parameter, it is the programmer’s responsibility not to pass a null value to that function. Programmer-level restrictions like this allow the KNI implementation to be more efficient, as the KNI implementation does not check for null pointers or other similar conditions. In general, KNI is a “shoot yourself in the foot” interface that performs only a minimum number of checks at runtime to ensure the validity of the parameters.

5.1 Version Information

5.1.1 KNI_GetVersion

5.2 Class and Interface Operations

5.2.1 KNI_FindClass

5.2.2 KNI_GetSuperClass

5.2.3 KNI_IsAssignableFrom

5.3 Exceptions

5.3.1 KNI_ThrowNew

5.3.2 KNI_FatalError

5.4 Object Operations

5.4.1 KNI_GetObjectClass

5.4.2 KNI_IsInstanceOf

5.5 Instance Field Access

5.5.1 KNI_GetFieldID

5.5.2 KNI_Get<Type>Field

This family of functions consists of eight members that are listed in the table below. Note that those functions that manipulate jfloat or jdouble data types are assumed to be available only if the underlying virtual machine or J2ME configuration supports floating point data types.

5.5.3 KNI_Set<Type>Field

This family of functions consists of nine members that are listed in the table below. Note that those functions that manipulate jfloat or jdouble data types are assumed to be available only if the underlying virtual machine or J2ME configuration supports floating point data types.

5.5.4 KNI_GetObjectField

5.5.5 KNI_SetObjectField

5.6 Static Field Access

5.6.1 KNI_GetStaticFieldID

5.6.2 KNI_GetStatic<Type>Field

This family of functions consists of eight members that are listed in the table below. Note that those functions that manipulate jfloat or jdouble data types are assumed to be available only if the underlying virtual machine or J2ME configuration supports floating point data types:

5.6.3 KNI_SetStatic<Type>Field

This family of functions consists of eight members that are listed in the table below. Note that those functions that manipulate jfloat or jdouble data types are assumed to be available only if the underlying virtual machine or J2ME configuration supports floating point data types:

5.6.4 KNI_GetStaticObjectField

5.6.5 KNI_SetStaticObjectField

5.7 String Operations

5.7.1 KNI_GetStringLength

5.7.2 KNI_GetStringRegion

5.7.3 KNI_NewString

5.7.4 KNI_NewStringUTF

5.8 Array Operations

5.8.1 KNI_GetArrayLength

5.8.2 KNI_Get<Type>ArrayElement

This family of functions consists of eight members that are listed in the table below. Note that those functions that manipulate jfloat or jdouble data types are assumed to be available only if the underlying virtual machine or J2ME configuration supports floating point data types.

5.8.3 KNI_Set<Type>ArrayElement

This family of functions consists of eight members that are listed in the table below. Note that those functions that manipulate jfloat or jdouble data types are assumed to be available only if the underlying virtual machine or J2ME configuration supports floating point data types.

5.8.4 KNI_GetObjectArrayElement

5.8.5 KNI_SetObjectArrayElement

5.8.6 KNI_GetRawArrayRegion

5.8.7 KNI_SetRawArrayRegion

5.9 Parameter (Operand Stack) Access

KNI introduces a new set of functions for reading the parameters (local variables) that a Java method has passed on to a native method, as well as a set of functions for returning values back from native methods to Java methods. These functions are typically used in conjunction of the handle operations introduced in Section 5.10 “Handle Operations.”

5.9.1 KNI_GetParameterAs<Type>

Note – It is important to note that parameters of type long or double take up two entries on the operand stack. For example, when calling the following function

native void foo(int a, long b, int c);

the index of parameter ‘a’ would be 1, index of parameter ‘b’ would be 2, and index of parameter ‘c’ would 4.

---

This family of functions consists of eight members that are listed in the table below. Note that those functions that manipulate jfloat or jdouble data types are assumed to be available only if the underlying virtual machine or J2ME configuration supports floating point data types.

TABLE 42  –  Support for accessing a native method actual parameters

KNI_GetParameterAs<Type>	<Type>	<ReturnType>
KNI_GetParameterAsBoolean	Boolean	jboolean
KNI_GetParameterAsByte	Byte	jbyte
KNI_GetParameterAsChar	Char	jchar
KNI_GetParameterAsShort	Short	jshort
KNI_GetParameterAsInt	Int	jint
KNI_GetParameterAsLong	Long	jlong
KNI_GetParameterAsFloat	Float	jfloat
KNI_GetParameterAsDouble	Double	jdouble

5.9.2 KNI_GetParameterAsObject

TABLE 43  –  KNI_GetParameterAsObject

Function	Description
Prototype	void KNI_GetParameterAsObject(jint index, jobject toHandle);
Description	Reads the value (object reference) of the parameter specified by index, and stores it in the handle toHandle. Parameter indices are mapped from left to right. Index value 1 refers to the leftmost parameter that has been passed on to the native method. No type checking or index range checking is performed.
Parameters	index: the index of a parameter of a reference type to the native method. Index value 1 refers to the leftmost parameter in the Java method. toHandle: a handle to to which the return value will be assigned.
Return Values	Returns nothing directly, but handle toHandle will contain the return value.
Exceptions	None.

5.9.3 KNI_GetThisPointer

TABLE 44  –  KNI_GetThisPointer

Function	Description
Prototype	void KNI_GetThisPointer(jobject toHandle);
Description	Reads the value of the ‘this’ pointer in the current stack frame of an instance (non-static) native method, and stores the value in the handle toHandle.
Parameters	toHandle: a handle to contain the ‘this’ pointer.
Return Values	Returns nothing directly, but handle toHandle will contain the return value. The return value is unspecified if this method is called inside a static native method.
Exceptions	None.

---

Note – The function KNI_GetThisPointer should only be used only inside instance (non-static) native methods. The return value of this function is unspecified if the function is called from a static native method.

---

5.9.4 KNI_GetClassPointer

TABLE 45  –  KNI_GetClassPointer

Function	Description
Prototype	void KNI_GetClassPointer(jclass toHandle);
Description	Reads the value of the class pointer in the current stack frame of a static native method, and stores the value in the handle toHandle.
Parameters	toHandle: a handle to contain the class pointer.
Return Values	Returns nothing directly, but handle toHandle will contain the return value.
Exceptions	None.

5.9.5 KNI_ReturnVoid

TABLE 46  –  KNI_ReturnVoid

Function	Description
Prototype	void KNI_ReturnVoid();
Description	Returns a void value from a native function. Calling this function terminates the execution of the native function immediately.
Parameters	None.
Return Values	None
Exceptions	None.

---

Note – IMPORTANT: The KNI_ReturnVoid function MUST BE CALLED at the end of a native function when a native function function does not want to return a value back to the calling Java function. Otherwise the operand stack of the Java virtual machine may become corrupted.

---

5.9.6 KNI_Return<Type>

TABLE 47  –  KNI_Return<Type>

Function	Description
Prototype	void KNI_Return<Type>(<NativeType> value);
Description	Returns a primitive value from a native function. Calling any of the KNI_Return<Type> functions will terminate the execution of the native function immediately.
Parameters	value: the result value of the native method.
Return Values	Returns a primitive value back to the function that called the native function containing the KNI_Return<Type> call.
Exceptions	None.

---

Note – The semantics of the KNI_Return<Type> functions are similar to the standard C/C++ return statement. The execution of the function is terminated immediately, and the control is returned back to the caller.

---

This family of functions consists of eight members that are listed in the table below. Note that those functions that manipulate jfloat or jdouble data types are assumed to be available only if the underlying virtual machine or J2ME configuration supports floating point data types.

TABLE 48  –  Support for setting a native result value

KNI_Return<Type>	<Type>	<NativeType>
KNI_ReturnBoolean	Boolean	jboolean
KNI_ReturnByte	Byte	jbyte
KNI_ReturnChar	Char	jchar
KNI_ReturnShort	Short	jshort
KNI_ReturnInt	Int	jint
KNI_ReturnLong	Long	jlong
KNI_ReturnFloat	Float	jfloat
KNI_ReturnDouble	Double	jdouble

5.10 Handle Operations

To avoid garbage collection problems , all the object references used by KNI are handles to objects rather than direct object references. Many KNI functions (such as KNI_GetParameterAsObject and KNI_GetObjectField) use object handles as input or output parameters. It is the programmer’s responsibility to allocate, declare and unallocate the handles that are needed inside a native function.

Seven handle functions are provided, as listed below.

---

Note – It is important to notice that the implementation of KNI handle operations may vary significantly from one virtual machine to another. The native function programmer should not assume anything about the internal structure or behavior of the handles. In order to write portable code, the programmer must only use the public KNI handle operations defined below.

---

5.10.1 KNI_StartHandles

TABLE 49  –  KNI_StartHandles

Function	Description
Prototype	void KNI_StartHandles(n)
Description	Allocates enough space for n handles for the current native method.
Parameters	n: a positive integer specifying the number of handles to allocate.
Return Values	Nothing directly, but allocates space for a number of handles in an implementation-dependent fashion.
Exceptions	None.

---

Note – Every call to KNI_StartHandles must be matched with a corresponding KNI_EndHandles or KNI_EndHandlesAndReturnObject call. Nested KNI_StartHandles and KNI_EndHandles / KNI_EndHandlesAndReturnObject calls are not allowed inside the same C/C++ code block ({ ... }).

---

5.10.2 KNI_DeclareHandle

TABLE 50  –  KNI_DeclareHandle

Function	Description
Prototype	void KNI_DeclareHandle(handle)
Description	Declares a handle that can be used as an input, output, or in/out parameter to an appropriate KNI function. The initial value of the handle is unspecified. If the programmer has not allocated enough space for the handle in the preceding call to KNI_StartHandles, the behavior of this function is unspecified.
Parameters	handle: the name by which the handle will be identified between the calls to KNI_StartHandles and KNI_EndHandles / KNI_EndHandlesAndReturnObject.
Return Values	Nothing directly, but declares a handle in an implementation-dependent fashion.
Exceptions	None.

5.10.3 KNI_IsNullHandle

TABLE 51  –  KNI_IsNullHandle

Function	Description
Prototype	jboolean KNI_IsNullHandle(handle)
Description	Checks if the given handle is NULL.
Parameters	handle: the handle whose contents will be examined.
Return Values	KNI_TRUE if the handle is NULL, KNI_FALSE otherwise.
Exceptions	None.

5.10.4 KNI_IsSameObject

TABLE 52  –  KNI_IsSameObject

Function	Description
Prototype	jboolean KNI_IsSameObject(handle1, handle2)
Description	Checks if the given two handles refer to the same object. No parameter type checking is performed.
Parameters	handle1: a handle pointing to an object. handle2: a handle pointing to an object.
Return Values	KNI_TRUE if the handles refer to the same object, KNI_FALSE otherwise.
Exceptions	None.

5.10.5 KNI_ReleaseHandle

TABLE 53  –  KNI_ReleaseHandle

Function	Description
Prototype	void KNI_ReleaseHandle(handle)
Description	Sets the value of the given handle to NULL.
Parameters	handle: the handle whose value will be set to NULL.
Return Values	None.
Exceptions	None.

5.10.6 KNI_EndHandles

TABLE 54  –  KNI_EndHandles

Function	Description
Prototype	void KNI_EndHandles()
Description	Undeclares and unallocates the handles defined after the preceding KNI_StartHandles call.
Parameters	None.
Return Values	None.
Exceptions	None.

---

Note – Every call to KNI_StartHandles must be matched with a corresponding KNI_EndHandles or KNI_EndHandlesAndReturnObject call. Nested KNI_StartHandles and KNI_EndHandles/KNI_EndHandlesAndReturnObject calls are not allowed inside the same C/C++ code block ({ ... }).

---

5.10.7 KNI_EndHandlesAndReturnObject

TABLE 55  –  KNI_EndHandlesAndReturnObject

Function	Description
Prototype	void KNI_EndHandlesAndReturnObject(jobject objectHandle);
Description	Undeclares and unallocates the handles defined after the preceding KNI_StartHandles call. At the same time, this function will terminate the execution of the native function immediately and return an object reference back to the caller.
Parameters	objectHandle: the handle from which the result value will be read.
Return Values	Returns an object value back to the function that called the native function containing the KNI_EndHandlesAndReturnObject call.
Exceptions	None.

 

---

KNI Specification K Native Interface (KNI), 1.0

 

Copyright © 2002 Sun Microsystems, Inc. All rights reserved.