《Java 本地接口规范》- JNI 函数(二)
2011-10-19 09:40
447 查看
对象操作
AllocObject
jobjectAllocObject(JNIEnv *env, jclass clazz);分配新 Java 对象而不调用该对象的任何构造函数。返回该对象的引用。
clazz 参数务必不要引用数组类。
参数:
env:JNI 接口指针。clazz:Java 类对象。
返回值:
返回 Java 对象。如果无法构造该对象,则返回NULL。
抛出:
InstantiationException:如果该类为一个接口或抽象类。OutOfMemoryError:如果系统内存不足。
NewObject
NewObjectA
NewObjectV
jobjectNewObject(JNIEnv *env, jclass clazz,jmethodIDmethodID, ...);
jobject NewObjectA(JNIEnv *env,jclass clazz,
jmethodIDmethodID, jvalue *args);
jobject NewObjectV(JNIEnv *env,jclass clazz,
jmethodIDmethodID,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_FALSE。
NULL对象可强制转换为任何类。
IsSameObject
jbooleanIsSameObject(JNIEnv *env, jobject ref1,jobject ref2);
测试两个引用是否引用同一 Java 对象。
参数:
env:JNI 接口指针。ref1:Java 对象。
ref2:Java 对象。
返回值:
如果ref1和
ref2引用同一 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,
jmethodIDmethodID, ...);
NativeTypeCall<type>MethodA
(JNIEnv *env, jobject obj,
jmethodIDmethodID, jvalue *args);
NativeTypeCall<type>MethodV
(JNIEnv *env, jobject obj,
jmethodIDmethodID,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, jmethodIDmethodID, ...);
NativeTypeCallNonvirtual<type>MethodA
(JNIEnv *env, jobject obj,
jclass clazz, jmethodIDmethodID, jvalue *args);
NativeTypeCallNonvirtual<type>MethodV
(JNIEnv *env, jobject obj,
jclass clazz, jmethodIDmethodID,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,
jmethodIDmethodID, ...);
NativeTypeCallStatic<type>MethodA
(JNIEnv *env, jclass clazz,
jmethodIDmethodID, jvalue *args);
NativeTypeCallStatic<type>MethodV
(JNIEnv *env, jclass clazz,
jmethodIDmethodID,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 方法时抛出的异常。相关文章推荐
- 《Java 本地接口规范》- JNI 函数(一)
- 《Java 本地接口规范》- JNI 函数(三)
- 《Java 本地接口规范》-JNI 的类型和数据结构
- JNI(java Native Interface)linux下 java调用本地c函数
- 《Java 本地接口规范》
- Java本地调用JNI使用规范详解
- Java本地调用JNI使用规范详解
- 《Java 本地接口规范》- 简介
- Android: JNI本地函数控制Java端代码
- 详解Java 本地接口 JNI 使用方法
- 《Java 本地接口规范》- 设计概述
- JNI的替代者—使用JNA访问Java外部函数接口
- Android使用JNI(从java调用本地函数)
- 关于Android的JNI开发SO库调java接口函数注意事项
- 《Java 本地接口规范》
- 《Java 本地接口规范》- 调用 API
- Java 本地接口规范
- JNI的又一替代者—使用JNR访问Java外部函数接口(jnr-ffi)
- Java 本地接口 JNI 使用详解
- Java本地调用JNI使用规范详解