JNI接口函数<一>

JNI 函数

本章为 JNI 函数提供参考信息。其中列出了全部 JNI 函数，同时也给出了 JNI 函数表的准确布局。

注意：“必须”一词用于约束 JNI 编程人员。例如，当说明某个 JNI 函数必须接收非空对象时，就应确保不要向该 JNI 函数传递 NULL。这时，JNI 实现将无需在该 JNI 函数中执行 NULL 指针检查。

本章的部分资料改编自 Netscape 的 JRI 文档。

该参考资料按用法对函数进行组织。参考部分按下列函数区域进行组织：

• 版本信息
• 类操作
• 异常
• 全局及局部引用
• 对象操作
• 访问对象的域
• 调用实例方法
• 访问静态域
• 调用静态方法
• 字符串操作
• 数组操作
• 注册本地方法
• 监视程序操作
• Java 虚拟机接口

接口函数表

每个函数均可通过 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

jint   GetVersion(JNIEnv *env);

返回本地方法接口的版本。

参数

env：JNI 接口指针。

返回值：

高 16 位返回主版本号，低 16 位返回次版本号。

在 JDK1.1 中，

GetVersion()

 返回 0x00010001。

类操作

DefineClass

jclass  DefineClass(JNIEnv *env, jobject loader, 

const jbyte *buf, jsize bufLen);

从原始类数据的缓冲区中加载类。

参数：

env：JNI 接口指针。

loader

：分派给所定义的类的类加载器。

buf

：包含 

.class

 文件数据的缓冲区。

bufLen

：缓冲区长度。

返回值：

返回 Java 类对象。如果出错则返回

NULL

。

抛出：

ClassFormatError：如果类数据指定的类无效。

ClassCircularityError

：如果类或接口是自身的超类或超接口。 

OutOfMemoryError

：如果系统内存不足。

FindClass

jclass  FindClass(JNIEnv *env, const char *name);

该函数用于加载本地定义的类。它将搜索由

CLASSPATH

 环境变量为具有指定名称的类所指定的目录和 zip 文件。

参数：

env：JNI 接口指针。

name

：类全名（即包名后跟类名，之间由“

/

”分隔）。如果该名称以“

[

”（数组签名字符）打头，则返回一个数组类。

返回值：

返回类对象全名。如果找不到该类，则返回 

NULL

。

抛出：

ClassFormatError：如果类数据指定的类无效。

ClassCircularityError

：如果类或接口是自身的超类或超接口。

NoClassDefFoundError

：如果找不到所请求的类或接口的定义。

OutOfMemoryError

：如果系统内存不足。

GetSuperclass

jclass  GetSuperclass(JNIEnv *env, jclass clazz);

如果 

clazz

 代表类而非类 

object

，则该函数返回由 

clazz

 所指定的类的超类。

如果 

clazz

 指定类 

object

 或代表某个接口，则该函数返回

NULL

。

参数：

env：JNI 接口指针。

clazz

：Java 类对象。

返回值：

由 

clazz

 所代表的类的超类或 

NULL

。

IsAssignableFrom

jboolean  IsAssignableFrom(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

jint  ThrowNew(JNIEnv *env, jclass clazz, 

const char *message);

利用指定类的消息（由 

message

 指定）构造异常对象并抛出该异常。

参数：

env：JNI 接口指针。

clazz

：

java.lang.Throwable

 的子类。

message

：用于构造

java.lang.Throwable

 对象的消息。

返回值：

成功时返回 0，失败时返回负数。

抛出：

新构造的

 java.lang.Throwable 

对象。

ExceptionOccurred

jthrowable  ExceptionOccurred(JNIEnv *env);

确定是否某个异常正被抛出。在平台相关代码调用 

ExceptionClear()

 或 Java 代码处理该异常前，异常将始终保持抛出状态。

参数：

env：JNI 接口指针。

返回值：

返回正被抛出的异常对象，如果当前无异常被抛出，则返回

NULL

。

ExceptionDescribe

void  ExceptionDescribe(JNIEnv *env);

将异常及堆栈的回溯输出到系统错误报告信道（例如 

stderr

）。该例程可便利调试操作。

参数：

env：JNI 接口指针。

ExceptionClear

void  ExceptionClear(JNIEnv *env);

清除当前抛出的任何异常。如果当前无异常，则此例程不产生任何效果。

参数：

env：JNI 接口指针。

FatalError

void  FatalError(JNIEnv *env, const char *msg);

抛出致命错误并且不希望虚拟机进行修复。该函数无返回值。

参数：

env：JNI 接口指针。

msg

：错误消息。

全局及局部引用

NewGlobalRef

jobject  NewGlobalRef(JNIEnv *env, jobject obj);

创建 

obj

 参数所引用对象的新全局引用。

obj

 参数既可以是全局引用，也可以是局部引用。全局引用通过调用 

DeleteGlobalRef()

 来显式撤消。

参数：

env：JNI 接口指针。

obj

：全局或局部引用。

返回值：

返回全局引用。如果系统内存不足则返回 

NULL

。

DeleteGlobalRef

void  DeleteGlobalRef(JNIEnv *env, jobject globalRef);

删除 

globalRef

 所指向的全局引用。

参数：

env：JNI 接口指针。

globalRef

：全局引用。

DeleteLocalRef

void   DeleteLocalRef(JNIEnv *env, jobject localRef);

删除 

localRef

所指向的局部引用。

参数：

env：JNI 接口指针。

localRef

：局部引用。