JNI 函数
本章为 JNI 函数提供参考信息。其中列出了全部 JNI 函数，同时也给出了 JNI 函数表的准确布局。
注意：“必须”一词用于约束 JNI 编程人员。例如，当说明某个 JNI 函数必须接收非空对象时，就应确保不要向该 JNI 函数传递 NULL。这时，JNI 实现将无需在该 JNI 函数中执行 NULL 指针检查。
本章的部分资料改编自 Netscape 的 JRI 文档。
该参考资料按用法对函数进行组织。参考部分按下列函数区域进行组织：
- 版本信息
- 类操作
- 异常
- 全局及局部引用
- 对象操作
- 访问对象的域
- 调用实例方法
- 访问静态域
- 调用静态方法
- 字符串操作
- 数组操作
- 注册本地方法
- 监视程序操作
- Java 虚拟机接口
接口函数表
每个函数均可通过 JNIEnv 参数以固定偏移量进行访问。JNIEnv
注意：前三项留作将来与 COM 兼容。此外，我们在函数表开头部分也留出来多个 NULL 项，从而可将将来与类有关的 JNI 操作添加到 FindClass 后面，而非函数表的末尾。
注意，函数表可在所有 JNI 接口指针间共享。
代码示例 4-1 |
const struct JNINativeInterface ... = { |
NULL, |
NULL, |
NULL, |
NULL, |
GetVersion, |
|
DefineClass, |
FindClass, |
NULL, |
NULL, |
NULL, |
GetSuperclass, |
IsAssignableFrom, |
NULL, |
|
Throw, |
ThrowNew, |
ExceptionOccurred, |
ExceptionDescribe, |
ExceptionClear, |
FatalError, |
NULL, |
NULL, |
|
NewGlobalRef, |
DeleteGlobalRef, |
DeleteLocalRef, |
IsSameObject, |
NULL, |
NULL, |
|
AllocObject, |
NewObject, |
NewObjectV, |
NewObjectA, |
|
GetObjectClass, |
IsInstanceOf, |
|
GetMethodID, |
|
CallObjectMethod, |
CallObjectMethodV, |
CallObjectMethodA, |
CallBooleanMethod, |
CallBooleanMethodV, |
CallBooleanMethodA, |
CallByteMethod, |
CallByteMethodV, |
CallByteMethodA, |
CallCharMethod, |
CallCharMethodV, |
CallCharMethodA, |
CallShortMethod, |
CallShortMethodV, |
CallShortMethodA, |
CallIntMethod, |
CallIntMethodV, |
CallIntMethodA, |
CallLongMethod, |
CallLongMethodV, |
CallLongMethodA, |
CallFloatMethod, |
CallFloatMethodV, |
CallFloatMethodA, |
CallDoubleMethod, |
CallDoubleMethodV, |
CallDoubleMethodA, |
CallVoidMethod, |
CallVoidMethodV, |
CallVoidMethodA, |
|
CallNonvirtualObjectMethod, |
CallNonvirtualObjectMethodV, |
CallNonvirtualObjectMethodA, |
CallNonvirtualBooleanMethod, |
CallNonvirtualBooleanMethodV, |
CallNonvirtualBooleanMethodA, |
CallNonvirtualByteMethod, |
CallNonvirtualByteMethodV, |
CallNonvirtualByteMethodA, |
CallNonvirtualCharMethod, |
CallNonvirtualCharMethodV, |
CallNonvirtualCharMethodA, |
CallNonvirtualShortMethod, |
CallNonvirtualShortMethodV, |
CallNonvirtualShortMethodA, |
CallNonvirtualIntMethod, |
CallNonvirtualIntMethodV, |
CallNonvirtualIntMethodA, |
CallNonvirtualLongMethod, |
CallNonvirtualLongMethodV, |
CallNonvirtualLongMethodA, |
CallNonvirtualFloatMethod, |
CallNonvirtualFloatMethodV, |
CallNonvirtualFloatMethodA, |
CallNonvirtualDoubleMethod, |
CallNonvirtualDoubleMethodV, |
CallNonvirtualDoubleMethodA, |
CallNonvirtualVoidMethod, |
CallNonvirtualVoidMethodV, |
CallNonvirtualVoidMethodA, |
|
GetFieldID, |
|
GetObjectField, |
GetBooleanField, |
GetByteField, |
GetCharField, |
GetShortField, |
GetIntField, |
GetLongField, |
GetFloatField, |
GetDoubleField, |
SetObjectField, |
SetBooleanField, |
SetByteField, |
SetCharField, |
SetShortField, |
SetIntField, |
SetLongField, |
SetFloatField, |
SetDoubleField, |
|
GetStaticMethodID, |
|
CallStaticObjectMethod, |
CallStaticObjectMethodV, |
CallStaticObjectMethodA, |
CallStaticBooleanMethod, |
CallStaticBooleanMethodV, |
CallStaticBooleanMethodA, |
CallStaticByteMethod, |
CallStaticByteMethodV, |
CallStaticByteMethodA, |
CallStaticCharMethod, |
CallStaticCharMethodV, |
CallStaticCharMethodA, |
CallStaticShortMethod, |
CallStaticShortMethodV, |
CallStaticShortMethodA, |
CallStaticIntMethod, |
CallStaticIntMethodV, |
CallStaticIntMethodA, |
CallStaticLongMethod, |
CallStaticLongMethodV, |
CallStaticLongMethodA, |
CallStaticFloatMethod, |
CallStaticFloatMethodV, |
CallStaticFloatMethodA, |
CallStaticDoubleMethod, |
CallStaticDoubleMethodV, |
CallStaticDoubleMethodA, |
CallStaticVoidMethod, |
CallStaticVoidMethodV, |
CallStaticVoidMethodA, |
|
GetStaticFieldID, |
|
GetStaticObjectField, |
GetStaticBooleanField, |
GetStaticByteField, |
GetStaticCharField, |
GetStaticShortField, |
GetStaticIntField, |
GetStaticLongField, |
GetStaticFloatField, |
GetStaticDoubleField, |
|
SetStaticObjectField, |
SetStaticBooleanField, |
SetStaticByteField, |
SetStaticCharField, |
SetStaticShortField, |
SetStaticIntField, |
SetStaticLongField, |
SetStaticFloatField, |
SetStaticDoubleField, |
|
NewString, |
GetStringLength, |
GetStringChars, |
ReleaseStringChars, |
|
NewStringUTF, |
GetStringUTFLength, |
GetStringUTFChars, |
ReleaseStringUTFChars, |
|
GetArrayLength, |
|
NewObjectArray, |
GetObjectArrayElement, |
SetObjectArrayElement, |
|
NewBooleanArray, |
NewByteArray, |
NewCharArray, |
NewShortArray, |
NewIntArray, |
NewLongArray, |
NewFloatArray, |
NewDoubleArray, |
|
GetBooleanArrayElements, |
GetByteArrayElements, |
GetCharArrayElements, |
GetShortArrayElements, |
GetIntArrayElements, |
GetLongArrayElements, |
GetFloatArrayElements, |
GetDoubleArrayElements, |
|
ReleaseBooleanArrayElements, |
ReleaseByteArrayElements, |
ReleaseCharArrayElements, |
ReleaseShortArrayElements, |
ReleaseIntArrayElements, |
ReleaseLongArrayElements, |
ReleaseFloatArrayElements, |
ReleaseDoubleArrayElements, |
|
GetBooleanArrayRegion, |
GetByteArrayRegion, |
GetCharArrayRegion, |
GetShortArrayRegion, |
GetIntArrayRegion, |
GetLongArrayRegion, |
GetFloatArrayRegion, |
GetDoubleArrayRegion, |
SetBooleanArrayRegion, |
SetByteArrayRegion, |
SetCharArrayRegion, |
SetShortArrayRegion, |
SetIntArrayRegion, |
SetLongArrayRegion, |
SetFloatArrayRegion, |
SetDoubleArrayRegion, |
|
RegisterNatives, |
UnregisterNatives, |
|
MonitorEnter, |
MonitorExit, |
|
GetJavaVM, |
}; |
版本信息
GetVersion
jintGetVersion(JNIEnv *env);
返回本地方法接口的版本。
参数
env：JNI 接口指针。
返回值：
高 16 位返回主版本号，低 16 位返回次版本号。
在 JDK1.1 中，GetVersion() 返回 0x00010001。
类操作
DefineClass
jclassDefineClass(JNIEnv *env, jobject loader,
const jbyte *buf, jsize bufLen);
从原始类数据的缓冲区中加载类。
参数：
env：JNI 接口指针。
loader：分派给所定义的类的类加载器。
buf：包含 .class 文件数据的缓冲区。
bufLen：缓冲区长度。
返回值：
返回 Java 类对象。如果出错则返回NULL。
抛出：
ClassFormatError：如果类数据指定的类无效。
ClassCircularityError：如果类或接口是自身的超类或超接口。
OutOfMemoryError：如果系统内存不足。
FindClass
jclassFindClass(JNIEnv *env, const char *name);
该函数用于加载本地定义的类。它将搜索由CLASSPATH 环境变量为具有指定名称的类所指定的目录和 zip 文件。
参数：
env：JNI 接口指针。
name：类全名（即包名后跟类名，之间由“/”分隔）。如果该名称以“[”（数组签名字符）打头，则返回一个数组类。
返回值：
返回类对象全名。如果找不到该类，则返回 NULL。
抛出：
ClassFormatError：如果类数据指定的类无效。
ClassCircularityError：如果类或接口是自身的超类或超接口。
NoClassDefFoundError：如果找不到所请求的类或接口的定义。
OutOfMemoryError：如果系统内存不足。
GetSuperclass
jclassGetSuperclass(JNIEnv *env, jclass clazz);
如果 clazz 代表类而非类 object，则该函数返回由 clazz 所指定的类的超类。
如果 clazz 指定类 object 或代表某个接口，则该函数返回NULL。
参数：
env：JNI 接口指针。
clazz：Java 类对象。
返回值：
由 clazz 所代表的类的超类或 NULL。
IsAssignableFrom
jbooleanIsAssignableFrom(JNIEnv *env, jclass clazz1,
jclass clazz2);
确定 clazz1 的对象是否可安全地强制转换为clazz2。
参数：
env：JNI 接口指针。
clazz1：第一个类参数。
clazz2：第二个类参数。
返回值：
下列某个情况为真时返回 JNI_TRUE：
- 第一及第二个类参数引用同一个 Java 类。
- 第一个类是第二个类的子类。
- 第二个类是第一个类的某个接口。
异常
Throw
jintThrow(JNIEnv *env, jthrowable obj);
抛出 java.lang.Throwable 对象。
参数：
env：JNI 接口指针。
obj：java.lang.Throwable 对象。
返回值：
成功时返回 0，失败时返回负数。
抛出：
java.lang.Throwable 对象 obj。
ThrowNew
jintThrowNew(JNIEnv *env, jclass clazz,
const char *message);
利用指定类的消息（由 message 指定）构造异常对象并抛出该异常。
参数：
env：JNI 接口指针。
clazz：java.lang.Throwable 的子类。
message：用于构造java.lang.Throwable 对象的消息。
返回值：
成功时返回 0，失败时返回负数。
抛出：
新构造的 java.lang.Throwable 对象。
ExceptionOccurred
jthrowableExceptionOccurred(JNIEnv *env);
确定是否某个异常正被抛出。在平台相关代码调用 ExceptionClear() 或 Java 代码处理该异常前，异常将始终保持抛出状态。
参数：
env：JNI 接口指针。
返回值：
返回正被抛出的异常对象，如果当前无异常被抛出，则返回NULL。
ExceptionDescribe
voidExceptionDescribe(JNIEnv *env);
将异常及堆栈的回溯输出到系统错误报告信道（例如 stderr）。该例程可便利调试操作。
参数：
env：JNI 接口指针。
ExceptionClear
voidExceptionClear(JNIEnv *env);
清除当前抛出的任何异常。如果当前无异常，则此例程不产生任何效果。
参数：
env：JNI 接口指针。
FatalError
voidFatalError(JNIEnv *env, const char *msg);
抛出致命错误并且不希望虚拟机进行修复。该函数无返回值。
参数：
env：JNI 接口指针。
msg：错误消息。
全局及局部引用
NewGlobalRef
jobjectNewGlobalRef(JNIEnv *env, jobject obj);
创建 obj 参数所引用对象的新全局引用。obj 参数既可以是全局引用，也可以是局部引用。全局引用通过调用 DeleteGlobalRef() 来显式撤消。
参数：
env：JNI 接口指针。
obj：全局或局部引用。
返回值：
返回全局引用。如果系统内存不足则返回 NULL。
DeleteGlobalRef
voidDeleteGlobalRef(JNIEnv *env, jobject globalRef);
删除 globalRef 所指向的全局引用。
参数：
env：JNI 接口指针。
globalRef：全局引用。
DeleteLocalRef
voidDeleteLocalRef(JNIEnv *env, jobject localRef);
删除 localRef所指向的局部引用。
参数：
env：JNI 接口指针。
localRef：局部引用。
