JNI 函数
本章为 JNI 函数提供参考信息。其中列出了全部 JNI 函数,同时也给出了 JNI 函数表的准确布局。
注意:“必须”一词用于约束 JNI 编程人员。例如,当说明某个 JNI 函数必须接收非空对象时,就应确保不要向该 JNI 函数传递 NULL。这时,JNI 实现将无需在该 JNI 函数中执行 NULL 指针检查。
本章的部分资料改编自 Netscape 的 JRI 文档。
该参考资料按用法对函数进行组织。参考部分按下列函数区域进行组织:
接口函数表
每个函数均可通过 JNIEnv 参数以固定偏移量进行访问。JNIEnv 的类型是一个指针,指向存储全部 JNI 函数指针的结构。其定义如下:
注意:前三项留作将来与 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
:局部引用。