《Java 本地接口规范》- JNI 函数(二)

对象操作

 

AllocObject

jobjectAllocObject(JNIEnv *env, jclass clazz);

分配新 Java 对象而不调用该对象的任何构造函数。返回该对象的引用。

clazz 参数务必不要引用数组类。

参数:

env:JNI 接口指针。

clazz:Java 类对象。

返回值:

返回 Java 对象。如果无法构造该对象,则返回NULL

抛出:

InstantiationException:如果该类为一个接口或抽象类。

OutOfMemoryError:如果系统内存不足。

 

NewObject
NewObjectA
NewObjectV

jobjectNewObject(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() 获得,且调用时的方法名必须为 <init>,而返回类型必须为 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

jclassGetObjectClass(JNIEnv *env, jobject obj);

返回对象的类。

参数:

env:JNI 接口指针。

obj:Java 对象(不能为 NULL)。

返回值:

返回 Java 类对象。

 

IsInstanceOf

jbooleanIsInstanceOf(JNIEnv *env, jobject obj,
jclass clazz);

测试对象是否为某个类的实例。

参数:

env:JNI 接口指针。

obj:Java 对象。

clazz:Java 类对象。

返回值:

如果可将 obj 强制转换为 clazz,则返回 JNI_TRUE。否则返回 JNI_FALSENULL 对象可强制转换为任何类。

 

IsSameObject

jbooleanIsSameObject(JNIEnv *env, jobject ref1,
jobject ref2);

测试两个引用是否引用同一 Java 对象。

参数:

env:JNI 接口指针。

ref1:Java 对象。

ref2:Java 对象。

返回值:

如果 ref1ref2 引用同一 Java 对象或均为 NULL,则返回 JNI_TRUE。否则返回 JNI_FALSE


访问对象的域

 

GetFieldID

jfieldIDGetFieldID(JNIEnv *env, jclass clazz,
const char *name, const char *sig);

返回类的实例(非静态)域的域 ID。该域由其名称及签名指定。访问器函数的Get<type>Field 及 Set<type>Field 系列使用域 ID 检索对象域。

GetFieldID() 将未初始化的类初始化。

GetFieldID() 不能用于获取数组的长度域。应使用GetArrayLength()

参数:

env:JNI 接口指针。

clazz:Java 类对象。

name:0 终结的 UTF-8 字符串中的域名。

sig:0 终结的 UTF-8 字符串中的域签名。

返回值:

域 ID。如果操作失败,则返回NULL

抛出:

NoSuchFieldError:如果找不到指定的域。

ExceptionInInitializerError:如果由于异常而导致类初始化程序失败。

OutOfMemoryError:如果系统内存不足。

 

Get<type>Field 例程

NativeTypeGet<type>Field(JNIEnv*env, jobject obj,
jfieldID fieldID);

该访问器例程系列返回对象的实例(非静态)域的值。要访问的域由通过调用GetFieldID() 而得到的域 ID 指定。

下表说明了 Get<type>Field 例程名及结果类型。应将 Get<type>Field 中的 type 替换为域的 Java 类型(或使用表中的某个实际例程名),然后将NativeType 替换为该例程对应的本地类型。

表 4-1 Get<type>Field 访问器例程系列

Get<type>Field 例程名

本地类型

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。

返回值:

域的内容。

 

Set<type>Field 例程

voidSet<type>Field(JNIEnv *env, jobject obj, jfieldID fieldID,
NativeType value);

该访问器例程系列设置对象的实例(非静态)域的值。要访问的域由通过调用SetFieldID() 而得到的域 ID 指定。

下表说明了 Set<type>Field 例程名及结果类型。应将 Set<type>Field 中的 type 替换为域的 Java 类型(或使用表中的某个实际例程名),然后将NativeType 替换为该例程对应的本地类型。

表4-2 Set<type>Field 访问器例程系列

Set<type>Field 例程名

本地类型

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

jmethodIDGetMethodID(JNIEnv *env, jclass clazz,
const char *name, const char *sig);

返回类或接口实例(非静态)方法的方法 ID。方法可在某个 clazz 的超类中定义,也可从 clazz 继承。该方法由其名称和签名决定。

GetMethodID() 可使未初始化的类初始化。

要获得构造函数的方法 ID,应将 <init> 作为方法名,同时将 void (V) 作为返回类型。

参数:

env:JNI 接口指针。

clazz:Java 类对象。

name:0 终结的 UTF-8 字符串中的方法名。

sig:0 终结的 UTF-8 字符串中的方法签名。

返回值:

方法 ID,如果找不到指定的方法,则为 NULL

抛出:

NoSuchMethodError:如果找不到指定方法。

ExceptionInInitializerError:如果由于异常而导致类初始化程序失败。

OutOfMemoryError:如果系统内存不足。

 

Call<type>Method 例程
Call<type>MethodA 例程
Call<type>MethodV 例程

NativeTypeCall<type>Method(JNIEnv*env, jobject obj,
jmethodID methodID, ...);

NativeTypeCall<type>MethodA(JNIEnv *env, jobject obj,
jmethodID methodID, jvalue *args);

NativeTypeCall<type>MethodV(JNIEnv *env, jobject obj,
jmethodID methodID, va_list args);

这三个操作的方法用于从本地方法调用Java 实例方法。它们的差别仅在于向其所调用的方法传递参数时所用的机制。

这三个操作将根据所指定的方法 ID 调用 Java 对象的实例(非静态)方法参数 methodID 必须通过调用 GetMethodID() 来获得。

当这些函数用于调用私有方法和构造函数时,方法 ID 必须从 obj 的真实类派生而来,而不应从其某个超类派生。

Call<type>Method例程

编程人员应将要传给方法的所有参数紧跟着放在 methodID 参数之后。Call<type>Method 例程接受这些参数并将其传给编程人员所要调用的 Java 方法。

Call<type>MethodA 例程

编程人员应将要传给方法的所有参数放在紧跟在 methodID 参数之后的 jvalues 类型数组 args 中。Call<type>MethodA routine 接受这些数组中的参数并将其传给编程人员所要调用的 Java 方法。

Call<type>MethodV例程

编程人员将方法的所有参数放在紧跟着在 methodID 参数之后的 va_list 类型参数变量中。Call<type>MethodV routine 接受这些参数并将其传给编程人员所要调用的 Java 方法。

下表根据结果类型说明了各个方法调用例程。用户应将Call<type>Method 中的 type 替换为所调用方法的 Java 类型(或使用表中的实际方法调用例程名),同时将 NativeType 替换为该例程相应的本地类型。

表 4-3 实例方法调用例程

Call<type>Method 例程名

本地类型

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。

Call<type>Method例程的其它参数:

要传给 Java 方法的参数。

Call<type>MethodA例程的其它参数:

args:参数数组。

Call<type>MethodV例程的其它参数:

args:参数的 va_list。

返回值:

返回调用 Java 方法的结果。

抛出:

执行 Java 方法时抛出的异常。

 

CallNonvirtual<type>Method 例程
CallNonvirtual<type>MethodA 例程
CallNonvirtual<type>MethodV 例程

NativeTypeCallNonvirtual<type>Method(JNIEnv *env, jobject obj,
jclass clazz, jmethodID methodID, ...);

NativeTypeCallNonvirtual<type>MethodA(JNIEnv *env, jobject obj,
jclass clazz, jmethodID methodID, jvalue *args);

NativeTypeCallNonvirtual<type>MethodV(JNIEnv *env, jobject obj,
jclass clazz, jmethodID methodID, va_list args);

这些操作根据指定的类和方法 ID 调用某 Java 对象的实例(非静态)方法。参数 methodID 必须通过调用 clazz 类的GetMethodID() 获得。

CallNonvirtual<type>Method 和 Call<type>Method 例程系列并不相同。Call<type>Method 例程根据对象的类调用方法,而 CallNonvirtual<type>Method 例程则根据获得方法 ID 的(由 clazz 参数指定)类调用方法。方法 ID 必须从对象的真实类或其某个超类获得。

CallNonvirtual<type>Method例程

编程人员应将要传给方法的所有参数紧跟着放在 methodID 参数之后。CallNonvirtual<type>Method routine 接受这些参数并将其传给编程人员所要调用的 Java 方法。

CallNonvirtual<type>MethodA例程

编程人员应将要传给方法的所有参数放在紧跟在 methodID 参数之后的 jvalues 类型数组 args 中。CallNonvirtual<type>MethodAroutine 接受这些数组中的参数并将其传给编程人员所要调用的 Java 方法。

CallNonvirtual<type>MethodV例程

编程人员应将要传给方法的所有参数放在紧跟在 methodID 参数之后的 va_list 类型参数 args 中。CallNonvirtualMethodV routine 接受这些参数并将其传给编程人员所要调用的 Java 方法。

下表根据结果类型说明了各个方法调用例程。用户应将CallNonvirtual<type>Method 中的 type 替换为所调用方法的 Java 类型(或使用表中的实际方法调用例程名),同时将 NativeType 替换为该例程相应的本地类型。

表 4-4 CallNonvirtual<type>Method 例程

CallNonvirtual<type>Method 例程名

本地类型

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。

CallNonvirtual<type>Method例程的其它参数:

要传给 Java 方法的参数。

CallNonvirtual<type>MethodA例程的其它参数:

args:参数数组。

CallNonvirtual<type>MethodV例程的其它参数:

args:参数的 va_list

返回值:

调用 Java 方法的结果。

抛出:

执行 Java 方法时所抛出的异常。


访问静态域

 

GetStaticFieldID

jfieldIDGetStaticFieldID(JNIEnv *env, jclass clazz,
const char *name, const char *sig);

返回类的静态域的域 ID。域由其名称和签名指定。GetStatic<type>Field 和 SetStatic<type>Field 访问器函数系列使用域 ID 检索静态域。

GetStaticFieldID() 将未初始化的类初始化。

参数:

env:JNI 接口指针。

clazz:Java 类对象。

name: 0 终结的 UTF-8 字符串中的静态域名。 

sig:0 终结的 UTF-8 字符串中的域签名。

返回值:

域 ID。如果找不到指定的静态域,则为 NULL

抛出:

NoSuchFieldError:如果找不到指定的静态域。

ExceptionInInitializerError:如果由于异常而导致类初始化程序失败。

OutOfMemoryError:如果系统内存不足。

 

GetStatic<type>Field 例程

NativeTypeGetStatic<type>Field(JNIEnv*env, jclass clazz,
jfieldID fieldID);

该访问器例程系列返回对象的静态域的值。要访问的域由通过调用GetStaticFieldID()而得到的域 ID 指定。

下表说明了 GetStatic<type>Field 例程名及结果类型。应将 GetStatic<type>Field 中的 type 替换为域的 Java 类型(或使用表中的某个实际例程名),然后将NativeType 替换为该例程对应的本地类型。

表 4-5 GetStatic<type>Field 访问器例程系列

GetStatic<type>Field 例程名

本地类型

GetStaticObjectField()

jobject

GetStaticBooleanField()

jboolean

GetStaticByteField()

jbyte

GetStaticCharField()

jchar

GetStaticShortField()

jshort

GetStaticIntField()

jint

GetStaticLongField()

jlong

GetStaticFloatField()

jfloat

GetStaticDoubleField()

jdouble

参数:

env:JNI 接口指针。

clazz:Java 类对象。

fieldID:静态域 ID。

返回值:

静态域的内容。

 

SetStatic<type>Field 例程

voidSetStatic<type>Field(JNIEnv *env, jclass clazz,
jfieldID fieldID, NativeType value);

该访问器例程系列设置对象的静态域的值。要访问的域由通过调用GetStaticFieldID()而得到的域 ID 指定。

下表说明了 SetStatic<type>Field 例程名及结果类型。应将 SetStatic<type>Field 中的 type 替换为域的 Java 类型(或使用表中的某个实际例程名),然后将NativeType 替换为该例程对应的本地类型。

表4-6 SetStatic<type>Field 访问器例程系列

SetStatic<type>Field 例程名

本地类型

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

jmethodIDGetStaticMethodID(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:如果系统内存不足。

 

CallStatic<type>Method 例程
CallStatic<type>MethodA 例程
CallStatic<type>MethodV 例程

NativeTypeCallStatic<type>Method(JNIEnv*env, jclass clazz,
jmethodID methodID, ...);

NativeTypeCallStatic<type>MethodA(JNIEnv *env, jclass clazz,
jmethodID methodID, jvalue *args);

NativeTypeCallStatic<type>MethodV(JNIEnv *env, jclass clazz,
jmethodID methodID, va_list args);

这些操作将根据指定的方法 ID 调用 Java 对象的静态方法。methodID 参数必须通过调用GetStaticMethodID() 得到。

方法 ID 必须从 clazz 派生,而不能从其超类派生。

CallStatic<type>Method例程

编程人员应将要传给方法的所有参数紧跟着放在 methodID 参数之后。 CallStatic<type>Method routine 接受这些参数并将其传给编程人员所要调用的 Java 方法。

CallStatic<type>MethodA 例程

编程人员应将要传给方法的所有参数放在紧跟在 methodID 参数之后的 jvalues 类型数组 args 中。CallStaticMethodA routine 接受这些数组中的参数并将其传给编程人员所要调用的 Java 方法。

CallStatic<type>MethodV例程

编程人员应将要传给方法的所有参数放在紧跟在 methodID 参数之后的 va_list 类型参数 args 中。CallStaticMethodV routine 接受这些参数并将其传给编程人员所要调用的 Java 方法。

下表根据结果类型说明了各个方法调用例程。用户应将CallStatic<type>Method 中的 type 替换为所调用方法的 Java 类型(或使用表中的实际方法调用例程名),同时将 NativeType 替换为该例程相应的本地类型。

表 4-7 CallStatic<type>Method 调用例程

CallStatic<type>Method 例程名

本地类型

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。

CallStatic<type>Method例程的其它参数:

要传给静态方法的参数。

CallStatic<type>MethodA例程的其它参数:

args:参数数组。

CallStatic<type>MethodV例程的其它参数:

args:参数的 va_list

返回值:

返回调用静态 Java 方法的结果。

抛出:

执行 Java 方法时抛出的异常。

上一篇:wordpress自定义post_type,并且自定义固定链接


下一篇:fastdfs的动态扩容及删除节点