閱讀664 返回首頁    go iPhone_iPad_Mac_apple

《Java 本地接口規範》- JNI 函數（三）

字符串操作

 

NewString

jstringNewString(JNIEnv *env, const jchar *unicodeChars,
jsize len);

利用 Unicode 字符數組構造新的 java.lang.String 對象。

參數：

env：JNI 接口指針。

unicodeChars：指向 Unicode 字符串的指針。

len：Unicode 字符串的長度。

返回值：

Java 字符串對象。如果無法構造該字符串，則為 NULL。

拋出：

OutOfMemoryError：如果係統內存不足。

 

GetStringLength

jsizeGetStringLength(JNIEnv *env, jstring string);

返回 Java 字符串的長度（Unicode 字符數）。

參數：

env：JNI 接口指針。

string：Java 字符串對象。

返回值：

Java 字符串的長度。

 

GetStringChars

constjchar * GetStringChars(JNIEnv *env, jstring string,
jboolean *isCopy);

返回指向字符串的 Unicode 字符數組的指針。該指針在調用 ReleaseStringchars() 前一直有效。

如果 isCopy 非空，則在複製完成後將 *isCopy 設為 JNI_TRUE。如果沒有複製，則設為JNI_FALSE。

參數：

env：JNI 接口指針。

string：Java 字符串對象。

isCopy：指向布爾值的指針。

返回值：

指向 Unicode 字符串的指針，如果操作失敗，則返回NULL。

 

ReleaseStringChars

voidReleaseStringChars(JNIEnv *env, jstring string,
const jchar *chars);

通知虛擬機平台相關代碼無需再訪問 chars。參數 chars 是一個指針，可通過 GetStringChars() 從 string 獲得。

參數：

env：JNI 接口指針。

string：Java 字符串對象。

chars：指向 Unicode 字符串的指針。

 

NewStringUTF

jstringNewStringUTF(JNIEnv *env, const char *bytes);

利用 UTF-8 字符數組構造新 java.lang.String 對象。

參數：

env：JNI 接口指針。如果無法構造該字符串，則為 NULL。

bytes：指向 UTF-8 字符串的指針。

返回值：

Java 字符串對象。如果無法構造該字符串，則為 NULL。

拋出：

OutOfMemoryError：如果係統內存不足。

 

GetStringUTFLength

jsizeGetStringUTFLength(JNIEnv *env, jstring string);

以字節為單位返回字符串的 UTF-8 長度。

參數：

env：JNI 接口指針。

string：Java 字符串對象。

返回值：

返回字符串的 UTF-8 長度。

 

GetStringUTFChars

constchar* 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

voidReleaseStringUTFChars(JNIEnv *env, jstring string,
const char *utf);

通知虛擬機平台相關代碼無需再訪問 utf。utf 參數是一個指針，可利用 GetStringUTFChars() 從 string 獲得。

參數：

env：JNI 接口指針。

string：Java 字符串對象。

utf：指向 UTF-8 字符串的指針。

數組操作

 

GetArrayLength

jsizeGetArrayLength(JNIEnv *env, jarray array);

返回數組中的元素數。

參數：

env：JNI 接口指針。

array：Java 數組對象。

返回值：

數組的長度。

 

NewObjectArray

jarrayNewObjectArray(JNIEnv *env, jsize length,
jclass elementClass, jobject initialElement);

構造新的數組，它將保存類 elementClass 中的對象。所有元素初始值均設為 initialElement。

參數：

env：JNI 接口指針。

length：數組大小。

elementClass：數組元素類。

initialElement：初始值。

返回值：

Java 數組對象。如果無法構造數組，則為 NULL。

拋出：

OutOfMemoryError：如果係統內存不足。

 

GetObjectArrayElement

jobjectGetObjectArrayElement(JNIEnv *env,
jobjectArray array, jsize index);

返回 Object 數組的元素。

參數：

env：JNI 接口指針。

array：Java 數組。

index：數組下標。

返回值：

Java 對象。

拋出：

ArrayIndexOutOfBoundsException：如果 index 不是數組中的有效下標。

 

SetObjectArrayElement

voidSetObjectArrayElement(JNIEnv *env, jobjectArray array,
jsize index, jobject value);

設置 Object 數組的元素。

參數：

env：JNI 接口指針。

array：Java 數組。

index：數組下標。

value：新值。

拋出：

ArrayIndexOutOfBoundsException：如果 index 不是數組中的有效下標。

ArrayStoreException：如果 value 的類不是數組元素類的子類。

 

New<PrimitiveType>Array 例程

ArrayTypeNew<PrimitiveType>Array(JNIEnv*env, jsize length);

用於構造新基本類型數組對象的一係列操作。表 4-8 說明了特定的基本類型數組構造函數。用戶應把New<PrimitiveType>Array 替換為某個實際的基本類型數組構造函數例程名（見下表），然後將 ArrayType 替換為該例程相應的數組類型。

表 4-8 New<PrimitiveType>Array 數組構造函數係列

New<PrimitiveType>Array 例程

數組類型

NewBooleanArray()

jbooleanArray

NewByteArray()

jbyteArray

NewCharArray()

jcharArray

NewShortArray()

jshortArray

NewIntArray()

jintArray

NewLongArray()

jlongArray

NewFloatArray()

jfloatArray

NewDoubleArray()

jdoubleArray

參數：

env：JNI 接口指針。

length：數組長度。

返回值：

Java 數組。如果無法構造該數組，則為 NULL。

 

Get<PrimitiveType>ArrayElements 例程

NativeType *Get<PrimitiveType>ArrayElements(JNIEnv *env,
ArrayType array, jboolean*isCopy);

一組返回基本類型數組體的函數。結果在調用相應的 Release<PrimitiveType>ArrayElements()函數前將一直有效。由於返回的數組可能是 Java 數組的副本，因此對返回數組的更改不必在基本類型數組中反映出來，直到調用了Release<PrimitiveType>ArrayElements()。

如果 isCopy 不是 NULL，*isCopy 在複製完成後即被設為 JNI_TRUE。如果未複製，則設為 JNI_FALSE。

下表說明了特定的基本類型數組元素訪問器。應進行下列替換；

  • 將 Get<PrimitiveType>ArrayElements 替換為表中某個實際的基本類型元素訪問器例程名。
  • 將 ArrayType 替換為對應的數組類型。
  • 將 NativeType 替換為該例程對應的本地類型。

不管布爾數組在 Java 虛擬機中如何表示，GetBooleanArrayElements() 將始終返回一個 jbooleans 類型的指針，其中每一字節代表一個元素（開包表示）。內存中將確保所有其它類型的數組為連續的。

表4-9 Get<PrimitiveType>ArrayElements 訪問器例程係列

Get<PrimitiveType>ArrayElements 例程

數組類型

本地類型

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。

 

Release<PrimitiveType>ArrayElements 例程

voidRelease<PrimitiveType>ArrayElements(JNIEnv *env,
ArrayType array, NativeType *elems, jintmode);

通知虛擬機平台相關代碼無需再訪問 elems 的一組函數。elems 參數是一個通過使用對應的Get<PrimitiveType>ArrayElements() 函數由 array 導出的指針。必要時，該函數將把對 elems 的修改複製回基本類型數組。

mode參數將提供有關如何釋放數組緩衝區的信息。如果elems 不是 array 中數組元素的副本，mode將無效。否則，mode 將具有下表所述的功能：

表 4-10 基本類型數組釋放模式

模式

動作

0

複製回內容並釋放 elems 緩衝區

JNI_COMMIT

複製回內容但不釋放 elems 緩衝區

JNI_ABORT

釋放緩衝區但不複製回變化

多數情況下，編程人員將把“0”傳給 mode 參數以確保固定的數組和複製的數組保持一致。其它選項可以使編程人員進一步控製內存管理，但使用時務必慎重。

下表說明了構成基本類型數組撤消程序係列的特定例程。應進行如下替換；

  • 將 Release<PrimitiveType>ArrayElements 替換為表 4-11 中的某個實際基本類型數組撤消程序例程名。 
  • 將 ArrayType 替換為對應的數組類型。
  • 將 NativeType 替換為該例程對應的本地類型。

表 4-11 Release<PrimitiveType>ArrayElements 數組例程係列

Release<PrimitiveType>ArrayElements 例程

數組類型

本地類型

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：釋放模式。

 

Get<PrimitiveType>ArrayRegion 例程

voidGet<PrimitiveType>ArrayRegion(JNIEnv *env, ArrayType array,
jsize start, jsize len, NativeType *buf);

將基本類型數組某一區域複製到緩衝區中的一組函數。

下表說明了特定的基本類型數組元素訪問器。應進行如下替換：

  • 將 Get<PrimitiveType>ArrayRegion 替換為表 4-12 中的某個實際基本類型元素訪問器例程名。
  • 將 ArrayType 替換為對應的數組類型。
  • 將 NativeType 替換為該例程對應的本地類型。

表 4-12 Get<PrimitiveType>ArrayRegion 數組訪問器例程係列

Get<PrimitiveType>ArrayRegion 例程

數組類型

本地類型

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：如果區域中的某個下標無效。

 

Set<PrimitiveType>ArrayRegion 例程

voidSet<PrimitiveType>ArrayRegion(JNIEnv *env, ArrayType array,
jsize start, jsize len, NativeType *buf);

將基本類型數組的某一區域從緩衝區中複製回來的一組函數。

下表說明了特定的基本類型數組元素訪問器。應進行如下替換：

  • 將 Set<PrimitiveType>ArrayRegion 替換為表中的實際基本類型元素訪問器例程名。
  • 將 ArrayType 替換為對應的數組類型。
  • 將 NativeType 替換為該例程對應的本地類型。

表 4-13 Set<PrimitiveType>ArrayRegion 數組訪問器例程係列

Set<PrimitiveType>ArrayRegion 例程

數組類型

本地類型

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

jintRegisterNatives(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

jintUnregisterNatives(JNIEnv *env, jclass clazz);

取消注冊類的本地方法。類將返回到鏈接或注冊了本地方法函數前的狀態。

該函數不應在常規平台相關代碼中使用。相反，它可以為某些程序提供一種重新加載和重新鏈接本地庫的途徑。

參數：

env：JNI 接口指針。

clazz：Java 類對象。

返回值：

成功時返回“0”；失敗時返回負數。

監視程序操作

 

MonitorEnter

jintMonitorEnter(JNIEnv *env, jobject obj);

進入與 obj 所引用的基本 Java 對象相關聯的監視程序。

每個 Java 對象都有一個相關聯的監視程序。如果當前線程已經擁有與obj 相關聯的監視程序，它將使指示該線程進入監視程序次數的監視程序計數器增 1。如果與 obj 相關聯的監視程序並非由某個線程所擁有，則當前線程將變為該監視程序的所有者，同時將該監視程序的計數器設置為 1。如果另一個線程已擁有與 obj 關聯的監視程序，則在監視程序被釋放前當前線程將處於等待狀態。監視程序被釋放後，當前線程將嚐試重新獲得所有權。

參數：

env：JNI 接口指針。

obj：常規 Java 對象或類對象。

返回值：

成功時返回“0”；失敗時返回負數。

 

MonitorExit

jintMonitorExit(JNIEnv *env, jobject obj);

當前線程必須是與 obj 所引用的基本 Java 對象相關聯的監視程序的所有者。線程將使指示進入監視程序次數的計數器減 1。如果計數器的值變為 0，當前線程釋放監視程序。

參數：

env：JNI 接口指針。

obj：常規 Java 對象或類對象。

返回值：

成功時返回“0”；失敗時返回負數。

Java 虛擬機接口

 

GetJavaVM

jintGetJavaVM(JNIEnv *env, JavaVM **vm);

返回與當前線程相關聯的 Java 虛擬機接口（用於調用 API 中）。結果將放在第二個參數 vm 所指向的位置。

參數：

env：JNI 接口指針。

vm：指向放置結果的位置的指針。

返回值：

成功時返回“0”；失敗時返回負數。

最後更新：2017-04-02 06:52:01

  上一篇：go API Demos 2.3 學習筆記 (15)-- Views-&gt;Radio Group
  下一篇：go Android超時機製