JNI接口函数<一>

来源:互联网 发布:网络证券交易平台规划 编辑:程序博客网 时间:2024/03/29 16:41

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 接口指针。

objjava.lang.Throwable 对象。

返回值:

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

抛出:

java.lang.Throwable 对象 obj

 

ThrowNew

jint  ThrowNew(JNIEnv *env, jclass clazz, 
const char *message);

利用指定类的消息(由 message 指定)构造异常对象并抛出该异常。

参数:

env:JNI 接口指针。

clazzjava.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:局部引用。

0 0