📄 jnistring.html
字号:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<TITLE>Writing Advanced Applications, Chapter 5: JNI Technology
</TITLE>
<META NAME="AUTHOR" CONTENT="Monica Pawlan and Calvin Austin">
<META NAME="KEYWORDS" CONTENT="programming, advanced, Java 2">
<META NAME="OWNER" CONTENT="Editorial/JDC">
<META NAME="revision" CONTENT="@(#)jni.src 1.3 07/20/99 JDC">
</HEAD>
<!-- Start Body Insert-->
<BODY BGCOLOR="#ffffff">
<!-- End Body Insert-->
<!-- Start PageTop Insert -->
<TABLE BORDER="0" CELLSPACING="0" CELLPADDING="0" WIDTH="100%">
<TR ALIGN="CENTER" VALIGN="TOP">
<TD WIDTH="157" ALIGN="LEFT">
<IMG SRC="/images/pixel.gif" HEIGHT="40" WIDTH="40" ALT="">
<A HREF="http://java.sun.com/index.html"><IMG SRC="/images/javalogo52x88.gif" WIDTH="52" HEIGHT="88" ALT="Java Technology Home Page" BORDER="0"></A>
<BR>
<IMG SRC="/images/pixel.gif" WIDTH="157" HEIGHT="1" ALT=""></TD>
<TD>
<FORM NAME="seek1" METHOD="GET" ACTION="http://search.java.sun.com/query.html">
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="0" WIDTH="100%">
<TR>
<TD ALIGN="RIGHT">
<IMG SRC="/images/stripelt.gif" WIDTH="6" HEIGHT="14" ALT=""></TD>
<TD WIDTH="100%">
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="0" WIDTH="100%">
<TR>
<TD BGCOLOR="#CC9966" WIDTH="100%">
<IMG SRC="/images/pixel.gif" HEIGHT="2" WIDTH="1" ALT=""></TD>
</TR>
<TR>
<TD>
<IMG SRC="/images/pixel.gif" HEIGHT="2" WIDTH="1" ALT=""></TD>
</TR>
<TR>
<TD BGCOLOR="#CC9966">
<IMG SRC="/images/pixel.gif" HEIGHT="2" WIDTH="1" ALT=""></TD>
</TR>
<TR>
<TD>
<IMG SRC="/images/pixel.gif" HEIGHT="2" WIDTH="1" ALT=""></TD>
</TR>
<TR>
<TD BGCOLOR="#CC9966">
<IMG SRC="/images/pixel.gif" HEIGHT="2" WIDTH="1" ALT=""></TD>
</TR>
<TR>
<TD>
<IMG SRC="/images/pixel.gif" HEIGHT="2" WIDTH="1" ALT=""></TD>
</TR>
<TR>
<TD BGCOLOR="#CC9966">
<IMG SRC="/images/pixel.gif" HEIGHT="2" WIDTH="1" ALT=""></TD>
</TR>
</TABLE>
</TD>
<TD ALIGN="LEFT">
<IMG SRC="/images/stripert.gif" WIDTH="6" HEIGHT="14" ALT=""></TD>
<TD>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="0">
<TR>
<TD VALIGN="CENTER">
<A HREF="http://java.sun.com/a-z/index.html"><IMG SRC="/images/azindex.gif" BORDER="0" WIDTH="72" HEIGHT="11" ALT="A-Z Index"></A></TD>
<TD VALIGN="CENTER">
<FONT FACE="Helvetica" SIZE="1">
<INPUT TYPE="text" SIZE="15" MAXLENGTH="128" NAME=qt></FONT></TD>
<TD VALIGN="CENTER">
<INPUT TYPE="image" SRC="/images/search.button.gif"
value="search" BORDER="0" WIDTH="55" HEIGHT="14" ALT="Search"></TD>
</TR>
</TABLE>
</TD>
</TR>
</TABLE>
</FORM>
<P>
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="0" CELLSPACING="0">
<TR VALIGN="TOP">
<TD WIDTH="100%"><IMG SRC="/images/chiclet.row.gif" WIDTH="55"
HEIGHT="18" ALT=""></TD>
<TD ROWSPAN="4" ALIGN="RIGHT" WIDTH="152">
<A HREF="/developer/index.html"><IMG SRC="/images/developer.connection.header.gif" BORDER="0" HEIGHT="42" WIDTH="319" ALT="Java Developer Connection(SM)"></A></TD>
</TR>
<TR VALIGN="TOP">
<TD BGCOLOR="#FFFFFF" HEIGHT="1" WIDTH="100%">
<IMG SRC="/images/pixel.gif" HEIGHT="1" WIDTH="1" ALT=""></TD>
</TR>
<TR VALIGN="TOP">
<TD BGCOLOR="#CC9966" HEIGHT="1" WIDTH="100%">
<IMG SRC="/images/pixel.gif" HEIGHT="1" WIDTH="1" ALT=""></TD>
</TR>
<TR VALIGN="TOP">
<TD><A HREF="/developer/onlineTraining/"><IMG SRC="/images/online-training.gif" ALT="Online Training" BORDER=0></A></TD>
</TR>
</TABLE>
</TD>
</TR>
</TABLE>
<!-- End PageTop Insert -->
<!-- Start NavBar Insert -->
<TABLE BORDER="0" CELLSPACING="0" CELLPADDING="3" BGCOLOR="#FFFFFF" WIDTH="157" ALIGN="LEFT">
<!-- tab categories -->
<TR>
<TD><A HREF="http://java.sun.com/products/"><IMG SRC="/images/side.tab.products.gif" HEIGHT="15" WIDTH="130" BORDER="0" ALT="Downloads, APIs, Documentation"></A></TD>
</TR>
<TR>
<TD><A HREF="/developer/index.html"><IMG SRC="/images/side.tab.developer.gif" HEIGHT="15" WIDTH="130" BORDER="0" ALT="Java Developer Connection"></A></TD>
</TR>
<TR>
<TD><A HREF="/developer/infodocs/index.shtml"><IMG SRC="/images/side.tab.docs.gif" HEIGHT="15" WIDTH="130" BORDER="0" ALT="Tutorials, Tech Articles, Training"></A></TD>
</TR>
<TR>
<TD><A HREF="/developer/support/index.html"><IMG SRC="/images/side.tab.support.gif" HEIGHT="15" WIDTH="130" BORDER="0" ALT="Online Support"></A></TD>
</TR>
<TR>
<TD><A HREF="/developer/community/index.html"><IMG SRC="/images/side.tab.community.gif" HEIGHT="15" WIDTH="130" BORDER="0" ALT="Community Discussion"></A></TD>
</TR>
<TR>
<TD><A HREF="http://java.sun.com/industry/"><IMG SRC="/images/side.tab.news.gif" HEIGHT="15" WIDTH="130" BORDER="0" ALT="News & Events from Everywhere"></A></TD>
</TR>
<TR>
<TD><A HREF="http://java.sun.com/solutions"><IMG SRC="/images/side.tab.solutions.gif" HEIGHT="15" WIDTH="130" BORDER="0" ALT="Products from Everywhere"></A></TD>
</TR>
<TR>
<TD><A HREF="http://java.sun.com/casestudies"><IMG SRC="/images/side.tab.case.gif" HEIGHT="15" WIDTH="130" BORDER="0" ALT="How Java Technology is Used Worldwide"></A></TD>
</TR>
<TR><TD> </TD></TR>
<!-- End NavBar Insert -->
<!-- START SUB-NAV -->
<TR>
<TD><!-- INSERT SUB-NAV INFO -->
</TD>
</TR>
<!-- END SUB-NAV -->
</TABLE>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="0">
<TR>
<TD>
<!-- Template Version 2.0 -->
<!-- ================== -->
<!-- Start Main Content -->
<!-- ================== -->
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="0">
<TR>
<TD VALIGN="TOP">
<FONT FACE="Verdana, Arial, Helvetica, sans-serif">
<A NAME="top"></A>
<DIV ALIGN="RIGHT">
<FONT SIZE="-1"><A HREF="/developer/onlineTraining/index.html">Training Index</A></FONT>
<H2>Writing Advanced Applications<BR>
<FONT SIZE="3">Chapter 5 Continued: Strings and Arrays</FONT></H2>
<FONT SIZE="-1">[<A HREF="jniexamp.html"><<BACK</A>] [<A HREF="index.html#contents">CONTENTS</A>] [<A HREF="jniref.html">NEXT>></A>]</FONT></DIV>
<P>
This section explains how to pass string and array data
between a program written in the Java<FONT SIZE="-2"><SUP>TM</SUP></FONT> programming language and
other languages.
<UL>
<LI><FONT FACE="Verdana, Arial, Helvetica, sans-serif">
<A HREF="#string">Passing Strings</A></FONT>
<LI><FONT FACE="Verdana, Arial, Helvetica, sans-serif">
<A HREF="#array">Passing Arrays</A></FONT>
<LI><FONT FACE="Verdana, Arial, Helvetica, sans-serif">
<A HREF="#pin">Pinning Array</A></FONT>
<LI><FONT FACE="Verdana, Arial, Helvetica, sans-serif">
<A HREF="#object">Object Arrays</A></FONT>
<LI><FONT FACE="Verdana, Arial, Helvetica, sans-serif">
<A HREF="#multi">Multi-Dimensional Arrays</A></FONT>
</UL>
<HR>
<A NAME="string"></A>
<H3>Passing Strings</H3>
The <CODE>String</CODE> object in the Java language, which is
represented as <CODE>jstring</CODE> in Java Native Interface (JNI), is
a 16 bit unicode string. In C a
string is by default constructed from 8 bit characters. So, to
access a Java language <CODE>String</CODE> object passed to a
C or C++ function or return a C or C++ string to a Java language
method, you need to use JNI conversion functions in your native method
implementation.
<P>
The <CODE>GetStringUTFChar</CODE> function retrieves 8-bit
characters from a 16-bit <CODE>jstring</CODE> using the
Unicode Transformation Format
(UTF). UTF represents Unicode as a string of 8 or 16 bit characters
without losing any information. The third parameter
<CODE>GetStringUTFChar</CODE> results the result
<CODE>JNI_TRUE</CODE> if it made a local copy of the
<CODE>jstring</CODE> or <CODE>JNI_FALSE</CODE> otherwise.
<PRE>
<STRONG>C Version:</STRONG>
(*env)->GetStringUTFChars(env, name, iscopy)
<STRONG>C++ Version:</STRONG>
env->GetStringUTFChars(name, iscopy)
</PRE>
<P>
The following C JNI function converts an array
of C characters to a <CODE>jstring</CODE>:
<PRE>
(*env)->NewStringUTF(env, lastfile)
</PRE>
The example below converts the <CODE>lastfile[80]</CODE> C
character array to a <CODE>jstring</CODE>, which is returned
to the calling Java language method:
<PRE>
static char lastfile[80];
JNIEXPORT jstring JNICALL Java_ReadFile_lastFile
(JNIEnv *env, jobject jobj) {
return((*env)->NewStringUTF(env, lastfile));
}
</PRE>
To let the Java<A HREF="#TJVM"><SUP>1</SUP></A> virtual machine know you are finished with the UTF
representation, call the <CODE>ReleaseStringUTFChars</CODE> conversion
function as shown below. The second argument is the original <CODE>jstring</CODE>
value used to construct the UTF representation, and the third argument is the
reference to the local representation of that <CODE>String</CODE>.
<PRE>
(*env)->ReleaseStringUTFChars(env, name, mfile);
</PRE>
If your native code can work with Unicode, without needing the intermediate
UTF representation, call the <CODE>GetStringChars</CODE> function
to retrieve the unicode string, and release the reference with
a call to <CODE>ReleaseStringChars</CODE>:
<PRE>
JNIEXPORT jbyteArray JNICALL Java_ReadFile_loadFile
(JNIEnv * env, jobject jobj, jstring name) {
caddr_t m;
jbyteArray jb;
struct stat finfo;
jboolean iscopy;
const jchar *mfile = (*env)->GetStringChars(env,
name, &iscopy);
//...
(*env)->ReleaseStringChars(env, name, mfile);
</PRE>
<A NAME="array"></A>
<H3>Passing Arrays</H3>
In the example presented in the last section, the
<CODE>loadFile</CODE> native method
returns the contents of a file in a byte array, which is a
primitive type in the Java programming language. You can retrieve and create
primitive types in the Java language by calling the appropriate
<CODE>Type</CODE>Array function.
<P>
For example, to create a new array of floats, call <CODE>NewFloatArray</CODE>,
or to create a new array of bytes, call <CODE>NewByteArray</CODE>. This
naming scheme extends to retrieving elements from, adding elements to, and
changing elements in the array. To get a new array of bytes, call
<CODE>GetByteArrayElements</CODE>. To add elements to or change elements in
the array, call <CODE>Set<type>ArrayElements</CODE>.
<P>
The <CODE>GetByteArrayElements</CODE> function affects the entire array. To
work on a portion of the array, call <CODE>GetByteArrayRegion</CODE> instead.
There is only a <CODE>Set<type>ArrayRegion</CODE> function for
changing array elements.
However the region could be of size 1, which is equivalent
to the non-existent <CODE>Sete<type>ArrayElements</CODE>.
<P>
<TABLE BORDER=2 CELLPADDING=1 CELLSPACING=1>
<TR><TH><FONT FACE="Verdana, Arial, Helvetica, sans-serif">Native<BR>Code Type</FONT></TH><TH><FONT FACE="Verdana, Arial, Helvetica, sans-serif">Functions used</FONT></TH></TR>
<TR><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">jboolean</FONT></TD><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">NewBooleanArray</FONT></TD>
<TR><TD></TD><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">GetBooleanArrayElements</FONT></TD></TR>
<TR><TD></TD><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">GetBooleanArrayRegion/SetBooleanArrayRegion</FONT></TD></TR>
<TR><TD></TD><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">ReleaseBooleanArrayRegion</FONT></TD></TR>
<TR><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">jbyte</FONT></TD><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">NewByteArray</FONT></TD>
<TR><TD></TD><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">GetByteArrayElements</FONT></TD></TR>
<TR><TD></TD><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">GetByteArrayRegion/SetByteArrayRegion</FONT></TD></TR>
<TR><TD></TD><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">ReleaseByteArrayRegion</FONT></TD></TR>
<TR><TD>jchar</TD><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">NewCharArray</FONT></TD>
<TR><TD></TD><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">GetCharArrayElements</FONT></TD></TR>
<TR><TD></TD><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">GetCharArrayRegion/SetCharArrayRegion</FONT></TD></TR>
<TR><TD></TD><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">ReleaseCharArrayRegion</FONT></TD></TR>
<TR><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">jdouble</FONT></TD><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">NewDoubleArray</FONT></TD>
<TR><TD></TD><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">GetDoubleArrayElements</FONT></TD></TR>
<TR><TD></TD><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">GetDoubleArrayRegion/SetDoubleArrayRegion</FONT></TD></TR>
<TR><TD></TD><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">ReleaseDoubleArrayRegion</FONT></TD></TR>
<TR><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">jfloat</FONT></TD><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">NewFloatArray</FONT></TD>
<TR><TD></TD><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">GetFloatArrayElements</FONT></TD></TR>
<TR><TD></TD><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">GetFloatArrayRegion/SetFloatArrayRegion</FONT></TD></TR>
<TR><TD></TD>
<TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">ReleaseFloatArrayRegion</FONT></TD></TR>
<TR><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">jint</FONT></TD><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">NewIntArray</FONT></TD>
<TR><TD></TD><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">GetIntArrayElements</FONT></TD></TR>
<TR><TD></TD><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">GetIntArrayRegion/SetIntArrayRegion</FONT></TD></TR>
<TR><TD></TD><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">ReleaseIntArrayRegion</FONT></TD></TR>
<TR><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">jlong</FONT></TD><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">NewLongArray</FONT></TD>
<TR><TD></TD><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">GetLongArrayElements</FONT></TD></TR>
<TR><TD></TD><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">GetLongArrayRegion/SetLongArrayRegion</FONT></TD></TR>
<TR><TD></TD><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">ReleaseLongArrayRegion</FONT></TD></TR>
<TR><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">jobject</FONT></TD><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">NewObjectArray</FONT></TD>
<TR><TD></TD><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">GetObjectArrayElement/SetObjectArrayElement</FONT></TD></TR>
<TR><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">jshort</FONT></TD><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">NewShortArray</FONT></TD>
<TR><TD></TD><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">GetShortArrayElements</FONT></TD></TR>
<TR><TD></TD><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">GetShortArrayRegion/SetShortArrayRegion</FONT></TD></TR>
<TR><TD></TD><TD><FONT FACE="Verdana, Arial, Helvetica, sans-serif">ReleaseShortArrayRegion</FONT></TD></TR>
</TABLE>
<P>
In the <CODE>loadFile</CODE> native method from the example in the
previous section, the entire array is updated by
specifying a region that is the size of the file being read in:
<PRE>
jbyteArray jb;
jb=(*env)->NewByteArray(env, finfo.st_size);
(*env)->SetByteArrayRegion(env, jb, 0,
finfo.st_size, (jbyte *)m);
close(fd);
</PRE>
The array is returned to the calling Java language
method, which in turn, garbage collects the reference to the array
when it is no longer used. The array can be explicitly freed with
the following call.
<PRE>
(*env)-> ReleaseByteArrayElements(env, jb,
(jbyte *)m, 0);
</PRE>
The last argument to the <CODE>ReleaseByteArrayElements</CODE> function
above can have the following values:
<UL>
<LI><FONT FACE="Verdana, Arial, Helvetica, sans-serif">0: Updates to the array from within the C code are reflected in the
Java language copy.</FONT>
<P>
<LI><FONT FACE="Verdana, Arial, Helvetica, sans-serif"><CODE>JNI_COMMIT</CODE>: The Java language copy is
updated, but the local <CODE>jbyteArray</CODE> is not freed.</FONT>
<P>
<LI><FONT FACE="Verdana, Arial, Helvetica, sans-serif">JNI_ABORT: Changes are not copied back, but the <CODE>jbyteArray</CODE>
is freed. The value is used only if the array is obtained with a get mode of
<CODE>JNI_TRUE</CODE> meaning the array is a copy.</FONT>
</UL>
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -