android JNI編程 一些技巧
本篇將介紹在JNI編程中如何傳遞參數和返回值。
首先要強調的是，native方法不但可以傳遞Java的基本類型做參數，還可以傳遞更復雜的類型，比如String，數組，甚至自定義的類。這一切都可以在jni.h中找到答案。
1. Java基本類型的傳遞
用過Java的人都知道，Java中的基本類型包括boolean，byte，char，short，int，long，float，double 這樣幾種，如果你用這幾種類型做native方法的參數，當你通過javah -jni生成.h文件的時候，只要看一下生成的.h文件，就會一清二楚，這些類型分別對應的類型是 jboolean，jbyte，jchar，jshort，jint，jlong，jfloat，jdouble 。這幾種類型幾乎都可以當成對應的C++類型來用，所以沒什么好說的。
2. String參數的傳遞
Java的String和C++的string是不能對等起來的，所以處理起來比較麻煩。先看一個例子，
class Prompt {
// native method that prints a prompt and reads a line
private native String getLine(String prompt);
public static void main(String args[]) {
Prompt p = new Prompt();
String input = p.getLine("Type a line: ");
System.out.println("User typed: " + input);
}
static {
System.loadLibrary("Prompt");
}
}
在這個例子中，我們要實現一個native方法
String getLine(String prompt);
讀入一個String參數，返回一個String值。
通過執行javah -jni得到的頭文件是這樣的
#include <jni.h>
#ifndef _Included_Prompt
#define _Included_Prompt
#ifdef __cplusplus
extern "C" {
#endif
JNIEXPORT jstring JNICALL Java_Prompt_getLine(JNIEnv *env, jobject this, jstring prompt);
#ifdef __cplusplus
}
#endif
#endif
jstring是JNI中對應于String的類型，但是和基本類型不同的是，jstring不能直接當作C++的string用。如果你用
cout << prompt << endl;
編譯器肯定會扔給你一個錯誤信息的。
其實要處理jstring有很多種方式，這里只講一種我認為最簡單的方式，看下面這個例子，
#include "Prompt.h"
#include <iostream>
JNIEXPORT jstring JNICALL Java_Prompt_getLine(JNIEnv *env, jobject obj, jstring prompt)
{
const char* str;
str = env->GetStringUTFChars(prompt, false);
if(str == NULL) {
return NULL; /* OutOfMemoryError already thrown */
}
std::cout << str << std::endl;
env->ReleaseStringUTFChars(prompt, str);
char* tmpstr = "return string succeeded";
jstring rtstr = env->NewStringUTF(tmpstr);
return rtstr;
}
在上面的例子中，作為參數的prompt不能直接被C++程序使用，先做了如下轉換
str = env->GetStringUTFChars(prompt, false);
將jstring類型變成一個char*類型。
返回的時候，要生成一個jstring類型的對象，也必須通過如下命令，
jstring rtstr = env->NewStringUTF(tmpstr);
這里用到的GetStringUTFChars和NewStringUTF都是JNI提供的處理String類型的函數，還有其他的函數這里就不一一列舉了。
3. 數組類型的傳遞
和String一樣，JNI為Java基本類型的數組提供了j*Array類型，比如int[]對應的就是jintArray。來看一個傳遞int數組的例子，Java程序就不寫了，
JNIEXPORT jint JNICALL Java_IntArray_sumArray(JNIEnv *env, jobject obj, jintArray arr)
{
jint *carr;
carr = env->GetIntArrayElements(arr, false);
if(carr == NULL) {
return 0; /* exception occurred */
}
jint sum = 0;
for(int i=0; i<10; i++) {
sum += carr[i];
}
env->ReleaseIntArrayElements(arr, carr, 0);
return sum;
}
這個例子中的GetIntArrayElements和ReleaseIntArrayElements函數就是JNI提供用于處理int數組的函數。如果試圖用arr[i]的方式去訪問jintArray類型，毫無疑問會出錯。JNI還提供了另一對函數GetIntArrayRegion和 ReleaseIntArrayRegion訪問int數組，就不介紹了，對于其他基本類型的數組，方法類似。
4. 二維數組和String數組
在JNI中，二維數組和String數組都被視為object數組，因為數組和String被視為object。仍然用一個例子來說明，這次是一個二維int數組，作為返回值。
JNIEXPORT jobjectArray JNICALL Java_ObjectArrayTest_initInt2DArray(JNIEnv *env, jclass cls, int size)
{
jobjectArray result;
jclass intArrCls = env->FindClass("[I");
result = env->NewObjectArray(size, intArrCls, NULL);
for (int i = 0; i < size; i++) {
jint tmp[256]; /* make sure it is large enough! */
jintArray iarr = env->NewIntArray(size);
for(int j = 0; j < size; j++) {
tmp[j] = i + j;
}
env->SetIntArrayRegion(iarr, 0, size, tmp);
env->SetObjectArrayElement(result, i, iarr);
env->DeleteLocalRef(iarr);
}
return result;
}
上面代碼中的第三行，
jobjectArray result;
因為要返回值，所以需要新建一個jobjectArray對象。
jclass intArrCls = env->FindClass("[I");
是創建一個jclass的引用，因為result的元素是一維int數組的引用，所以intArrCls必須是一維int數組的引用，這一點是如何保證的呢？注意FindClass的參數"[I"，JNI就是通過它來確定引用的類型的，I表示是int類型，[標識是數組。對于其他的類型，都有相應的表示方法，
Z boolean
B byte
C char
S short
I int
J long
F float
D double
String是通過“Ljava/lang/String;”表示的，那相應的，String數組就應該是“[Ljava/lang/String;”。
還是回到代碼，
result = env->NewObjectArray(size, intArrCls, NULL);
的作用是為result分配空間。
jintArray iarr = env->NewIntArray(size);
是為一維int數組iarr分配空間。
env->SetIntArrayRegion(iarr, 0, size, tmp);
是為iarr賦值。
env->SetObjectArrayElement(result, i, iarr);
是為result的第i個元素賦值。
通過上面這些步驟，我們就創建了一個二維int數組，并賦值完畢，這樣就可以做為參數返回了。
如果了解了上面介紹的這些內容，基本上大部分的任務都可以對付了。雖然在操作數組類型，尤其是二維數組和String數組的時候，比起在單獨的語言中編程要麻煩，但既然我們享受了跨語言編程的好處，必然要付出一定的代價。
有一點要補充的是，本文所用到的函數調用方式都是針對C++的，如果要在C中使用，所有的env->都要被替換成(*env)->，而且后面的函數中需要增加一個參數env，具體請看一下jni.h的代碼。另外還有些省略的內容，可以參考JNI的文檔：Java Native Interface 6.0 Specification，在JDK的文檔里就可以找到。如果要進行更深入的JNI編程，需要仔細閱讀這個文檔。接下來的高級篇，也會討論更深入的話題。
關于JNI編程更深入的話題，包括：在native方法中訪問Java類的域和方法，將Java中自定義的類作為參數和返回值傳遞等等。了解這些內容，將會對JNI編程有更深入的理解，寫出的程序也更清晰，易用性更好。
1. 在一般的Java類中定義native方法
在前兩篇的例子中，都是將native方法放在main方法的Java類中，實際上，完全可以在任何類中定義native方法。這樣，對于外部來說，這個類和其他的Java類沒有任何區別。
2. 訪問Java類的域和方法
native方法雖然是native的，但畢竟是方法，那么就應該同其他方法一樣，能夠訪問類的私有域和方法。實際上，JNI的確可以做到這一點，我們通過幾個例子來說明，
public class ClassA {
String str_ = "abcde";
int number_;
public native void nativeMethod();
private void javaMethod() {
System.out.println("call java method succeeded");
}
static {
System.loadLibrary("ClassA");
}
}
在這個例子中，我們在一個沒有main方法的Java類中定義了native方法。我們將演示如何在nativeMethod()中訪問域str_，number_和方法javaMethod()，nativeMethod()的C++實現如下，
JNIEXPORT void JNICALL Java_testclass_ClassCallDLL_nativeMethod(JNIEnv *env, jobject obj) {
// access field
jclass cls = env->GetObjectClass(obj);
jfieldID fid = env->GetFieldID(cls, "str_", "Ljava/lang/String;");
jstring jstr = (jstring)env->GetObjectField(obj, fid);
const char *str = env->GetStringUTFChars(jstr, false);
if(std::string(str) == "abcde")
std::cout << "access field succeeded" << std::endl;
jint i = 2468;
fid = env->GetFieldID(cls, "number_", "I");
env->SetIntField(obj, fid, i);
// access method
jmethodID mid = env->GetMethodID(cls, "javaMethod", "()V");
env->CallVoidMethod(obj, mid);
}
上面的代碼中，通過如下兩行代碼獲得str_的值，
jfieldID fid = env->GetFieldID(cls, "str_", "Ljava/lang/String;");
jstring jstr = (jstring)env->GetObjectField(obj, fid);
第一行代碼獲得str_的id，在GetFieldID函數的調用中需要指定str_的類型，第二行代碼通過str_的id獲得它的值，當然我們讀到的是一個jstring類型，不能直接顯示，需要轉化為char*類型。
接下來我們看如何給Java類的域賦值，看下面兩行代碼，
fid = env->GetFieldID(cls, "number_", "I");
env->SetIntField(obj, fid, i);
第一行代碼同前面一樣，獲得number_的id，第二行我們通過SetIntField函數將i的值賦給number_，其他類似的函數可以參考JDK的文檔。
訪問javaMethod()的過程同訪問域類似，
jmethodID mid = env->GetMethodID(cls, "javaMethod", "()V");
env->CallVoidMethod(obj, mid);
需要強調的是，在GetMethodID中，我們需要指定javaMethod方法的類型，域的類型很容易理解，方法的類型如何定義呢，在上面的例子中，我們用的是()V，V表示返回值為空，()表示參數為空。如果是更復雜的函數類型如何表示？看一個例子，
long f (int n, String s, int[] arr);
這個函數的類型符號是(ILjava/lang/String;[I)J，I表示int類型，Ljava/lang/String;表示String類型，[I表示int數組，J表示long。這些都可以在文檔中查到。
3. 在native方法中使用用戶定義的類
JNI不僅能使用Java的基礎類型，還能使用用戶定義的類，這樣靈活性就大多了。大體上使用自定義的類和使用Java的基礎類(比如 String)沒有太大的區別，關鍵的一點是，如果要使用自定義類，首先要能訪問類的構造函數，看下面這一段代碼，我們在native方法中使用了自定義的Java類ClassB，
jclass cls = env->FindClass("Ltestclass/ClassB;");
jmethodID id = env->GetMethodID(cls, "<init>", "(D)V");
jdouble dd = 0.033;
jvalue args[1];
args[0].d = dd;
jobject obj = env->NewObjectA(cls, id, args);
首先要創建一個自定義類的引用，通過FindClass函數來完成，參數同前面介紹的創建String對象的引用類似，只不過類名稱變成自定義類的名稱。然后通過GetMethodID函數獲得這個類的構造函數，注意這里方法的名稱是"<init>"，它表示這是一個構造函數。
jobject obj = env->NewObjectA(cls, id, args);
生成了一個ClassB的對象，args是ClassB的構造函數的參數，它是一個jvalue*類型。
通過以上介紹的三部分內容，native方法已經看起來完全像Java自己的方法了，至少主要功能上齊備了，只是實現上稍麻煩。而了解了這些，JNI編程的水平也更上一層樓。下面要討論的話題也是一個重要內容，至少如果沒有它，我們的程序只能停留在演示階段，不具有實用價值。
4. 異常處理
在C++和Java的編程中，異常處理都是一個重要的內容。但是在JNI中，麻煩就來了，native方法是通過C++實現的，如果在native方法中發生了異常，如何傳導到Java呢？
JNI提供了實現這種功能的機制。我們可以通過下面這段代碼拋出一個Java可以接收的異常，
jclass errCls;
env->ExceptionDescribe();
env->ExceptionClear();
errCls = env->FindClass("java/lang/IllegalArgumentException");
env->ThrowNew(errCls, "thrown from C++ code");
如果要拋出其他類型的異常，替換掉FindClass的參數即可。這樣，在Java中就可以接收到native方法中拋出的異常。