Programmers_Guide/html/md_2__samples_sample--hellojni.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.5"/>
<title>NDK Programmer&#39;s Guide: hello-jni</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
  $(window).load(resizeHeight);
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td style="padding-left: 0.5em;">
   <div id="projectname">NDK Programmer&#39;s Guide
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.5 -->
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;"
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('md_2__samples_sample--hellojni.html','');});
</script>
<div id="doc-content">
<div class="header">
  <div class="headertitle">
<div class="title">hello-jni </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>This sample provides a bare-bones look at a minimal
application built with the NDK.</p>
<h3>Android.mk</h3>
<p>The following two lines provide the name of the native source file, along
with the name of the shared library to build. The full name of the built
library is <code>libhello-jni.so</code>, but you should omit the
<code>lib</code> prefix and the <code>.so</code> extension.</p>
<pre class="fragment">LOCAL_SRC_FILES := hello-jni.c
LOCAL_MODULE    := hello-jni
</pre><p>For more information on what this file does, and how to use it, see
the <a
href="./md_3__key__topics__building__chapter_1-section_8__android_8mk.html">Android.mk</a> section.</p>
<h3>Application.mk</h3>
<p>This line tells the build system the architecture against which to build. If
you don't specify anything, the build system defaults to armeabi.</p>
<pre class="fragment">APP_ABI := all
</pre><p>For more information on what this file does, and how to use it, see
the <a
href="./md_3__key__topics__building__a_p_p_l_i_c_a_t_i_o_n-_m_k.html">Application.mk</a> section.</p>
<h3>Java-side implementation</h3>
<p>This file calls a function to retrieve a string from the native side, then
displays it on the screen.</p>
<p>The source code contains three lines of particular interest to the NDK user.
They are presented here in the order in which they are used, rather than by
line order.</p>
<p>This function call loads the <code>.so</code> file upon application
startup.</p>
<pre class="fragment">System.loadLibrary("hello-jni");
</pre><p>The <code>native</code> keyword in this method declaration tells the
DVM that the function is in the shared library (i.e., implemented on the native
side).</p>
<pre class="fragment">public native String stringFromJNI();
</pre><p>The Android framework calls the function loaded and declared in the
previous steps, displaying the string on the screen.</p>
<pre class="fragment">tv.setText( stringFromJNI() );
</pre><h3>C-side implementation</h3>
<p>This file contains a function that returns a string that the Java side
requested (see "Java-side implementation"). The function declaration is as
follows:</p>
<pre class="fragment">jstring Java_com_example_hellojni_HelloJni_stringFromJNI(
JNIEnv* env,
                                              jobject x )
</pre><p>This declaration corresponds to the native function declared in the
Java source code. The return type, <code>jstring</code>, is a data type defined
in the <a
href="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/jniTOC.html
">Java Native Interface Specification</a>. It is not actually a string, but a
pointer to a Java string.</p>
<p>After <code>jstring</code> comes the function name, which is based on the
Java function name and and the path to the file containing it. Construct it
according to the following rules:</p>
<ul>
<li>Prepend <code>Java_</code> to it.</li>
<li>Describe the filepath relative to the top-level source directory.</li>
<li>Use underscores in place of forward slashes.</li>
<li>Omit the <code>.java</code> file extension.</li>
<li>After the last underscore, append the function name.</li>
</ul>
<p>Thus, in this example, the function name
<code>Java_com_example_hellojni_HelloJni_stringFromJNI</code> refers to a Java
function called <code>stringFromJNI()</code>, which resides in
<code>hellojni/src/com/example/hellojni/HelloJni.java</code>.</p>
<p>Finally, <code>JNIEnv*</code> is the pointer to the VM, and
<code>jobject</code> is a pointer to the implicit “this” object passed from
the Java side.</p>
<p>The following line calls the VM API (*env), and passes it a return value:
that is, the string that the function on the Java side had requested. </p>
<pre class="fragment">return (*env)-&gt;NewStringUTF(env, "Hello from JNI !
Compiled with ABI " ABI "."); </pre> </div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated on Wed Jun 25 2014 00:51:19 for NDK
Programmer&#39;s Guide by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.5 </li>
  </ul>
</div>
</body>
</html>