1 page.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 20 application built with the NDK. This sample is in the {@code samples/hello-jni/} directory 21 under 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 26 with the name of the shared library to build. The full name of the built 27 library 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"> 31 LOCAL_SRC_FILES := hello-jni.c 32 LOCAL_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 40 example, the build system builds for all supported architectures.</p> 41 42 <pre class="no-pretty-print"> 43 APP_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 51 a 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. 54 They are presented here in the order in which they are used, rather than by 55 line order.</p> 56 57 <p>This function call loads the {@code .so} file upon application startup.</p> 58 59 <pre class="no-pretty-print"> 60 System.loadLibrary("hello-jni"); 61 </pre> 62 63 <p>The {@code native} keyword in this method declaration tells the 64 virtual machine that the function is in the shared library (that is, implemented on the native 65 side).</p> 66 67 <pre class="no-pretty-print"> 68 public native String stringFromJNI(); 69 </pre> 70 71 <p>The Android framework calls the function loaded and declared in the 72 previous steps, displaying the string on the screen.</p> 73 74 <pre class="no-pretty-print"> 75 tv.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 80 returns a string that <a href="#ji">the Java side requested</a>). The function declaration is as 81 follows:</p> 82 83 <pre> 84 jstring 85 Java_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 90 Java source code. The return type, {@code jstring}, is a data type defined 91 in the 92 <a href="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/jniTOC.html">Java Native 93 Interface Specification</a>. It is not actually a string, but a 94 pointer to a Java string.</p> 95 96 <p>After {@code jstring} comes the function name, which is based on the 97 Java function name and and the path to the file containing it. Construct it 98 according 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 110 function 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 115 the Java side.</p> 116 117 <p>The following line calls the VM API {@code (*env)}, and passes it a return value: 118 that is, the string that the function on the Java side had requested.</p> 119 120 <pre class="no-pretty-print"> 121 return (*env)->NewStringUTF(env, "Hello from JNI ! 122 Compiled with ABI " ABI "."); 123 </pre> 124
