160
阿裏雲 技術社區[雲棲]
《Java 本地接口規範》- JNI 函數（一）
JNI 函數
本章為 JNI 函數提供參考信息。其中列出了全部 JNI 函數，同時也給出了 JNI 函數表的準確布局。
注意：“必須”一詞用於約束 JNI 編程人員。例如，當說明某個 JNI 函數必須接收非空對象時，就應確保不要向該 JNI 函數傳遞 NULL。這時，JNI 實現將無需在該 JNI 函數中執行 NULL 指針檢查。
本章的部分資料改編自 Netscape 的 JRI 文檔。
該參考資料按用法對函數進行組織。參考部分按下列函數區域進行組織：
接口函數表
每個函數均可通過 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
jintGetVersion(JNIEnv *env);
返回本地方法接口的版本。
參數
env：JNI 接口指針。
返回值：
高 16 位返回主版本號，低 16 位返回次版本號。
在 JDK1.1 中，GetVersion() 返回 0x00010001。
類操作
DefineClass
jclassDefineClass(JNIEnv *env, jobject loader,
const jbyte *buf, jsize bufLen);
從原始類數據的緩衝區中加載類。
參數：
env：JNI 接口指針。
loader：分派給所定義的類的類加載器。
buf：包含 .class 文件數據的緩衝區。
bufLen：緩衝區長度。
返回值：
返回 Java 類對象。如果出錯則返回NULL。
拋出：
ClassFormatError：如果類數據指定的類無效。
ClassCircularityError：如果類或接口是自身的超類或超接口。
OutOfMemoryError：如果係統內存不足。
FindClass
jclassFindClass(JNIEnv *env, const char *name);
該函數用於加載本地定義的類。它將搜索由CLASSPATH 環境變量為具有指定名稱的類所指定的目錄和 zip 文件。
參數：
env：JNI 接口指針。
name：類全名（即包名後跟類名，之間由“/”分隔）。如果該名稱以“[”（數組簽名字符）打頭，則返回一個數組類。
返回值：
返回類對象全名。如果找不到該類，則返回 NULL。
拋出：
ClassFormatError：如果類數據指定的類無效。
ClassCircularityError：如果類或接口是自身的超類或超接口。
NoClassDefFoundError：如果找不到所請求的類或接口的定義。
OutOfMemoryError：如果係統內存不足。
GetSuperclass
jclassGetSuperclass(JNIEnv *env, jclass clazz);
如果 clazz 代表類而非類 object，則該函數返回由
clazz 所指定的類的超類。
如果 clazz 指定類 object 或代表某個接口，則該函數返回NULL。
參數：
env：JNI 接口指針。
clazz：Java 類對象。
返回值：
由 clazz 所代表的類的超類或 NULL。
IsAssignableFrom
jbooleanIsAssignableFrom(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 接口指針。
obj：java.lang.Throwable 對象。
返回值：
成功時返回 0，失敗時返回負數。
拋出：
java.lang.Throwable 對象 obj。
ThrowNew
jintThrowNew(JNIEnv *env, jclass clazz,
const char *message);
利用指定類的消息（由 message 指定）構造異常對象並拋出該異常。
參數：
env：JNI 接口指針。
clazz：java.lang.Throwable 的子類。
message：用於構造java.lang.Throwable 對象的消息。
返回值：
成功時返回 0，失敗時返回負數。
拋出：
新構造的 java.lang.Throwable 對象。
ExceptionOccurred
jthrowableExceptionOccurred(JNIEnv *env);
確定是否某個異常正被拋出。在平台相關代碼調用 ExceptionClear() 或 Java 代碼處理該異常前，異常將始終保持拋出狀態。
參數：
env：JNI 接口指針。
返回值：
返回正被拋出的異常對象，如果當前無異常被拋出，則返回NULL。
ExceptionDescribe
voidExceptionDescribe(JNIEnv *env);
將異常及堆棧的回溯輸出到係統錯誤報告信道（例如 stderr）。該例程可便利調試操作。
參數：
env：JNI 接口指針。
ExceptionClear
voidExceptionClear(JNIEnv *env);
清除當前拋出的任何異常。如果當前無異常，則此例程不產生任何效果。
參數：
env：JNI 接口指針。
FatalError
voidFatalError(JNIEnv *env, const char *msg);
拋出致命錯誤並且不希望虛擬機進行修複。該函數無返回值。
參數：
env：JNI 接口指針。
msg：錯誤消息。
全局及局部引用
NewGlobalRef
jobjectNewGlobalRef(JNIEnv *env, jobject obj);
創建 obj 參數所引用對象的新全局引用。obj 參數既可以是全局引用，也可以是局部引用。全局引用通過調用
DeleteGlobalRef() 來顯式撤消。
參數：
env：JNI 接口指針。
obj：全局或局部引用。
返回值：
返回全局引用。如果係統內存不足則返回 NULL。
DeleteGlobalRef
voidDeleteGlobalRef(JNIEnv *env, jobject globalRef);
刪除 globalRef 所指向的全局引用。
參數：
env：JNI 接口指針。
globalRef：全局引用。
DeleteLocalRef
voidDeleteLocalRef(JNIEnv *env, jobject localRef);
刪除 localRef所指向的局部引用。
參數：
env：JNI 接口指針。
localRef：局部引用。
最後更新：2017-04-02 06:52:01