JNI接口函数 (2)

对象操作

AllocObject
jobject AllocObject(JNIEnv *env, jclass clazz);
分配新 Java 对象而不调用该对象的任何构造函数。返回该对象的引用。
clazz 参数务必不要引用数组类。
参数：
env：JNI 接口指针。
clazz：Java 类对象。
返回值：
返回 Java 对象。如果无法构造该对象，则返回NULL。
抛出：
InstantiationException：如果该类为一个接口或抽象类。
OutOfMemoryError：如果系统内存不足。

NewObject
NewObjectA
NewObjectV
jobject NewObject(JNIEnv *env, jclass clazz,
jmethodID methodID, …);
jobject NewObjectA(JNIEnv *env,jclass clazz,
jmethodID methodID, jvalue *args);
jobject NewObjectV(JNIEnv *env,jclass clazz,
jmethodID methodID, va_list args);
构造新 Java 对象。方法 ID指示应调用的构造函数方法。该 ID 必须通过调用 GetMethodID() 获得，且调用时的方法名必须为 ，而返回类型必须为 void (V)。
clazz参数务必不要引用数组类。
NewObject
编程人员应将传递给构造函数的所有参数紧跟着放在 methodID 参数的后面。NewObject() 收到这些参数后，将把它们传给编程人员所要调用的 Java 方法。
NewObjectA
编程人员应将传递给构造函数的所有参数放在 jvalues 类型的数组 args 中，该数组紧跟着放在 methodID 参数的后面。NewObject() 收到数组中的这些参数后，将把它们传给编程人员所要调用的 Java 方法。
NewObjectV
编程人员应将传递给构造函数的所有参数放在 va_list 类型的参数 args 中，该参数紧跟着放在 methodID 参数的后面。NewObject() 收到这些参数后，将把它们传给编程人员所要调用的 Java 方法。
参数：
env：JNI 接口指针。
clazz：Java 类对象。
methodID：构造函数的方法 ID。
NewObject 的其它参数：
传给构造函数的参数。
NewObjectA 的其它参数：
args：传给构造函数的参数数组。
NewObjectV 的其它参数：
args：传给构造函数的参数 va_list。
返回值：
返回 Java 对象，如果无法构造该对象，则返回NULL。
抛出：
InstantiationException：如果该类为接口或抽象类。
OutOfMemoryError：如果系统内存不足。
构造函数抛出的任何异常。

GetObjectClass
jclass GetObjectClass(JNIEnv *env, jobject obj);
返回对象的类。
参数：
env：JNI 接口指针。
obj：Java 对象（不能为 NULL）。
返回值：
返回 Java 类对象。

IsInstanceOf
jboolean IsInstanceOf(JNIEnv *env, jobject obj,
jclass clazz);
测试对象是否为某个类的实例。
参数：
env：JNI 接口指针。
obj：Java 对象。
clazz：Java 类对象。
返回值：
如果可将 obj 强制转换为 clazz，则返回 JNI_TRUE。否则返回 JNI_FALSE。NULL 对象可强制转换为任何类。

IsSameObject
jbooleanIsSameObject(JNIEnv *env, jobject ref1,
jobject ref2);
测试两个引用是否引用同一 Java 对象。
参数：
env：JNI 接口指针。
ref1：Java 对象。
ref2：Java 对象。
返回值：
如果 ref1 和 ref2 引用同一 Java 对象或均为 NULL，则返回 JNI_TRUE。否则返回 JNI_FALSE。
访问对象的域

GetFieldID
jfieldID GetFieldID(JNIEnv *env, jclass clazz,
const char *name, const char *sig);
返回类的实例（非静态）域的域 ID。该域由其名称及签名指定。访问器函数的GetField 及 SetField 系列使用域 ID 检索对象域。
GetFieldID() 将未初始化的类初始化。
GetFieldID() 不能用于获取数组的长度域。应使用GetArrayLength()。
参数：
env：JNI 接口指针。
clazz：Java 类对象。
name:0 终结的 UTF-8 字符串中的域名。
sig：0 终结的 UTF-8 字符串中的域签名。
返回值：
域 ID。如果操作失败，则返回NULL。
抛出：
NoSuchFieldError：如果找不到指定的域。
ExceptionInInitializerError：如果由于异常而导致类初始化程序失败。
OutOfMemoryError：如果系统内存不足。

GetField 例程
NativeType GetField(JNIEnv*env, jobject obj,
jfieldID fieldID);
该访问器例程系列返回对象的实例（非静态）域的值。要访问的域由通过调用GetFieldID() 而得到的域 ID 指定。
下表说明了 GetField 例程名及结果类型。应将 GetField 中的 type 替换为域的 Java 类型（或使用表中的某个实际例程名），然后将NativeType 替换为该例程对应的本地类型。
表 4-1 GetField 访问器例程系列
GetField 例程名
本地类型
GetObjectField()
jobject
GetBooleanField()
jboolean
GetByteField()
jbyte
GetCharField()
jchar
GetShortField()
jshort
GetIntField()
jint
GetLongField()
jlong
GetFloatField()
jfloat
GetDoubleField()
jdouble
参数：
env：JNI 接口指针。
obj：Java 对象（不能为 NULL）。
fieldID：有效的域 ID。
返回值：
域的内容。

SetField 例程
void SetField(JNIEnv *env, jobject obj, jfieldID fieldID,
NativeType value);
该访问器例程系列设置对象的实例（非静态）域的值。要访问的域由通过调用SetFieldID() 而得到的域 ID 指定。
下表说明了 SetField 例程名及结果类型。应将 SetField 中的 type 替换为域的 Java 类型（或使用表中的某个实际例程名），然后将NativeType 替换为该例程对应的本地类型。
表4-2 SetField 访问器例程系列
SetField 例程名
本地类型
SetObjectField()
jobject
SetBooleanField()
jboolean
SetByteField()
jbyte
SetCharField()
jchar
SetShortField()
jshort
SetIntField()
jint
SetLongField()
jlong
SetFloatField()
jfloat
SetDoubleField()
jdouble
参数：
env：JNI 接口指针。
obj：Java 对象（不能为 NULL）。
fieldID：有效的域 ID。
value：域的新值。
调用实例方法

GetMethodID
jmethodID GetMethodID(JNIEnv *env, jclass clazz,
const char *name, const char *sig);
返回类或接口实例（非静态）方法的方法 ID。方法可在某个 clazz 的超类中定义，也可从 clazz 继承。该方法由其名称和签名决定。
GetMethodID() 可使未初始化的类初始化。
要获得构造函数的方法 ID，应将 作为方法名，同时将 void (V) 作为返回类型。
参数：
env：JNI 接口指针。
clazz：Java 类对象。
name：0 终结的 UTF-8 字符串中的方法名。
sig：0 终结的 UTF-8 字符串中的方法签名。
返回值：
方法 ID，如果找不到指定的方法，则为 NULL。
抛出：
NoSuchMethodError：如果找不到指定方法。
ExceptionInInitializerError：如果由于异常而导致类初始化程序失败。
OutOfMemoryError：如果系统内存不足。

CallMethod 例程
CallMethodA 例程
CallMethodV 例程
NativeType CallMethod(JNIEnv*env, jobject obj,
jmethodID methodID, …);
NativeType CallMethodA(JNIEnv *env, jobject obj,
jmethodID methodID, jvalue *args);
NativeType CallMethodV(JNIEnv *env, jobject obj,
jmethodID methodID, va_list args);
这三个操作的方法用于从本地方法调用Java 实例方法。它们的差别仅在于向其所调用的方法传递参数时所用的机制。
这三个操作将根据所指定的方法 ID 调用 Java 对象的实例（非静态）方法。参数 methodID 必须通过调用 GetMethodID() 来获得。
当这些函数用于调用私有方法和构造函数时，方法 ID 必须从 obj 的真实类派生而来，而不应从其某个超类派生。
CallMethod例程
编程人员应将要传给方法的所有参数紧跟着放在 methodID 参数之后。CallMethod 例程接受这些参数并将其传给编程人员所要调用的 Java 方法。
CallMethodA 例程
编程人员应将要传给方法的所有参数放在紧跟在 methodID 参数之后的 jvalues 类型数组 args 中。CallMethodA routine 接受这些数组中的参数并将其传给编程人员所要调用的 Java 方法。
CallMethodV例程
编程人员将方法的所有参数放在紧跟着在 methodID 参数之后的 va_list 类型参数变量中。CallMethodV routine 接受这些参数并将其传给编程人员所要调用的 Java 方法。
下表根据结果类型说明了各个方法调用例程。用户应将CallMethod 中的 type 替换为所调用方法的 Java 类型（或使用表中的实际方法调用例程名），同时将 NativeType 替换为该例程相应的本地类型。
表 4-3 实例方法调用例程
CallMethod 例程名
本地类型
CallVoidMethod() CallVoidMethodA() CallVoidMethodV()
void
CallObjectMethod() CallObjectMethodA() CallObjectMethodV()
jobject
CallBooleanMethod() CallBooleanMethodA() CallBooleanMethodV()
jboolean
CallByteMethod() CallByteMethodA() CallByteMethodV()
jbyte
CallCharMethod() CallCharMethodA() CallCharMethodV()
jchar
CallShortMethod() CallShortMethodA() CallShortMethodV()
jshort
CallIntMethod() CallIntMethodA() CallIntMethodV()
jint
CallLongMethod() CallLongMethodA() CallLongMethodV()
jlong
CallFloatMethod() CallFloatMethodA() CallFloatMethodV()
jfloat
CallDoubleMethod() CallDoubleMethodA() CallDoubleMethodV()
jdouble
参数：
env：JNI 接口指针。
obj：Java 对象。
methodID：方法 ID。
CallMethod例程的其它参数：
要传给 Java 方法的参数。
CallMethodA例程的其它参数：
args：参数数组。
CallMethodV例程的其它参数：
args：参数的 va_list。
返回值：
返回调用 Java 方法的结果。
抛出：
执行 Java 方法时抛出的异常。

CallNonvirtualMethod 例程
CallNonvirtualMethodA 例程
CallNonvirtualMethodV 例程
NativeType CallNonvirtualMethod(JNIEnv *env, jobject obj,
jclass clazz, jmethodID methodID, …);
NativeType CallNonvirtualMethodA(JNIEnv *env, jobject obj,
jclass clazz, jmethodID methodID, jvalue *args);
NativeType CallNonvirtualMethodV(JNIEnv *env, jobject obj,
jclass clazz, jmethodID methodID, va_list args);
这些操作根据指定的类和方法 ID 调用某 Java 对象的实例（非静态）方法。参数 methodID 必须通过调用 clazz 类的GetMethodID() 获得。
CallNonvirtualMethod 和 CallMethod 例程系列并不相同。CallMethod 例程根据对象的类调用方法，而 CallNonvirtualMethod 例程则根据获得方法 ID 的（由 clazz 参数指定）类调用方法。方法 ID 必须从对象的真实类或其某个超类获得。
CallNonvirtualMethod例程
编程人员应将要传给方法的所有参数紧跟着放在 methodID 参数之后。CallNonvirtualMethod routine 接受这些参数并将其传给编程人员所要调用的 Java 方法。
CallNonvirtualMethodA例程
编程人员应将要传给方法的所有参数放在紧跟在 methodID 参数之后的 jvalues 类型数组 args 中。CallNonvirtualMethodAroutine 接受这些数组中的参数并将其传给编程人员所要调用的 Java 方法。
CallNonvirtualMethodV例程
编程人员应将要传给方法的所有参数放在紧跟在 methodID 参数之后的 va_list 类型参数 args 中。CallNonvirtualMethodV routine 接受这些参数并将其传给编程人员所要调用的 Java 方法。
下表根据结果类型说明了各个方法调用例程。用户应将CallNonvirtualMethod 中的 type 替换为所调用方法的 Java 类型（或使用表中的实际方法调用例程名），同时将 NativeType 替换为该例程相应的本地类型。
表 4-4 CallNonvirtualMethod 例程
CallNonvirtualMethod 例程名
本地类型
CallNonvirtualVoidMethod() CallNonvirtualVoidMethodA() CallNonvirtualVoidMethodV()
void
CallNonvirtualObjectMethod() CallNonvirtualObjectMethodA() CallNonvirtualObjectMethodV()
jobject
CallNonvirtualBooleanMethod() CallNonvirtualBooleanMethodA() CallNonvirtualBooleanMethodV()
jboolean
CallNonvirtualByteMethod() CallNonvirtualByteMethodA() CallNonvirtualByteMethodV()
jbyte
CallNonvirtualCharMethod() CallNonvirtualCharMethodA() CallNonvirtualCharMethodV()
jchar
CallNonvirtualShortMethod() CallNonvirtualShortMethodA() CallNonvirtualShortMethodV()
jshort
CallNonvirtualIntMethod() CallNonvirtualIntMethodA() CallNonvirtualIntMethodV()
jint
CallNonvirtualLongMethod() CallNonvirtualLongMethodA() CallNonvirtualLongMethodV()
jlong
CallNonvirtualFloatMethod() CallNonvirtualFloatMethodA() CallNonvirtualFloatMethodV()
jfloat
CallNonvirtualDoubleMethod() CallNonvirtualDoubleMethodA() CallNonvirtualDoubleMethodV()
jdouble
参数：
env：JNI 接口指针。
clazz：Java 类。
obj: Java 对象。
methodID：方法 ID。
CallNonvirtualMethod例程的其它参数：
要传给 Java 方法的参数。
CallNonvirtualMethodA例程的其它参数：
args：参数数组。
CallNonvirtualMethodV例程的其它参数：
args：参数的 va_list。
返回值：
调用 Java 方法的结果。
抛出：
执行 Java 方法时所抛出的异常。
访问静态域

GetStaticFieldID
jfieldID GetStaticFieldID(JNIEnv *env, jclass clazz,
const char *name, const char *sig);
返回类的静态域的域 ID。域由其名称和签名指定。GetStaticField 和 SetStaticField 访问器函数系列使用域 ID 检索静态域。
GetStaticFieldID() 将未初始化的类初始化。
参数：
env：JNI 接口指针。
clazz：Java 类对象。
name: 0 终结的 UTF-8 字符串中的静态域名。
sig：0 终结的 UTF-8 字符串中的域签名。
返回值：
域 ID。如果找不到指定的静态域，则为 NULL。
抛出：
NoSuchFieldError：如果找不到指定的静态域。
ExceptionInInitializerError：如果由于异常而导致类初始化程序失败。
OutOfMemoryError：如果系统内存不足。

GetStaticField 例程
NativeType GetStaticField(JNIEnv*env, jclass clazz,
jfieldID fieldID);
该访问器例程系列返回对象的静态域的值。要访问的域由通过调用GetStaticFieldID()而得到的域 ID 指定。
下表说明了 GetStaticField 例程名及结果类型。应将 GetStaticField 中的 type 替换为域的 Java 类型（或使用表中的某个实际例程名），然后将NativeType 替换为该例程对应的本地类型。
表 4-5 GetStaticField 访问器例程系列
GetStaticField 例程名
本地类型
GetStaticObjectField()
jobject
GetStaticBooleanField()
jboolean
GetStaticByteField()
jbyte
GetStaticCharField()
jchar
GetStaticShortField()
jshort
GetStaticIntField()
jint
GetStaticLongField()
jlong
GetStaticFloatField()
jfloat
GetStaticDoubleField()
jdouble
参数：
env：JNI 接口指针。
clazz：Java 类对象。
fieldID：静态域 ID。
返回值：
静态域的内容。

SetStaticField 例程
void SetStaticField(JNIEnv *env, jclass clazz,
jfieldID fieldID, NativeType value);
该访问器例程系列设置对象的静态域的值。要访问的域由通过调用GetStaticFieldID()而得到的域 ID 指定。
下表说明了 SetStaticField 例程名及结果类型。应将 SetStaticField 中的 type 替换为域的 Java 类型（或使用表中的某个实际例程名），然后将NativeType 替换为该例程对应的本地类型。
表4-6 SetStaticField 访问器例程系列
SetStaticField 例程名
本地类型
SetStaticObjectField()
jobject
SetStaticBooleanField()
jboolean
SetStaticByteField()
jbyte
SetStaticCharField()
jchar
SetStaticShortField()
jshort
SetStaticIntField()
jint
SetStaticLongField()
jlong
SetStaticFloatField()
jfloat
SetStaticDoubleField()
jdouble
参数：
env：JNI 接口指针。
clazz：Java 类对象。
fieldID：静态域 ID。
value：域的新值。
调用静态方法

GetStaticMethodID
jmethodID GetStaticMethodID(JNIEnv *env, jclass clazz,
const char *name, const char *sig);
返回类的静态方法的方法 ID。方法由其名称和签名指定。
GetStaticMethodID() 将未初始化的类初始化。
参数：
env：JNI 接口指针。
clazz：Java 类对象。
name：0 终结 UTF-8 字符串中的静态方法名。
sig：0 终结 UTF-8 字符串中的方法签名。
返回值：
方法 ID，如果操作失败，则为 NULL。
抛出：
NoSuchMethodError：如果找不到指定的静态方法。
ExceptionInInitializerError：如果由于异常而导致类初始化程序失败。
OutOfMemoryError：如果系统内存不足。

CallStaticMethod 例程
CallStaticMethodA 例程
CallStaticMethodV 例程
NativeType CallStaticMethod(JNIEnv*env, jclass clazz,
jmethodID methodID, …);
NativeType CallStaticMethodA(JNIEnv *env, jclass clazz,
jmethodID methodID, jvalue *args);
NativeType CallStaticMethodV(JNIEnv *env, jclass clazz,
jmethodID methodID, va_list args);
这些操作将根据指定的方法 ID 调用 Java 对象的静态方法。methodID 参数必须通过调用GetStaticMethodID() 得到。
方法 ID 必须从 clazz 派生，而不能从其超类派生。
CallStaticMethod例程
编程人员应将要传给方法的所有参数紧跟着放在 methodID 参数之后。 CallStaticMethod routine 接受这些参数并将其传给编程人员所要调用的 Java 方法。
CallStaticMethodA 例程
编程人员应将要传给方法的所有参数放在紧跟在 methodID 参数之后的 jvalues 类型数组 args 中。CallStaticMethodA routine 接受这些数组中的参数并将其传给编程人员所要调用的 Java 方法。
CallStaticMethodV例程
编程人员应将要传给方法的所有参数放在紧跟在 methodID 参数之后的 va_list 类型参数 args 中。CallStaticMethodV routine 接受这些参数并将其传给编程人员所要调用的 Java 方法。
下表根据结果类型说明了各个方法调用例程。用户应将CallStaticMethod 中的 type 替换为所调用方法的 Java 类型（或使用表中的实际方法调用例程名），同时将 NativeType 替换为该例程相应的本地类型。
表 4-7 CallStaticMethod 调用例程
CallStaticMethod 例程名
本地类型
CallStaticVoidMethod() CallStaticVoidMethodA() CallStaticVoidMethodV()
void
CallStaticObjectMethod() CallStaticObjectMethodA() CallStaticObjectMethodV()
jobject
CallStaticBooleanMethod() CallStaticBooleanMethodA() CallStaticBooleanMethodV()
jboolean
CallStaticByteMethod() CallStaticByteMethodA() CallStaticByteMethodV()
jbyte
CallStaticCharMethod() CallStaticCharMethodA() CallStaticCharMethodV()
jchar
CallStaticShortMethod() CallStaticShortMethodA() CallStaticShortMethodV()
jshort
CallStaticIntMethod() CallStaticIntMethodA() CallStaticIntMethodV()
jint
CallStaticLongMethod() CallStaticLongMethodA() CallStaticLongMethodV()
jlong
CallStaticFloatMethod() CallStaticFloatMethodA() CallStaticFloatMethodV()
jfloat
CallStaticDoubleMethod() CallStaticDoubleMethodA() CallStaticDoubleMethodV()
jdouble
参数：
env：JNI 接口指针。
clazz：Java 类对象。
methodID：静态方法 ID。
CallStaticMethod例程的其它参数：
要传给静态方法的参数。
CallStaticMethodA例程的其它参数：
args：参数数组。
CallStaticMethodV例程的其它参数：
args：参数的 va_list。
返回值：
返回调用静态 Java 方法的结果。
抛出：
执行 Java 方法时抛出的异常。