Start of Tutorial > Start of Trail > Start of Lesson |
Search
Feedback Form |
When a Java application passes a string to a native method, it passes the string as ajstring
type. Thisjstring
type is different from the regular C string type (char *). If your code tries to print ajstring
directly, it will likely result in a VM crash. For example, the following code segment incorrectly tries to print ajstring
and may result in a VM crash:/* DO NOT USE jstring THIS WAY !!! */ JNIEXPORT jstring JNICALL Java_Prompt_getLine(JNIEnv *env, jobject obj, jstring prompt) { printf("%s", prompt); ...Your native method code must use JNI functions to convert Java strings to native strings. The JNI supports the conversion to and from native Unicode and UTF-8 strings. In particular, UTF-8 strings use the highest bit-to-signal multibyte characters; they are therefore upwards-compatible with 7-bit ASCII. In Java, UTF-8 strings are always 0-terminated.
GetStringUTFChars
to correctly print the string passed to it from a Java application. GetStringUTFChars
converts the built-in Unicode representation of a
Java string into a UTF-8 string.
After the jstring
has been converted to
a UTF-8 string, you can directly pass the string to most
regular C language functions,
such as printf
,
as is shown in Prompt.c
:
If the original string contained only characters in the ASCII range of Unicode, then all standard C library functions will work on the UTF-8 string exactly as they would on the corresponding ASCII string (because in this case, they are identical strings). If the original string contained non-ASCII characters, some library functions may not behave as expected if passed the converted, UTF-8 string. For example, the result of passing such a UTF-8 string to theJNIEXPORT jstring JNICALL Java_Prompt_getLine(JNIEnv *env, jobject obj, jstring prompt) { char buf[128]; const char *str = (*env)->GetStringUTFChars(env, prompt, 0); printf("%s", str); (*env)->ReleaseStringUTFChars(env, prompt, str); ...
strlen
function will not be the number of
Unicode characters in the string.
Note: When your native code is finished using the UTF-8 string, it must callReleaseStringUTFChars
.ReleaseStringUTFChars
informs the VM that the native method is finished with the string so that the VM can free the memory taken by the UTF-8 string. Failing to callReleaseStringUTFChars
results in a memory leak. This will ultimately lead to system memory exhaustion.
The native method can also construct a new string using the JNI
function NewStringUTF
. The following lines of code from
Java_Prompt_getLine
show this:
... scanf("%s", buf); return (*env)->NewStringUTF(env, buf); }
Native methods must access and manipulate Java objects, such as
strings, through the env
interface pointer. In C, this
requires using the env
pointer to reference the JNI
function. Notice how the native method uses the env
interface pointer to reference the two functions,
GetStringUTFChars
and ReleaseStringUTFChars
,
that it calls. Not only does the native method use env
as an interface pointer, env
is passed as the first parameter to
these functions.
The JNI also provides functions to obtain the Unicode representation of Java strings. This is useful, for example, on those operating systems that support Unicode as the native format. There are also utility functions to obtain both the UTF-8 and Unicode length of Java strings.
GetStringChars
takes the Java string and returns a
pointer to an array of Unicode characters
that comprise the string.ReleaseStringChars
releases the pointer to the array
of Unicode characters.NewString
constructs a new
java.lang.String
object from an array of Unicode
characters.GetStringLength
returns the length of a string that
is comprised of an array of Unicode characters.GetStringUTFLength
returns the length of a string if
it is represented in the UTF-8 format.Start of Tutorial > Start of Trail > Start of Lesson |
Search
Feedback Form |
Copyright 1995-2005 Sun Microsystems, Inc. All rights reserved.