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)-&gt;NewStringUTF(env, "Hello from JNI !
122Compiled with ABI " ABI ".");
123</pre>
124