1page.title=Sample: hello-jni 2@jd:body 3 4<div id="qv-wrapper"> 5 <div id="qv"> 6 <h2>On this page</h2> 7 8 <ol> 9 <li><a href="#an">Android.mk</a></li> 10 <li><a href="#ap">Application.mk</a></li> 11 <li><a href="#ji">Java-side Implementation</a></li> 12 <li><a href="#ci">C-side Implementation</a></li> 13 </ol> 14 </li> 15 </ol> 16 </div> 17 </div> 18 19<p>This sample guides you through HelloJNI, a minimal 20application built with the NDK. This sample is in the {@code samples/hello-jni/} directory 21under the root directory of your NDK installation.</p> 22 23<h2 id="an">Android.mk</h2> 24 25<p>The following two lines provide the name of the native source file, along 26with the name of the shared library to build. The full name of the built 27library is {@code libhello-jni.so}, once the build system adds the 28{@code lib} prefix and the {@code .so} extension.</p> 29 30<pre class="no-pretty-print"> 31LOCAL_SRC_FILES := hello-jni.c 32LOCAL_MODULE := hello-jni 33</pre> 34 35<p>For more information about what the {@code Android.mk} file does, and how to use it, see 36<a href="{@docRoot}ndk/guides/android_mk.html">Android.mk</a>.</p> 37 38<h2 id="ap">Application.mk</h2> 39<p>This line tells the build system the CPU and architecture against which to build. In this 40example, the build system builds for all supported architectures.</p> 41 42<pre class="no-pretty-print"> 43APP_ABI := all 44</pre> 45 46<p>For more information about the {@code Application.mk} file, and how to use it, see 47<a href="{@docRoot}ndk/guides/application_mk.html">Application.mk</a>.</p> 48 49<h2 id="ji">Java-side Implementation</h2> 50<p>The {@code helloJNI.java} file is located in {@code hellojni/src/com/example/hellojni/}. It calls 51a function to retrieve a string from the native side, then displays it on the screen.</p> 52 53<p>The source code contains three lines of particular interest to the NDK user. 54They are presented here in the order in which they are used, rather than by 55line order.</p> 56 57<p>This function call loads the {@code .so} file upon application startup.</p> 58 59<pre class="no-pretty-print"> 60System.loadLibrary("hello-jni"); 61</pre> 62 63<p>The {@code native} keyword in this method declaration tells the 64virtual machine that the function is in the shared library (that is, implemented on the native 65side).</p> 66 67<pre class="no-pretty-print"> 68public native String stringFromJNI(); 69</pre> 70 71<p>The Android framework calls the function loaded and declared in the 72previous steps, displaying the string on the screen.</p> 73 74<pre class="no-pretty-print"> 75tv.setText( stringFromJNI() ); 76</pre> 77 78<h2 id="ci">C-side Implementation</h2> 79<p>The {@code hello-jni.c} file is located in {@code hello-jni/jni/}. It contains a function that 80returns a string that <a href="#ji">the Java side requested</a>). The function declaration is as 81follows:</p> 82 83<pre> 84jstring 85Java_com_example_hellojni_HelloJni_stringFromJNI( JNIEnv* env, 86 jobject thiz ) 87</pre> 88 89<p>This declaration corresponds to the native function declared in the 90Java source code. The return type, {@code jstring}, is a data type defined 91in the 92<a href="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/jniTOC.html">Java Native 93Interface Specification</a>. It is not actually a string, but a 94pointer to a Java string.</p> 95 96<p>After {@code jstring} comes the function name, which is based on the 97Java function name and and the path to the file containing it. Construct it 98according to the following rules:</p> 99 100<ul> 101<li>Prepend {@code Java_} to it.</li> 102<li>Describe the filepath relative to the top-level source directory.</li> 103<li>Use underscores in place of forward slashes.</li> 104<li>Omit the {@code .java} file extension.</li> 105<li>After the last underscore, append the function name.</li> 106</ul> 107 108<p>Following these rules, this example uses the function name 109{@code Java_com_example_hellojni_HelloJni_stringFromJNI}. This name refers to a Java 110function called {@code stringFromJNI()}, which resides in 111{@code hellojni/src/com/example/hellojni/HelloJni.java}.</p> 112 113<p>{@code JNIEnv*} is the pointer to the VM, and 114{@code jobject} is a pointer to the implicit {@code this} object passed from 115the Java side.</p> 116 117<p>The following line calls the VM API {@code (*env)}, and passes it a return value: 118that is, the string that the function on the Java side had requested.</p> 119 120<pre class="no-pretty-print"> 121return (*env)->NewStringUTF(env, "Hello from JNI ! 122Compiled with ABI " ABI "."); 123</pre> 124