Android 开发之JNI学习笔记

 

JNI—java native interface

官方文档

JNI is the Java Native Interface. It defines a way for managed code (written in the Java programming language) to interact with native code (written in C/C++). It's vendor-neutral, has support for loading code from dynamic shared libraries, and while cumbersome at times is reasonably efficient.

JNI 即java 本地接口，它定义了一种方法(用java语言写)管理代码和本地代码（用C语言或者C++语言）交互。它是中立，它支持动态地从分享库中加载代码，虽然操做会麻烦些，但有时候它是必须的，有效的。

If you're not already familiar with it, read through the Java Native Interface Specification to get a sense for how JNI works and what features are available. Some aspects of the interface aren't immediately obvious on first reading, so you may find the next few sections handy.

若是你以前并不熟悉它，经过阅读这java 本地接口规范去了解JNI是如何工做的和一些有用的功能特性。第一次阅读接口的某些方面不能马上明白，然而你会在后面几个部分中发现它。

JavaVM and JNIEnv

---

JNI defines two key data structures, "JavaVM" and "JNIEnv". Both of these are essentially pointers to pointers to function tables. (In the C++ version, they're classes with a pointer to a function table and a member function for each JNI function that indirects through the table.) The JavaVM provides the "invocation interface" functions, which allow you to create and destroy a JavaVM. In theory you can have multiple JavaVMs per process, but Android only allows one.

JNI定义了两个重要的数据结构，javavm和JNIEnv。这二者本质上就是指向函数的指针构成的表。（在C++版本，该段实在翻译不出来），javaVM（java虚拟机） 提供了调用接口的功能函数。这些接口功能函数容许你去建立和销毁一个java虚拟机，理论上每一个进程你能够有多个虚拟机，可是android只容许你有一个。

 

The JNIEnv provides most of the JNI functions. Your native functions all receive a JNIEnv as the first argument.

JNI（JNINativeInterface）

提供了不少java 本地接口函数，你的全部的本地方法都接收一个JNIEnv做为第一个参数

The JNIEnv is used for thread-local storage. For this reason, you cannot share a JNIEnv between threads. If a piece of code has no other way to get its JNIEnv, you should share the JavaVM, and use GetEnv to discover the thread's JNIEnv. (Assuming it has one; see AttachCurrentThread below.)

JNIEnv是使用本地线程存储的，出于这个缘由，你不能在线程间共享JNIEnv。若是一段代码没有其余的方法去获得JNIEnv，你应该共享java虚拟机而后使用GetEnv查找这线程中的JNIEnv

The C declarations of JNIEnv and JavaVM are different from the C++ declarations. The "jni.h" include file provides different typedefs depending on whether it's included into C or C++. For this reason it's a bad idea to include JNIEnv arguments in header files included by both languages. (Put another way: if your header file requires #ifdef __cplusplus, you may have to do some extra work if anything in that header refers to JNIEnv.)

JNIEnv 和JAVA虚拟机在C中的声明与在C++中声明是不一样的。这个jni.h所包含的文件提供了不一样的类型取决因而否包含C或者C++。出于这个缘由，在两种语言的头文件中包含JNIEnv参数是很是不可取的。（换句话说：若是你的具备JNIEnv的头文件引用须要#ifdef __cplusplus标签，你可能不得很少作一些 额外的工做

Threads

All threads are Linux threads, scheduled by the kernel. They're usually started from managed code (usingThread.start), but they can also be created elsewhere and then attached to the JavaVM. For example, a thread started with pthread_create can be attached with the JNI AttachCurrentThread orAttachCurrentThreadAsDaemon functions. Until a thread is attached, it has no JNIEnv, and cannot make JNI calls.

全部的线程都是linux线程，这些线程被kernet（内核）调度。线程一般从托管代码开启（使用 thread.start），可是他们也能够在其余地方被建立而后与java虚拟机相链接。例如，一个从pthread_create开始的线程能够和JNI函数链接在一块儿（经过AttachCurrentThread orAttachCurrentThreadAsDaemon）。直到一个可链接的线程由于没有JNIEnv不能被JNI调用。

Attaching a natively-created thread causes a java.lang.Thread object to be constructed and added to the "main" ThreadGroup, making it visible to the debugger. Calling AttachCurrentThread on an already-attached thread is a no-op.

一个了链接的本地线程被建立引发一个java.lang.Thread 对象呗构造出阿里并增长到主线程组中，打开可视化的调试，在一个早已链接的线程中调用AttachCurrentThread会等待。

Android does not suspend threads executing native code. If garbage collection is in progress, or the debugger has issued a suspend request, Android will pause the thread the next time it makes a JNI call.

Android 不支持线程执行不低代码，若是垃圾回收器正在处理垃圾，或者调试已经发出了一个调试请求，Android将会暂停下次调用JNI的线程

Threads attached through JNI must call DetachCurrentThread before they exit. If coding this directly is awkward, in Android 2.0 (Eclair) and higher you can use pthread_key_create to define a destructor function that will be called before the thread exits, and call DetachCurrentThread from there. (Use that key withpthread_setspecific to store the JNIEnv in thread-local-storage; that way it'll be passed into your destructor as the argument.)

经过JNI链接的线程在他们退出以前必须滴啊用DetachCurrentThread方法。若是直接编译困在，再ANdroid2.0或者更高版本的系统上你可使用pthread_key_create 去定义一个在线程退出时被调用的析构函数。使用用pthread_setspecific键 在本地线程中去保存JNIEnv；它将能被你的析构函数做为参数调用

 

jclass, jmethodID, and jfieldID

---

If you want to access an object's field from native code, you would do the following:

若是你想从本地代码中去接受一个对象字段。须要作以下操做

• Get the class object reference for the class with FindClass
• 使用findClass获得类对象的引用
• Get the field ID for the field with GetFieldID
• 使用GetFieldID获得字段的ID
• Get the contents of the field with something appropriate, such as GetIntField
• GetIntField 获得字段中某些内容信息

Similarly, to call a method, you'd first get a class object reference and then a method ID. The IDs are often just pointers to internal runtime data structures. Looking them up may require several string comparisons, but once you have them the actual call to get the field or invoke the method is very quick.

相似的，你要去调用一个方法，首先要得到一个类的对象的引用和这个方法的ID。ID经常只是内部运行的结构体的指针。查看他们可能须要比较几个字符串。可是一旦你获得了他们自己再去获得字段或者调用方法是很是容易的。

If performance is important, it's useful to look the values up once and cache the results in your native code. Because there is a limit of one JavaVM per process, it's reasonable to store this data in a static local structure.

若是要求高性能，在你的本地代码中经常查看一次这个值并缓存起来。由于这是java虚拟机的一个限制，将这些数据用静态局部结构体存储起来是颇有用的。

The class references, field IDs, and method IDs are guaranteed valid until the class is unloaded. Classes are only unloaded if all classes associated with a ClassLoader can be garbage collected, which is rare but will not be impossible in Android. Note however that the jclass is a class reference and must be protected with a call toNewGlobalRef (see the next section).

知道类被卸载以前，这个类的引用，字段的ID，方法的ID都是被保证有效的。发生与类加载器所加载的类中只有被卸载的类才能被垃圾回收器回收的几率，这在android中是不可能的。注意无论这么样这jclass做为一个类的引用且必须调用NewGlobalRef去保护它。

If you would like to cache the IDs when a class is loaded, and automatically re-cache them if the class is ever unloaded and reloaded, the correct way to initialize the IDs is to add a piece of code that looks like this to the appropriate class:

若是你想在一个类被加载的时候缓存它的ID而且在类被卸载后再次加载时自动缓存他们的ID，正确初始化ID的方法是去增长一段代码到合适的类中

    /*
     * We use a class initializer to allow the native code to cache some
     * field offsets. This native function looks up and caches interesting
     * class/field/method IDs. Throws on failure.
     */
    private static native void nativeInit();

    static {
        nativeInit();
    }

Create a nativeClassInit method in your C/C++ code that performs the ID lookups. The code will be executed once, when the class is initialized. If the class is ever unloaded and then reloaded, it will be executed again.

在你的C或者C++代码中建立一个ntiveClassInit方法 去执行ID的查找工做，在类初始化的时候，这方法将被执行一次。若是这类

曾经被卸载而后从新加载，这个方法将再次被执行。

Local and Global References

局部和全局引用

Every argument passed to a native method, and almost every object returned by a JNI function is a "local reference". This means that it's valid for the duration of the current native method in the current thread. Even if the object itself continues to live on after the native method returns, the reference is not valid.

几乎将每个参数传递给本地方法而后都经过一个局部引用的JNI函数返回给对象。这意味着在当前线程中的当前的本地方法在这段期间是有效的。过了这段时间，即便这个对象自己在本地方法返回后仍然活着，它也是无效的。

This applies to all sub-classes of jobject, including jclass, jstring, and jarray. (The runtime will warn you about most reference mis-uses when extended JNI checks are enabled.)

这适用于全部的jobject的子类包括jclass, jstring, 和 jarray. （当启用扩展的JNI检测时，在运行时将给出你过多的引用被滥用的警告）

The only way to get non-local references is via the functions NewGlobalRef and NewWeakGlobalRef.

这获得非局部引用的惟一的方法是经过NewGlobalRef 和NewWeakGlobalRef功能函数，

If you want to hold on to a reference for a longer period, you must use a "global" reference. The NewGlobalReffunction takes the local reference as an argument and returns a global one. The global reference is guaranteed to be valid until you call DeleteGlobalRef.

若是你想在很长一段时间内持有一个引用，你必须适用global应用。NewGlobalRef函数适用一个局部引用做为参数返回一个全局引用，这全局在你调用DeleteGlobalRef方法前都被保证是有效的

This pattern is commonly used when caching a jclass returned from FindClass, e.g.:

在缓存一个来自FindClass方法返回的jclass对象时，这种模式一般是有用的。

jclass localClass = env->FindClass("MyClass");
jclass globalClass = reinterpret_cast<jclass>(env->NewGlobalRef(localClass));

All JNI methods accept both local and global references as arguments. It's possible for references to the same object to have different values. For example, the return values from consecutive calls to NewGlobalRef on the same object may be different. To see if two references refer to the same object, you must use theIsSameObject function. Never compare references with == in native code.

全部的JNI方法都接收两个局部和者全局引用做为参数。经过同样的对象去获得不一样的值这是合适的。例如，用同样的对象连续的去调用NewGlobalRef 方法返回的值多是不一样的。要看是否两个引用引用同样的对象，你必须适用theIsSameObject 方法去判断。在本地代码中绝对不要适用==去比较。

One consequence of this is that you must not assume object references are constant or unique in native code. The 32-bit value representing an object may be different from one invocation of a method to the next, and it's possible that two different objects could have the same 32-bit value on consecutive calls. Do not use jobjectvalues as keys.

做为结论在本地代码中你不能假设对象的引用是一个常数或者惟一的。一个用32位表示的对象从一个方法调用下一个方法多是不一样的，它多是两个不一样的32位对象在连续的调用。不要适用jobject值做为键

Programmers are required to "not excessively allocate" local references. In practical terms this means that if you're creating large numbers of local references, perhaps while running through an array of objects, you should free them manually with DeleteLocalRef instead of letting JNI do it for you. The implementation is only required to reserve slots for 16 local references, so if you need more than that you should either delete as you go or use EnsureLocalCapacity/PushLocalFrame to reserve more.

程序员须要适当的分配本地引用。在实践中这表示是否你建立了大量的局部引用，或者当经过一个数组对象运行时，你应该手动的用DeleteLocalRef 释放他们而不是让JNI去作这些事。实现只须要你去保存16个局部引用，因此你须要更多的区删除或者使用EnsureLocalCapacity/PushLocalFrame 去储备更多。

Note that jfieldIDs and jmethodIDs are opaque types, not object references, and should not be passed toNewGlobalRef. The raw data pointers returned by functions like GetStringUTFChars andGetByteArrayElements are also not objects. (They may be passed between threads, and are valid until the matching Release call.)

注意jfieldIDs 和jmethodIDs是空类型，不是对象引用，不该该传递给NewGlobalRef方法。经过像GetStringUTFChars 和andGetByteArrayElements 返回的原始数据也不是对象（在被析构以前他们经过在两个线程间传递是有效的。）

One unusual case deserves separate mention. If you attach a native thread with AttachCurrentThread, the code you are running will never automatically free local references until the thread detaches. Any local references you create will have to be deleted manually. In general, any native code that creates local references in a loop probably needs to do some manual deletion.

一个特别的案例值得单独说：若是你用AttachCurrentThread附加一个本地线程，你运行的代码将不会自动的清除局部引用，直到线程死去。你建立的任何局部引用必须手动的删除。通常来讲，在循环中任何本地菜吗建立的局部引用可能需作一些手动删除

UTF-8 and UTF-16 Strings

，（持续更新中）

---

The Java programming language uses UTF-16. For convenience, JNI provides methods that work with Modified UTF-8 as well. The modified encoding is useful for C code because it encodes \u0000 as 0xc0 0x80 instead of 0x00. The nice thing about this is that you can count on having C-style zero-terminated strings, suitable for use with standard libc string functions. The down side is that you cannot pass arbitrary UTF-8 data to JNI and expect it to work correctly.

If possible, it's usually faster to operate with UTF-16 strings. Android currently does not require a copy inGetStringChars, whereas GetStringUTFChars requires an allocation and a conversion to UTF-8. Note thatUTF-16 strings are not zero-terminated, and \u0000 is allowed, so you need to hang on to the string length as well as the jchar pointer.

Don't forget to Release the strings you Get. The string functions return jchar* or jbyte*, which are C-style pointers to primitive data rather than local references. They are guaranteed valid until Release is called, which means they are not released when the native method returns.

Data passed to NewStringUTF must be in Modified UTF-8 format. A common mistake is reading character data from a file or network stream and handing it to NewStringUTF without filtering it. Unless you know the data is 7-bit ASCII, you need to strip out high-ASCII characters or convert them to proper Modified UTF-8 form. If you don't, the UTF-16 conversion will likely not be what you expect. The extended JNI checks will scan strings and warn you about invalid data, but they won't catch everything.

Primitive Arrays

---

JNI provides functions for accessing the contents of array objects. While arrays of objects must be accessed one entry at a time, arrays of primitives can be read and written directly as if they were declared in C.

To make the interface as efficient as possible without constraining the VM implementation, theGet<PrimitiveType>ArrayElements family of calls allows the runtime to either return a pointer to the actual elements, or allocate some memory and make a copy. Either way, the raw pointer returned is guaranteed to be valid until the corresponding Release call is issued (which implies that, if the data wasn't copied, the array object will be pinned down and can't be relocated as part of compacting the heap). You must Release every array you Get. Also, if the Get call fails, you must ensure that your code doesn't try to Release a NULL pointer later.

You can determine whether or not the data was copied by passing in a non-NULL pointer for the isCopyargument. This is rarely useful.

The Release call takes a mode argument that can have one of three values. The actions performed by the runtime depend upon whether it returned a pointer to the actual data or a copy of it:

• 0
  • Actual: the array object is un-pinned.
  • Copy: data is copied back. The buffer with the copy is freed.
• JNI_COMMIT
  • Actual: does nothing.
  • Copy: data is copied back. The buffer with the copy is not freed.
• JNI_ABORT
  • Actual: the array object is un-pinned. Earlier writes are not aborted.
  • Copy: the buffer with the copy is freed; any changes to it are lost.

One reason for checking the isCopy flag is to know if you need to call Release with JNI_COMMIT after making changes to an array — if you're alternating between making changes and executing code that uses the contents of the array, you may be able to skip the no-op commit. Another possible reason for checking the flag is for efficient handling of JNI_ABORT. For example, you might want to get an array, modify it in place, pass pieces to other functions, and then discard the changes. If you know that JNI is making a new copy for you, there's no need to create another "editable" copy. If JNI is passing you the original, then you do need to make your own copy.

It is a common mistake (repeated in example code) to assume that you can skip the Release call if *isCopy is false. This is not the case. If no copy buffer was allocated, then the original memory must be pinned down and can't be moved by the garbage collector.

Also note that the JNI_COMMIT flag does not release the array, and you will need to call Release again with a different flag eventually.

Region Calls

---

There is an alternative to calls like Get<Type>ArrayElements and GetStringChars that may be very helpful when all you want to do is copy data in or out. Consider the following:

    jbyte* data = env->GetByteArrayElements(array, NULL);
    if (data != NULL) {
        memcpy(buffer, data, len);
        env->ReleaseByteArrayElements(array, data, JNI_ABORT);
    }

This grabs the array, copies the first len byte elements out of it, and then releases the array. Depending upon the implementation, the Get call will either pin or copy the array contents. The code copies the data (for perhaps a second time), then calls Release; in this case JNI_ABORT ensures there's no chance of a third copy.

One can accomplish the same thing more simply:

    env->GetByteArrayRegion(array, 0, len, buffer);

This has several advantages:

• Requires one JNI call instead of 2, reducing overhead.
• Doesn't require pinning or extra data copies.
• Reduces the risk of programmer error — no risk of forgetting to call Release after something fails.

Similarly, you can use the Set<Type>ArrayRegion call to copy data into an array, and GetStringRegion orGetStringUTFRegion to copy characters out of a String.

Exceptions

---

You must not call most JNI functions while an exception is pending. Your code is expected to notice the exception (via the function's return value, ExceptionCheck, or ExceptionOccurred) and return, or clear the exception and handle it.

The only JNI functions that you are allowed to call while an exception is pending are:

• DeleteGlobalRef
• DeleteLocalRef
• DeleteWeakGlobalRef
• ExceptionCheck
• ExceptionClear
• ExceptionDescribe
• ExceptionOccurred
• MonitorExit
• PopLocalFrame
• PushLocalFrame
• Release<PrimitiveType>ArrayElements
• ReleasePrimitiveArrayCritical
• ReleaseStringChars
• ReleaseStringCritical
• ReleaseStringUTFChars

Many JNI calls can throw an exception, but often provide a simpler way of checking for failure. For example, ifNewString returns a non-NULL value, you don't need to check for an exception. However, if you call a method (using a function like CallObjectMethod), you must always check for an exception, because the return value is not going to be valid if an exception was thrown.

Note that exceptions thrown by interpreted code do not unwind native stack frames, and Android does not yet support C++ exceptions. The JNI Throw and ThrowNew instructions just set an exception pointer in the current thread. Upon returning to managed from native code, the exception will be noted and handled appropriately.

Native code can "catch" an exception by calling ExceptionCheck or ExceptionOccurred, and clear it withExceptionClear. As usual, discarding exceptions without handling them can lead to problems.

There are no built-in functions for manipulating the Throwable object itself, so if you want to (say) get the exception string you will need to find the Throwable class, look up the method ID for getMessage "()Ljava/lang/String;", invoke it, and if the result is non-NULL use GetStringUTFChars to get something you can hand to printf(3) or equivalent.

Extended Checking

---

JNI does very little error checking. Errors usually result in a crash. Android also offers a mode called CheckJNI, where the JavaVM and JNIEnv function table pointers are switched to tables of functions that perform an extended series of checks before calling the standard implementation.

The additional checks include:

• Arrays: attempting to allocate a negative-sized array.
• Bad pointers: passing a bad jarray/jclass/jobject/jstring to a JNI call, or passing a NULL pointer to a JNI call with a non-nullable argument.
• Class names: passing anything but the “java/lang/String” style of class name to a JNI call.
• Critical calls: making a JNI call between a “critical” get and its corresponding release.
• Direct ByteBuffers: passing bad arguments to NewDirectByteBuffer.
• Exceptions: making a JNI call while there’s an exception pending.
• JNIEnv*s: using a JNIEnv* from the wrong thread.
• jfieldIDs: using a NULL jfieldID, or using a jfieldID to set a field to a value of the wrong type (trying to assign a StringBuilder to a String field, say), or using a jfieldID for a static field to set an instance field or vice versa, or using a jfieldID from one class with instances of another class.
• jmethodIDs: using the wrong kind of jmethodID when making a Call*Method JNI call: incorrect return type, static/non-static mismatch, wrong type for ‘this’ (for non-static calls) or wrong class (for static calls).
• References: using DeleteGlobalRef/DeleteLocalRef on the wrong kind of reference.
• Release modes: passing a bad release mode to a release call (something other than 0, JNI_ABORT, orJNI_COMMIT).
• Type safety: returning an incompatible type from your native method (returning a StringBuilder from a method declared to return a String, say).
• UTF-8: passing an invalid Modified UTF-8 byte sequence to a JNI call.

(Accessibility of methods and fields is still not checked: access restrictions don't apply to native code.)

There are several ways to enable CheckJNI.

If you’re using the emulator, CheckJNI is on by default.

If you have a rooted device, you can use the following sequence of commands to restart the runtime with CheckJNI enabled:

adb shell stop
adb shell setprop dalvik.vm.checkjni true
adb shell start

In either of these cases, you’ll see something like this in your logcat output when the runtime starts:

D AndroidRuntime: CheckJNI is ON

If you have a regular device, you can use the following command:

adb shell setprop debug.checkjni 1

This won’t affect already-running apps, but any app launched from that point on will have CheckJNI enabled. (Change the property to any other value or simply rebooting will disable CheckJNI again.) In this case, you’ll see something like this in your logcat output the next time an app starts:

D Late-enabling CheckJNI

You can also set the android:debuggable attribute in your application's manifest to turn on CheckJNI just for your app. Note that the Android build tools will do this automatically for certain build types.