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
jint Throw(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:局部引用。
對象操作
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() 獲得,且調用時的方法名必須為 ,而返回類型必須為 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。
調用實例方法
GetMethodID
jmethodID GetMethodID(JNIEnv *env, jclass clazz, const char *name, const char *sig);
返回類或接口實例(非靜態)方法的方法 ID。方法可在某個 clazz 的超類中定義,也可從 clazz 繼承。該方法由其名稱和簽名決定。
GetMethodID() 可使未初始化的類初始化。
要獲得構造函數的方法 ID,應將 作為方法名,同時將 void (V) 作為返回類型。
參數:
env:JNI 接口指針。
clazz:Java 類對象。
name:0 終結的 UTF-8 字符串中的方法名。
sig:0 終結的 UTF-8 字符串中的方法簽名。
返回值:
方法 ID,如果找不到指定的方法,則為 NULL。
拋出:
NoSuchMethodError:如果找不到指定方法。
ExceptionInInitializerError:如果由於異常而導致類初始化程序失敗。
OutOfMemoryError:如果系統內存不足。
CallMethod 例程
CallMethodA 例程
CallMethodV 例程
NativeType CallMethod(JNIEnv*env, jobject obj, jmethodID methodID, ...);
NativeType CallMethodA(JNIEnv *env, jobject obj,jmethodID methodID, jvalue *args);
NativeType CallMethodV(JNIEnv *env, jobject obj, jmethodID methodID, va_list args);
這三個操作的方法用於從本地方法調用Java 實例方法。
它們的差別僅在於向其所調用的方法傳遞參數時所用的機制。
這三個操作將根據所指定的方法 ID 調用 Java 對象的實例(非靜態)方法。參數 methodID 必須通過調用 GetMethodID() 來獲得。
當這些函數用於調用私有方法和構造函數時,方法 ID 必須從 obj 的真實類派生而來,而不應從其某個超類派生。
CallMethod例程
編程人員應將要
傳給方法的所有參數緊跟着放在 methodID 參數之后。CallMethod 例程接受這些參數並將其傳給編程人員所要調用的 Java 方法。
CallMethodA 例程
編 程人員應將要
傳給方法的所有參數放在緊跟在 methodID 參數之后的 jvalues 類型數組 args 中。 CallMethodA routine 接受這些數組中的參數並將其傳給編程人員所要調用的 Java 方 法。
CallMethodV例程
編程人員將
方法的所有參數放在緊跟着在 methodID 參數之后的 va_list 類型參數變量中。CallMethodV routine 接受這些參數並將其傳給編程人員所要調用的 Java 方法。
下表根據結果類型說明了各個方法調用例程。用戶應將CallMethod 中的 type 替換為所調用方法的 Java 類型(或使用表中的實際方法調用例程名),同時將 NativeType 替換為該例程相應的本地類型。
表 4-3 實例方法調用例程
CallMethod 例程名 本地類型
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。
CallMethod例程的其它參數:
要傳給 Java 方法的參數。
CallMethodA例程的其它參數:
args:參數數組。
CallMethodV例程的其它參數:
args:參數的 va_list。
返回值:
返回調用 Java 方法的結果。
拋出:
執行 Java 方法時拋出的異常。
字符串操作
NewString
jstring NewString(JNIEnv *env, const jchar *unicodeChars, jsize len);
利用 Unicode 字符數組構造新的 java.lang.String 對象。
參數:
env:JNI 接口指針。
unicodeChars:指向 Unicode 字符串的指針。
len:Unicode 字符串的長度。
返回值:
Java 字符串對象。如果無法構造該字符串,則為 NULL。
拋出:
OutOfMemoryError:如果系統內存不足。
GetStringLength
jsize GetStringLength(JNIEnv *env, jstring string);
返回 Java 字符串的長度(Unicode 字符數)。
參數:
env:JNI 接口指針。
string:Java 字符串對象。
返回值:
Java 字符串的長度。
GetStringChars
const jchar * GetStringChars(JNIEnv *env, jstring string, jboolean *isCopy);
返回指向字符串的 Unicode 字符數組的指針。該指針在調用 ReleaseStringchars() 前一直有效。
如果 isCopy 非空,則在復制完成后將 *isCopy 設為 JNI_TRUE。如果沒有復制,則設為JNI_FALSE。
參數:
env:JNI 接口指針。
string:Java 字符串對象。
isCopy:指向布爾值的指針。
返回值:
指向 Unicode 字符串的指針,如果操作失敗,則返回NULL。
ReleaseStringChars
void ReleaseStringChars(JNIEnv *env, jstring string, const jchar *chars);
通知虛擬機平台相關代碼無需再訪問 chars。參數 chars 是一個指針,可通過 GetStringChars() 從 string 獲得。
參數:
env:JNI 接口指針。
string:Java 字符串對象。
chars:指向 Unicode 字符串的指針。
NewStringUTF
jstring NewStringUTF(JNIEnv *env, const char *bytes);
利用 UTF-8 字符數組構造新 java.lang.String 對象。
參數:
env:JNI 接口指針。如果無法構造該字符串,則為 NULL。
bytes:指向 UTF-8 字符串的指針。
返回值:
Java 字符串對象。如果無法構造該字符串,則為 NULL。
拋出:
OutOfMemoryError:如果系統內存不足。
GetStringUTFLength
jsize GetStringUTFLength(JNIEnv *env, jstring string);
以字節為單位返回字符串的 UTF-8 長度。
參數:
env:JNI 接口指針。
string:Java 字符串對象。
返回值:
返回字符串的 UTF-8 長度。
GetStringUTFChars
const char* GetStringUTFChars(JNIEnv *env, jstring string, jboolean *isCopy);
返回指向字符串的 UTF-8 字符數組的指針。該數組在被ReleaseStringUTFChars() 釋放前將一直有效。
如果 isCopy 不是 NULL,*isCopy 在復制完成后即被設為 JNI_TRUE。如果未復制,則設為 JNI_FALSE。
參數:
env:JNI 接口指針。
string:Java 字符串對象。
isCopy:指向布爾值的指針。
返回值:
指向 UTF-8 字符串的指針。如果操作失敗,則為 NULL。
ReleaseStringUTFChars
void ReleaseStringUTFChars(JNIEnv *env, jstring string, const char *utf);
通知虛擬機平台相關代碼無需再訪問 utf。utf 參數是一個指針,可利用 GetStringUTFChars() 從 string 獲得。
參數:
env:JNI 接口指針。
string:Java 字符串對象。
utf:指向 UTF-8 字符串的指針。
數組操作
GetArrayLength
jsize GetArrayLength(JNIEnv *env, jarray array);
返回數組中的元素數。
參數:
env:JNI 接口指針。
array:Java 數組對象。
返回值:
數組的長度。
NewObjectArray
jarray NewObjectArray(JNIEnv *env, jsize length, jclass elementClass, jobject initialElement);
構造新的數組,它將保存類 elementClass 中的對象。所有元素初始值均設為 initialElement。
參數:
env:JNI 接口指針。
length:數組大小。
elementClass:數組元素類。
initialElement:初始值。
返回值:
Java 數組對象。如果無法構造數組,則為 NULL。
拋出:
OutOfMemoryError:如果系統內存不足。
GetObjectArrayElement
jobject GetObjectArrayElement(JNIEnv *env, jobjectArray array, jsize index);
返回 Object 數組的元素。
參數:
env:JNI 接口指針。
array:Java 數組。
index:數組下標。
返回值:
Java 對象。
拋出:
ArrayIndexOutOfBoundsException:如果 index 不是數組中的有效下標。
SetObjectArrayElement
void SetObjectArrayElement(JNIEnv *env, jobjectArray array, jsize index, jobject value);
設置 Object 數組的元素。
參數:
env:JNI 接口指針。
array:Java 數組。
index:數組下標。
value:新值。
拋出:
ArrayIndexOutOfBoundsException:如果 index 不是數組中的有效下標。
ArrayStoreException:如果 value 的類不是數組元素類的子類。
NewArray 例程
ArrayType NewArray(JNIEnv*env, jsize length);
用 於構造新基本類型數組對象的一系列操作。表 4-8 說明了特定的基本類型數組構造函數。用戶應把 NewArray 替換為某個實際的基本類型數組構造函數例程名(見下表),然后將 ArrayType替換 為該例程相應的數組類型。
表 4-8 NewArray 數組構造函數系列
NewArray 例程 數組類型
NewBooleanArray() jbooleanArray
NewByteArray() jbyteArray
NewCharArray() jcharArray
NewShortArray() jshortArray
NewIntArray() jintArray
NewLongArray() jlongArray
NewFloatArray() jfloatArray
NewDoubleArray() jdoubleArray
參數:
env:JNI 接口指針。
length:數組長度。
返回值:
Java 數組。如果無法構造該數組,則為 NULL。
GetArrayElements 例程
NativeType *GetArrayElements(JNIEnv *env, ArrayType array, jboolean*isCopy);
一 組返回基本類型數組體的函數。結果在調用相應的 ReleaseArrayElements()函數前將一直 有效。由於返回的數組可能是 Java 數組的副本,因此對返回數組的更改不必在基本類型數組中反映出來,直到調用了 ReleaseArrayElements()。
如果 isCopy 不是 NULL,*isCopy 在復制完成后即被設為 JNI_TRUE。如果未復制,則設為 JNI_FALSE。
下表說明了特定的基本類型數組元素訪問器。應進行下列替換;
將 GetArrayElements 替換為表中某個實際的基本類型元素訪問器例程名。
將 ArrayType 替換為對應的數組類型。
將 NativeType 替換為該例程對應的本地類型。
不管布爾數組在 Java 虛擬機中如何表示,GetBooleanArrayElements() 將始終返回一個 jbooleans 類型的指針,其中每一字節代表一個元素(開包表示)。內存中將確保所有其它類型的數組為連續的。
表4-9 GetArrayElements 訪問器例程系列
GetArrayElements 例程 數組類型 本地類型
GetBooleanArrayElements() jbooleanArray jboolean
GetByteArrayElements() jbyteArray jbyte
GetCharArrayElements() jcharArray jchar
GetShortArrayElements() jshortArray jshort
GetIntArrayElements() jintArray jint
GetLongArrayElements() jlongArray jlong
GetFloatArrayElements() jfloatArray jfloat
GetDoubleArrayElements() jdoubleArray jdouble
參數:
env:JNI 接口指針。
array:Java 字符串對象。
isCopy:指向布爾值的指針。
返回值:
返回指向數組元素的指針,如果操作失敗,則為 NULL。
ReleaseArrayElements 例程
void ReleaseArrayElements(JNIEnv *env, ArrayType array, NativeType *elems, jintmode);
通 知虛擬機平台相關代碼無需再訪問 elems 的一組函數。elems 參數是一個通過使用對應的 GetArrayElements() 函數由 array 導出的指針。必要時,該函數將把 對 elems 的修改復制回基本類型數組。
mode參數將提供有關如何釋放數組緩沖區的信息。如果elems 不是 array 中數組元素的副本,mode將無效。否則,mode 將具有下表所述的功能:
表 4-10 基本類型數組釋放模式
模式 動作
0 復制回內容並釋放 elems 緩沖區
JNI_COMMIT 復制回內容但不釋放 elems 緩沖區
JNI_ABORT 釋放緩沖區但不復制回變化
多數情況下,編程人員將把“0”傳給 mode 參數以確保固定的數組和復制的數組保持一致。其它選項可以使編程人員進一步控制內存管理,但使用時務必慎重。
下表說明了構成基本類型數組撤消程序系列的特定例程。應進行如下替換;
將 ReleaseArrayElements 替換為表 4-11 中的某個實際基本類型數組撤消程序例程名。
將 ArrayType 替換為對應的數組類型。
將 NativeType 替換為該例程對應的本地類型。
表 4-11 ReleaseArrayElements 數組例程系列
ReleaseArrayElements 例程 數組類型 本地類型
ReleaseBooleanArrayElements() jbooleanArray jboolean
ReleaseByteArrayElements() jbyteArray jbyte
ReleaseCharArrayElements() jcharArray jchar
ReleaseShortArrayElements() jshortArray jshort
ReleaseIntArrayElements() jintArray jint
ReleaseLongArrayElements() jlongArray jlong
ReleaseFloatArrayElements() jfloatArray jfloat
ReleaseDoubleArrayElements() jdoubleArray jdouble
參數:
env:JNI 接口指針。
array:Java 數組對象。
elems:指向數組元素的指針。
mode:釋放模式。
GetArrayRegion 例程
void GetArrayRegion(JNIEnv *env, ArrayType array, jsize start, jsize len, NativeType *buf);
將基本類型數組某一區域復制到緩沖區中的一組函數。
下表說明了特定的基本類型數組元素訪問器。應進行如下替換:
將 GetArrayRegion 替換為表 4-12 中的某個實際基本類型元素訪問器例程名。
將 ArrayType 替換為對應的數組類型。
將 NativeType 替換為該例程對應的本地類型。
表 4-12 GetArrayRegion 數組訪問器例程系列
GetArrayRegion 例程 數組類型 本地類型
GetBooleanArrayRegion() jbooleanArray jboolean
GetByteArrayRegion() jbyteArray jbyte
GetCharArrayRegion() jcharArray jchar
GetShortArrayRegion() jshortArray jhort
GetIntArrayRegion() jintArray jint
GetLongArrayRegion() jlongArray jlong
GetFloatArrayRegion() jfloatArray jloat
GetDoubleArrayRegion() jdoubleArray jdouble
參數:
env:JNI 接口指針。
array:Java 指針。
start:起始下標。
len:要復制的元素數。
buf:目的緩沖區。
拋出:
ArrayIndexOutOfBoundsException:如果區域中的某個下標無效。
SetArrayRegion 例程
void SetArrayRegion(JNIEnv *env, ArrayType array, jsize start, jsize len, NativeType *buf);
將基本類型數組的某一區域從緩沖區中復制回來的一組函數。
下表說明了特定的基本類型數組元素訪問器。應進行如下替換:
將 SetArrayRegion 替換為表中的實際基本類型元素訪問器例程名。
將 ArrayType 替換為對應的數組類型。
將 NativeType 替換為該例程對應的本地類型。
表 4-13 SetArrayRegion 數組訪問器例程系列
SetArrayRegion 例程 數組類型 本地類型
SetBooleanArrayRegion() jbooleanArray jboolean
SetByteArrayRegion() jbyteArray jbyte
SetCharArrayRegion() jcharArray jchar
SetShortArrayRegion() jshortArray jshort
SetIntArrayRegion() jintArray jint
SetLongArrayRegion() jlongArray jlong
SetFloatArrayRegion() jfloatArray jfloat
SetDoubleArrayRegion() jdoubleArray jdouble
參數:
env:JNI 接口指針。
array: Java 數組。
start:起始下標。
len:要復制的元素數。
buf:源緩沖區。
拋出:
ArrayIndexOutOfBoundsException:如果區域中的某個下標無效。
注冊本地方法
RegisterNatives
jint RegisterNatives(JNIEnv *env, jclass clazz, const JNINativeMethod *methods, jint nMethods);
向 clazz 參 數指定的類注冊本地方法。methods 參數將指定 JNINativeMethod 結構的數組,其中包含本地方法的名稱、簽名和函數指針。 nMethods 參數將指定數組中的本地方法數。JNINativeMethod 結構定義如下所示:
typedef struct {
char *name;
char *signature;
void *fnPtr;
} JNINativeMethod;
函數指針通常必須有下列簽名:
ReturnType (*fnPtr)(JNIEnv *env, jobject objectOrClass, ...);
參數:
env:JNI 接口指針。
clazz:Java 類對象。
methods:類中的本地方法。
nMethods:類中的本地方法數。
返回值:
成功時返回 "0";失敗時返回負數。
拋出:
NoSuchMethodError:如果找不到指定的方法或方法不是本地方法。
UnregisterNatives
jint UnregisterNatives(JNIEnv *env, jclass clazz);
取消注冊類的本地方法。類將返回到鏈接或注冊了本地方法函數前的狀態。
該函數不應在常規平台相關代碼中使用。相反,它可以為某些程序提供一種重新加載和重新鏈接本地庫的途徑。
參數:
env:JNI 接口指針。
clazz:Java 類對象。
返回值:
成功時返回“0”;失敗時返回負數。
訪問對象的域
GetFieldID
jfieldID GetFieldID(JNIEnv *env, jclass clazz, const char *name, const char *sig);
返回類的實例(非靜態)域的域 ID。該域由其名稱及簽名指定。訪問器函數的GetField 及 SetField 系列使用域 ID 檢索對象域。
GetFieldID() 將未初始化的類初始化。
GetFieldID() 不能用於獲取數組的長度域。應使用GetArrayLength()。
參數:
env:JNI 接口指針。
clazz:Java 類對象。
name:0 終結的 UTF-8 字符串中的域名。
sig:0 終結的 UTF-8 字符串中的域簽名。
返回值:
域 ID。如果操作失敗,則返回NULL。
拋出:
NoSuchFieldError:如果找不到指定的域。
ExceptionInInitializerError:如果由於異常而導致類初始化程序失敗。
OutOfMemoryError:如果系統內存不足。
GetField 例程
NativeType GetField(JNIEnv*env, jobject obj, jfieldID fieldID);
該訪問器例程系列返回對象的實例(非靜態)域的值。要訪問的域由通過調用GetFieldID() 而得到的域 ID 指定。
下 表說明了 GetField 例程名及結果類型。應將 GetField 中的 type 替換為域 的 Java 類型(或使用表中的某個實際例程名),然后將NativeType 替換為該例程對應的本地類型。
表 4-1 GetField 訪問器例程系列
GetField 例程名 本地類型
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。
返回值:
域的內容。
SetField 例程
void SetField(JNIEnv *env, jobject obj, jfieldID fieldID, NativeType value);
該訪問器例程系列設置對象的實例(非靜態)域的值。要訪問的域由通過調用SetFieldID() 而得到的域 ID 指定。
下 表說明了 SetField 例程名及結果類型。應將 SetField 中的 type 替換為域 的 Java 類型(或使用表中的某個實際例程名),然后將NativeType 替換為該例程對應的本地類型。
表4-2 SetField 訪問器例程系列
SetField 例程名 本地類型
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:域的新值。