android - JNI接口函数 (2)
android - JNI接口函数 (2)
转自：http://blog.csdn.net/ztp800201/article/details/7351957
对象操作
AllocObject
jobject AllocObject(JNIEnv *env, jclass clazz);
分配新 Java 对象而不调用该对象的任何构造函数。返回该对象的引用。
clazz 参数务必不要引用数组类。
参数：
env：JNI 接口指针。
clazz：Java 类对象。
返回值：
返回 Java 对象。如果无法构造该对象，则返回NULL。
抛出：
InstantiationException：如果该类为一个接口或抽象类。
OutOfMemoryError：如果系统内存不足。
NewObject
NewObjectA
NewObjectV
jobject NewObject(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
jclass GetObjectClass(JNIEnv *env, jobject obj);
返回对象的类。
参数：
env：JNI 接口指针。
obj：Java 对象（不能为 NULL）。
返回值：
返回 Java 类对象。
IsInstanceOf
jboolean IsInstanceOf(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
jfieldID GetFieldID(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 例程
NativeType Get<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 例程名 |
本地类型 |
| |
jobject |
| |
jboolean |
| |
jbyte |
| |
jchar |
| |
jshort |
| |
jint |
| |
jlong |
| |
jfloat |
| |
jdouble |
参数：
env：JNI 接口指针。
obj：Java 对象（不能为 NULL）。
fieldID：有效的域 ID。
返回值：
域的内容。
Set<type>Field 例程
void Set<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 例程名 |
本地类型 |
| |
jobject |
| S |
jboolean |
| |
jbyte |
| |
jchar |
| |
jshort |
| |
jint |
| |
jlong |
| |
jfloat |
| |
jdouble |
参数：
env：JNI 接口指针。
obj：Java 对象（不能为 NULL）。
fieldID：有效的域 ID。
value：域的新值。
调用实例方法
GetMethodID
jmethodID GetMethodID(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 例程
NativeType Call<type>Method(JNIEnv*env, jobject obj,
jmethodID methodID, ...);
NativeType Call<type>MethodA(JNIEnv *env, jobject obj,
jmethodID methodID, jvalue *args);
NativeType Call<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 例程名 |
本地类型 |
| |
void |
| |
jobject |
| |
jboolean |
| |
jbyte |
| |
jchar |
| |
jshort |
| |
jint |
| |
jlong |
| |
jfloat |
| |
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 例程
NativeType CallNonvirtual<type>Method(JNIEnv *env, jobject obj,
jclass clazz, jmethodID methodID, ...);
NativeType CallNonvirtual<type>MethodA(JNIEnv *env, jobject obj,
jclass clazz, jmethodID methodID, jvalue *args);
NativeType CallNonvirtual<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 例程名 |
本地类型 |
| |
void |
| |
jobject |
| |
jboolean |
| |
jbyte |
| |
jchar |
| |
jshort |
| |
jint |
| |
jlong |
| |
jfloat |
| |
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
jfieldID GetStaticFieldID(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 例程
NativeType GetStatic<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 例程名 |
本地类型 |
| |
jobject |
| |
jboolean |
| |
jbyte |
| |
jchar |
| |
jshort |
| |
jint |
| |
jlong |
| |
jfloat |
| |
jdouble |
参数：
env：JNI 接口指针。
clazz：Java 类对象。
fieldID：静态域 ID。
返回值：
静态域的内容。
SetStatic<type>Field 例程
void SetStatic<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 例程名 |
本地类型 |
| |
jobject |
| |
jboolean |
| |
jbyte |
| |
jchar |
| |
jshort |
| |
jint |
| |
jlong |
| |
jfloat |
| |
jdouble |
参数：
env：JNI 接口指针。
clazz：Java 类对象。
fieldID：静态域 ID。
value：域的新值。
调用静态方法
GetStaticMethodID
jmethodID GetStaticMethodID(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 例程
NativeType CallStatic<type>Method(JNIEnv*env, jclass clazz,
jmethodID methodID, ...);
NativeType CallStatic<type>MethodA(JNIEnv *env, jclass clazz,
jmethodID methodID, jvalue *args);
NativeType CallStatic<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 例程名 |
本地类型 |
| |
void |
| |
jobject |
| |
jboolean |
| |
jbyte |
| |
jchar |
| |
jshort |
| |
jint |
| |
jlong |
| |
jfloat |
| |
jdouble |
参数：
env：JNI 接口指针。
clazz：Java 类对象。
methodID：静态方法 ID。
CallStatic<type>Method例程的其它参数：
要传给静态方法的参数。
CallStatic<type>MethodA例程的其它参数：
args：参数数组。
CallStatic<type>MethodV例程的其它参数：
args：参数的 va_list。
返回值：
返回调用静态 Java 方法的结果。
抛出：
执行 Java 方法时抛出的异常。