Lines Matching full:code
24 <li><a href="#faq_ULE">FAQ: Why do I get <code>UnsatisfiedLinkError</code></a></li>
25 <li><a href="#faq_FindClass">FAQ: Why didn't <code>FindClass</code> find my class?</a></li>
26 <li><a href="#faq_sharing">FAQ: How do I share raw data with native code?</a></li>
32 <p>JNI is the Java Native Interface. It defines a way for managed code
34 code (written in C/C++). It's vendor-neutral, has support for loading code from
58 If a piece of code has no other way to get its JNIEnv, you should share
59 the JavaVM, and use <code>GetEnv</code> to discover the thread's JNIEnv. (Assuming it has one; see <code>AttachCurrentThread</code> below.)</p>
62 declarations. The <code>"jni.h"</code> include file provides different typedefs
65 header file requires <code>#ifdef __cplusplus</code>, you may have to do some extra work if anything in
72 started from managed code (using <code>Thread.start</code>),
74 example, a thread started with <code>pthread_create</code> can be attached
75 with the JNI <code>AttachCurrentThread</code> or
76 <code>AttachCurrentThreadAsDaemon</code> functions. Until a thread is
79 <p>Attaching a natively-created thread causes a <code>java.lang.Thread</code>
80 object to be constructed and added to the "main" <code>ThreadGroup</code>,
81 making it visible to the debugger. Calling <code>AttachCurrentThread</code>
84 <p>Android does not suspend threads executing native code. If
89 <code>DetachCurrentThread</code> before they exit</strong>.
91 can use <code>pthread_key_create</code> to define a destructor
93 call <code>DetachCurrentThread</code> from there. (Use that
94 key with <code>pthread_setspecific</code> to store the JNIEnv in
102 <p>If you want to access an object's field from native code, you would do the following:</p>
105 <li> Get the class object reference for the class with <code>FindClass</code></li>
106 <li> Get the field ID for the field with <code>GetFieldID</code></li>
108 <code>GetIntField</code></li>
117 in your native code. Because there is a limit of one JavaVM per process, it's reasonable
123 the <code>jclass</code>
125 to <code>NewGlobalRef</code> (see the next section).</p>
129 the IDs is to add a piece of code that looks like this to the appropriate class:</p>
132 * We use a class initializer to allow the native code to cache some
142 <p>Create a <code>nativeClassInit</code> method in your C/C++ code that performs the ID lookups. The code
154 <p>This applies to all sub-classes of <code>jobject</code>, including
155 <code>jclass</code>, <code>jstring</code>, and <code>jarray</code>.
159 <code>NewGlobalRef</code> and <code>NewWeakGlobalRef</code>.
162 a "global" reference. The <code>NewGlobalRef</code> function takes the
165 <code>DeleteGlobalRef</code>.</p>
168 from <code>FindClass</code>, e.g.:</p>
175 <code>NewGlobalRef</code> on the same object may be different.
177 you must use the <code>IsSameObject</code> function.</strong> Never compare
178 references with <code>==</code> in native code.</p>
182 in native code. The 32-bit value representing an object may be different
185 not use <code>jobject</code> values as keys.</p>
190 <code>DeleteLocalRef</code> instead of letting JNI do it for you. The
193 <code>EnsureLocalCapacity</code>/<code>PushLocalFrame</code> to reserve more.</p>
195 <p>Note that <code>jfieldID</code>s and <code>jmethodID</code>s are opaque
197 <code>NewGlobalRef</code>. The raw data
198 pointers returned by functions like <code>GetStringUTFChars</code>
199 and <code>GetByteArrayElements</code> are also not objects. (They may be passed
203 thread with <code>AttachCurrentThread</code>, the code you are running will
206 code that creates local references in a loop probably needs to do some manual
213 modified encoding is useful for C code because it encodes \u0000 as 0xc0 0x80 instead of 0x00.
219 currently does not require a copy in <code>GetStringChars</code>, whereas
220 <code>GetStringUTFChars</code> requires an allocation and a conversion to
226 <p><strong>Don't forget to <code>Release</code> the strings you <code>Get</code></strong>. The
227 string functions return <code>jchar*</code> or <code>jbyte*</code>, which
229 are guaranteed valid until <code>Release</code> is called, which means they are not
234 and handing it to <code>NewStringUTF</code> without filtering it.
249 the VM implementation, the <code>Get<PrimitiveType>ArrayElements</code>
252 is guaranteed to be valid until the corresponding <code>Release</code> call
255 <strong>You must <code>Release</code> every array you <code>Get</code>.</strong> Also, if the <code>Get</code>
256 call fails, you must ensure that your code doesn't try to <code>Release</code> a NULL
260 non-NULL pointer for the <code>isCopy</code> argument. This is rarely
263 <p>The <code>Release</code> call takes a <code>mode</code> argument that can
268 <li><code>0</code>
273 <li><code>JNI_COMMIT</code>
279 <li><code>JNI_ABORT</code>
287 <p>One reason for checking the <code>isCopy</code> flag is to know if
288 you need to call <code>Release</code> with <code>JNI_COMMIT</code>
290 changes and executing code that uses the contents of the array, you may be
293 efficient handling of <code>JNI_ABORT</code>. For example, you might want
299 <p>It is a common mistake (repeated in example code) to assume that you can skip the <code>Release</code> call if
300 <code>*isCopy</code> is false. This is not the case. If no copy buffer was
304 <p>Also note that the <code>JNI_COMMIT</code> flag does <strong>not</strong> release the array,
305 and you will need to call <code>Release</code> again with a different flag
312 <p>There is an alternative to calls like <code>Get<Type>ArrayElements</code>
313 and <code>GetStringChars</code> that may be very helpful when all you want
322 <p>This grabs the array, copies the first <code>len</code> byte
324 implementation, the <code>Get</code> call will either pin or copy the array
326 The code copies the data (for perhaps a second time), then calls <code>Release</code>; in this case
327 <code>JNI_ABORT</code> ensures there's no chance of a third copy.</p>
337 to call <code>Release</code> after something fails.
340 <p>Similarly, you can use the <code>Set<Type>ArrayRegion</code> call
341 to copy data into an array, and <code>GetStringRegion</code> or
342 <code>GetStringUTFRegion</code> to copy characters out of a
343 <code>String</code>.
350 Your code is expected to notice the exception (via the function's return value,
351 <code>ExceptionCheck</code>, or <code>ExceptionOccurred</code>) and return,
357 <li><code>DeleteGlobalRef</code>
358 <li><code>DeleteLocalRef</code>
359 <li><code>DeleteWeakGlobalRef</code>
360 <li><code>ExceptionCheck</code>
361 <li><code>ExceptionClear</code>
362 <li><code>ExceptionDescribe</code>
363 <li><code>ExceptionOccurred</code>
364 <li><code>MonitorExit</code>
365 <li><code>PopLocalFrame</code>
366 <li><code>PushLocalFrame</code>
367 <li><code>Release<PrimitiveType>ArrayElements</code>
368 <li><code>ReleasePrimitiveArrayCritical</code>
369 <li><code>ReleaseStringChars</code>
370 <li><code>ReleaseStringCritical</code>
371 <li><code>ReleaseStringUTFChars</code>
375 of checking for failure. For example, if <code>NewString</code> returns
377 you call a method (using a function like <code>CallObjectMethod</code>),
381 <p>Note that exceptions thrown by interpreted code do not unwind native stack
383 The JNI <code>Throw</code> and <code>ThrowNew</code> instructions just
385 from native code, the exception will be noted and handled appropriately.</p>
387 <p>Native code can "catch" an exception by calling <code>ExceptionCheck</code> or
388 <code>ExceptionOccurred</code>, and clear it with
389 <code>ExceptionClear</code>. As usual,
392 <p>There are no built-in functions for manipulating the <code>Throwable</code> object
394 find the <code>Throwable</code> class, look up the method ID for
395 <code>getMessage "()Ljava/lang/String;"</code>, invoke it, and if the result
396 is non-NULL use <code>GetStringUTFChars</code> to get something you can
397 hand to <code>printf(3)</code> or equivalent.</p>
412 <li>Direct ByteBuffers: passing bad arguments to <code>NewDirectByteBuffer</code>.</li>
416 <li>jmethodIDs: using the wrong kind of jmethodID when making a <code>Call*Method</code> JNI call: incorrect return type, static/non-static mismatch, wrong type for ?this? (for non-static calls) or wrong class (for static calls).</li>
417 <li>References: using <code>DeleteGlobalRef</code>/<code>DeleteLocalRef</code> on the wrong kind of reference.</li>
418 <li>Release modes: passing a bad release mode to a release call (something other than <code>0</code>, <code>JNI_ABORT</code>, or <code>JNI_COMMIT</code>).</li>
423 <p>(Accessibility of methods and fields is still not checked: access restrictions don't apply to native code.)</p>
453 <p>You can load native code from shared libraries with the standard
454 <code>System.loadLibrary</code> call. The
455 preferred way to get at your native code is:</p>
458 <li> Call <code>System.loadLibrary</code> from a static class
460 <code>nativeClassInit</code>.) The argument is the "undecorated"
462 <li> Provide a native function: <code><strong>jint JNI_OnLoad(JavaVM* vm, void* reserved)</strong></code></li>
463 <li>In <code>JNI_OnLoad</code>, register all of your native methods. You
469 <p>The <code>JNI_OnLoad</code> function should look something like this if
484 <p>You can also call <code>System.load</code> with the full path name of the
490 <code>JNI_OnLoad</code> function.
495 <p>One other note about <code>JNI_OnLoad</code>: any <code>FindClass</code>
497 that was used to load the shared library. Normally <code>FindClass</code>
501 <code>JNI_OnLoad</code> a convenient place to look up and cache class
511 when interacting with native code,
515 <code>long</code> field rather than an <code>int</code></strong>.
523 <li><code>DefineClass</code> is not implemented. Android does not use
537 <p>Until Android 2.0 (Eclair), it was not possible to use a <code>pthread_key_create</code>
546 be passed to <code>NewLocalRef</code>, <code>NewGlobalRef</code>, and
547 <code>DeleteWeakGlobalRef</code>. (The spec strongly encourages
558 <li><b>Determining reference type with <code>GetObjectRefType</code></b>
561 <code>GetObjectRefType</code> correctly. Instead we used a heuristic
566 you called <code>GetObjectRefType</code> on a global jclass that happened
568 native method, you'd get <code>JNILocalRefType</code> rather than
569 <code>JNIGlobalRefType</code>.
574 <h2>FAQ: Why do I get <code>UnsatisfiedLinkError</code>?</h2>
576 <p>When working on native code it's not uncommon to see a failure like this:</p>
580 other cases the library exists but couldn't be opened by <code>dlopen(3)</code>, and
586 <code>adb shell ls -l <path></code> to check its presence
592 <p>Another class of <code>UnsatisfiedLinkError</code> failures looks like:</p>
609 with <code>extern "C"</code> and appropriate
610 visibility (<code>JNIEXPORT</code>). Note that prior to Ice Cream
612 an old <code>jni.h</code> won't work.
613 You can use <code>arm-eabi-nm</code>
615 mangled (something like <code>_Z15Java_Foo_myfuncP7_JNIEnvP7_jclass</code>
616 rather than <code>Java_Foo_myfunc</code>), or if the symbol type is
622 Remember that 'B' is <code>byte</code> and 'Z' is <code>boolean</code>.
625 inner-class names (<code>Ljava/util/Map$Entry;</code>, say).
629 <p>Using <code>javah</code> to automatically generate JNI headers may help
634 <h2>FAQ: Why didn't <code>FindClass</code> find my class?</h2>
638 such as <code>java/lang/String</code>. If you're looking up an array class,
641 <code>String</code> would be <code>[Ljava/lang/String;</code>.</p>
644 issue. <code>FindClass</code> wants to start the class search in the
645 class loader associated with your code. It examines the call stack,
651 <p>The topmost method is <code>Foo.myfunc</code>. <code>FindClass</code>
652 finds the <code>ClassLoader</code> object associated with the <code>Foo</code>
656 create a thread yourself (perhaps by calling <code>pthread_create</code>
657 and then attaching it with <code>AttachCurrentThread</code>).
661 <p>The topmost method is <code>NativeStart.run</code>, which isn't part of
662 your application. If you call <code>FindClass</code> from this thread, the
668 <li>Do your <code>FindClass</code> lookups once, in
669 <code>JNI_OnLoad</code>, and cache the class references for later
670 use. Any <code>FindClass</code> calls made as part of executing
671 <code>JNI_OnLoad</code> will use the class loader associated with
672 the function that called <code>System.loadLibrary</code> (this is a
674 If your app code is loading the library, <code>FindClass</code>
678 then passing <code>Foo.class</code> in.
679 <li>Cache a reference to the <code>ClassLoader</code> object somewhere
680 handy, and issue <code>loadClass</code> calls directly. This requires
686 <h2>FAQ: How do I share raw data with native code?</h2>
689 buffer of raw data from both managed and native code. Common examples
693 <p>You can store the data in a <code>byte[]</code>. This allows very fast
694 access from managed code. On the native side, however, you're
696 some implementations, <code>GetByteArrayElements</code> and
697 <code>GetPrimitiveArrayCritical</code> will return actual pointers to the
702 can be created with <code>java.nio.ByteBuffer.allocateDirect</code>, or
703 the JNI <code>NewDirectByteBuffer</code> function. Unlike regular
705 always be accessed directly from native code (get the address
706 with <code>GetDirectBufferAddress</code>). Depending on how direct
707 byte buffer access is implemented, accessing the data from managed code
712 <li>Will most of the data accesses happen from code written in Java
717 <code>ByteBuffer</code> might be unwise.)
