1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3 <html lang="en-US" xmlns="http://www.w3.org/1999/xhtml" xml:lang=
4 "en">
5 <head>
6 <title>JNI Functions</title>
7 <meta name="collection" content="api" />
8 <link rel="Table of Contents" href="jniTOC.html" />
9 <link rel="Previous" href="types.html" />
10 <link rel="Next" href="invocation.html" />
11 <link rel="Index" href="backcover.html" />
12 </head>
13 <body>
14 <a href="#skip" title="Skip navigation bar"></a>
15 <table width="100%" summary="">
16 <tbody>
17 <tr>
18 <td><a accesskey="c" href="jniTOC.html">Contents</a> |
19 <a accesskey="p" href="types.html">Previous</a> | <a accesskey="n"
20 href="invocation.html">Next</a></td>
21 </tr>
22 </tbody>
23 </table>
24 <a name="skip"></a>
25
26 <h1>Chapter 4: JNI Functions</h1>
27
28 <p>This chapter serves as the reference section for
29 the JNI functions. It provides a complete listing of all the JNI
30 functions. It also presents the exact layout of the JNI function
31 table.</p>
32
33 <p>Note the use of the term “must” to
34 describe restrictions on JNI programmers. For example, when you see
35 that a certain JNI function <em>must</em> receive
36 a non-NULL object, it is your responsibility to ensure that NULL is
37 not passed to that JNI function. As a result, a JNI implementation
38 does not need to perform NULL pointer checks in that JNI
39 function.</p>
40
41 <p>A portion of this chapter is adapted from
42 Netscape’s JRI documentation.</p>
43
44 <p>The reference material groups functions by their
45 usage. The reference section is organized by the following
46 functional areas:</p>
47
48 <ul>
49 <li><a href="#interface_function_table">Interface Function Table</a>
50 <li><a href="#version_information">Version Information</a><ul>
51 <li><a href="#GetVersion">GetVersion</a></li>
52 <li><a href="#Constants">Constants</a></li>
53 </ul></li>
54 <li><a href="#class_operations">Class Operations</a><ul>
55 <li><a href="#DefineClass">DefineClass</a></li>
56 <li><a href="#FindClass">FindClass</a></li>
57 <li><a href="#GetSuperclass">GetSuperclass</a></li>
58 <li><a href="#IsAssignableFrom">IsAssignableFrom</a></li>
59 </ul></li>
60 <li><a href="#exceptions">Exceptions</a><ul>
61 <li><a href="#Throw">Throw</a></li>
62 <li><a href="#ThrowNew">ThrowNew</a></li>
63 <li><a href="#ExceptionOccurred">ExceptionOccurred</a></li>
64 <li><a href="#ExceptionDescribe">ExceptionDescribe</a></li>
65 <li><a href="#ExceptionClear">ExceptionClear</a></li>
66 <li><a href="#FatalError">FatalError</a></li>
67 <li><a href="#ExceptionCheck">ExceptionCheck</a></li>
68 </ul></li>
69 <li><a href="#global_and_local_references">Global and Local References</a><ul>
70 <li><a href="#global_references">Global References</a></li>
71 <li><a href="#NewGlobalRef">NewGlobalRef</a></li>
72 <li><a href="#DeleteGlobalRef">DeleteGlobalRef</a></li>
73 <li><a href="#local_references">Local References</a></li>
74 <li><a href="#DeleteLocalRef">DeleteLocalRef</a></li>
75 <li><a href="#EnsureLocalCapacity">EnsureLocalCapacity</a></li>
76 <li><a href="#PushLocalFrame">PushLocalFrame</a></li>
77 <li><a href="#PopLocalFrame">PopLocalFrame</a></li>
78 <li><a href="#NewLocalRef">NewLocalRef</a></li>
79 </ul></li>
80 <li><a href="#weak_global_references">Weak Global References</a><ul>
81 <li><a href="#NewWeakGlobalRef">NewWeakGlobalRef</a></li>
82 <li><a href="#DeleteWeakGlobalRef">DeleteWeakGlobalRef</a></li>
83 </ul></li>
84 <li><a href="#object_operations">Object Operations</a><ul>
85 <li><a href="#AllocObject">AllocObject</a></li>
86 <li><a href="#NewObject">NewObject, NewObjectA, NewObjectV</a></li>
87 <li><a href="#GetObjectClass">GetObjectClass</a></li>
88 <li><a href="#GetObjectRefType">GetObjectRefType</a></li>
89 <li><a href="#IsInstanceOf">IsInstanceOf</a></li>
90 <li><a href="#IsSameObject">IsSameObject</a></li>
91 </ul></li>
92 <li><a href="#accessing_fields_of_objects">Accessing Fields of Objects</a><ul>
93 <li><a href="#GetFieldID">GetFieldID</a></li>
94 <li><a href="#Get_type_Field_routines">Get<type>Field Routines</a></li>
95 <li><a href="#Set_type_Field_routines">Set<type>Field Routines</a></li>
96 </ul></li>
97 <li><a href="#calling_instance_methods">Calling Instance Methods</a><ul>
98 <li><a href="#GetMethodID">GetMethodID</a></li>
99 <li><a href="#Call_type_Method_routines">Call<type>Method Routines, Call<type>MethodA Routines, Call<type>MethodV Routines</a></li>
100 <li><a href="#CallNonvirtual_type_Method_routines">CallNonvirtual<type>Method Routines, CallNonvirtual<type>MethodA Routines, CallNonvirtual<type>MethodV Routines</a></li>
101 </ul></li>
102 <li><a href="#accessing_static_fields">Accessing Static Fields</a><ul>
103 <li><a href="#GetStaticFieldID">GetStaticFieldID</a></li>
104 <li><a href="#GetStatic_type_Field_routines">GetStatic<type>Field Routines</a></li>
105 <li><a href="#SetStatic_type_Field_routines">SetStatic<type>Field Routines</a></li>
106 </ul></li>
107 <li><a href="#calling_static_methods">Calling Static Methods</a><ul>
108 <li><a href="#GetStaticMethodID">GetStaticMethodID</a></li>
109 <li><a href="#CallStatic_type_Method_routines">CallStatic<type>Method Routines, CallStatic<type>MethodA Routines, CallStatic<type>MethodV Routines</a></li>
110 </ul></li>
111 <li><a href="#string_operations">String Operations</a><ul>
112 <li><a href="#NewString">NewString</a></li>
113 <li><a href="#GetStringLength">GetStringLength</a></li>
114 <li><a href="#GetStringChars">GetStringChars</a></li>
115 <li><a href="#ReleaseStringChars">ReleaseStringChars</a></li>
116 <li><a href="#NewStringUTF">NewStringUTF</a></li>
117 <li><a href="#GetStringUTFLength">GetStringUTFLength</a></li>
118 <li><a href="#GetStringUTFChars">GetStringUTFChars</a></li>
119 <li><a href="#ReleaseStringUTFChars">ReleaseStringUTFChars</a></li>
120 <li><a href="#GetStringRegion">GetStringRegion</a></li>
121 <li><a href="#GetStringUTFRegion">GetStringUTFRegion</a></li>
122 <li><a href="#GetStringCritical_ReleaseStringCritical">GetStringCritical, ReleaseStringCritical</a></li>
123 </ul></li>
124 <li><a href="#array_operations">Array Operations</a><ul>
125 <li><a href="#GetArrayLength">GetArrayLength</a></li>
126 <li><a href="#NewObjectArray">NewObjectArray</a></li>
127 <li><a href="#GetObjectArrayElement">GetObjectArrayElement</a></li>
128 <li><a href="#SetObjectArrayElement">SetObjectArrayElement</a></li>
129 <li><a href="#New_PrimitiveType_Array_routines">New<PrimitiveType>Array Routines</a></li>
130 <li><a href="#Get_PrimitiveType_ArrayElements_routines">Get<PrimitiveType>ArrayElements Routines</a></li>
131 <li><a href="#Release_PrimitiveType_ArrayElements_routines">Release<PrimitiveType>ArrayElements Routines</a></li>
132 <li><a href="#Get_PrimitiveType_ArrayRegion_routines">Get<PrimitiveType>ArrayRegion Routines</a></li>
133 <li><a href="#Set_PrimitiveType_ArrayRegion_routines">Set<PrimitiveType>ArrayRegion Routines</a></li>
134 <li><a href="#GetPrimitiveArrayCritical_ReleasePrimitiveArrayCritical">GetPrimitiveArrayCritical, ReleasePrimitiveArrayCritical</a></li>
135 </ul></li>
136 <li><a href="#registering_native_methods">Registering Native Methods</a><ul>
137 <li><a href="#RegisterNatives">RegisterNatives</a></li>
138 <li><a href="#UnregisterNatives">UnregisterNatives</a></li>
139 </ul></li>
140 <li><a href="#monitor_operations">Monitor Operations</a><ul>
141 <li><a href="#MonitorEnter">MonitorEnter</a></li>
142 <li><a href="#MonitorExit">MonitorExit</a></li>
143 </ul></li>
144 <li><a href="#nio_support">NIO Support</a><ul>
145 <li><a href="#NewDirectByteBuffer">NewDirectByteBuffer</a></li>
146 <li><a href="#GetDirectBufferAddress">GetDirectBufferAddress</a></li>
147 <li><a href="#GetDirectBufferCapacity">GetDirectBufferCapacity</a></li>
148 </ul></li>
149 <li><a href="#reflection_support">Reflection Support</a><ul>
150 <li><a href="#FromReflectedMethod">FromReflectedMethod</a></li>
151 <li><a href="#FromReflectedField">FromReflectedField</a></li>
152 <li><a href="#ToReflectedMethod">ToReflectedMethod</a></li>
153 <li><a href="#ToReflectedField">ToReflectedField</a></li>
154 </ul></li>
155 <li><a href="#java_vm_interface">Java VM Interface</a><ul>
156 <li><a href="#GetJavaVM">GetJavaVM</a></li>
157 </ul></li>
158 </ul>
159
160
161 <!-- ******************************************************** -->
162 <h2><a name="interface_function_table">Interface Function Table</a></h2>
163
164 <p>Each function is accessible at a fixed offset
165 through the <em>JNIEnv</em> argument. The
166 <em>JNIEnv</em> type is a pointer to a structure
167 storing all JNI function pointers. It is defined as follows:</p>
168
169 <pre class="codeblock">typedef const struct JNINativeInterface *JNIEnv;</pre>
170
171 <p>The VM initializes the function table, as shown by the following code example. Note that the first three
172 entries are reserved for future compatibility with COM. In
173 addition, we reserve a number of additional <code>NULL</code> entries near the beginning of the function
174 table, so that, for example, a future class-related JNI operation
175 can be added after FindClass, rather than at the end of the
176 table.</p>
177
178 <p>Note that the function table can be shared among
179 all JNI interface pointers.</p>
180
181 <pre class="codeblock">const struct JNINativeInterface ... = {
182
183 NULL,
184 NULL,
185 NULL,
186 NULL,
187 GetVersion,
188
189 DefineClass,
190 FindClass,
191
192 FromReflectedMethod,
193 FromReflectedField,
194 ToReflectedMethod,
195
196 GetSuperclass,
197 IsAssignableFrom,
198
199 ToReflectedField,
200
201 Throw,
202 ThrowNew,
203 ExceptionOccurred,
204 ExceptionDescribe,
205 ExceptionClear,
206 FatalError,
207
208 PushLocalFrame,
209 PopLocalFrame,
210
211 NewGlobalRef,
212 DeleteGlobalRef,
213 DeleteLocalRef,
214 IsSameObject,
215 NewLocalRef,
216 EnsureLocalCapacity,
217
218 AllocObject,
219 NewObject,
220 NewObjectV,
221 NewObjectA,
222
223 GetObjectClass,
224 IsInstanceOf,
225
226 GetMethodID,
227
228 CallObjectMethod,
229 CallObjectMethodV,
230 CallObjectMethodA,
231 CallBooleanMethod,
232 CallBooleanMethodV,
233 CallBooleanMethodA,
234 CallByteMethod,
235 CallByteMethodV,
236 CallByteMethodA,
237 CallCharMethod,
238 CallCharMethodV,
239 CallCharMethodA,
240 CallShortMethod,
241 CallShortMethodV,
242 CallShortMethodA,
243 CallIntMethod,
244 CallIntMethodV,
245 CallIntMethodA,
246 CallLongMethod,
247 CallLongMethodV,
248 CallLongMethodA,
249 CallFloatMethod,
250 CallFloatMethodV,
251 CallFloatMethodA,
252 CallDoubleMethod,
253 CallDoubleMethodV,
254 CallDoubleMethodA,
255 CallVoidMethod,
256 CallVoidMethodV,
257 CallVoidMethodA,
258
259 CallNonvirtualObjectMethod,
260 CallNonvirtualObjectMethodV,
261 CallNonvirtualObjectMethodA,
262 CallNonvirtualBooleanMethod,
263 CallNonvirtualBooleanMethodV,
264 CallNonvirtualBooleanMethodA,
265 CallNonvirtualByteMethod,
266 CallNonvirtualByteMethodV,
267 CallNonvirtualByteMethodA,
268 CallNonvirtualCharMethod,
269 CallNonvirtualCharMethodV,
270 CallNonvirtualCharMethodA,
271 CallNonvirtualShortMethod,
272 CallNonvirtualShortMethodV,
273 CallNonvirtualShortMethodA,
274 CallNonvirtualIntMethod,
275 CallNonvirtualIntMethodV,
276 CallNonvirtualIntMethodA,
277 CallNonvirtualLongMethod,
278 CallNonvirtualLongMethodV,
279 CallNonvirtualLongMethodA,
280 CallNonvirtualFloatMethod,
281 CallNonvirtualFloatMethodV,
282 CallNonvirtualFloatMethodA,
283 CallNonvirtualDoubleMethod,
284 CallNonvirtualDoubleMethodV,
285 CallNonvirtualDoubleMethodA,
286 CallNonvirtualVoidMethod,
287 CallNonvirtualVoidMethodV,
288 CallNonvirtualVoidMethodA,
289
290 GetFieldID,
291
292 GetObjectField,
293 GetBooleanField,
294 GetByteField,
295 GetCharField,
296 GetShortField,
297 GetIntField,
298 GetLongField,
299 GetFloatField,
300 GetDoubleField,
301 SetObjectField,
302 SetBooleanField,
303 SetByteField,
304 SetCharField,
305 SetShortField,
306 SetIntField,
307 SetLongField,
308 SetFloatField,
309 SetDoubleField,
310
311 GetStaticMethodID,
312
313 CallStaticObjectMethod,
314 CallStaticObjectMethodV,
315 CallStaticObjectMethodA,
316 CallStaticBooleanMethod,
317 CallStaticBooleanMethodV,
318 CallStaticBooleanMethodA,
319 CallStaticByteMethod,
320 CallStaticByteMethodV,
321 CallStaticByteMethodA,
322 CallStaticCharMethod,
323 CallStaticCharMethodV,
324 CallStaticCharMethodA,
325 CallStaticShortMethod,
326 CallStaticShortMethodV,
327 CallStaticShortMethodA,
328 CallStaticIntMethod,
329 CallStaticIntMethodV,
330 CallStaticIntMethodA,
331 CallStaticLongMethod,
332 CallStaticLongMethodV,
333 CallStaticLongMethodA,
334 CallStaticFloatMethod,
335 CallStaticFloatMethodV,
336 CallStaticFloatMethodA,
337 CallStaticDoubleMethod,
338 CallStaticDoubleMethodV,
339 CallStaticDoubleMethodA,
340 CallStaticVoidMethod,
341 CallStaticVoidMethodV,
342 CallStaticVoidMethodA,
343
344 GetStaticFieldID,
345
346 GetStaticObjectField,
347 GetStaticBooleanField,
348 GetStaticByteField,
349 GetStaticCharField,
350 GetStaticShortField,
351 GetStaticIntField,
352 GetStaticLongField,
353 GetStaticFloatField,
354 GetStaticDoubleField,
355
356 SetStaticObjectField,
357 SetStaticBooleanField,
358 SetStaticByteField,
359 SetStaticCharField,
360 SetStaticShortField,
361 SetStaticIntField,
362 SetStaticLongField,
363 SetStaticFloatField,
364 SetStaticDoubleField,
365
366 NewString,
367
368 GetStringLength,
369 GetStringChars,
370 ReleaseStringChars,
371
372 NewStringUTF,
373 GetStringUTFLength,
374 GetStringUTFChars,
375 ReleaseStringUTFChars,
376
377 GetArrayLength,
378
379 NewObjectArray,
380 GetObjectArrayElement,
381 SetObjectArrayElement,
382
383 NewBooleanArray,
384 NewByteArray,
385 NewCharArray,
386 NewShortArray,
387 NewIntArray,
388 NewLongArray,
389 NewFloatArray,
390 NewDoubleArray,
391
392 GetBooleanArrayElements,
393 GetByteArrayElements,
394 GetCharArrayElements,
395 GetShortArrayElements,
396 GetIntArrayElements,
397 GetLongArrayElements,
398 GetFloatArrayElements,
399 GetDoubleArrayElements,
400
401 ReleaseBooleanArrayElements,
402 ReleaseByteArrayElements,
403 ReleaseCharArrayElements,
404 ReleaseShortArrayElements,
405 ReleaseIntArrayElements,
406 ReleaseLongArrayElements,
407 ReleaseFloatArrayElements,
408 ReleaseDoubleArrayElements,
409
410 GetBooleanArrayRegion,
411 GetByteArrayRegion,
412 GetCharArrayRegion,
413 GetShortArrayRegion,
414 GetIntArrayRegion,
415 GetLongArrayRegion,
416 GetFloatArrayRegion,
417 GetDoubleArrayRegion,
418 SetBooleanArrayRegion,
419 SetByteArrayRegion,
420 SetCharArrayRegion,
421 SetShortArrayRegion,
422 SetIntArrayRegion,
423 SetLongArrayRegion,
424 SetFloatArrayRegion,
425 SetDoubleArrayRegion,
426
427 RegisterNatives,
428 UnregisterNatives,
429
430 MonitorEnter,
431 MonitorExit,
432
433 GetJavaVM,
434
435 GetStringRegion,
436 GetStringUTFRegion,
437
438 GetPrimitiveArrayCritical,
439 ReleasePrimitiveArrayCritical,
440
441 GetStringCritical,
442 ReleaseStringCritical,
443
444 NewWeakGlobalRef,
445 DeleteWeakGlobalRef,
446
447 ExceptionCheck,
448
449 NewDirectByteBuffer,
450 GetDirectBufferAddress,
451 GetDirectBufferCapacity,
452
453 GetObjectRefType
454 };
455 </pre>
456
457
458
459 <!-- ******************************************************** -->
460 <h2><a name="version_information">Version Information</a></h2>
461
462 <h3><a name="GetVersion">GetVersion</a></h3>
463
464 <p><code>jint GetVersion(JNIEnv
465 *env);</code></p>
466
467 <p>Returns the version of the native method
468 interface.</p>
469
470 <h4>LINKAGE:</h4>
471 <p>Index 4 in the JNIEnv interface function table.</p>
472 <h4>PARAMETERS:</h4>
473
474 <p><code>env</code>: the JNI interface
475 pointer.</p>
476
477 <h4>RETURNS:</h4>
478
479 <p>Returns the major version number in the higher 16
480 bits and the minor version number in the lower 16 bits.</p>
481
482 <p>In JDK/JRE 1.1, <code class=
483 "cCode">GetVersion()</code> returns <code>0x00010001</code>.</p>
484 <p>In JDK/JRE 1.2, <code>GetVersion()</code> returns
485 <code>0x00010002</code>.</p>
486 <p>In JDK/JRE 1.4, <code>GetVersion()</code> returns
487 <code>0x00010004</code>.</p>
488 <p>In JDK/JRE 1.6, <code>GetVersion()</code> returns
489 <code>0x00010006</code>.</p>
490 <h3><a name="Constants">Constants</a></h3>
491 <h4>SINCE JDK/JRE 1.2:</h4>
492 <pre class="codeblock">
493 #define JNI_VERSION_1_1 0x00010001
494 #define JNI_VERSION_1_2 0x00010002
495
496 /* Error codes */
497 #define JNI_EDETACHED (-2) /* thread detached from the VM */
498 #define JNI_EVERSION (-3) /* JNI version error
499 </pre>
500 <h4>SINCE JDK/JRE 1.4:</h4>
501 <pre class="codeblock">
502 #define JNI_VERSION_1_4 0x00010004
503 </pre>
504 <h4>SINCE JDK/JRE 1.6:</h4>
505 <pre class="codeblock">
506 #define JNI_VERSION_1_6 0x00010006
507 </pre>
508 <!-- ******************************************************** -->
509 <h2><a name="class_operations">Class Operations</a></h2>
510
511 <h3><a name="DefineClass">DefineClass</a></h3>
512
513 <p><code>jclass DefineClass(JNIEnv
514 *env, const char *name, jobject loader,<br />
515 const jbyte *buf, jsize bufLen);</code></p>
516
517 <p>Loads a class from a buffer of raw class data. The
518 buffer containing the raw class data is not referenced by the VM
519 after the DefineClass call returns, and it may be discarded if
520 desired.</p>
521
522 <h4>LINKAGE:</h4>
523 <p>Index 5 in the JNIEnv interface function table.</p>
524 <h4>PARAMETERS:</h4>
525
526 <p><code>env</code>: the JNI interface
527 pointer.</p>
528 <p><code>name</code>: the name of the
529 class or interface to be defined. The string is encoded in modified
530 UTF-8.</p>
531
532 <p><code>loader</code>: a class loader
533 assigned to the defined class.</p>
534
535 <p><code>buf</code>: buffer containing
536 the <code>.class</code> file data.</p>
537
538 <p><code>bufLen</code>: buffer
539 length.</p>
540
541 <h4>RETURNS:</h4>
542
543 <p>Returns a Java class object or <code class=
544 "cCode">NULL</code> if an error occurs.</p>
545
546 <h4>THROWS:</h4>
547
548 <p><code>ClassFormatError</code>: if
549 the class data does not specify a valid class.</p>
550
551 <p><code>ClassCircularityError</code>:
552 if a class or interface would be its own superclass or
553 superinterface.</p>
554
555 <p><code>OutOfMemoryError</code>: if
556 the system runs out of memory.</p>
557 <a name="secExDefineClass"></a>
558 <p><code>SecurityException</code>: if
559 the caller attempts to define a class in the "java" package
560 tree.</p>
561
562 <h3><a name="FindClass">FindClass</a></h3>
563
564 <p><code>jclass FindClass(JNIEnv *env,
565 const char *name);</code></p>
566
567 <p>In JDK release 1.1, this function loads a
568 locally-defined class. It searches the directories and zip files
569 specified by the <code>CLASSPATH</code> environment
570 variable for the class with the specified name.</p>
571 <p>Since Java 2 SDK release 1.2, the Java security model allows
572 non-system classes to load and call native methods.
573 <code>FindClass</code> locates the class loader associated with the
574 current native method; that is, the class loader of the class that
575 declared the native method. If the native method belongs to a
576 system class, no class loader will be involved. Otherwise, the
577 proper class loader will be invoked to load and link the named
578 class.</p>
579 <p>Since Java 2 SDK release 1.2, when <code>FindClass</code> is
580 called through the Invocation Interface, there is no current native
581 method or its associated class loader. In that case, the result of
582 <code>ClassLoader.getSystemClassLoader</code> is used. This is the
583 class loader the virtual machine creates for applications, and is
584 able to locate classes listed in the <code>java.class.path</code>
585 property.</p>
586 <p>The <code>name</code> argument is a fully-qualified class name
587 or an array type signature . For example, the fully-qualified class
588 name for the <code>java.lang.String</code> class is:</p>
589 <pre class="codeblock">
590 <a name="a69011" id=
591 "a69011"> </a> "java/lang/String"
592
593 </pre>
594 <p>The array type signature of the array class
595 <code>java.lang.Object[]</code> is:</p>
596 <pre class="codeblock">
597 <a name="a69010" id=
598 "a69010"> </a> "[Ljava/lang/Object;"
599
600
601 </pre>
602
603 <h4>LINKAGE:</h4>
604 <p>Index 6 in the JNIEnv interface function table.</p>
605 <h4>PARAMETERS:</h4>
606
607 <p><code>env</code>: the JNI interface
608 pointer.</p>
609
610 <p><code>name</code>: a fully-qualified
611 class name (that is, a package name, delimited by
612 “<code>/</code>”, followed by the class
613 name). If the name begins with “<code class=
614 "cCode">[</code>“ (the array signature character), it returns
615 an array class. The string is encoded in modified UTF-8.</p>
616
617 <h4>RETURNS:</h4>
618
619 <p>Returns a class object from a fully-qualified
620 name, or <code>NULL</code> if the class cannot be
621 found.</p>
622
623 <h4>THROWS:</h4>
624
625 <p><code>ClassFormatError</code>: if
626 the class data does not specify a valid class.</p>
627
628 <p><code>ClassCircularityError</code>:
629 if a class or interface would be its own superclass or
630 superinterface.</p>
631
632 <p><code>NoClassDefFoundError</code>:
633 if no definition for a requested class or interface can be
634 found.</p>
635
636 <p><code>OutOfMemoryError</code>: if
637 the system runs out of memory.</p>
638 <h3><a name="GetSuperclass">GetSuperclass</a></h3>
639
640 <p><code>jclass GetSuperclass(JNIEnv
641 *env, jclass clazz);</code></p>
642
643 <p>If <code>clazz</code> represents any
644 class other than the class <code>Object</code>, then
645 this function returns the object that represents the superclass of
646 the class specified by <code>clazz</code>.</p>
647
648 <p>If <code>clazz</code> specifies the
649 class <code>Object</code>, or <code class=
650 "cCode">clazz</code> represents an interface, this function returns
651 <code>NULL</code>.</p>
652
653 <h4>LINKAGE:</h4>
654 <p>Index 10 in the JNIEnv interface function table.</p>
655 <h4>PARAMETERS:</h4>
656
657 <p><code>env</code>: the JNI interface
658 pointer.</p>
659
660 <p><code>clazz</code>: a Java class
661 object.</p>
662
663 <h4>RETURNS:</h4>
664
665 <p>Returns the superclass of the class represented by
666 <code>clazz</code>, or <code class=
667 "cCode">NULL</code>.</p>
668
669 <h3><a name="IsAssignableFrom">IsAssignableFrom</a></h3>
670
671 <p><code>jboolean
672 IsAssignableFrom(JNIEnv *env, jclass clazz1,<br />
673 jclass clazz2);</code></p>
674
675 <p>Determines whether an object of <code class=
676 "cCode">clazz1</code> can be safely cast to <code class=
677 "cCode">clazz2</code>.</p>
678
679 <h4>LINKAGE:</h4>
680 <p>Index 11 in the JNIEnv interface function table.</p>
681 <h4>PARAMETERS:</h4>
682
683 <p><code>env</code>: the JNI interface
684 pointer.</p>
685
686 <p><code>clazz1</code>: the first class
687 argument.</p>
688
689 <p><code>clazz2</code>: the second
690 class argument.</p>
691
692 <h4>RETURNS:</h4>
693
694 <p>Returns <code>JNI_TRUE</code> if
695 either of the following is true:</p>
696
697
698 <ul>
699 <li>The first and second class arguments refer to the same Java
700 class.</li>
701 <li>The first class is a subclass of the second class.</li>
702 <li>The first class has the second class as one of its
703 interfaces.</li>
704 </ul>
705
706
707
708 <!-- ******************************************************** -->
709 <h2><a name="exceptions">Exceptions</a></h2>
710
711 <h3><a name="Throw">Throw</a></h3>
712
713 <p><code>jint Throw(JNIEnv *env,
714 jthrowable obj);</code></p>
715
716 <p>Causes a <code class=
717 "cCode">java.lang.Throwable</code> object to be thrown.</p>
718
719 <h4>LINKAGE:</h4>
720 <p>Index 13 in the JNIEnv interface function table.</p>
721 <h4>PARAMETERS:</h4>
722
723 <p><code>env</code>: the JNI interface
724 pointer.</p>
725
726 <p><code>obj</code>: a <code class=
727 "cCode">java.lang.Throwable</code> object.</p>
728
729 <h4>RETURNS:</h4>
730
731 <p>Returns 0 on success; a negative value on
732 failure.</p>
733
734 <h4>THROWS:</h4>
735
736 <p>the <code>java.lang.Throwable</code>
737 <code>object</code> <code class=
738 "cCode">obj</code><code>.</code></p>
739
740 <h3><a name="ThrowNew">ThrowNew</a></h3>
741
742 <p><code>jint ThrowNew(JNIEnv *env,
743 jclass clazz,<br />
744 const char *message);</code></p>
745
746 <p>Constructs an exception object from the specified
747 class with the message specified by <code class=
748 "cCode">message</code> and causes that exception to be thrown.</p>
749
750 <h4>LINKAGE:</h4>
751 <p>Index 14 in the JNIEnv interface function table.</p>
752 <h4>PARAMETERS:</h4>
753
754 <p><code>env</code>: the JNI interface
755 pointer.</p>
756
757 <p><code>clazz</code>: a subclass of
758 <code>java.lang.Throwable</code>.</p>
759
760 <p><code>message</code>: the message
761 used to construct the <code class=
762 "cCode">java.lang.Throwable</code> object. The string is encoded in
763 modified UTF-8.</p>
764
765 <h4>RETURNS:</h4>
766
767 <p>Returns 0 on success; a negative value on
768 failure.</p>
769
770 <h4>THROWS:</h4>
771
772 <p>the newly constructed <code class=
773 "cCode">java.lang.Throwable</code> object.</p>
774
775 <h3><a name="ExceptionOccurred">ExceptionOccurred</a></h3>
776
777 <p><code>jthrowable
778 ExceptionOccurred(JNIEnv *env);</code></p>
779
780 <p>Determines if an exception is being thrown. The
781 exception stays being thrown until either the native code calls
782 <code>ExceptionClear()</code>, or the Java code
783 handles the exception.</p>
784
785 <h4>LINKAGE:</h4>
786 <p>Index 15 in the JNIEnv interface function table.</p>
787 <h4>PARAMETERS:</h4>
788
789 <p><code>env</code>: the JNI interface
790 pointer.</p>
791
792 <h4>RETURNS:</h4>
793
794 <p>Returns the exception object that is currently in
795 the process of being thrown, or <code>NULL</code> if
796 no exception is currently being thrown.</p>
797
798 <h3><a name="ExceptionDescribe">ExceptionDescribe</a></h3>
799
800 <p><code>void ExceptionDescribe(JNIEnv
801 *env);</code></p>
802
803 <p>Prints an exception and a backtrace of the stack
804 to a system error-reporting channel, such as <code class=
805 "cCode">stderr</code>. This is a convenience routine provided for
806 debugging.</p>
807
808 <h4>LINKAGE:</h4>
809 <p>Index 16 in the JNIEnv interface function table.</p>
810 <h4>PARAMETERS:</h4>
811
812 <p><code>env</code>: the JNI interface
813 pointer.</p>
814
815 <h3><a name="ExceptionClear">ExceptionClear</a></h3>
816
817 <p><code>void ExceptionClear(JNIEnv
818 *env);</code></p>
819
820 <p>Clears any exception that is currently being
821 thrown. If no exception is currently being thrown, this routine has
822 no effect.</p>
823
824 <h4>LINKAGE:</h4>
825 <p>Index 17 in the JNIEnv interface function table.</p>
826 <h4>PARAMETERS:</h4>
827
828 <p><code>env</code>: the JNI interface
829 pointer.</p>
830
831 <h3><a name="FatalError">FatalError</a></h3>
832
833 <p><code>void FatalError(JNIEnv *env,
834 const char *msg);</code></p>
835
836 <p>Raises a fatal error and does not expect the VM to
837 recover. This function does not return.</p>
838
839 <h4>LINKAGE:</h4>
840 <p>Index 18 in the JNIEnv interface function table.</p>
841 <h4>PARAMETERS:</h4>
842
843 <p><code>env</code>: the JNI interface
844 pointer.</p>
845
846 <p><code>msg</code>: an error message.
847 The string is encoded in modified UTF-8.</p>
848
849 <h3><a name="ExceptionCheck">ExceptionCheck</a></h3>
850 We introduce a convenience function to check for pending exceptions
851 without creating a local reference to the exception object.
852 <p><code>jboolean
853 ExceptionCheck(JNIEnv *env);</code></p>
854 <p>Returns <code>JNI_TRUE</code> when there is a pending exception;
855 otherwise, returns <code>JNI_FALSE</code>.</p>
856 <h4>LINKAGE:</h4>
857 Index 228 in the JNIEnv interface function table.
858 <h4>SINCE:</h4>
859 <p>JDK/JRE 1.2</p>
860 <a name="weakrefs"></a>
861
862 <!-- ******************************************************** -->
863 <h2><a name="global_and_local_references">Global and Local References</a></h2>
864
865 <h3><a name="global_references">Global References</a></h3>
866
867 <h3><a name="NewGlobalRef">NewGlobalRef</a></h3>
868
869 <p><code>jobject NewGlobalRef(JNIEnv
870 *env, jobject obj);</code></p>
871
872 <p>Creates a new global reference to the object
873 referred to by the <code>obj</code> argument. The
874 <code>obj</code> argument may be a global or local
875 reference. Global references must be explicitly disposed of by
876 calling <code>DeleteGlobalRef()</code>.</p>
877
878 <h4>LINKAGE:</h4>
879 <p>Index 21 in the JNIEnv interface function table.</p>
880 <h4>PARAMETERS:</h4>
881
882 <p><code>env</code>: the JNI interface
883 pointer.</p>
884
885 <p><code>obj</code>: a global or local
886 reference.</p>
887
888 <h4>RETURNS:</h4>
889
890 <p>Returns a global reference, or <code class=
891 "cCode">NULL</code> if the system runs out of memory.</p>
892
893 <h3><a name="DeleteGlobalRef">DeleteGlobalRef</a></h3>
894
895 <p><code>void DeleteGlobalRef(JNIEnv
896 *env, jobject globalRef);</code></p>
897
898 <p>Deletes the global reference pointed to by
899 <code>globalRef</code>.</p>
900
901 <h4>LINKAGE:</h4>
902 <p>Index 22 in the JNIEnv interface function
903 table.</p>
904 <h4>PARAMETERS:</h4>
905
906 <p><code>env</code>: the JNI interface
907 pointer.</p>
908
909 <p><code>globalRef</code>: a global
910 reference.</p>
911
912 <h3><a name="local_references">Local References</a></h3>
913
914 <p>Local references are valid for the duration of a native method
915 call. They are freed automatically after the native method returns.
916 Each local reference costs some amount of Java Virtual Machine
917 resource. Programmers need to make sure that native methods do not
918 excessively allocate local references. Although local references
919 are automatically freed after the native method returns to Java,
920 excessive allocation of local references may cause the VM to run
921 out of memory during the execution of a native method.</p>
922
923 <h3><a name="DeleteLocalRef">DeleteLocalRef</a></h3>
924
925 <p><code>void DeleteLocalRef(JNIEnv
926 *env, jobject localRef);</code></p>
927
928 <p>Deletes the local reference pointed to by
929 <code>localRef</code>.</p>
930
931 <h4>LINKAGE:</h4>
932 <p>Index 23 in the JNIEnv interface function table.</p>
933 <h4>PARAMETERS:</h4>
934
935 <p><code>env</code>: the JNI interface
936 pointer.</p>
937
938 <p><code>localRef</code>: a local
939 reference.</p>
940
941 <p><strong>Note</strong>: JDK/JRE 1.1 provides the <code>DeleteLocalRef</code> function
942 above so that programmers can manually delete local references. For
943 example, if native code iterates through a potentially large array
944 of objects and uses one element in each iteration, it is a good
945 practice to delete the local reference to the no-longer-used array
946 element before a new local reference is created in the next
947 iteration.</p>
948 <p>As of JDK/JRE 1.2 an additional set of functions are provided
949 for local reference lifetime management. They are the four
950 functions listed below.</p>
951
952 <h3><a name="EnsureLocalCapacity">EnsureLocalCapacity</a></h3>
953
954 <p><code>jint EnsureLocalCapacity(JNIEnv *env, jint
955 capacity);</code></p>
956 <p>Ensures that <em>at least</em> a given number of local
957 references can be created in the current thread. Returns 0 on
958 success; otherwise returns a negative number and throws an
959 <code>OutOfMemoryError</code>.</p>
960 <p>Before it enters a native method, the VM automatically ensures
961 that at least <strong>16</strong> local references can be
962 created.</p>
963 <p>For backward compatibility, the VM allocates local references
964 beyond the ensured capacity. (As a debugging support, the VM may
965 give the user warnings that too many local references are being
966 created. In the JDK, the programmer can supply the
967 <code>-verbose:jni</code> command line option to turn on these
968 messages.) The VM calls <code>FatalError</code> if no more local
969 references can be created beyond the ensured capacity.</p>
970 <h4>LINKAGE:</h4>
971 Index 26 in the JNIEnv interface function table.
972 <h4>SINCE:</h4>
973 <p>JDK/JRE 1.2</p>
974 <h3><a name="PushLocalFrame">PushLocalFrame</a></h3>
975 <p><code>jint
976 PushLocalFrame(JNIEnv *env, jint capacity);</code></p>
977 <p>Creates a new local reference frame, in which at least a given
978 number of local references can be created. Returns 0 on success, a
979 negative number and a pending <code>OutOfMemoryError</code> on
980 failure.</p>
981 <p>Note that local references already created in previous local
982 frames are still valid in the current local frame.</p>
983 <h4>LINKAGE:</h4>
984 Index 19 in the JNIEnv interface function table.
985 <h4>SINCE:</h4>
986 <p>JDK/JRE 1.2</p>
987 <h3><a name="PopLocalFrame">PopLocalFrame</a></h3>
988 <p><code>jobject
989 PopLocalFrame(JNIEnv *env, jobject result);</code></p>
990 <p>Pops off the current local reference frame, frees all the local
991 references, and returns a local reference in the previous local
992 reference frame for the given <code>result</code> object.</p>
993 <p>Pass <code>NULL</code> as <code>result</code> if you do not need
994 to return a reference to the previous frame.</p>
995 <h4>LINKAGE:</h4>
996 Index 20 in the JNIEnv interface function table.
997 <h4>SINCE:</h4>
998 <p>JDK/JRE 1.2</p>
999 <h3><a name="NewLocalRef">NewLocalRef</a></h3>
1000 <p><code>jobject
1001 NewLocalRef(JNIEnv *env, jobject ref);</code></p>
1002 <p>Creates a new local reference that refers to the same object as
1003 <code>ref</code>. The given <code>ref</code> may be a global or
1004 local reference. Returns <code>NULL</code> if <code>ref</code>
1005 refers to <code>null</code>.</p>
1006 <h4>LINKAGE:</h4>
1007 Index 25 in the JNIEnv interface function table.
1008 <h4>SINCE:</h4>
1009 <p>JDK/JRE 1.2</p>
1010 <!-- ******************************************************** -->
1011 <h2><a name="weak_global_references">Weak Global References</a></h2>
1012 Weak global references are a special kind of global reference.
1013 Unlike normal global references, a weak global reference allows the
1014 underlying Java object to be garbage collected. Weak global
1015 references may be used in any situation where global or local
1016 references are used. When the garbage collector runs, it frees the
1017 underlying object if the object is only referred to by weak
1018 references. A weak global reference pointing to a freed object is
1019 functionally equivalent to <code>NULL</code>. Programmers can
1020 detect whether a weak global reference points to a freed object by
1021 using <code>IsSameObject</code> to compare the weak reference
1022 against <code>NULL</code>.
1023 <p>Weak global references in JNI are a simplified version of the
1024 Java Weak References, available as part of the Java 2 Platform API
1025 ( <code>java.lang.ref</code> package and its classes). <a name=
1026 "weakrefs__clarification"></a></p>
1027 <p><strong>Clarification</strong> <i>(added June
1028 2001)</i></p>
1029 <p><i>Since garbage collection may occur while native methods are
1030 running, objects referred to by weak global references can be freed
1031 at any time. While weak global references can be used where global
1032 references are used, it is generally inappropriate to do so, as
1033 they may become functionally equivalent to</i> <code>NULL</code>
1034 <i>without notice.</i></p>
1035 <p><i>While</i> <code>IsSameObject</code> <i>can be used to
1036 determine whether a weak global reference refers to a freed object,
1037 it does not prevent the object from being freed immediately
1038 thereafter. Consequently, programmers may not rely on this check to
1039 determine whether a weak global reference may used (as a
1040 non-</i><code>NULL</code> <i>reference) in any future JNI function
1041 call.</i></p>
1042 <p><i>To overcome this inherent limitation, it is recommended that
1043 a standard (strong) local or global reference to the same object be
1044 acquired using the JNI functions</i> <code>NewLocalRef</code>
1045 <i>or</i> <code>NewGlobalRef</code><i>, and that this strong
1046 reference be used to access the intended object. These functions
1047 will return</i> <code>NULL</code> <i>if the object has been freed,
1048 and otherwise will return a strong reference (which will prevent
1049 the object from being freed). The new reference should be
1050 explicitly deleted when immediate access to the object is no longer
1051 required, allowing the object to be freed.</i></p>
1052 <p><i>The weak global reference is weaker than other types of weak
1053 references (Java objects of the SoftReference or WeakReference
1054 classes). A weak global reference to a specific object will not
1055 become functionally equivalent to</i> <code>NULL</code> <i>until
1056 after SoftReference or WeakReference objects referring to that same
1057 specific object have had their references cleared.</i></p>
1058 <p><i>The weak global reference is weaker than Java's internal
1059 references to objects requiring finalization. A weak global
1060 reference will not become functionally equivalent to</i>
1061 <code>NULL</code> <i>until after the completion of the finalizer
1062 for the referenced object, if present.</i></p>
1063 <p><i>Interactions between weak global references and
1064 PhantomReferences are undefined. In particular, implementations of
1065 a Java VM may (or may not) process weak global references after
1066 PhantomReferences, and it may (or may not) be possible to use weak
1067 global references to hold on to objects which are also referred to
1068 by PhantomReference objects. This undefined use of weak global
1069 references should be avoided.</i></p>
1070 <h3><a name="NewWeakGlobalRef">NewWeakGlobalRef</a></h3>
1071 <p><code>jweak NewWeakGlobalRef(JNIEnv *env, jobject
1072 obj);</code></p>
1073 <p>Creates a new weak global reference. Returns <code>NULL</code>
1074 if <code>obj</code> refers to <code>null</code>, or if the VM runs
1075 out of memory. If the VM runs out of memory, an
1076 <code>OutOfMemoryError</code> will be thrown.</p>
1077 <h4>LINKAGE:</h4>
1078 Index 226 in the JNIEnv interface function table.
1079 <h4>SINCE:</h4>
1080 <p>JDK/JRE 1.2</p>
1081 <h3><a name="DeleteWeakGlobalRef">DeleteWeakGlobalRef</a></h3>
1082 <p><code>void DeleteWeakGlobalRef(JNIEnv *env, jweak
1083 obj);</code></p>
1084 <p>Delete the VM resources needed for the given weak global
1085 reference.</p>
1086 <h4>LINKAGE:</h4>
1087 Index 227 in the JNIEnv interface function table.
1088 <h4>SINCE:</h4>
1089 <p>JDK/JRE 1.2<a name="arrayops"></a></p>
1090 <!-- ******************************************************** -->
1091 <h2><a name="object_operations">Object Operations</a></h2>
1092
1093 <h3><a name="AllocObject">AllocObject</a></h3>
1094
1095 <p><code>jobject AllocObject(JNIEnv
1096 *env, jclass clazz);</code></p>
1097
1098 <p>Allocates a new Java object without invoking any
1099 of the constructors for the object. Returns a reference to the
1100 object.</p>
1101
1102 <p>The clazz argument must not refer to an array
1103 class.</p>
1104
1105 <h4>LINKAGE:</h4>
1106 <p>Index 27 in the JNIEnv interface function table.</p>
1107 <h4>PARAMETERS:</h4>
1108
1109 <p><code>env</code>: the JNI interface
1110 pointer.</p>
1111
1112 <p><code>clazz</code>: a Java class
1113 object.</p>
1114
1115 <h4>RETURNS:</h4>
1116
1117 <p>Returns a Java object, or <code class=
1118 "cCode">NULL</code> if the object cannot be constructed.</p>
1119
1120 <h4>THROWS:</h4>
1121
1122 <p><code>InstantiationException</code>:
1123 if the class is an interface or an abstract class.</p>
1124
1125 <p><code>OutOfMemoryError</code>: if
1126 the system runs out of memory.</p>
1127
1128 <h3><a name="NewObject">NewObject, NewObjectA, NewObjectV</a></h3>
1129
1130 <p><code>jobject NewObject(JNIEnv *env,
1131 jclass clazz,<br />
1132 jmethodID methodID, ...);</code></p>
1133
1134 <p><code>jobject NewObjectA(JNIEnv
1135 *env, jclass clazz,<br />
1136 jmethodID methodID, const jvalue *args);</code></p>
1137
1138 <p><code>jobject NewObjectV(JNIEnv
1139 *env, jclass clazz,<br />
1140 jmethodID methodID, va_list args);</code></p>
1141
1142 <p>Constructs a new Java object. The method ID
1143 indicates which constructor method to invoke. This ID must be
1144 obtained by calling <code>GetMethodID()</code> with
1145 <code><init></code> as the method name and
1146 <code>void</code> (<code>V</code>) as
1147 the return type.</p>
1148
1149 <p>The <code>clazz</code> argument must
1150 not refer to an array class.</p>
1151
1152 <h4>NewObject</h4>
1153
1154 <p>Programmers place all arguments that are to be
1155 passed to the constructor immediately following the <code class=
1156 "cCode">methodID</code> argument. <code class=
1157 "cCode">NewObject()</code> accepts these arguments and passes them
1158 to the Java method that the programmer wishes to invoke.</p>
1159
1160 <h4>LINKAGE:</h4>
1161 <p>Index 28 in the JNIEnv interface function table.</p>
1162 <h4>NewObjectA</h4>
1163
1164 <p>Programmers place all arguments that are to be
1165 passed to the constructor in an <code>args</code>
1166 array of <code>jvalues</code> that immediately
1167 follows the <code>methodID</code> argument.
1168 <code>NewObjectA()</code> accepts the arguments in
1169 this array, and, in turn, passes them to the Java method that the
1170 programmer wishes to invoke.</p>
1171
1172 <h4>LINKAGE:</h4>
1173 <p>Index 30 in the JNIEnv interface function table.</p>
1174 <h4>NewObjectV</h4>
1175
1176 <p>Programmers place all arguments that are to be
1177 passed to the constructor in an <code>args</code>
1178 argument of type <code>va_list</code> that
1179 immediately follows the <code>methodID</code>
1180 argument. <code>NewObjectV()</code> accepts these
1181 arguments, and, in turn, passes them to the Java method that the
1182 programmer wishes to invoke.</p>
1183
1184 <h4>LINKAGE:</h4>
1185 <p>Index 29 in the JNIEnv interface function table.</p>
1186 <h4>PARAMETERS:</h4>
1187
1188 <p><code>env</code>: the JNI interface
1189 pointer.</p>
1190
1191 <p><code>clazz</code>: a Java class
1192 object.</p>
1193
1194 <p><code>methodID</code>: the method ID
1195 of the constructor.</p>
1196
1197 <h4>Additional Parameter for NewObject:</h4>
1198
1199 <p>arguments to the constructor.</p>
1200
1201 <h4>Additional Parameter for NewObjectA:</h4>
1202
1203 <p><code>args</code>: an array of
1204 arguments to the constructor.</p>
1205
1206 <h4>Additional Parameter for NewObjectV:</h4>
1207
1208 <p><code>args</code>: a va_list of
1209 arguments to the constructor.</p>
1210
1211 <h4>RETURNS:</h4>
1212
1213 <p>Returns a Java object, or <code class=
1214 "cCode">NULL</code> if the object cannot be constructed.</p>
1215
1216 <h4>THROWS:</h4>
1217
1218 <p><code>InstantiationException</code>:
1219 if the class is an interface or an abstract class.</p>
1220
1221 <p><code>OutOfMemoryError</code>: if
1222 the system runs out of memory.</p>
1223
1224 <p>Any exceptions thrown by the constructor.</p>
1225
1226 <h3><a name="GetObjectClass">GetObjectClass</a></h3>
1227
1228 <p><code>jclass GetObjectClass(JNIEnv
1229 *env, jobject obj);</code></p>
1230 <p>Returns the class of an object.</p>
1231
1232 <h4>LINKAGE:</h4>
1233 <p>Index 31 in the JNIEnv interface function table.</p>
1234 <h4>PARAMETERS:</h4>
1235
1236 <p><code>env</code>: the JNI interface
1237 pointer.</p>
1238
1239 <p><code>obj</code>: a Java object
1240 (must not be <code>NULL</code>).</p>
1241
1242 <h4>RETURNS:</h4>
1243
1244 <p>Returns a Java class object.</p>
1245 <!-- ******** added 9.30.05. works in j6.0 -->
1246 <a name="objreftype"></a>
1247 <h3><a name="GetObjectRefType">GetObjectRefType</a></h3>
1248
1249 <p><code>jobjectRefType
1250 GetObjectRefType(JNIEnv* env, jobject obj);</code></p>
1251
1252
1253 <p>Returns the type of the object referred to by the
1254 <code>obj</code> argument. The argument <code>obj</code> can either
1255 be a local, global or weak global reference.</p>
1256 <h4>LINKAGE:</h4>
1257 <p>Index 232 in the JNIEnv interface function table.</p>
1258 <h4>PARAMETERS:</h4>
1259 <p><code>env</code>: the JNI interface
1260 pointer.</p>
1261 <p><code>obj</code>: a local, global or
1262 weak global reference.<br />
1263 <br />
1264 <code>vm</code>: the virtual machine instance from
1265 which the interface will be retrieved.<br />
1266 <br />
1267 <code>env</code>: pointer to the location where the
1268 JNI interface pointer for the current thread will be placed.<br />
1269 <br />
1270 <code>version</code>: the requested JNI version.</p>
1271 <h4>RETURNS:</h4>
1272
1273 <p>The function <code>GetObjectRefType</code> returns
1274 one of the following enumerated values defined as a <code class=
1275 "cCode">jobjectRefType</code>:</p>
1276 <code>JNIInvalidRefType = 0,</code><br />
1277 <code>JNILocalRefType = 1,</code><br />
1278 <code>JNIGlobalRefType = 2,</code><br />
1279 <code>JNIWeakGlobalRefType = 3</code>
1280 <p>If the argument <code>obj</code> is a weak global reference
1281 type, the return will be <code class=
1282 "cCode">JNIWeakGlobalRefType</code>.</p>
1283 <p>If the argument <code>obj</code> is a global reference type, the
1284 return value will be <code class=
1285 "cCode">JNIGlobalRefType</code>.</p>
1286 <p>If the argument <code>obj</code> is a local reference type, the
1287 return will be <code>JNILocalRefType</code>.</p>
1288 <p>If the <code>obj</code> argument is not a valid reference, the
1289 return value for this function will be <code class=
1290 "cCode">JNIInvalidRefType</code>.</p>
1291 <p>An invalid reference is a reference which is not a valid handle.
1292 That is, the <code>obj</code> pointer address does not point to a
1293 location in memory which has been allocated from one of the Ref
1294 creation functions or returned from a JNI function.</p>
1295 <p>As such, <code>NULL</code> would be an invalid
1296 reference and <code>GetObjectRefType(env,NULL)</code>
1297 would return <code>JNIInvalidRefType</code>.</p>
1298 <p>On the other hand, a null reference, which is a reference that
1299 points to a null, would return the type of reference that the null
1300 reference was originally created as.</p>
1301 <p><code>GetObjectRefType</code> cannot be used on
1302 deleted references.</p>
1303 <p>Since references are typically implemented as pointers to memory
1304 data structures that can potentially be reused by any of the
1305 reference allocation services in the VM, once deleted, it is not
1306 specified what value the <code class=
1307 "cCode">GetObjectRefType</code> will return.</p>
1308 <h4>SINCE:</h4>
1309 <p>JDK/JRE 1.6</p>
1310 <!-- ********** end getobjectreftype v6 stuff ************** -->
1311
1312 <h3><a name="IsInstanceOf">IsInstanceOf</a></h3>
1313
1314 <p><code>jboolean IsInstanceOf(JNIEnv
1315 *env, jobject obj,<br />
1316 jclass clazz);</code></p>
1317
1318 <p>Tests whether an object is an instance of a
1319 class.</p>
1320
1321 <h4>LINKAGE:</h4>
1322 <p>Index 32 in the JNIEnv interface function table.</p>
1323 <h4>PARAMETERS:</h4>
1324
1325 <p><code>env</code>: the JNI interface
1326 pointer.</p>
1327
1328 <p><code>obj</code>: a Java object.</p>
1329
1330 <p><code>clazz</code>: a Java class
1331 object.</p>
1332
1333 <h4>RETURNS:</h4>
1334
1335 <p>Returns <code>JNI_TRUE</code> if
1336 <code>obj</code> can be cast to <code class=
1337 "cCode">clazz</code>; otherwise, returns <code class=
1338 "cCode">JNI_FALSE</code>. A <code>NULL</code> object
1339 can be cast to any class.</p>
1340
1341 <h3><a name="IsSameObject">IsSameObject</a></h3>
1342
1343 <p><code>jboolean IsSameObject(JNIEnv
1344 *env, jobject ref1,<br />
1345 jobject ref2);</code></p>
1346
1347 <p>Tests whether two references refer to the same
1348 Java object.</p>
1349
1350 <h4>LINKAGE:</h4>
1351 <p>Index 24 in the JNIEnv interface function table.</p>
1352 <h4>PARAMETERS:</h4>
1353
1354 <p><code>env</code>: the JNI interface
1355 pointer.</p>
1356
1357 <p><code>ref1</code>: a Java
1358 object.</p>
1359
1360 <p><code>ref2</code>: a Java
1361 object.</p>
1362
1363 <h4>RETURNS:</h4>
1364
1365 <p>Returns <code>JNI_TRUE</code> if
1366 <code>ref1</code> and <code>ref2</code>
1367 refer to the same Java object, or are both <code class=
1368 "cCode">NULL</code>; otherwise, returns <code class=
1369 "cCode">JNI_FALSE</code>.</p>
1370
1371 <!-- ******************************************************** -->
1372 <h2><a name="accessing_fields_of_objects">Accessing Fields of Objects</a></h2>
1373
1374 <h3><a name="GetFieldID">GetFieldID</a></h3>
1375
1376 <p><code>jfieldID GetFieldID(JNIEnv
1377 *env, jclass clazz,<br />
1378 const char *name, const char *sig);</code></p>
1379
1380 <p>Returns the field ID for an instance (nonstatic)
1381 field of a class. The field is specified by its name and signature.
1382 The <em>Get<type>Field</em> and <em class=
1383 "cEmphasis">Set<type>Field</em> families of accessor
1384 functions use field IDs to retrieve object fields.</p>
1385
1386 <p><code>GetFieldID()</code> causes an
1387 uninitialized class to be initialized.</p>
1388
1389 <p><code>GetFieldID()</code> cannot be
1390 used to obtain the length field of an array. Use <code class=
1391 "cCode">GetArrayLength()</code> instead.</p>
1392
1393 <h4>LINKAGE:</h4>
1394 <p>Index 94 in the JNIEnv interface function table.</p>
1395 <h4>PARAMETERS:</h4>
1396
1397 <p><code>env</code>: the JNI interface
1398 pointer.</p>
1399
1400 <p><code>clazz</code>: a Java class
1401 object.</p>
1402
1403 <p><code>name</code>: the field name in
1404 a 0-terminated modified UTF-8 string.</p>
1405
1406 <p><code>sig</code>: the field
1407 signature in a 0-terminated modified UTF-8 string.</p>
1408
1409 <h4>RETURNS:</h4>
1410
1411 <p>Returns a field ID, or <code class=
1412 "cCode">NULL</code> if the operation fails.</p>
1413
1414 <h4>THROWS:</h4>
1415
1416 <p><code>NoSuchFieldError</code>: if
1417 the specified field cannot be found.</p>
1418
1419 <p><code class=
1420 "cCode">ExceptionInInitializerError</code>: if the class
1421 initializer fails due to an exception.</p>
1422
1423 <p><code>OutOfMemoryError</code>: if
1424 the system runs out of memory.</p>
1425
1426 <h3><a name="Get_type_Field_routines">Get<type>Field Routines</a></h3>
1427
1428 <p><em>NativeType</em> <em class=
1429 "cEmphasis">Get<type>Field</em><code>(JNIEnv
1430 *env, jobject obj,<br />
1431 jfieldID fieldID);</code></p>
1432
1433 <p>This family of accessor routines returns the value
1434 of an instance (nonstatic) field of an object. The field to access
1435 is specified by a field ID obtained by calling <code class=
1436 "cCode">GetFieldID()</code>.</p>
1437
1438 <p>The following table describes the
1439 Get<type>Field routine name and result type. You should
1440 replace <em>type</em> in <em class=
1441 "cEmphasis">Get<type>Field</em> with the Java type of the
1442 field, or use one of the actual routine names from the table, and
1443 replace <em>NativeType</em> with the
1444 corresponding native type for that routine.</p>
1445
1446 <table border="1" summary="Get <type>Field Family of Accessor Routine">
1447 <caption>Get<type>Field Family of Accessor Routines</caption>
1448 <thead>
1449 <tr>
1450 <th>
1451
1452 Get<type>Field Routine Name
1453 </th>
1454 <th>
1455 Native Type
1456 </th>
1457 </tr>
1458 </thead>
1459 <tbody>
1460 <tr>
1461 <td>
1462 <code class=
1463 "cCode">GetObjectField()</code>
1464 </td>
1465 <td>
1466 jobject
1467 </td>
1468 </tr>
1469 <tr>
1470 <td>
1471 <code class=
1472 "cCode">GetBooleanField()</code>
1473 </td>
1474 <td>
1475 jboolean
1476 </td>
1477 </tr>
1478 <tr>
1479 <td>
1480 <code class=
1481 "cCode">GetByteField()</code>
1482 </td>
1483 <td>
1484 jbyte
1485 </td>
1486 </tr>
1487 <tr>
1488 <td>
1489 <code class=
1490 "cCode">GetCharField()</code>
1491 </td>
1492 <td>
1493 jchar
1494 </td>
1495 </tr>
1496 <tr>
1497 <td>
1498 <code class=
1499 "cCode">GetShortField()</code>
1500 </td>
1501 <td>
1502 jshort
1503 </td>
1504 </tr>
1505 <tr>
1506 <td>
1507 <code class=
1508 "cCode">GetIntField()</code>
1509 </td>
1510 <td>
1511 jint
1512 </td>
1513 </tr>
1514 <tr>
1515 <td>
1516 <code class=
1517 "cCode">GetLongField()</code>
1518 </td>
1519 <td>
1520 jlong
1521 </td>
1522 </tr>
1523 <tr>
1524 <td>
1525 <code class=
1526 "cCode">GetFloatField()</code>
1527 </td>
1528 <td>
1529 jfloat
1530 </td>
1531 </tr>
1532 <tr>
1533 <td>
1534 <code class=
1535 "cCode">GetDoubleField()</code>
1536 </td>
1537 <td>
1538 jdouble
1539 </td>
1540 </tr>
1541 </tbody>
1542 </table>
1543
1544
1545
1546 <h4>LINKAGE:</h4>
1547
1548 <p>Indices in the JNIEnv interface function table:</p>
1549
1550 <table border="1" summary=
1551 "Get <type>Field Family of Accessor Routine">
1552 <caption>Get<type>Field
1553 Family of Accessor Routines</caption>
1554 <thead>
1555 <tr>
1556 <th>
1557
1558 Get<type>Field Routine Name
1559 </th>
1560 <th>
1561 Index
1562 </th>
1563 </tr>
1564 </thead>
1565 <tbody>
1566 <tr>
1567 <td>
1568 <code class=
1569 "cCode">GetObjectField()</code>
1570 </td>
1571 <td>95</td>
1572 </tr>
1573 <tr>
1574 <td>
1575 <code class=
1576 "cCode">GetBooleanField()</code>
1577 </td>
1578 <td>96</td>
1579 </tr>
1580 <tr>
1581 <td>
1582 <code class=
1583 "cCode">GetByteField()</code>
1584 </td>
1585 <td>97</td>
1586 </tr>
1587 <tr>
1588 <td>
1589 <code class=
1590 "cCode">GetCharField()</code>
1591 </td>
1592 <td>98</td>
1593 </tr>
1594 <tr>
1595 <td>
1596 <code class=
1597 "cCode">GetShortField()</code>
1598 </td>
1599 <td>99
1600
1601 </td>
1602 </tr>
1603 <tr>
1604 <td>
1605 <code class=
1606 "cCode">GetIntField()</code>
1607 </td>
1608 <td>100</td>
1609 </tr>
1610 <tr>
1611 <td>
1612 <code class=
1613 "cCode">GetLongField()</code>
1614 </td>
1615 <td>101</td>
1616 </tr>
1617 <tr>
1618 <td>
1619 <code class=
1620 "cCode">GetFloatField()</code>
1621 </td>
1622 <td>102
1623
1624 </td>
1625 </tr>
1626 <tr>
1627 <td>
1628 <code class=
1629 "cCode">GetDoubleField()</code>
1630 </td>
1631 <td>103
1632
1633 </td>
1634 </tr>
1635 </tbody>
1636 </table>
1637 <h4>PARAMETERS:</h4>
1638
1639 <p><code>env</code>: the JNI interface
1640 pointer.</p>
1641
1642 <p><code>obj</code>: a Java object
1643 (must not be <code>NULL</code>).</p>
1644
1645 <p><code>fieldID</code>: a valid field
1646 ID.</p>
1647
1648 <h4>RETURNS:</h4>
1649
1650 <p>Returns the content of the field.</p>
1651
1652 <h3><a name="Set_type_Field_routines">Set<type>Field Routines</a></h3>
1653
1654 <p><code>void</code> <em class=
1655 "cEmphasis">Set<type>Field</em><code>(JNIEnv
1656 *env, jobject obj, jfieldID fieldID,<br /></code> <em class=
1657 "cEmphasis">NativeType</em> <code>value);</code></p>
1658
1659 <p>This family of accessor routines sets the value of
1660 an instance (nonstatic) field of an object. The field to access is
1661 specified by a field ID obtained by calling <code class=
1662 "cCode">GetFieldID()</code>.</p>
1663
1664 <p>The following table describes the
1665 Set<type>Field routine name and value type. You should
1666 replace <em>type</em> in <em class=
1667 "cEmphasis">Set<type>Field</em> with the Java type of the
1668 field, or use one of the actual routine names from the table, and
1669 replace <em>NativeType</em> with the
1670 corresponding native type for that routine.</p>
1671
1672 <table border="1" summary=
1673 "Set <type>Fielf Family of Accessor Routine">
1674 <caption>Set<type>Field
1675 Family of Accessor Routines</caption>
1676 <thead>
1677 <tr>
1678 <th>
1679
1680 Set<type>Field Routine
1681 </th>
1682 <th>
1683 Native Type
1684 </th>
1685 </tr>
1686 </thead>
1687 <tbody>
1688 <tr>
1689 <td>
1690 <code class=
1691 "cCode">SetObjectField()</code>
1692 </td>
1693 <td>
1694 jobject
1695 </td>
1696 </tr>
1697 <tr>
1698 <td>
1699 S<code class=
1700 "cCode">etBooleanField()</code>
1701 </td>
1702 <td>
1703 jboolean
1704 </td>
1705 </tr>
1706 <tr>
1707 <td>
1708 <code class=
1709 "cCode">SetByteField()</code>
1710 </td>
1711 <td>
1712 jbyte
1713 </td>
1714 </tr>
1715 <tr>
1716 <td>
1717 <code class=
1718 "cCode">SetCharField()</code>
1719 </td>
1720 <td>
1721 jchar
1722 </td>
1723 </tr>
1724 <tr>
1725 <td>
1726 <code class=
1727 "cCode">SetShortField()</code>
1728 </td>
1729 <td>
1730 jshort
1731 </td>
1732 </tr>
1733 <tr>
1734 <td>
1735 <code class=
1736 "cCode">SetIntField()</code>
1737 </td>
1738 <td>
1739 jint
1740 </td>
1741 </tr>
1742 <tr>
1743 <td>
1744 <code class=
1745 "cCode">SetLongField()</code>
1746 </td>
1747 <td>
1748 jlong
1749 </td>
1750 </tr>
1751 <tr>
1752 <td>
1753 <code class=
1754 "cCode">SetFloatField()</code>
1755 </td>
1756 <td>
1757 jfloat
1758 </td>
1759 </tr>
1760 <tr>
1761 <td>
1762 <code class=
1763 "cCode">SetDoubleField()</code>
1764 </td>
1765 <td>
1766 jdouble
1767 </td>
1768 </tr>
1769 </tbody>
1770 </table>
1771
1772
1773
1774 <h4>LINKAGE:</h4>
1775
1776 <p>Indices in the JNIEnv interface function table.</p>
1777
1778 <table border="1" summary=
1779 "Set <type>Fielf Family of Accessor Routine">
1780 <caption>Set<type>Field
1781 Family of Accessor Routines</caption>
1782 <thead>
1783 <tr>
1784 <th>
1785
1786 Set<type>Field Routine
1787 </th>
1788 <th>
1789 Index
1790 </th>
1791 </tr>
1792 </thead>
1793 <tbody>
1794 <tr>
1795 <td>
1796 <code class=
1797 "cCode">SetObjectField()</code>
1798 </td>
1799 <td>104</td>
1800 </tr>
1801 <tr>
1802 <td>
1803 S<code class=
1804 "cCode">etBooleanField()</code>
1805 </td>
1806 <td>105</td>
1807 </tr>
1808 <tr>
1809 <td>
1810 <code class=
1811 "cCode">SetByteField()</code>
1812 </td>
1813 <td>106</td>
1814 </tr>
1815 <tr>
1816 <td>
1817 <code class=
1818 "cCode">SetCharField()</code>
1819 </td>
1820 <td>107
1821
1822 </td>
1823 </tr>
1824 <tr>
1825 <td>
1826 <code class=
1827 "cCode">SetShortField()</code>
1828 </td>
1829 <td>108</td>
1830 </tr>
1831 <tr>
1832 <td>
1833 <code class=
1834 "cCode">SetIntField()</code>
1835 </td>
1836 <td>109</td>
1837 </tr>
1838 <tr>
1839 <td>
1840 <code class=
1841 "cCode">SetLongField()</code>
1842 </td>
1843 <td>110</td>
1844 </tr>
1845 <tr>
1846 <td>
1847 <code class=
1848 "cCode">SetFloatField()</code>
1849 </td>
1850 <td>111
1851
1852 </td>
1853 </tr>
1854 <tr>
1855 <td>
1856 <code class=
1857 "cCode">SetDoubleField()</code>
1858 </td>
1859 <td>112</td>
1860 </tr>
1861 </tbody>
1862 </table>
1863 <h4>PARAMETERS:</h4>
1864
1865 <p><code>env</code>: the JNI interface
1866 pointer.</p>
1867
1868 <p><code>obj</code>: a Java object
1869 (must not be <code>NULL</code>).</p>
1870
1871 <p><code>fieldID</code>: a valid field
1872 ID.</p>
1873
1874 <p><code>value</code>: the new value of
1875 the field.</p>
1876
1877 <!-- ******************************************************** -->
1878 <h2><a name="calling_instance_methods">Calling Instance Methods</a></h2>
1879
1880 <h3><a name="GetMethodID">GetMethodID</a></h3>
1881
1882 <p><code>jmethodID GetMethodID(JNIEnv
1883 *env, jclass clazz,<br />
1884 const char *name, const char *sig);</code></p>
1885
1886 <p>Returns the method ID for an instance (nonstatic)
1887 method of a class or interface. The method may be defined in one of
1888 the <code>clazz</code>’s superclasses and
1889 inherited by <code>clazz</code>. The method is
1890 determined by its name and signature.</p>
1891
1892 <p><code>GetMethodID()</code> causes an
1893 uninitialized class to be initialized.</p>
1894
1895 <p>To obtain the method ID of a constructor, supply
1896 <code><init></code> as the method name and
1897 <code>void</code> (<code>V</code>) as
1898 the return type.</p>
1899
1900 <h4>LINKAGE:</h4>
1901 <p>Index 33 in the JNIEnv interface function table.</p>
1902 <h4>PARAMETERS:</h4>
1903
1904 <p><code>env</code>: the JNI interface
1905 pointer.</p>
1906
1907 <p><code>clazz</code>: a Java class
1908 object.</p>
1909 <p><code>name</code>: the method name
1910 in a 0-terminated modified UTF-8 string.</p>
1911
1912 <p><code>sig</code>: the method
1913 signature in 0-terminated modified UTF-8 string.</p>
1914
1915 <h4>RETURNS:</h4>
1916
1917 <p>Returns a method ID, or <code class=
1918 "cCode">NULL</code> if the specified method cannot be found.</p>
1919
1920 <h4>THROWS:</h4>
1921
1922 <p><code>NoSuchMethodError</code>: if
1923 the specified method cannot be found.</p>
1924
1925 <p><code class=
1926 "cCode">ExceptionInInitializerError</code>: if the class
1927 initializer fails due to an exception.</p>
1928
1929 <p><code>OutOfMemoryError</code>: if
1930 the system runs out of memory.</p>
1931
1932 <h3><a name="Call_type_Method_routines">Call<type>Method Routines, Call<type>MethodA Routines, Call<type>MethodV Routines</a></h3>
1933
1934 <p><em>NativeType</em> <em class=
1935 "cEmphasis">Call<type>Method</em><code>(JNIEnv
1936 *env, jobject obj,<br />
1937 jmethodID methodID, ...);</code></p>
1938
1939 <p><em>NativeType</em> <em class=
1940 "cEmphasis">Call<type>MethodA</em><code>(JNIEnv
1941 *env, jobject obj,<br />
1942 jmethodID methodID, const jvalue *args);</code></p>
1943
1944 <p><em>NativeType</em> <em class=
1945 "cEmphasis">Call<type>MethodV</em><code>(JNIEnv
1946 *env, jobject obj,<br />
1947 jmethodID methodID, va_list args);</code></p>
1948
1949 <p>Methods from these three families of operations
1950 are used to call a Java instance method from a native method.They
1951 only differ in their mechanism for passing parameters to the
1952 methods that they call.</p>
1953
1954 <p>These families of operations invoke an instance
1955 (nonstatic) method on a Java object, according to the specified
1956 method ID. The <code>methodID</code> argument must be
1957 obtained by calling <code class=
1958 "cCode">GetMethodID</code><code>()</code>.</p>
1959
1960 <p>When these functions are used to call private
1961 methods and constructors, the method ID must be derived from the
1962 real class of <code>obj</code>, not from one of its
1963 superclasses.</p>
1964
1965 <h4>Call<type>Method Routines</h4>
1966
1967 <p>Programmers place all arguments that are to be
1968 passed to the method immediately following the <code class=
1969 "cCode">methodID</code> argument. The <em class=
1970 "cEmphasis">Call<type>Method</em> routine accepts these
1971 arguments and passes them to the Java method that the programmer
1972 wishes to invoke.</p>
1973
1974 <h4>Call<type>MethodA Routines</h4>
1975
1976 <p>Programmers place all arguments to the method in
1977 an <code>args</code> array of <code class=
1978 "cCode">jvalues</code> that immediately follows the <code class=
1979 "cCode">methodID</code> argument. The <em class=
1980 "cEmphasis">Call<type>MethodA</em> routine accepts the
1981 arguments in this array, and, in turn, passes them to the Java
1982 method that the programmer wishes to invoke.</p>
1983
1984 <h4>Call<type>MethodV Routines</h4>
1985
1986 <p>Programmers place all arguments to the method in
1987 an <code>args</code> argument of type <code class=
1988 "cCode">va_list</code> that immediately follows the <code class=
1989 "cCode">methodID</code> argument. The <em class=
1990 "cEmphasis">Call<type>MethodV</em> routine accepts the
1991 arguments, and, in turn, passes them to the Java method that the
1992 programmer wishes to invoke.</p>
1993
1994 <p>The following table describes each of the method
1995 calling routines according to their result type. You should replace
1996 <em>type</em> in <em class=
1997 "cEmphasis">Call<type>Method</em> with the Java type of the
1998 method you are calling (or use one of the actual method calling
1999 routine names from the table) and replace <em class=
2000 "cEmphasis">NativeType</em> with the corresponding native type for
2001 that routine.</p>
2002
2003 <table border="1" summary=
2004 "Instance Method Calling Routines">
2005 <caption>Instance Method Calling
2006 Routines</caption>
2007 <thead>
2008 <tr>
2009 <th>
2010
2011 Call<type>Method Routine Name
2012 </th>
2013 <th>
2014 Native Type
2015 </th>
2016 </tr>
2017 </thead>
2018 <tbody>
2019 <tr>
2020 <td>
2021 <code class=
2022 "cCode">CallVoidMethod()</code>
2023
2024 <code class=
2025 "cCode">CallVoidMethodA()</code>
2026
2027 <code class=
2028 "cCode">CallVoidMethodV()</code>
2029 </td>
2030 <td>
2031 void
2032 </td>
2033 </tr>
2034 <tr>
2035 <td>
2036 <code class=
2037 "cCode">CallObjectMethod()</code>
2038
2039 <code class=
2040 "cCode">CallObjectMethodA()</code>
2041
2042 <code class=
2043 "cCode">CallObjectMethodV()</code>
2044 </td>
2045 <td>
2046 jobject
2047 </td>
2048 </tr>
2049 <tr>
2050 <td>
2051 <code class=
2052 "cCode">CallBooleanMethod()</code>
2053
2054 <code class=
2055 "cCode">CallBooleanMethodA()</code>
2056
2057 <code class=
2058 "cCode">CallBooleanMethodV()</code>
2059 </td>
2060 <td>
2061 jboolean
2062 </td>
2063 </tr>
2064 <tr>
2065 <td>
2066 <code class=
2067 "cCode">CallByteMethod()</code>
2068
2069 <code class=
2070 "cCode">CallByteMethodA()</code>
2071
2072 <code class=
2073 "cCode">CallByteMethodV()</code>
2074 </td>
2075 <td>
2076 jbyte
2077 </td>
2078 </tr>
2079 <tr>
2080 <td>
2081 <code class=
2082 "cCode">CallCharMethod()</code>
2083
2084 <code class=
2085 "cCode">CallCharMethodA()</code>
2086
2087 <code class=
2088 "cCode">CallCharMethodV()</code>
2089 </td>
2090 <td>
2091 jchar
2092 </td>
2093 </tr>
2094 <tr>
2095 <td>
2096 <code class=
2097 "cCode">CallShortMethod()</code>
2098
2099 <code class=
2100 "cCode">CallShortMethodA()</code>
2101
2102 <code class=
2103 "cCode">CallShortMethodV()</code>
2104 </td>
2105 <td>
2106 jshort
2107 </td>
2108 </tr>
2109 <tr>
2110 <td>
2111 <code class=
2112 "cCode">CallIntMethod()</code>
2113
2114 <code class=
2115 "cCode">CallIntMethodA()</code>
2116
2117 <code class=
2118 "cCode">CallIntMethodV()</code>
2119 </td>
2120 <td>
2121 jint
2122 </td>
2123 </tr>
2124 <tr>
2125 <td>
2126 <code class=
2127 "cCode">CallLongMethod()</code>
2128
2129 <code class=
2130 "cCode">CallLongMethodA()</code>
2131
2132 <code class=
2133 "cCode">CallLongMethodV()</code>
2134 </td>
2135 <td>
2136 jlong
2137 </td>
2138 </tr>
2139 <tr>
2140 <td>
2141 <code class=
2142 "cCode">CallFloatMethod()</code>
2143
2144 <code class=
2145 "cCode">CallFloatMethodA()</code>
2146
2147 <code class=
2148 "cCode">CallFloatMethodV()</code>
2149 </td>
2150 <td>
2151 jfloat
2152 </td>
2153 </tr>
2154 <tr>
2155 <td>
2156 <code class=
2157 "cCode">CallDoubleMethod()</code>
2158
2159 <code class=
2160 "cCode">CallDoubleMethodA()</code>
2161
2162 <code class=
2163 "cCode">CallDoubleMethodV()</code>
2164 </td>
2165 <td>
2166 jdouble
2167 </td>
2168 </tr>
2169 </tbody>
2170 </table>
2171
2172 <h4>LINKAGE:</h4>
2173 <p>Indices in the JNIEnv interface function table:</p>
2174
2175 <table border="1" summary=
2176 "Instance Method Calling Routines">
2177 <caption>Instance Method Calling
2178 Routines</caption>
2179 <thead>
2180 <tr>
2181 <th>
2182
2183 Call<type>Method Routine Name
2184 </th>
2185 <th>
2186 Index
2187 </th>
2188 </tr>
2189 </thead>
2190 <tbody>
2191 <tr>
2192 <td>
2193 <code class=
2194 "cCode">CallVoidMethod()</code>
2195 <code class=
2196 "cCode">CallVoidMethodA()</code>
2197 <code class=
2198 "cCode">CallVoidMethodV()</code>
2199 </td>
2200 <td>
2201
2202 <p>61<br />
2203 63<br />
2204 62</p>
2205
2206 </td>
2207 </tr>
2208 <tr>
2209 <td>
2210 <code class=
2211 "cCode">CallObjectMethod()</code>
2212 <code class=
2213 "cCode">CallObjectMethodA()</code>
2214 <code class=
2215 "cCode">CallObjectMethodV()</code>
2216 </td>
2217 <td>
2218 <p>34<br />
2219 36<br />
2220 35</p>
2221 </td>
2222 </tr>
2223 <tr>
2224 <td>
2225 <code class=
2226 "cCode">CallBooleanMethod()</code>
2227 <code class=
2228 "cCode">CallBooleanMethodA()</code>
2229 <code class=
2230 "cCode">CallBooleanMethodV()</code>
2231 </td>
2232 <td>
2233 <p>37<br />
2234 39<br />
2235 38</p>
2236 </td>
2237 </tr>
2238 <tr>
2239 <td>
2240 <code class=
2241 "cCode">CallByteMethod()</code>
2242 <code class=
2243 "cCode">CallByteMethodA()</code>
2244 <code class=
2245 "cCode">CallByteMethodV()</code>
2246 </td>
2247 <td>
2248 <p>40<br />
2249 42<br />
2250 41</p>
2251 </td>
2252 </tr>
2253 <tr>
2254 <td>
2255 <code class=
2256 "cCode">CallCharMethod()</code>
2257 <code class=
2258 "cCode">CallCharMethodA()</code>
2259 <code class=
2260 "cCode">CallCharMethodV()</code>
2261 </td>
2262 <td>
2263 <p>43<br />
2264 45<br />
2265 44</p>
2266 </td>
2267 </tr>
2268 <tr>
2269 <td>
2270 <code class=
2271 "cCode">CallShortMethod()</code>
2272 <code class=
2273 "cCode">CallShortMethodA()</code>
2274 <code class=
2275 "cCode">CallShortMethodV()</code>
2276 </td>
2277 <td>
2278 <p>46<br />
2279 48<br />
2280 47</p>
2281 </td>
2282 </tr>
2283 <tr>
2284 <td>
2285 <code class=
2286 "cCode">CallIntMethod()</code>
2287 <code class=
2288 "cCode">CallIntMethodA()</code>
2289 <code class=
2290 "cCode">CallIntMethodV()</code>
2291 </td>
2292 <td>
2293 <p>49<br />
2294 51<br />
2295 50</p>
2296 </td>
2297 </tr>
2298 <tr>
2299 <td>
2300 <code class=
2301 "cCode">CallLongMethod()</code>
2302 <code class=
2303 "cCode">CallLongMethodA()</code>
2304 <code class=
2305 "cCode">CallLongMethodV()</code>
2306 </td>
2307 <td>
2308 <p>52<br />
2309 54<br />
2310 53</p>
2311 </td>
2312 </tr>
2313 <tr>
2314 <td>
2315 <code class=
2316 "cCode">CallFloatMethod()</code>
2317 <code class=
2318 "cCode">CallFloatMethodA()</code>
2319 <code class=
2320 "cCode">CallFloatMethodV()</code>
2321 </td>
2322 <td>
2323 <p>55<br />
2324 57<br />
2325 56</p>
2326 </td>
2327 </tr>
2328 <tr>
2329 <td>
2330 <code class=
2331 "cCode">CallDoubleMethod()</code>
2332 <code class=
2333 "cCode">CallDoubleMethodA()</code>
2334 <code class=
2335 "cCode">CallDoubleMethodV()</code>
2336 </td>
2337 <td>
2338 <p>58<br />
2339 60<br />
2340 59</p>
2341 </td>
2342 </tr>
2343 </tbody>
2344 </table>
2345 <h4>PARAMETERS:</h4>
2346
2347 <p><code>env</code>: the JNI interface
2348 pointer.</p>
2349
2350 <p><code>obj</code>: a Java object.</p>
2351
2352 <p><code>methodID</code>: a method
2353 ID.</p>
2354
2355 <h4>Additional Parameter for
2356 Call<type>Method Routines:</h4>
2357
2358 <p>arguments to the Java method.</p>
2359
2360 <h4>Additional Parameter for
2361 Call<type>MethodA Routines:</h4>
2362
2363 <p><code>args</code>: an array of
2364 arguments.</p>
2365
2366 <h4>Additional Parameter for
2367 Call<type>MethodV Routines:</h4>
2368
2369 <p><code>args</code>: a va_list of
2370 arguments.</p>
2371
2372 <h4>RETURNS:</h4>
2373
2374 <p>Returns the result of calling the Java method.</p>
2375
2376 <h4>THROWS:</h4>
2377
2378 <p><code>Exceptions raised during the
2379 execution of the Java method.</code></p>
2380
2381 <h3><a name="CallNonvirtual_type_Method_routines">CallNonvirtual<type>Method Routines, CallNonvirtual<type>MethodA Routines, CallNonvirtual<type>MethodV Routines</a></h3>
2382
2383 <p><em>NativeType</em> <em class=
2384 "cEmphasis">CallNonvirtual<type>Method</em><code class=
2385 "cCode">(JNIEnv *env, jobject obj,<br />
2386 jclass clazz, jmethodID methodID, ...);</code></p>
2387
2388 <p><em>NativeType</em> <em class=
2389 "cEmphasis">CallNonvirtual<type>MethodA</em><code class=
2390 "cCode">(JNIEnv *env, jobject obj,<br />
2391 jclass clazz, jmethodID methodID, const jvalue *args);</code></p>
2392
2393 <p><em>NativeType</em> <em class=
2394 "cEmphasis">CallNonvirtual<type>MethodV</em><code class=
2395 "cCode">(JNIEnv *env, jobject obj,<br />
2396 jclass clazz, jmethodID methodID, va_list args);</code></p>
2397
2398 <p>These families of operations invoke an instance
2399 (nonstatic) method on a Java object, according to the specified
2400 class and method ID. The <code>methodID</code>
2401 argument must be obtained by calling <code class=
2402 "cCode">GetMethodID</code><code>()</code> on the
2403 class <code>clazz</code>.</p>
2404
2405 <p>The <em class=
2406 "cEmphasis">CallNonvirtual<type>Method</em> families of
2407 routines and the <em>Call<type>Method</em>
2408 families of routines are different. <em class=
2409 "cEmphasis">Call<type>Method</em> routines invoke the method
2410 based on the class of the object, while <em class=
2411 "cEmphasis">CallNonvirtual<type>Method</em> routines invoke
2412 the method based on the class, designated by the <code class=
2413 "cCode">clazz</code> parameter, from which the method ID is
2414 obtained. The method ID must be obtained from the real class of the
2415 object or from one of its superclasses.</p>
2416
2417 <h4>CallNonvirtual<type>Method
2418 Routines</h4>
2419
2420 <p>Programmers place all arguments that are to be
2421 passed to the method immediately following the <code class=
2422 "cCode">methodID</code> argument. The <em class=
2423 "cEmphasis">CallNonvirtual<type>Method</em> routine accepts
2424 these arguments and passes them to the Java method that the
2425 programmer wishes to invoke.</p>
2426
2427 <h4>CallNonvirtual<type>MethodA
2428 Routines</h4>
2429
2430 <p>Programmers place all arguments to the method in
2431 an <code>args</code> array of <code class=
2432 "cCode">jvalues</code> that immediately follows the <code class=
2433 "cCode">methodID</code> argument. The <em class=
2434 "cEmphasis">CallNonvirtual<type>MethodA</em> routine accepts
2435 the arguments in this array, and, in turn, passes them to the Java
2436 method that the programmer wishes to invoke.</p>
2437
2438 <h4>CallNonvirtual<type>MethodV
2439 Routines</h4>
2440
2441 <p>Programmers place all arguments to the method in
2442 an <code>args</code> argument of type <code class=
2443 "cCode">va_list</code> that immediately follows the <code class=
2444 "cCode">methodID</code> argument. The <em class=
2445 "cEmphasis">CallNonvirtualMethodV</em> routine accepts the
2446 arguments, and, in turn, passes them to the Java method that the
2447 programmer wishes to invoke.</p>
2448
2449 <p>The following table describes each of the method
2450 calling routines according to their result type. You should replace
2451 <em>type</em> in <em class=
2452 "cEmphasis">CallNonvirtual<type>Method</em> with the Java
2453 type of the method, or use one of the actual method calling routine
2454 names from the table, and replace <em class=
2455 "cEmphasis">NativeType</em> with the corresponding native type for
2456 that routine.</p>
2457
2458 <table border="1" summary=
2459 "CallNonvirtual<type> Method Routines">
2460 <caption>CallNonvirtual<type>Method Routines</caption>
2461 <thead>
2462 <tr>
2463 <th>
2464
2465 CallNonvirtual<type>Method Routine Name
2466 </th>
2467 <th>
2468 Native Type
2469 </th>
2470 </tr>
2471 </thead>
2472 <tbody>
2473 <tr>
2474 <td>
2475 <code class=
2476 "cCode">CallNonvirtualVoidMethod()</code>
2477
2478 <code class=
2479 "cCode">CallNonvirtualVoidMethodA()</code>
2480
2481 <code class=
2482 "cCode">CallNonvirtualVoidMethodV()</code>
2483 </td>
2484 <td>
2485 void
2486 </td>
2487 </tr>
2488 <tr>
2489 <td>
2490 <code class=
2491 "cCode">CallNonvirtualObjectMethod()</code>
2492
2493 <code class=
2494 "cCode">CallNonvirtualObjectMethodA()</code>
2495
2496 <code class=
2497 "cCode">CallNonvirtualObjectMethodV()</code>
2498 </td>
2499 <td>
2500 jobject
2501 </td>
2502 </tr>
2503 <tr>
2504 <td>
2505 <code class=
2506 "cCode">CallNonvirtualBooleanMethod()</code>
2507
2508 <code class=
2509 "cCode">CallNonvirtualBooleanMethodA()</code>
2510
2511 <code class=
2512 "cCode">CallNonvirtualBooleanMethodV()</code>
2513 </td>
2514 <td>
2515 jboolean
2516 </td>
2517 </tr>
2518 <tr>
2519 <td>
2520 <code class=
2521 "cCode">CallNonvirtualByteMethod()</code>
2522
2523 <code class=
2524 "cCode">CallNonvirtualByteMethodA()</code>
2525
2526 <code class=
2527 "cCode">CallNonvirtualByteMethodV()</code>
2528 </td>
2529 <td>
2530 jbyte
2531 </td>
2532 </tr>
2533 <tr>
2534 <td>
2535 <code class=
2536 "cCode">CallNonvirtualCharMethod()</code>
2537
2538 <code class=
2539 "cCode">CallNonvirtualCharMethodA()</code>
2540
2541 <code class=
2542 "cCode">CallNonvirtualCharMethodV()</code>
2543 </td>
2544 <td>
2545 jchar
2546 </td>
2547 </tr>
2548 <tr>
2549 <td>
2550 <code class=
2551 "cCode">CallNonvirtualShortMethod()</code>
2552
2553 <code class=
2554 "cCode">CallNonvirtualShortMethodA()</code>
2555
2556 <code class=
2557 "cCode">CallNonvirtualShortMethodV()</code>
2558 </td>
2559 <td>
2560 jshort
2561 </td>
2562 </tr>
2563 <tr>
2564 <td>
2565 <code class=
2566 "cCode">CallNonvirtualIntMethod()</code>
2567
2568 <code class=
2569 "cCode">CallNonvirtualIntMethodA()</code>
2570
2571 <code class=
2572 "cCode">CallNonvirtualIntMethodV()</code>
2573 </td>
2574 <td>
2575 jint
2576 </td>
2577 </tr>
2578 <tr>
2579 <td>
2580 <code class=
2581 "cCode">CallNonvirtualLongMethod()</code>
2582
2583 <code class=
2584 "cCode">CallNonvirtualLongMethodA()</code>
2585
2586 <code class=
2587 "cCode">CallNonvirtualLongMethodV()</code>
2588 </td>
2589 <td>
2590 jlong
2591 </td>
2592 </tr>
2593 <tr>
2594 <td>
2595 <code class=
2596 "cCode">CallNonvirtualFloatMethod()</code>
2597
2598 <code class=
2599 "cCode">CallNonvirtualFloatMethodA()</code>
2600
2601 <code class=
2602 "cCode">CallNonvirtualFloatMethodV()</code>
2603 </td>
2604 <td>
2605 jfloat
2606 </td>
2607 </tr>
2608 <tr>
2609 <td>
2610 <code class=
2611 "cCode">CallNonvirtualDoubleMethod()</code>
2612
2613 <code class=
2614 "cCode">CallNonvirtualDoubleMethodA()</code>
2615
2616 <code class=
2617 "cCode">CallNonvirtualDoubleMethodV()</code>
2618 </td>
2619 <td>
2620 jdouble
2621 </td>
2622 </tr>
2623 </tbody>
2624 </table>
2625
2626
2627
2628 <h4>LINKAGE:</h4>
2629 <p>Indices in the JNIEnv interface function table.</p>
2630
2631 <table border="1" summary=
2632 "CallNonvirtual<type> Method Routines">
2633 <caption>CallNonvirtual<type>Method Routines</caption>
2634 <thead>
2635 <tr>
2636 <th>
2637
2638 CallNonvirtual<type>Method Routine Name
2639 </th>
2640 <th>
2641 Index
2642 </th>
2643 </tr>
2644 </thead>
2645 <tbody>
2646 <tr>
2647 <td>
2648 <code class=
2649 "cCode">CallNonvirtualVoidMethod()</code>
2650 <code class=
2651 "cCode">CallNonvirtualVoidMethodA()</code>
2652 <code class=
2653 "cCode">CallNonvirtualVoidMethodV()</code>
2654 </td>
2655 <td>91<br />
2656 93<br />
2657 92</td>
2658 </tr>
2659 <tr>
2660 <td>
2661 <code class=
2662 "cCode">CallNonvirtualObjectMethod()</code>
2663 <code class=
2664 "cCode">CallNonvirtualObjectMethodA()</code>
2665 <code class=
2666 "cCode">CallNonvirtualObjectMethodV()</code>
2667 </td>
2668 <td>64<br />
2669 66<br />
2670 65</td>
2671 </tr>
2672 <tr>
2673 <td>
2674 <code class=
2675 "cCode">CallNonvirtualBooleanMethod()</code>
2676 <code class=
2677 "cCode">CallNonvirtualBooleanMethodA()</code>
2678 <code class=
2679 "cCode">CallNonvirtualBooleanMethodV()</code>
2680 </td>
2681 <td>67<br />
2682 69<br />
2683 68</td>
2684 </tr>
2685 <tr>
2686 <td>
2687 <code class=
2688 "cCode">CallNonvirtualByteMethod()</code>
2689 <code class=
2690 "cCode">CallNonvirtualByteMethodA()</code>
2691 <code class=
2692 "cCode">CallNonvirtualByteMethodV()</code>
2693 </td>
2694 <td>70<br />
2695 72<br />
2696 71</td>
2697 </tr>
2698 <tr>
2699 <td>
2700 <code class=
2701 "cCode">CallNonvirtualCharMethod()</code>
2702 <code class=
2703 "cCode">CallNonvirtualCharMethodA()</code>
2704 <code class=
2705 "cCode">CallNonvirtualCharMethodV()</code>
2706 </td>
2707 <td>73<br />
2708 75<br />
2709 74</td>
2710 </tr>
2711 <tr>
2712 <td>
2713 <code class=
2714 "cCode">CallNonvirtualShortMethod()</code>
2715 <code class=
2716 "cCode">CallNonvirtualShortMethodA()</code>
2717 <code class=
2718 "cCode">CallNonvirtualShortMethodV()</code>
2719 </td>
2720 <td>76<br />
2721 78<br />
2722 77</td>
2723 </tr>
2724 <tr>
2725 <td>
2726 <code class=
2727 "cCode">CallNonvirtualIntMethod()</code>
2728 <code class=
2729 "cCode">CallNonvirtualIntMethodA()</code>
2730 <code class=
2731 "cCode">CallNonvirtualIntMethodV()</code>
2732 </td>
2733 <td>79<br />
2734 81<br />
2735 80</td>
2736 </tr>
2737 <tr>
2738 <td>
2739 <code class=
2740 "cCode">CallNonvirtualLongMethod()</code>
2741 <code class=
2742 "cCode">CallNonvirtualLongMethodA()</code>
2743 <code class=
2744 "cCode">CallNonvirtualLongMethodV()</code>
2745 </td>
2746 <td>82<br />
2747 84<br />
2748 83</td>
2749 </tr>
2750 <tr>
2751 <td>
2752 <code class=
2753 "cCode">CallNonvirtualFloatMethod()</code>
2754 <code class=
2755 "cCode">CallNonvirtualFloatMethodA()</code>
2756 <code class=
2757 "cCode">CallNonvirtualFloatMethodV()</code>
2758 </td>
2759 <td>85<br />
2760 87<br />
2761 86</td>
2762 </tr>
2763 <tr>
2764 <td>
2765 <code class=
2766 "cCode">CallNonvirtualDoubleMethod()</code>
2767 <code class=
2768 "cCode">CallNonvirtualDoubleMethodA()</code>
2769 <code class=
2770 "cCode">CallNonvirtualDoubleMethodV()</code>
2771 </td>
2772 <td>88<br />
2773 90<br />
2774 89</td>
2775 </tr>
2776 </tbody>
2777 </table>
2778 <h4>PARAMETERS:</h4>
2779
2780 <p><code>env</code>: the JNI interface
2781 pointer.</p>
2782
2783 <p><code>clazz:</code> <code class=
2784 "cCode">a</code> Java class.</p>
2785
2786 <p><code>obj</code>: a Java object.</p>
2787
2788 <p><code>methodID</code>: a method
2789 ID.</p>
2790
2791 <h4>Additional Parameter for
2792 CallNonvirtual<type>Method Routines:</h4>
2793
2794 <p>arguments to the Java method.</p>
2795
2796 <h4>Additional Parameter for
2797 CallNonvirtual<type>MethodA Routines:</h4>
2798
2799 <p><code>args</code>: an array of
2800 arguments.</p>
2801
2802 <h4>Additional Parameter for
2803 CallNonvirtual<type>MethodV Routines:</h4>
2804
2805 <p><code>args</code>: a <code class=
2806 "cCode">va_list</code> of arguments.</p>
2807
2808 <h4>RETURNS:</h4>
2809
2810 <p>Returns the result of calling the Java
2811 method.</p>
2812
2813 <h4>THROWS:</h4>
2814
2815 <p>Exceptions raised during the execution of the Java
2816 method.</p>
2817
2818 <!-- ******************************************************** -->
2819 <h2><a name="accessing_static_fields">Accessing Static Fields</a></h2>
2820
2821 <h3><a name="GetStaticFieldID">GetStaticFieldID</a></h3>
2822
2823 <p><code>jfieldID
2824 GetStaticFieldID(JNIEnv *env, jclass clazz,<br />
2825 const char *name, const char *sig);</code></p>
2826
2827 <p>Returns the field ID for a static field of a
2828 class. The field is specified by its name and signature. The
2829 <em>GetStatic<type>Field</em> and
2830 <em>SetStatic<type>Field</em> families of
2831 accessor functions use field IDs to retrieve static fields.</p>
2832
2833 <p><code>GetStaticFieldID()</code>
2834 causes an uninitialized class to be initialized.</p>
2835
2836 <h4>LINKAGE:</h4>
2837 <p>Index 144 in the JNIEnv interface function table.</p>
2838 <h4>PARAMETERS:</h4>
2839
2840 <p><code>env</code>: the JNI interface
2841 pointer.</p>
2842
2843 <p><code>clazz</code>: a Java class
2844 object.</p>
2845
2846 <p><code>name</code>: the static field
2847 name in a 0-terminated modified UTF-8 string.</p>
2848
2849 <p><code>sig</code>: the field
2850 signature in a 0-terminated modified UTF-8 string.</p>
2851
2852 <h4>RETURNS:</h4>
2853
2854 <p>Returns a field ID, or <code class=
2855 "cCode">NULL</code> if the specified static field cannot be
2856 found.</p>
2857
2858 <h4>THROWS:</h4>
2859
2860 <p><code>NoSuchFieldError</code>: if
2861 the specified static field cannot be found.</p>
2862
2863 <p><code class=
2864 "cCode">ExceptionInInitializerError</code>: if the class
2865 initializer fails due to an exception.</p>
2866
2867 <p><code>OutOfMemoryError</code>: if
2868 the system runs out of memory.</p>
2869
2870 <h3><a name="GetStatic_type_Field_routines">GetStatic<type>Field Routines</a></h3>
2871
2872 <p><em>NativeType</em> <em class=
2873 "cEmphasis">GetStatic<type>Field</em><code class=
2874 "cCode">(JNIEnv *env, jclass clazz,<br />
2875 jfieldID fieldID);</code></p>
2876
2877 <p>This family of accessor routines returns the value
2878 of a static field of an object. The field to access is specified by
2879 a field ID, which is obtained by calling <code class=
2880 "cCode">GetStaticFieldID()</code>.</p>
2881
2882 <p>The following table describes the family of get
2883 routine names and result types. You should replace <em class=
2884 "cEmphasis">type</em> in <em class=
2885 "cEmphasis">GetStatic<type>Field</em> with the Java type of
2886 the field, or one of the actual static field accessor routine names
2887 from the table, and replace <em>NativeType</em>
2888 with the corresponding native type for that routine.</p>
2889
2890
2891
2892 <table border="1" summary=
2893 "GetStatic<type>Field Family of Accessor Routines">
2894 <caption>GetStatic<type>Field Family of Accessor Routines</caption>
2895 <thead>
2896 <tr>
2897 <th>
2898
2899 GetStatic<type>Field Routine Name
2900 </th>
2901 <th>
2902 Native Type
2903 </th>
2904 </tr>
2905 </thead>
2906 <tbody>
2907 <tr>
2908 <td>
2909 <code class=
2910 "cCode">GetStaticObjectField</code><code class=
2911 "cCode">()</code>
2912 </td>
2913 <td>
2914 jobject
2915 </td>
2916 </tr>
2917 <tr>
2918 <td>
2919 <code class=
2920 "cCode">GetStaticBooleanField</code><code class=
2921 "cCode">()</code>
2922 </td>
2923 <td>
2924 jboolean
2925 </td>
2926 </tr>
2927 <tr>
2928 <td>
2929 <code class=
2930 "cCode">GetStaticByteField</code><code class=
2931 "cCode">()</code>
2932 </td>
2933 <td>
2934 jbyte
2935 </td>
2936 </tr>
2937 <tr>
2938 <td>
2939 <code class=
2940 "cCode">GetStaticCharField</code><code class=
2941 "cCode">()</code>
2942 </td>
2943 <td>
2944 jchar
2945 </td>
2946 </tr>
2947 <tr>
2948 <td>
2949 <code class=
2950 "cCode">GetStaticShortField</code><code class=
2951 "cCode">()</code>
2952 </td>
2953 <td>
2954 jshort
2955 </td>
2956 </tr>
2957 <tr>
2958 <td>
2959 <code class=
2960 "cCode">GetStaticIntField</code><code>()</code>
2961 </td>
2962 <td>
2963 jint
2964 </td>
2965 </tr>
2966 <tr>
2967 <td>
2968 <code class=
2969 "cCode">GetStaticLongField</code><code class=
2970 "cCode">()</code>
2971 </td>
2972 <td>
2973 jlong
2974 </td>
2975 </tr>
2976 <tr>
2977 <td>
2978 <code class=
2979 "cCode">GetStaticFloatField</code><code class=
2980 "cCode">()</code>
2981 </td>
2982 <td>
2983 jfloat
2984 </td>
2985 </tr>
2986 <tr>
2987 <td>
2988 <code class=
2989 "cCode">GetStaticDoubleField</code><code class=
2990 "cCode">()</code>
2991 </td>
2992 <td>
2993 jdouble
2994 </td>
2995 </tr>
2996 </tbody>
2997 </table>
2998
2999
3000
3001 <h4>LINKAGE:</h4>
3002 <p>Indices in the JNIEnv interface function table.</p>
3003
3004 <table border="1" summary=
3005 "GetStatic<type>Field Family of Accessor Routines">
3006 <caption>GetStatic<type>Field Family of Accessor Routines</caption>
3007 <thead>
3008 <tr>
3009 <th>
3010
3011 GetStatic<type>Field Routine Name
3012 </th>
3013 <th>
3014 Index
3015 </th>
3016 </tr>
3017 </thead>
3018 <tbody>
3019 <tr>
3020 <td>
3021 <code class=
3022 "cCode">GetStaticObjectField</code><code class=
3023 "cCode">()</code>
3024 </td>
3025 <td>145</td>
3026 </tr>
3027 <tr>
3028 <td>
3029 <code class=
3030 "cCode">GetStaticBooleanField</code><code class=
3031 "cCode">()</code>
3032 </td>
3033 <td>146</td>
3034 </tr>
3035 <tr>
3036 <td>
3037 <code class=
3038 "cCode">GetStaticByteField</code><code class=
3039 "cCode">()</code>
3040 </td>
3041 <td>147</td>
3042 </tr>
3043 <tr>
3044 <td>
3045 <code class=
3046 "cCode">GetStaticCharField</code><code class=
3047 "cCode">()</code>
3048 </td>
3049 <td>148</td>
3050 </tr>
3051 <tr>
3052 <td>
3053 <code class=
3054 "cCode">GetStaticShortField</code><code class=
3055 "cCode">()</code>
3056 </td>
3057 <td>149</td>
3058 </tr>
3059 <tr>
3060 <td>
3061 <code class=
3062 "cCode">GetStaticIntField</code><code>()</code>
3063 </td>
3064 <td>150</td>
3065 </tr>
3066 <tr>
3067 <td>
3068 <code class=
3069 "cCode">GetStaticLongField</code><code class=
3070 "cCode">()</code>
3071 </td>
3072 <td>151</td>
3073 </tr>
3074 <tr>
3075 <td>
3076 <code class=
3077 "cCode">GetStaticFloatField</code><code class=
3078 "cCode">()</code>
3079 </td>
3080 <td>152</td>
3081 </tr>
3082 <tr>
3083 <td>
3084 <code class=
3085 "cCode">GetStaticDoubleField</code><code class=
3086 "cCode">()</code>
3087 </td>
3088 <td>153</td>
3089 </tr>
3090 </tbody>
3091 </table>
3092 <h4>PARAMETERS:</h4>
3093
3094 <p><code>env</code>: the JNI interface
3095 pointer.</p>
3096
3097 <p><code>clazz</code>: a Java class
3098 object.</p>
3099
3100 <p><code>fieldID</code>: a static field
3101 ID.</p>
3102
3103 <h4>RETURNS:</h4>
3104
3105 <p>Returns the content of the static field.</p>
3106
3107 <h3><a name="SetStatic_type_Field_routines">SetStatic<type>Field Routines</a></h3>
3108
3109 <p><code>void</code> <em class=
3110 "cEmphasis">SetStatic<type>Field</em><code class=
3111 "cCode">(JNIEnv *env, jclass clazz,<br />
3112 jfieldID fieldID,</code> <em>NativeType</em>
3113 <code>value);</code></p>
3114
3115 <p>This family of accessor routines sets the value of
3116 a static field of an object. The field to access is specified by a
3117 field ID, which is obtained by calling <code class=
3118 "cCode">GetStaticFieldID()</code>.</p>
3119
3120 <p>The following table describes the set routine name
3121 and value types. You should replace <em>type</em>
3122 in <em>SetStatic<type>Field</em> with the
3123 Java type of the field, or one of the actual set static field
3124 routine names from the table, and replace <em class=
3125 "cEmphasis">NativeType</em> with the corresponding native type for
3126 that routine.</p>
3127
3128
3129 <table border="1" summary=
3130 "SetStatic<type>Field Family of Accessor Routines">
3131 <caption>SetStatic<type>Field Family of Accessor Routines</caption>
3132 <thead>
3133 <tr>
3134 <th>
3135
3136 SetStatic<type>Field Routine Name
3137 </th>
3138 <th>
3139 NativeType
3140 </th>
3141 </tr>
3142 </thead>
3143 <tbody>
3144 <tr>
3145 <td>
3146 <code class=
3147 "cCode">SetStaticObjectField</code><code class=
3148 "cCode">()</code>
3149 </td>
3150 <td>
3151 jobject
3152 </td>
3153 </tr>
3154 <tr>
3155 <td>
3156 <code class=
3157 "cCode">SetStaticBooleanField</code><code class=
3158 "cCode">()</code>
3159 </td>
3160 <td>
3161 jboolean
3162 </td>
3163 </tr>
3164 <tr>
3165 <td>
3166 <code class=
3167 "cCode">SetStaticByteField</code><code class=
3168 "cCode">()</code>
3169 </td>
3170 <td>
3171 jbyte
3172 </td>
3173 </tr>
3174 <tr>
3175 <td>
3176 <code class=
3177 "cCode">SetStaticCharField</code><code class=
3178 "cCode">()</code>
3179 </td>
3180 <td>
3181 jchar
3182 </td>
3183 </tr>
3184 <tr>
3185 <td>
3186 <code class=
3187 "cCode">SetStaticShortField</code><code class=
3188 "cCode">()</code>
3189 </td>
3190 <td>
3191 jshort
3192 </td>
3193 </tr>
3194 <tr>
3195 <td>
3196 <code class=
3197 "cCode">SetStaticIntField</code><code>()</code>
3198 </td>
3199 <td>
3200 jint
3201 </td>
3202 </tr>
3203 <tr>
3204 <td>
3205 <code class=
3206 "cCode">SetStaticLongField</code><code class=
3207 "cCode">()</code>
3208 </td>
3209 <td>
3210 jlong
3211 </td>
3212 </tr>
3213 <tr>
3214 <td>
3215 <code class=
3216 "cCode">SetStaticFloatField</code><code class=
3217 "cCode">()</code>
3218 </td>
3219 <td>
3220 jfloat
3221 </td>
3222 </tr>
3223 <tr>
3224 <td>
3225 <code class=
3226 "cCode">SetStaticDoubleField</code><code class=
3227 "cCode">()</code>
3228 </td>
3229 <td>
3230 jdouble
3231 </td>
3232 </tr>
3233 </tbody>
3234 </table>
3235
3236
3237
3238 <h4>LINKAGE:</h4>
3239 <p>Indices in the JNIEnv interface function table.</p>
3240
3241
3242 <table border="1" summary=
3243 "SetStatic<type>Field Family of Accessor Routines">
3244 <caption>SetStatic<type>Field Family of Accessor Routines</caption>
3245 <thead>
3246 <tr>
3247 <th>
3248
3249 SetStatic<type>Field Routine Name
3250 </th>
3251 <th>
3252 Index
3253 </th>
3254 </tr>
3255 </thead>
3256 <tbody>
3257 <tr>
3258 <td>
3259 <code class=
3260 "cCode">SetStaticObjectField</code><code class=
3261 "cCode">()</code>
3262 </td>
3263 <td>154</td>
3264 </tr>
3265 <tr>
3266 <td>
3267 <code class=
3268 "cCode">SetStaticBooleanField</code><code class=
3269 "cCode">()</code>
3270 </td>
3271 <td>155</td>
3272 </tr>
3273 <tr>
3274 <td>
3275 <code class=
3276 "cCode">SetStaticByteField</code><code class=
3277 "cCode">()</code>
3278 </td>
3279 <td>156</td>
3280 </tr>
3281 <tr>
3282 <td>
3283 <code class=
3284 "cCode">SetStaticCharField</code><code class=
3285 "cCode">()</code>
3286 </td>
3287 <td>157</td>
3288 </tr>
3289 <tr>
3290 <td>
3291 <code class=
3292 "cCode">SetStaticShortField</code><code class=
3293 "cCode">()</code>
3294 </td>
3295 <td>158</td>
3296 </tr>
3297 <tr>
3298 <td>
3299 <code class=
3300 "cCode">SetStaticIntField</code><code>()</code>
3301 </td>
3302 <td>159</td>
3303 </tr>
3304 <tr>
3305 <td>
3306 <code class=
3307 "cCode">SetStaticLongField</code><code class=
3308 "cCode">()</code>
3309 </td>
3310 <td>160</td>
3311 </tr>
3312 <tr>
3313 <td>
3314 <code class=
3315 "cCode">SetStaticFloatField</code><code class=
3316 "cCode">()</code>
3317 </td>
3318 <td>161</td>
3319 </tr>
3320 <tr>
3321 <td>
3322 <code class=
3323 "cCode">SetStaticDoubleField</code><code class=
3324 "cCode">()</code>
3325 </td>
3326 <td>162</td>
3327 </tr>
3328 </tbody>
3329 </table>
3330 <h4>PARAMETERS:</h4>
3331
3332 <p><code>env</code>: the JNI interface
3333 pointer.</p>
3334
3335 <p><code>clazz</code>: a Java class
3336 object.</p>
3337
3338 <p><code>fieldID</code>: a static field
3339 ID.</p>
3340
3341 <p><code>value</code>: the new value of
3342 the field.</p>
3343
3344 <!-- ******************************************************** -->
3345 <h2><a name="calling_static_methods">Calling Static Methods</a></h2>
3346
3347 <h3><a name="GetStaticMethodID">GetStaticMethodID</a></h3>
3348
3349 <p><code>jmethodID
3350 GetStaticMethodID(JNIEnv *env, jclass clazz,<br />
3351 const char *name, const char *sig);</code></p>
3352
3353 <p>Returns the method ID for a static method of a
3354 class. The method is specified by its name and signature.</p>
3355
3356 <p><code>GetStaticMethodID()</code>
3357 causes an uninitialized class to be initialized.</p>
3358
3359 <h4>LINKAGE:</h4>
3360 Index 113 in the JNIEnv interface function table.
3361 <h4>PARAMETERS:</h4>
3362
3363 <p><code>env</code>: the JNI interface
3364 pointer.</p>
3365
3366 <p><code>clazz</code>: a Java class
3367 object.</p>
3368
3369 <p><code>name</code>: the static method
3370 name in a 0-terminated modified UTF-8 string.</p>
3371
3372 <p><code>sig</code>: the method
3373 signature in a 0-terminated modified UTF-8 string.</p>
3374
3375 <h4>RETURNS:</h4>
3376
3377 <p>Returns a method ID, or <code class=
3378 "cCode">NULL</code> if the operation fails.</p>
3379
3380 <h4>THROWS:</h4>
3381
3382 <p><code>NoSuchMethodError</code>: if
3383 the specified static method cannot be found.</p>
3384
3385 <p><code class=
3386 "cCode">ExceptionInInitializerError</code>: if the class
3387 initializer fails due to an exception.</p>
3388
3389 <p><code>OutOfMemoryError</code>: if
3390 the system runs out of memory.</p>
3391
3392 <h3><a name="CallStatic_type_Method_routines">CallStatic<type>Method Routines, CallStatic<type>MethodA Routines, CallStatic<type>MethodV Routines</a></h3>
3393
3394 <p><em>NativeType</em> <em class=
3395 "cEmphasis">CallStatic<type>Method</em><code class=
3396 "cCode">(JNIEnv *env, jclass clazz,<br />
3397 jmethodID methodID, ...);</code></p>
3398
3399 <p><em>NativeType</em> <em class=
3400 "cEmphasis">CallStatic<type>MethodA</em><code class=
3401 "cCode">(JNIEnv *env, jclass clazz,<br />
3402 jmethodID methodID, jvalue *args);</code></p>
3403
3404 <p><em>NativeType</em> <em class=
3405 "cEmphasis">CallStatic<type>MethodV</em><code class=
3406 "cCode">(JNIEnv *env, jclass clazz,<br />
3407 jmethodID methodID, va_list args);</code></p>
3408
3409 <p>This family of operations invokes a static method
3410 on a Java object, according to the specified method ID. The
3411 <code>methodID</code> argument must be obtained by
3412 calling <code>GetStaticMethodID</code><code class=
3413 "cCode">()</code>.</p>
3414
3415 <p>The method ID must be derived from <code class=
3416 "cCode">clazz</code>, not from one of its superclasses.</p>
3417
3418 <h4>CallStatic<type>Method Routines</h4>
3419
3420 <p>Programmers should place all arguments that are to
3421 be passed to the method immediately following the <code class=
3422 "cCode">methodID</code> argument. The <em class=
3423 "cEmphasis">CallStatic<type>Method</em> routine accepts these
3424 arguments and passes them to the Java method that the programmer
3425 wishes to invoke.</p>
3426
3427 <h4>CallStatic<type>MethodA Routines</h4>
3428
3429 <p>Programmers should place all arguments to the
3430 method in an <code>args</code> array of <code class=
3431 "cCode">jvalues</code> that immediately follows the <code class=
3432 "cCode">methodID</code> argument. The <em class=
3433 "cEmphasis">CallStaticMethodA</em> routine accepts the arguments in
3434 this array, and, in turn, passes them to the Java method that the
3435 programmer wishes to invoke.</p>
3436
3437 <h4>CallStatic<type>MethodV Routines</h4>
3438
3439 <p>Programmers should place all arguments to the
3440 method in an <code>args</code> argument of type
3441 <code>va_list</code> that immediately follows the
3442 <code>methodID</code> argument. The <em class=
3443 "cEmphasis">CallStaticMethodV</em> routine accepts the arguments,
3444 and, in turn, passes them to the Java method that the programmer
3445 wishes to invoke.</p>
3446
3447 <p>The following table describes each of the method
3448 calling routines according to their result types. You should
3449 replace <em>type</em> in <em class=
3450 "cEmphasis">CallStatic<type>Method</em> with the Java type of
3451 the method, or one of the actual method calling routine names from
3452 the table, and replace <em>NativeType</em> with
3453 the corresponding native type for that routine.</p>
3454
3455
3456 <table border="1" summary=
3457 "CallStatic<type>Method Calling Routines">
3458 <caption>CallStatic<type>Method Calling Routines</caption>
3459 <thead>
3460 <tr>
3461 <th>
3462
3463 CallStatic<type>Method Routine Name
3464 </th>
3465 <th>
3466 Native Type
3467 </th>
3468 </tr>
3469 </thead>
3470 <tbody>
3471 <tr>
3472 <td>
3473 <code class=
3474 "cCode">CallStaticVoidMethod</code><code class=
3475 "cCode">()</code>
3476
3477 <code class=
3478 "cCode">CallStaticVoidMethodA</code><code class=
3479 "cCode">()</code>
3480
3481 <code class=
3482 "cCode">CallStaticVoidMethod</code><code class=
3483 "cCode">V()</code>
3484 </td>
3485 <td>
3486 void
3487 </td>
3488 </tr>
3489 <tr>
3490 <td>
3491 <code class=
3492 "cCode">CallStaticObjectMethod</code><code class=
3493 "cCode">()</code>
3494
3495 <code class=
3496 "cCode">CallStaticObjectMethod</code><code class=
3497 "cCode">A()</code>
3498
3499 <code class=
3500 "cCode">CallStaticObjectMethod</code><code class=
3501 "cCode">V()</code>
3502 </td>
3503 <td>
3504 jobject
3505 </td>
3506 </tr>
3507 <tr>
3508 <td>
3509 <code class=
3510 "cCode">CallStaticBooleanMethod</code><code class=
3511 "cCode">()</code>
3512
3513 <code class=
3514 "cCode">CallStaticBooleanMethod</code><code class=
3515 "cCode">A()</code>
3516
3517 <code class=
3518 "cCode">CallStaticBooleanMethod</code><code class=
3519 "cCode">V()</code>
3520 </td>
3521 <td>
3522 jboolean
3523 </td>
3524 </tr>
3525 <tr>
3526 <td>
3527 <code class=
3528 "cCode">CallStaticByteMethod</code><code class=
3529 "cCode">()</code>
3530
3531 <code class=
3532 "cCode">CallStaticByteMethod</code><code class=
3533 "cCode">A()</code>
3534
3535 <code class=
3536 "cCode">CallStaticByteMethod</code><code class=
3537 "cCode">V()</code>
3538 </td>
3539 <td>
3540 jbyte
3541 </td>
3542 </tr>
3543 <tr>
3544 <td>
3545 <code class=
3546 "cCode">CallStaticCharMethod</code><code class=
3547 "cCode">()</code>
3548
3549 <code class=
3550 "cCode">CallStaticCharMethod</code><code class=
3551 "cCode">A()</code>
3552
3553 <code class=
3554 "cCode">CallStaticCharMethod</code><code class=
3555 "cCode">V()</code>
3556 </td>
3557 <td>
3558 jchar
3559 </td>
3560 </tr>
3561 <tr>
3562 <td>
3563 <code class=
3564 "cCode">CallStaticShortMethod</code><code class=
3565 "cCode">()</code>
3566
3567 <code class=
3568 "cCode">CallStaticShortMethod</code><code class=
3569 "cCode">A()</code>
3570
3571 <code class=
3572 "cCode">CallStaticShortMethod</code><code class=
3573 "cCode">V()</code>
3574 </td>
3575 <td>
3576 jshort
3577 </td>
3578 </tr>
3579 <tr>
3580 <td>
3581 <code class=
3582 "cCode">CallStaticIntMethod</code><code class=
3583 "cCode">()</code>
3584
3585 <code class=
3586 "cCode">CallStaticIntMethod</code><code class=
3587 "cCode">A()</code>
3588
3589 <code class=
3590 "cCode">CallStaticIntMethod</code><code class=
3591 "cCode">V()</code>
3592 </td>
3593 <td>
3594 jint
3595 </td>
3596 </tr>
3597 <tr>
3598 <td>
3599 <code class=
3600 "cCode">CallStaticLongMethod</code><code class=
3601 "cCode">()</code>
3602
3603 <code class=
3604 "cCode">CallStaticLongMethod</code><code class=
3605 "cCode">A()</code>
3606
3607 <code class=
3608 "cCode">CallStaticLongMethod</code><code class=
3609 "cCode">V()</code>
3610 </td>
3611 <td>
3612 jlong
3613 </td>
3614 </tr>
3615 <tr>
3616 <td>
3617 <code class=
3618 "cCode">CallStaticFloatMethod</code><code class=
3619 "cCode">()</code>
3620
3621 <code class=
3622 "cCode">CallStaticFloatMethod</code><code class=
3623 "cCode">A()</code>
3624
3625 <code class=
3626 "cCode">CallStaticFloatMethod</code><code class=
3627 "cCode">V()</code>
3628 </td>
3629 <td>
3630 jfloat
3631 </td>
3632 </tr>
3633 <tr>
3634 <td>
3635 <code class=
3636 "cCode">CallStaticDoubleMethod</code><code class=
3637 "cCode">()</code>
3638
3639 <code class=
3640 "cCode">CallStaticDoubleMethod</code><code class=
3641 "cCode">A()</code>
3642
3643 <code class=
3644 "cCode">CallStaticDoubleMethod</code><code class=
3645 "cCode">V()</code>
3646 </td>
3647 <td>
3648 jdouble
3649 </td>
3650 </tr>
3651 </tbody>
3652 </table>
3653
3654
3655
3656 <h4>LINKAGE:</h4>
3657 <p>Indices in the JNIEnv interface function table.</p>
3658
3659 <table border="1" summary=
3660 "CallStatic<type>Method Calling Routines">
3661 <caption>CallStatic<type>Method Calling Routines</caption>
3662 <thead>
3663 <tr>
3664 <th>
3665
3666 CallStatic<type>Method Routine Name
3667 </th>
3668 <th>
3669 Index
3670 </th>
3671 </tr>
3672 </thead>
3673 <tbody>
3674 <tr>
3675 <td>
3676 <code class=
3677 "cCode">CallStaticVoidMethod</code><code class=
3678 "cCode">()</code>
3679 <code class=
3680 "cCode">CallStaticVoidMethodA</code><code class=
3681 "cCode">()</code>
3682 <code class=
3683 "cCode">CallStaticVoidMethod</code><code class=
3684 "cCode">V()</code>
3685 </td>
3686 <td>141<br />
3687 143<br />
3688 142</td>
3689 </tr>
3690 <tr>
3691 <td>
3692 <code class=
3693 "cCode">CallStaticObjectMethod</code><code class=
3694 "cCode">()</code>
3695 <code class=
3696 "cCode">CallStaticObjectMethod</code><code class=
3697 "cCode">A()</code>
3698 <code class=
3699 "cCode">CallStaticObjectMethod</code><code class=
3700 "cCode">V()</code>
3701 </td>
3702 <td>114<br />
3703 116<br />
3704 115</td>
3705 </tr>
3706 <tr>
3707 <td>
3708 <code class=
3709 "cCode">CallStaticBooleanMethod</code><code class=
3710 "cCode">()</code>
3711 <code class=
3712 "cCode">CallStaticBooleanMethod</code><code class=
3713 "cCode">A()</code>
3714 <code class=
3715 "cCode">CallStaticBooleanMethod</code><code class=
3716 "cCode">V()</code>
3717 </td>
3718 <td>117<br />
3719 119<br />
3720 118</td>
3721 </tr>
3722 <tr>
3723 <td>
3724 <code class=
3725 "cCode">CallStaticByteMethod</code><code class=
3726 "cCode">()</code>
3727 <code class=
3728 "cCode">CallStaticByteMethod</code><code class=
3729 "cCode">A()</code>
3730 <code class=
3731 "cCode">CallStaticByteMethod</code><code class=
3732 "cCode">V()</code>
3733 </td>
3734 <td>120<br />
3735 122<br />
3736 121</td>
3737 </tr>
3738 <tr>
3739 <td>
3740 <code class=
3741 "cCode">CallStaticCharMethod</code><code class=
3742 "cCode">()</code>
3743 <code class=
3744 "cCode">CallStaticCharMethod</code><code class=
3745 "cCode">A()</code>
3746 <code class=
3747 "cCode">CallStaticCharMethod</code><code class=
3748 "cCode">V()</code>
3749 </td>
3750 <td>123<br />
3751 125<br />
3752 124</td>
3753 </tr>
3754 <tr>
3755 <td>
3756 <code class=
3757 "cCode">CallStaticShortMethod</code><code class=
3758 "cCode">()</code>
3759 <code class=
3760 "cCode">CallStaticShortMethod</code><code class=
3761 "cCode">A()</code>
3762 <code class=
3763 "cCode">CallStaticShortMethod</code><code class=
3764 "cCode">V()</code>
3765 </td>
3766 <td>126<br />
3767 128<br />
3768 127</td>
3769 </tr>
3770 <tr>
3771 <td>
3772 <code class=
3773 "cCode">CallStaticIntMethod</code><code class=
3774 "cCode">()</code>
3775 <code class=
3776 "cCode">CallStaticIntMethod</code><code class=
3777 "cCode">A()</code>
3778 <code class=
3779 "cCode">CallStaticIntMethod</code><code class=
3780 "cCode">V()</code>
3781 </td>
3782 <td>129<br />
3783 131<br />
3784 130</td>
3785 </tr>
3786 <tr>
3787 <td>
3788 <code class=
3789 "cCode">CallStaticLongMethod</code><code class=
3790 "cCode">()</code>
3791 <code class=
3792 "cCode">CallStaticLongMethod</code><code class=
3793 "cCode">A()</code>
3794 <code class=
3795 "cCode">CallStaticLongMethod</code><code class=
3796 "cCode">V()</code>
3797 </td>
3798 <td>132<br />
3799 134<br />
3800 133</td>
3801 </tr>
3802 <tr>
3803 <td>
3804 <code class=
3805 "cCode">CallStaticFloatMethod</code><code class=
3806 "cCode">()</code>
3807 <code class=
3808 "cCode">CallStaticFloatMethod</code><code class=
3809 "cCode">A()</code>
3810 <code class=
3811 "cCode">CallStaticFloatMethod</code><code class=
3812 "cCode">V()</code>
3813 </td>
3814 <td>135<br />
3815 137<br />
3816 136</td>
3817 </tr>
3818 <tr>
3819 <td>
3820 <code class=
3821 "cCode">CallStaticDoubleMethod</code><code class=
3822 "cCode">()</code>
3823 <code class=
3824 "cCode">CallStaticDoubleMethod</code><code class=
3825 "cCode">A()</code>
3826 <code class=
3827 "cCode">CallStaticDoubleMethod</code><code class=
3828 "cCode">V()</code>
3829 </td>
3830 <td>138<br />
3831 140<br />
3832 139</td>
3833 </tr>
3834 </tbody>
3835 </table>
3836 <h4>PARAMETERS:</h4>
3837
3838 <p><code>env</code>: the JNI interface
3839 pointer.</p>
3840
3841 <p><code>clazz</code>: a Java class
3842 object.</p>
3843
3844 <p><code>methodID</code>: a static
3845 method ID.</p>
3846
3847 <h4>Additional Parameter for
3848 CallStatic<type>Method Routines:</h4>
3849
3850 <p>arguments to the static method.</p>
3851
3852 <h4>Additional Parameter for
3853 CallStatic<type>MethodA Routines:</h4>
3854
3855 <p><code>args</code>: an array of
3856 arguments.</p>
3857
3858 <h4>Additional Parameter for
3859 CallStatic<type>MethodV Routines:</h4>
3860
3861 <p><code>args</code>: a <code class=
3862 "cCode">va_list</code> of arguments.</p>
3863
3864 <h4>RETURNS:</h4>
3865
3866 <p>Returns the result of calling the static Java
3867 method.</p>
3868
3869 <h4>THROWS:</h4>
3870
3871 <p><code>Exceptions raised during the
3872 execution of the Java method.</code></p>
3873 <!-- ******************************************************** -->
3874 <h2><a name="string_operations">String Operations</a></h2>
3875
3876 <h3><a name="NewString">NewString</a></h3>
3877
3878 <p><code>jstring NewString(JNIEnv *env,
3879 const jchar *unicodeChars,<br />
3880 jsize len);</code></p>
3881
3882 <p>Constructs a new <code class=
3883 "cCode">java.lang.String</code> object from an array of Unicode
3884 characters.</p>
3885
3886 <h4>LINKAGE:</h4>
3887 Index 163 in the JNIEnv interface function table.
3888 <h4>PARAMETERS:</h4>
3889
3890 <p><code>env</code>: the JNI interface
3891 pointer.</p>
3892
3893 <p><code>unicodeChars</code>: pointer
3894 to a Unicode string.</p>
3895
3896 <p><code>len</code>: length of the
3897 Unicode string.</p>
3898
3899 <h4>RETURNS:</h4>
3900
3901 <p>Returns a Java string object, or <code class=
3902 "cCode">NULL</code> if the string cannot be constructed.</p>
3903
3904 <h4>THROWS:</h4>
3905
3906 <p><code>OutOfMemoryError</code>: if
3907 the system runs out of memory.</p>
3908
3909 <h3><a name="GetStringLength">GetStringLength</a></h3>
3910
3911 <p><code>jsize GetStringLength(JNIEnv
3912 *env, jstring string);</code></p>
3913
3914 <p>Returns the length (the count of Unicode
3915 characters) of a Java string.</p>
3916
3917 <h4>LINKAGE:</h4>
3918 Index 164 in the JNIEnv interface function table.
3919 <h4>PARAMETERS:</h4>
3920
3921 <p><code>env</code>: the JNI interface
3922 pointer.</p>
3923
3924 <p><code>string</code>: a Java string
3925 object.</p>
3926
3927 <h4>RETURNS:</h4>
3928
3929 <p>Returns the length of the Java string.</p>
3930
3931 <h3><a name="GetStringChars">GetStringChars</a></h3>
3932
3933 <p><code>const jchar *
3934 GetStringChars(JNIEnv *env, jstring string,<br />
3935 jboolean *isCopy);</code></p>
3936
3937 <p>Returns a pointer to the array of Unicode
3938 characters of the string. This pointer is valid until <code class=
3939 "cCode">ReleaseStringChars()</code> is called.</p>
3940
3941 <p>If <code>isCopy</code> is not
3942 <code>NULL</code>, then <code class=
3943 "cCode">*isCopy</code> is set to <code class=
3944 "cCode">JNI_TRUE</code> if a copy is made; or it is set to
3945 <code>JNI_FALSE</code> if no copy is made.</p>
3946
3947 <h4>LINKAGE:</h4>
3948 Index 165 in the JNIEnv interface function table.
3949 <h4>PARAMETERS:</h4>
3950
3951 <p><code>env</code>: the JNI interface
3952 pointer.</p>
3953
3954 <p><code>string</code>: a Java string
3955 object.</p>
3956
3957 <p><code>isCopy</code>: a pointer to a
3958 boolean.</p>
3959
3960 <h4>RETURNS:</h4>
3961
3962 <p>Returns a pointer to a Unicode string, or
3963 <code>NULL</code> if the operation fails.</p>
3964
3965 <h3><a name="ReleaseStringChars">ReleaseStringChars</a></h3>
3966
3967 <p><code>void ReleaseStringChars(JNIEnv
3968 *env, jstring string,<br />
3969 const jchar *chars);</code></p>
3970
3971 <p>Informs the VM that the native code no longer
3972 needs access to <code>chars</code>. The <code class=
3973 "cCode">chars</code> argument is a pointer obtained from
3974 <code>string</code> using <code class=
3975 "cCode">GetStringChars()</code>.</p>
3976
3977 <h4>LINKAGE:</h4>
3978 Index 166 in the JNIEnv interface function table.
3979 <h4>PARAMETERS:</h4>
3980
3981 <p><code>env</code>: the JNI interface
3982 pointer.</p>
3983
3984 <p><code>string</code>: a Java string
3985 object.</p>
3986
3987 <p><code>chars</code>: a pointer to a
3988 Unicode string.</p>
3989
3990 <h3><a name="NewStringUTF">NewStringUTF</a></h3>
3991
3992 <p><code>jstring NewStringUTF(JNIEnv
3993 *env, const char *bytes);</code></p>
3994
3995 <p>Constructs a new <code class=
3996 "cCode">java.lang.String</code> object from an array of characters
3997 in modified UTF-8 encoding.</p>
3998
3999 <h4>LINKAGE:</h4>
4000 Index 167 in the JNIEnv interface function table.
4001 <h4>PARAMETERS:</h4>
4002
4003 <p><code>env</code>: the JNI interface
4004 pointer.</p>
4005
4006 <p><code>bytes</code>: the pointer to a
4007 modified UTF-8 string.</p>
4008
4009 <h4>RETURNS:</h4>
4010
4011 <p>Returns a Java string object, or <code class=
4012 "cCode">NULL</code> if the string cannot be constructed.</p>
4013
4014 <h4>THROWS:</h4>
4015
4016 <p><code>OutOfMemoryError</code>: if
4017 the system runs out of memory.</p>
4018
4019 <h3><a name="GetStringUTFLength">GetStringUTFLength</a></h3>
4020
4021 <p><code>jsize
4022 GetStringUTFLength(JNIEnv *env, jstring string);</code></p>
4023
4024 <p>Returns the length in bytes of the modified UTF-8
4025 representation of a string.</p>
4026
4027 <h4>LINKAGE:</h4>
4028 Index 168 in the JNIEnv interface function table.
4029 <h4>PARAMETERS:</h4>
4030
4031 <p><code>env</code>: the JNI interface
4032 pointer.</p>
4033
4034 <p><code>string</code>: a Java string
4035 object.</p>
4036
4037 <h4>RETURNS:</h4>
4038
4039 <p>Returns the UTF-8 length of the string.</p>
4040
4041 <h3><a name="GetStringUTFChars">GetStringUTFChars</a></h3>
4042
4043 <p><code>const char *
4044 GetStringUTFChars(JNIEnv *env, jstring string,<br />
4045 jboolean *isCopy);</code></p>
4046
4047 <p>Returns a pointer to an array of bytes
4048 representing the string in modified UTF-8 encoding. This array is
4049 valid until it is released by <code class=
4050 "cCode">ReleaseStringUTFChars()</code>.</p>
4051
4052 <p>If <code>isCopy</code> is not
4053 <code>NULL</code>, then <code class=
4054 "cCode">*isCopy</code> is set to <code class=
4055 "cCode">JNI_TRUE</code> if a copy is made; or it is set to
4056 <code>JNI_FALSE</code> if no copy is made.</p>
4057
4058 <h4>LINKAGE:</h4>
4059 Index 169 in the JNIEnv interface function table.
4060 <h4>PARAMETERS:</h4>
4061
4062 <p><code>env</code>: the JNI interface
4063 pointer.</p>
4064
4065 <p><code>string</code>: a Java string
4066 object.</p>
4067
4068 <p><code>isCopy</code>: a pointer to a
4069 boolean.</p>
4070
4071 <h4>RETURNS:</h4>
4072
4073 <p>Returns a pointer to a modified UTF-8 string, or
4074 <code>NULL</code> if the operation fails.</p>
4075
4076 <h3><a name="ReleaseStringUTFChars">ReleaseStringUTFChars</a></h3>
4077
4078 <p><code>void
4079 ReleaseStringUTFChars(JNIEnv *env, jstring string,<br />
4080 const char *utf);</code></p>
4081
4082 <p>Informs the VM that the native code no longer
4083 needs access to <code>utf</code>. The <code class=
4084 "cCode">utf</code> argument is a pointer derived from <code class=
4085 "cCode">string</code> using <code class=
4086 "cCode">GetStringUTFChars()</code>.</p>
4087
4088 <h4>LINKAGE:</h4>
4089 Index 170 in the JNIEnv interface function table.
4090 <h4>PARAMETERS:</h4>
4091
4092 <p><code>env</code>: the JNI interface
4093 pointer.</p>
4094
4095 <p><code>string</code>: a Java string
4096 object.</p>
4097
4098 <p><code>utf</code>: a pointer to a
4099 modified UTF-8 string.</p>
4100
4101
4102 <p><strong>Note</strong>: In JDK/JRE 1.1, programmers can get primitive array elements in
4103 a user-supplied buffer. As of JDK/JRE 1.2 additional set of
4104 functions are provided allowing native code to obtain characters in
4105 Unicode (UTF-16) or modified UTF-8 encoding in a user-supplied
4106 buffer. See the functions below.</p>
4107
4108 <h3><a name="GetStringRegion">GetStringRegion</a></h3>
4109 <p><code>void GetStringRegion(JNIEnv *env, jstring str, jsize
4110 start, jsize len, jchar *buf);</code></p>
4111 <p>Copies <code>len</code> number of Unicode characters beginning
4112 at offset <code>start</code> to the given buffer
4113 <code>buf</code>.</p>
4114 <p>Throws <code>StringIndexOutOfBoundsException</code> on index
4115 overflow.</p>
4116 <h4>LINKAGE:</h4>
4117 Index 220 in the JNIEnv interface function table.
4118 <h4>SINCE:</h4>
4119 <p>JDK/JRE 1.2</p>
4120 <h3><a name="GetStringUTFRegion">GetStringUTFRegion</a></h3>
4121 <p>< <code>void GetStringUTFRegion(JNIEnv *env, jstring str,
4122 jsize start, jsize len, char *buf);</code></p>
4123 <p>Translates <code>len</code> number of Unicode characters
4124 beginning at offset <code>start</code> into modified UTF-8 encoding
4125 and place the result in the given buffer <code>buf</code>.</p>
4126 <p>Throws <code>StringIndexOutOfBoundsException</code> on index
4127 overflow.</p>
4128 <h4>LINKAGE:</h4>
4129 Index 221 in the JNIEnv interface function table.
4130 <h4>SINCE:</h4>
4131 <p>JDK/JRE 1.2</p>
4132 <h3><a name="GetStringCritical_ReleaseStringCritical">GetStringCritical, ReleaseStringCritical</a></h3>
4133 <p><code>const jchar * GetStringCritical(JNIEnv *env, jstring
4134 string, jboolean *isCopy);<br />
4135 void ReleaseStringCritical(JNIEnv *env, jstring string, const jchar
4136 *carray);</code></p>
4137 <p>The semantics of these two functions are similar to the existing
4138 <code>Get/ReleaseStringChars</code> functions. If possible, the VM
4139 returns a pointer to string elements; otherwise, a copy is made.
4140 <strong>However, there are significant restrictions on how these
4141 functions can be used.</strong> In a code segment enclosed by
4142 <code>Get/ReleaseStringCritical</code> calls, the native code must
4143 not issue arbitrary JNI calls, or cause the current thread to
4144 block.</p>
4145 <p>The restrictions on <code>Get/ReleaseStringCritical</code> are
4146 similar to those on
4147 <code>Get/ReleasePrimitiveArrayCritical</code>.</p>
4148 <h4>LINKAGE (GetStringCritical):</h4>
4149 Index 224 in the JNIEnv interface function table.
4150 <h4>LINKAGE (ReleaseStingCritical):</h4>
4151 Index 225 in the JNIEnv interface function table.
4152 <h4>SINCE:</h4>
4153 <p>JDK/JRE 1.2</p>
4154 <a name="reflection"></a>
4155 <!-- ******************************************************** -->
4156 <h2><a name="array_operations">Array Operations</a></h2>
4157
4158 <h3><a name="GetArrayLength">GetArrayLength</a></h3>
4159
4160 <p><code>jsize GetArrayLength(JNIEnv
4161 *env, jarray array);</code></p>
4162
4163 <p>Returns the number of elements in the array.</p>
4164
4165 <h4>LINKAGE:</h4>
4166 Index 171 in the JNIEnv interface function table.
4167 <h4>PARAMETERS:</h4>
4168
4169 <p><code>env</code>: the JNI interface
4170 pointer.</p>
4171
4172 <p><code>array</code>: a Java array
4173 object.</p>
4174
4175 <h4>RETURNS:</h4>
4176
4177 <p>Returns the length of the array.</p>
4178
4179 <h3><a name="NewObjectArray">NewObjectArray</a></h3>
4180
4181 <p><code>jobjectArray
4182 NewObjectArray(JNIEnv *env, jsize length,<br />
4183 jclass elementClass, jobject initialElement);</code></p>
4184
4185 <p>Constructs a new array holding objects in class
4186 <code>elementClass</code>. All elements are initially
4187 set to <code>initialElement</code>.</p>
4188
4189 <h4>LINKAGE:</h4>
4190 Index 172 in the JNIEnv interface function table.
4191 <h4>PARAMETERS:</h4>
4192
4193 <p><code>env</code>: the JNI interface
4194 pointer.</p>
4195
4196 <p><code>length</code>: array size.</p>
4197
4198 <p><code>elementClass</code>: array
4199 element class.</p>
4200
4201 <p><code>initialElement</code>:
4202 initialization value.</p>
4203
4204 <h4>RETURNS:</h4>
4205
4206 <p>Returns a Java array object, or <code class=
4207 "cCode">NULL</code> if the array cannot be constructed.</p>
4208
4209 <h4>THROWS:</h4>
4210
4211 <p><code>OutOfMemoryError</code>: if
4212 the system runs out of memory.</p>
4213
4214 <h3><a name="GetObjectArrayElement">GetObjectArrayElement</a></h3>
4215
4216 <p><code>jobject
4217 GetObjectArrayElement(JNIEnv *env,<br />
4218 jobjectArray array, jsize index);</code></p>
4219
4220 <p>Returns an element of an <code class=
4221 "cCode">Object</code> array.</p>
4222
4223 <h4>LINKAGE:</h4>
4224 Index 173 in the JNIEnv interface function table.
4225 <h4>PARAMETERS:</h4>
4226
4227 <p><code>env</code>: the JNI interface
4228 pointer.</p>
4229
4230 <p><code>array</code>: a Java
4231 array.</p>
4232
4233 <p><code>index</code>: array index.</p>
4234
4235 <h4>RETURNS:</h4>
4236
4237 <p>Returns a Java object.</p>
4238
4239 <h4>THROWS:</h4>
4240
4241 <p><code class=
4242 "cCode">ArrayIndexOutOfBoundsException</code>: if <code class=
4243 "cCode">index</code> does not specify a valid index in the
4244 array.</p>
4245
4246 <h3><a name="SetObjectArrayElement">SetObjectArrayElement</a></h3>
4247
4248 <p><code>void
4249 SetObjectArrayElement(JNIEnv *env, jobjectArray array,<br />
4250 jsize index, jobject value);</code></p>
4251
4252 <p>Sets an element of an <code class=
4253 "cCode">Object</code> array.</p>
4254
4255 <h4>LINKAGE:</h4>
4256 Index 174 in the JNIEnv interface function table.
4257 <h4>PARAMETERS:</h4>
4258
4259 <p><code>env</code>: the JNI interface
4260 pointer.</p>
4261
4262 <p><code>array</code>: a Java
4263 array.</p>
4264
4265 <p><code>index</code>: array index.</p>
4266
4267 <p><code>value</code>: the new
4268 value.</p>
4269
4270 <h4>THROWS:</h4>
4271
4272 <p><code class=
4273 "cCode">ArrayIndexOutOfBoundsException</code>: if <code class=
4274 "cCode">index</code> does not specify a valid index in the
4275 array.</p>
4276
4277 <p><code>ArrayStoreException</code>: if
4278 the class of <code>value</code> is not a subclass of
4279 the element class of the array.</p>
4280
4281 <h3><a name="New_PrimitiveType_Array_routines">New<PrimitiveType>Array Routines</a></h3>
4282
4283 <p><em>ArrayType</em> <em class=
4284 "cEmphasis">New<PrimitiveType>Array</em><code class=
4285 "cCode">(JNIEnv *env, jsize length);</code></p>
4286
4287 <p>A family of operations used to construct a new
4288 primitive array object. The following table
4289 describes the specific primitive array constructors. You should
4290 replace <em>New<PrimitiveType>Array</em>
4291 with one of the actual primitive array constructor routine names
4292 from this table, and replace ArrayType with the
4293 corresponding array type for that routine.</p>
4294
4295
4296
4297 <table border="1" summary=
4298 "New<PrimitiveType>Array Family of Array Constructors">
4299 <caption>New<PrimitiveType>Array Family of Array Constructors</caption>
4300 <thead>
4301 <tr>
4302 <th>
4303
4304 New<PrimitiveType>Array Routines
4305 </th>
4306 <th>
4307 Array Type
4308 </th>
4309 </tr>
4310 </thead>
4311 <tbody>
4312 <tr>
4313 <td>
4314 <code class=
4315 "cCode">NewBooleanArray()</code>
4316 </td>
4317 <td>
4318 jbooleanArray
4319 </td>
4320 </tr>
4321 <tr>
4322 <td>
4323 <code class=
4324 "cCode">NewByteArray()</code>
4325 </td>
4326 <td>
4327 jbyteArray
4328 </td>
4329 </tr>
4330 <tr>
4331 <td>
4332 <code class=
4333 "cCode">NewCharArray()</code>
4334 </td>
4335 <td>
4336 jcharArray
4337 </td>
4338 </tr>
4339 <tr>
4340 <td>
4341 <code class=
4342 "cCode">NewShortArray()</code>
4343 </td>
4344 <td>
4345 jshortArray
4346 </td>
4347 </tr>
4348 <tr>
4349 <td>
4350 <code class=
4351 "cCode">NewIntArray()</code>
4352 </td>
4353 <td>
4354 jintArray
4355 </td>
4356 </tr>
4357 <tr>
4358 <td>
4359 <code class=
4360 "cCode">NewLongArray()</code>
4361 </td>
4362 <td>
4363 jlongArray
4364 </td>
4365 </tr>
4366 <tr>
4367 <td>
4368 <code class=
4369 "cCode">NewFloatArray()</code>
4370 </td>
4371 <td>
4372 jfloatArray
4373 </td>
4374 </tr>
4375 <tr>
4376 <td>
4377 <code class=
4378 "cCode">NewDoubleArray()</code>
4379 </td>
4380 <td>
4381 jdoubleArray
4382 </td>
4383 </tr>
4384 </tbody>
4385 </table>
4386
4387
4388
4389 <h4>LINKAGE:</h4>
4390 <p>Indices in the JNIEnv interface function table.</p>
4391 <table border="1" summary=
4392 "New<PrimitiveType>Array Family of Array Constructors">
4393 <caption>New<PrimitiveType>Array Family of Array Constructors</caption>
4394 <thead>
4395 <tr>
4396 <th>
4397
4398 New<PrimitiveType>Array Routines
4399 </th>
4400 <th>
4401 Index
4402 </th>
4403 </tr>
4404 </thead>
4405 <tbody>
4406 <tr>
4407 <td>
4408 <code class=
4409 "cCode">NewBooleanArray()</code>
4410 </td>
4411 <td>
4412 175
4413 </td>
4414 </tr>
4415 <tr>
4416 <td>
4417 <code class=
4418 "cCode">NewByteArray()</code>
4419 </td>
4420 <td>
4421 176
4422 </td>
4423 </tr>
4424 <tr>
4425 <td>
4426 <code class=
4427 "cCode">NewCharArray()</code>
4428 </td>
4429 <td>
4430 177
4431 </td>
4432 </tr>
4433 <tr>
4434 <td>
4435 <code class=
4436 "cCode">NewShortArray()</code>
4437 </td>
4438 <td>
4439 178
4440 </td>
4441 </tr>
4442 <tr>
4443 <td>
4444 <code class=
4445 "cCode">NewIntArray()</code>
4446 </td>
4447 <td>
4448 179
4449 </td>
4450 </tr>
4451 <tr>
4452 <td>
4453 <code class=
4454 "cCode">NewLongArray()</code>
4455 </td>
4456 <td>
4457 180
4458 </td>
4459 </tr>
4460 <tr>
4461 <td>
4462 <code class=
4463 "cCode">NewFloatArray()</code>
4464 </td>
4465 <td>
4466 181
4467 </td>
4468 </tr>
4469 <tr>
4470 <td>
4471 <code class=
4472 "cCode">NewDoubleArray()</code>
4473 </td>
4474 <td>
4475 182
4476 </td>
4477 </tr>
4478 </tbody>
4479 </table>
4480 <h4>PARAMETERS:</h4>
4481
4482 <p><code>env</code>: the JNI interface
4483 pointer.</p>
4484
4485 <p><code>length</code>: the array
4486 length.</p>
4487
4488 <h4>RETURNS:</h4>
4489
4490 <p>Returns a Java array, or <code class=
4491 "cCode">NULL</code> if the array cannot be constructed.</p>
4492
4493 <h3><a name="Get_PrimitiveType_ArrayElements_routines">Get<PrimitiveType>ArrayElements Routines</a></h3>
4494
4495 <p><em>NativeType</em> <code class=
4496 "cCode">*</code><em class=
4497 "cEmphasis">Get<PrimitiveType>ArrayElements</em><code style=
4498 "font-style: normal;">(JNIEnv *env,<br /></code>
4499 <code style="font-style: italic;">ArrayType</code>
4500 <code>array, jboolean *isCopy);</code></p>
4501
4502 <p>A family of functions that returns the body of the
4503 primitive array. The result is valid until the corresponding
4504 <em style="font-style: italic;" class=
4505 "cEmphasis">Release</em><code style="font-style: italic;" class=
4506 "cCode"><</code><em style="font-style: italic;" class=
4507 "cEmphasis">PrimitiveType</em><code style="font-style: italic;"
4508 class="cCode">></code><em>ArrayElements()</em>
4509 function is called. S<em>ince the returned array
4510 may be a copy of the Java array, changes made to the returned array
4511 will not necessarily be reflected in the original</em> <code style=
4512 "font-style: normal;">array</code> <em style=
4513 "font-style: italic;">until</em> <code style=
4514 "font-style: italic;" class=
4515 "cCode">Release<PrimitiveType>ArrayElements()</code>
4516 <em>is called.</em></p>
4517
4518 <p>If <code>isCopy</code> is not
4519 <code>NULL</code>, then <code class=
4520 "cCode">*isCopy</code> is set to <code class=
4521 "cCode">JNI_TRUE</code> if a copy is made; or it is set to
4522 <code>JNI_FALSE</code> if no copy is made.</p>
4523
4524 <p>The following table describes the specific
4525 primitive array element accessors. You should make the following
4526 substitutions:</p>
4527
4528
4529 <ul>
4530 <li>Replace <em class=
4531 "cEmphasis">Get<PrimitiveType>ArrayElements</em> with one of
4532 the actual primitive element accessor routine names from the following
4533 table.</li>
4534 <li>Replace ArrayType with the corresponding array type.</li>
4535 <li>Replace <em>NativeType</em> with the
4536 corresponding native type for that routine.</li>
4537 </ul>
4538
4539
4540
4541 <p>Regardless of how boolean arrays are represented
4542 in the Java VM, <code class=
4543 "cCode">GetBooleanArrayElements()</code> always returns a pointer
4544 to <code>jbooleans</code>, with each byte denoting an
4545 element (the unpacked representation). All arrays of other types
4546 are guaranteed to be contiguous in memory.</p>
4547
4548
4549 <table border="1" summary=
4550 "Get<PrimitiveType>ArrayElements Family of Accessor Routines">
4551 <caption>Get<PrimitiveType>ArrayElements Family of Accessor
4552 Routines</caption>
4553 <thead>
4554 <tr>
4555 <th>
4556
4557 Get<PrimitiveType>ArrayElements Routines
4558 </th>
4559 <th>
4560 Array Type
4561 </th>
4562 <th>
4563 Native Type
4564 </th>
4565 </tr>
4566 </thead>
4567 <tbody>
4568 <tr>
4569 <td>
4570 <code class=
4571 "cCode">GetBooleanArrayElements()</code>
4572 </td>
4573 <td>
4574 jbooleanArray
4575 </td>
4576 <td>
4577 jboolean
4578 </td>
4579 </tr>
4580 <tr>
4581 <td>
4582 <code class=
4583 "cCode">GetByteArrayElements()</code>
4584 </td>
4585 <td>
4586 jbyteArray
4587 </td>
4588 <td>
4589 jbyte
4590 </td>
4591 </tr>
4592 <tr>
4593 <td>
4594 <code class=
4595 "cCode">GetCharArrayElements()</code>
4596 </td>
4597 <td>
4598 jcharArray
4599 </td>
4600 <td>
4601 jchar
4602 </td>
4603 </tr>
4604 <tr>
4605 <td>
4606 <code class=
4607 "cCode">GetShortArrayElements()</code>
4608 </td>
4609 <td>
4610 jshortArray
4611 </td>
4612 <td>
4613 jshort
4614 </td>
4615 </tr>
4616 <tr>
4617 <td>
4618 <code class=
4619 "cCode">GetIntArrayElements()</code>
4620 </td>
4621 <td>
4622 jintArray
4623 </td>
4624 <td>
4625 jint
4626 </td>
4627 </tr>
4628 <tr>
4629 <td>
4630 <code class=
4631 "cCode">GetLongArrayElements()</code>
4632 </td>
4633 <td>
4634 jlongArray
4635 </td>
4636 <td>
4637 jlong
4638 </td>
4639 </tr>
4640 <tr>
4641 <td>
4642 <code class=
4643 "cCode">GetFloatArrayElements()</code>
4644 </td>
4645 <td>
4646 jfloatArray
4647 </td>
4648 <td>
4649 jfloat
4650 </td>
4651 </tr>
4652 <tr>
4653 <td>
4654 <code class=
4655 "cCode">GetDoubleArrayElements()</code>
4656 </td>
4657 <td>
4658 jdoubleArray
4659 </td>
4660 <td>
4661 jdouble
4662 </td>
4663 </tr>
4664 </tbody>
4665 </table>
4666
4667
4668
4669 <h4>LINKAGE:</h4>
4670 <p>Indices in the JNIEnv interface function table.</p>
4671 <table border="1" summary="Get<PrimitiveType>ArrayElements Family of Accessor Routines">
4672 <caption>Get<PrimitiveType>ArrayElements Family of Accessor
4673 Routines</caption>
4674 <thead>
4675 <tr>
4676 <th>
4677
4678 Get<PrimitiveType>ArrayElements Routines
4679 </th>
4680 <th>
4681 Index
4682 </th>
4683 </tr>
4684 </thead>
4685 <tbody>
4686 <tr>
4687 <td>
4688 <code class=
4689 "cCode">GetBooleanArrayElements()</code>
4690 </td>
4691 <td>
4692 183
4693 </td>
4694 </tr>
4695 <tr>
4696 <td>
4697 <code class=
4698 "cCode">GetByteArrayElements()</code>
4699 </td>
4700 <td>
4701 184
4702 </td>
4703 </tr>
4704 <tr>
4705 <td>
4706 <code class=
4707 "cCode">GetCharArrayElements()</code>
4708 </td>
4709 <td>
4710 185
4711 </td>
4712 </tr>
4713 <tr>
4714 <td>
4715 <code class=
4716 "cCode">GetShortArrayElements()</code>
4717 </td>
4718 <td>
4719 186
4720 </td>
4721 </tr>
4722 <tr>
4723 <td>
4724 <code class=
4725 "cCode">GetIntArrayElements()</code>
4726 </td>
4727 <td>
4728 187
4729 </td>
4730 </tr>
4731 <tr>
4732 <td>
4733 <code class=
4734 "cCode">GetLongArrayElements()</code>
4735 </td>
4736 <td>
4737 188
4738 </td>
4739 </tr>
4740 <tr>
4741 <td>
4742 <code class=
4743 "cCode">GetFloatArrayElements()</code>
4744 </td>
4745 <td>
4746 189
4747 </td>
4748 </tr>
4749 <tr>
4750 <td>
4751 <code class=
4752 "cCode">GetDoubleArrayElements()</code>
4753 </td>
4754 <td>
4755 190
4756 </td>
4757 </tr>
4758 </tbody>
4759 </table>
4760 <h4>PARAMETERS:</h4>
4761
4762 <p><code>env</code>: the JNI interface
4763 pointer.</p>
4764
4765 <p><code>array</code>: a Java string
4766 object.</p>
4767
4768 <p><code>isCopy</code>: a pointer to a
4769 boolean.</p>
4770
4771 <h4>RETURNS:</h4>
4772
4773 <p>Returns a pointer to the array elements, or
4774 <code>NULL</code> if the operation fails.</p>
4775
4776 <h3><a name="Release_PrimitiveType_ArrayElements_routines">Release<PrimitiveType>ArrayElements Routines</a></h3>
4777
4778 <p><code>void</code> <em class=
4779 "cEmphasis">Release<PrimitiveType>ArrayElements</em><code style="font-style: normal;"
4780 class="cCode">(JNIEnv *env,<br /></code> <code style=
4781 "font-style: italic;">ArrayType</code> <code class=
4782 "cCode">array,</code> <em>NativeType</em>
4783 <code>*elems, jint mode);</code></p>
4784
4785 <p>A family of functions that informs the VM that the
4786 native code no longer needs access to <code class=
4787 "cCode">elems</code>. The <code>elems</code> argument
4788 is a pointer derived from <code>array</code> using
4789 the corresponding <em>Get</em><code class=
4790 "cCode"><</code><em class=
4791 "cEmphasis">PrimitiveType</em><code class=
4792 "cCode">></code><em>ArrayElements()</em>
4793 function. If necessary, this function copies back all changes made
4794 to <code>elems</code> to the original array.</p>
4795
4796 <p>The <code>mode</code> argument
4797 provides information on how the array buffer should be released.
4798 <code>mode</code> has no effect if <code class=
4799 "cCode">elems</code> is not a copy of the elements in <code class=
4800 "cCode">array</code>. Otherwise, <code>mode</code>
4801 has the following impact, as shown in the following table:</p>
4802
4803 <table border="1" summary=
4804 "Primitive Array Release Modes">
4805 <caption>Primitive Array Release
4806 Modes</caption>
4807 <thead>
4808 <tr>
4809 <th>
4810 mode
4811 </th>
4812 <th>
4813 actions
4814 </th>
4815 </tr>
4816 </thead>
4817 <tbody>
4818 <tr>
4819 <td>
4820 <code>0</code>
4821 </td>
4822 <td>
4823 copy back the content and free the
4824 <code>elems</code> buffer
4825 </td>
4826 </tr>
4827 <tr>
4828 <td>
4829 <code>JNI_COMMIT</code>
4830 </td>
4831 <td>
4832 copy back the content but do not free the
4833 <code>elems</code> buffer
4834 </td>
4835 </tr>
4836 <tr>
4837 <td>
4838 <code>JNI_ABORT</code>
4839 </td>
4840 <td>
4841 free the buffer without copying back the
4842 possible changes
4843 </td>
4844 </tr>
4845 </tbody>
4846 </table>
4847
4848
4849
4850 <p>In most cases, programmers pass “0” to
4851 the <code>mode</code> argument to ensure consistent
4852 behavior for both pinned and copied arrays. The other options give
4853 the programmer more control over memory management and should be
4854 used with extreme care.</p>
4855
4856 <p>The next table describes the specific routines
4857 that comprise the family of primitive array disposers. You should
4858 make the following substitutions:</p>
4859
4860
4861 <ul>
4862 <li>Replace <em>Release<PrimitiveType>ArrayElements</em> with one
4863 of the actual primitive array disposer routine names from the following table.</li>
4864 <li>Replace ArrayType with the corresponding array type.</li>
4865 <li>Replace <em>NativeType</em> with the
4866 corresponding native type for that routine.</li>
4867 </ul>
4868
4869 <table border="1" summary=
4870 "Release<PrimitiveType>ArrayElements Family of Array Routines">
4871 <caption>Release<PrimitiveType>ArrayElements Family of Array
4872 Routines</caption>
4873 <thead>
4874 <tr>
4875 <th>
4876
4877 Release<PrimitiveType>ArrayElements Routines
4878 </th>
4879 <th>
4880 Array Type
4881 </th>
4882 <th>
4883 Native Type
4884 </th>
4885 </tr>
4886 </thead>
4887 <tbody>
4888 <tr>
4889 <td>
4890 <code class=
4891 "cCode">ReleaseBooleanArrayElements()</code>
4892 </td>
4893 <td>
4894 jbooleanArray
4895 </td>
4896 <td>
4897 jboolean
4898 </td>
4899 </tr>
4900 <tr>
4901 <td>
4902 <code class=
4903 "cCode">ReleaseByteArrayElements()</code>
4904 </td>
4905 <td>
4906 jbyteArray
4907 </td>
4908 <td>
4909 jbyte
4910 </td>
4911 </tr>
4912 <tr>
4913 <td>
4914 <code class=
4915 "cCode">ReleaseCharArrayElements()</code>
4916 </td>
4917 <td>
4918 jcharArray
4919 </td>
4920 <td>
4921 jchar
4922 </td>
4923 </tr>
4924 <tr>
4925 <td>
4926 <code class=
4927 "cCode">ReleaseShortArrayElements()</code>
4928 </td>
4929 <td>
4930 jshortArray
4931 </td>
4932 <td>
4933 jshort
4934 </td>
4935 </tr>
4936 <tr>
4937 <td>
4938 <code class=
4939 "cCode">ReleaseIntArrayElements()</code>
4940 </td>
4941 <td>
4942 jintArray
4943 </td>
4944 <td>
4945 jint
4946 </td>
4947 </tr>
4948 <tr>
4949 <td>
4950 <code class=
4951 "cCode">ReleaseLongArrayElements()</code>
4952 </td>
4953 <td>
4954 jlongArray
4955 </td>
4956 <td>
4957 jlong
4958 </td>
4959 </tr>
4960 <tr>
4961 <td>
4962 <code class=
4963 "cCode">ReleaseFloatArrayElements()</code>
4964 </td>
4965 <td>
4966 jfloatArray
4967 </td>
4968 <td>
4969 jfloat
4970 </td>
4971 </tr>
4972 <tr>
4973 <td>
4974 <code class=
4975 "cCode">ReleaseDoubleArrayElements()</code>
4976 </td>
4977 <td>
4978 jdoubleArray
4979 </td>
4980 <td>
4981 jdouble
4982 </td>
4983 </tr>
4984 </tbody>
4985 </table>
4986
4987
4988
4989 <h4>LINKAGE:</h4>
4990 <p>Indices in the JNIEnv interface function table.</p>
4991 <table border="1" summary="Release<PrimitiveType>ArrayElements Family of Array Routines">
4992 <caption>Release<PrimitiveType>ArrayElements Family of Array
4993 Routines</caption>
4994 <thead>
4995 <tr>
4996 <th>
4997
4998 Release<PrimitiveType>ArrayElements Routines
4999 </th>
5000 <th>
5001 Index
5002 </th>
5003 </tr>
5004 </thead>
5005 <tbody>
5006 <tr>
5007 <td>
5008 <code class=
5009 "cCode">ReleaseBooleanArrayElements()</code>
5010 </td>
5011 <td>
5012 191
5013 </td>
5014 </tr>
5015 <tr>
5016 <td>
5017 <code class=
5018 "cCode">ReleaseByteArrayElements()</code>
5019 </td>
5020 <td>
5021 192
5022 </td>
5023 </tr>
5024 <tr>
5025 <td>
5026 <code class=
5027 "cCode">ReleaseCharArrayElements()</code>
5028 </td>
5029 <td>
5030 193
5031 </td>
5032 </tr>
5033 <tr>
5034 <td>
5035 <code class=
5036 "cCode">ReleaseShortArrayElements()</code>
5037 </td>
5038 <td>
5039 194
5040 </td>
5041 </tr>
5042 <tr>
5043 <td>
5044 <code class=
5045 "cCode">ReleaseIntArrayElements()</code>
5046 </td>
5047 <td>
5048 195
5049 </td>
5050 </tr>
5051 <tr>
5052 <td>
5053 <code class=
5054 "cCode">ReleaseLongArrayElements()</code>
5055 </td>
5056 <td>
5057 196
5058 </td>
5059 </tr>
5060 <tr>
5061 <td>
5062 <code class=
5063 "cCode">ReleaseFloatArrayElements()</code>
5064 </td>
5065 <td>
5066 197
5067 </td>
5068 </tr>
5069 <tr>
5070 <td>
5071 <code class=
5072 "cCode">ReleaseDoubleArrayElements()</code>
5073 </td>
5074 <td>
5075 198
5076 </td>
5077 </tr>
5078 </tbody>
5079 </table>
5080 <h4>PARAMETERS:</h4>
5081
5082 <p><code>env</code>: the JNI interface
5083 pointer.</p>
5084
5085 <p><code>array</code>: a Java array
5086 object.</p>
5087
5088 <p><code>elems</code>: a pointer to
5089 array elements.</p>
5090
5091 <p><code>mode</code>: the release
5092 mode.</p>
5093
5094 <h3><a name="Get_PrimitiveType_ArrayRegion_routines">Get<PrimitiveType>ArrayRegion Routines</a></h3>
5095
5096 <p><em>void</em> <em class=
5097 "cEmphasis">Get<PrimitiveType>ArrayRegion</em><code class=
5098 "cCode">(JNIEnv *env,</code> <em>ArrayType</em>
5099 <code>array,<br />
5100 jsize start, jsize len,</code> <em class=
5101 "cEmphasis">NativeType</em> <code>*buf);</code></p>
5102
5103 <p>A family of functions that copies a region of a
5104 primitive array into a buffer.</p>
5105
5106 <p>The following table describes the specific
5107 primitive array element accessors. You should do the following
5108 substitutions:</p>
5109
5110
5111 <ul>
5112 <li>Replace <em>Get<PrimitiveType>ArrayRegion</em> with one of
5113 the actual primitive element accessor routine names from the following table.</li>
5114 <li>Replace <em>ArrayType</em> with the
5115 corresponding array type.</li>
5116 <li>Replace <em>NativeType</em> with the
5117 corresponding native type for that routine.</li>
5118 </ul>
5119
5120
5121
5122
5123 <table border="1" summary="Get<PrimitiveType>ArrayRegion Family of Array Accessor Routines">
5124 <caption>Get<PrimitiveType>ArrayRegion Family of Array Accessor Routines</caption>
5125 <thead>
5126 <tr>
5127 <th>Get<PrimitiveType>ArrayRegion Routine</th>
5128 <th>Array Type</th>
5129 <th>Native Type</th>
5130 </tr>
5131 </thead>
5132 <tbody>
5133 <tr>
5134 <td><code>GetBooleanArrayRegion()</code></td>
5135 <td>jbooleanArray</td>
5136 <td>jboolean</td>
5137 </tr>
5138 <tr>
5139 <td><code>GetByteArrayRegion()</code>
5140 </td>
5141 <td>
5142 jbyteArray
5143 </td>
5144 <td>
5145 jbyte
5146 </td>
5147 </tr>
5148 <tr>
5149 <td>
5150 <code class=
5151 "cCode">GetCharArrayRegion()</code>
5152 </td>
5153 <td>
5154 jcharArray
5155 </td>
5156 <td>
5157 jchar
5158 </td>
5159 </tr>
5160 <tr>
5161 <td>
5162 <code class=
5163 "cCode">GetShortArrayRegion()</code>
5164 </td>
5165 <td>
5166 jshortArray
5167 </td>
5168 <td>
5169 jhort
5170 </td>
5171 </tr>
5172 <tr>
5173 <td>
5174 <code class=
5175 "cCode">GetIntArrayRegion()</code>
5176 </td>
5177 <td>
5178 jintArray
5179 </td>
5180 <td>
5181 jint
5182 </td>
5183 </tr>
5184 <tr>
5185 <td>
5186 <code class=
5187 "cCode">GetLongArrayRegion()</code>
5188 </td>
5189 <td>
5190 jlongArray
5191 </td>
5192 <td>
5193 jlong
5194 </td>
5195 </tr>
5196 <tr>
5197 <td>
5198 <code class=
5199 "cCode">GetFloatArrayRegion()</code>
5200 </td>
5201 <td>
5202 jfloatArray
5203 </td>
5204 <td>
5205 jloat
5206 </td>
5207 </tr>
5208 <tr>
5209 <td>
5210 <code class=
5211 "cCode">GetDoubleArrayRegion()</code>
5212 </td>
5213 <td>
5214 jdoubleArray
5215 </td>
5216 <td>
5217 jdouble
5218 </td>
5219 </tr>
5220 </tbody>
5221 </table>
5222
5223
5224
5225 <h4>LINKAGE:</h4>
5226 <p>Indices in the JNIEnv interface function table.</p>
5227 <table border="1" summary=
5228 "Get<PrimitiveType>ArrayRegion Family of Array Accessor Routines"
5229 >
5230 <caption>Get<PrimitiveType>ArrayRegion Family of Array Accessor
5231 Routines</caption>
5232 <thead>
5233 <tr>
5234 <th>
5235
5236 Get<PrimitiveType>ArrayRegion Routine
5237 </th>
5238 <th>
5239 Index
5240 </th>
5241 </tr>
5242 </thead>
5243 <tbody>
5244 <tr>
5245 <td>
5246 <code class=
5247 "cCode">GetBooleanArrayRegion()</code>
5248 </td>
5249 <td>
5250 199
5251 </td>
5252 </tr>
5253 <tr>
5254 <td>
5255 <code class=
5256 "cCode">GetByteArrayRegion()</code>
5257 </td>
5258 <td>
5259 200
5260 </td>
5261 </tr>
5262 <tr>
5263 <td>
5264 <code class=
5265 "cCode">GetCharArrayRegion()</code>
5266 </td>
5267 <td>
5268 201
5269 </td>
5270 </tr>
5271 <tr>
5272 <td>
5273 <code class=
5274 "cCode">GetShortArrayRegion()</code>
5275 </td>
5276 <td>
5277 202
5278 </td>
5279 </tr>
5280 <tr>
5281 <td>
5282 <code class=
5283 "cCode">GetIntArrayRegion()</code>
5284 </td>
5285 <td>
5286 203
5287 </td>
5288 </tr>
5289 <tr>
5290 <td>
5291 <code class=
5292 "cCode">GetLongArrayRegion()</code>
5293 </td>
5294 <td>
5295 204
5296 </td>
5297 </tr>
5298 <tr>
5299 <td>
5300 <code class=
5301 "cCode">GetFloatArrayRegion()</code>
5302 </td>
5303 <td>
5304 205
5305 </td>
5306 </tr>
5307 <tr>
5308 <td>
5309 <code class=
5310 "cCode">GetDoubleArrayRegion()</code>
5311 </td>
5312 <td>
5313 206
5314 </td>
5315 </tr>
5316 </tbody>
5317 </table>
5318 <h4>PARAMETERS:</h4>
5319
5320 <p><code>env</code>: the JNI interface
5321 pointer.</p>
5322
5323 <p><code>array</code>: a Java
5324 array.</p>
5325
5326 <p><code>start</code>: the starting
5327 index.</p>
5328
5329 <p><code>len</code>: the number of
5330 elements to be copied.</p>
5331
5332 <p><code>buf</code>: the destination
5333 buffer.</p>
5334
5335 <h4>THROWS:</h4>
5336
5337 <p><code class=
5338 "cCode">ArrayIndexOutOfBoundsException</code>: if one of the
5339 indexes in the region is not valid.</p>
5340
5341 <h3><a name="Set_PrimitiveType_ArrayRegion_routines">Set<PrimitiveType>ArrayRegion Routines</a></h3>
5342
5343 <p><code>void</code> <em class=
5344 "cEmphasis">Set<PrimitiveType>ArrayRegion</em><code class=
5345 "cCode">(JNIEnv *env,</code> <em>ArrayType</em>
5346 <code>array,<br />
5347 jsize start, jsize len,</code> const <em class=
5348 "cEmphasis">NativeType</em> <code>*buf);</code></p>
5349
5350 <p>A family of functions that copies back a region of
5351 a primitive array from a buffer.</p>
5352
5353 <p>The following table describes the specific
5354 primitive array element accessors. You should make the following
5355 replacements:</p>
5356
5357
5358 <ul>
5359 <li>Replace <em>Set<PrimitiveType>ArrayRegion</em> with one of the actual primitive element accessor routine names from the following table.</li>
5360 <li>Replace ArrayType with the corresponding array type.</li>
5361 <li>Replace <em>NativeType</em> with the corresponding native type for that routine.</li>
5362 </ul>
5363
5364 <table border="1" summary=
5365 "Set<PrimitiveType>ArrayRegion Family of Array Accessor Routines"
5366 >
5367 <caption>Set<PrimitiveType>ArrayRegion Family of Array Accessor
5368 Routines</caption>
5369 <thead>
5370 <tr>
5371 <th>
5372
5373 Set<PrimitiveType>ArrayRegion Routine
5374 </th>
5375 <th>
5376 Array Type
5377 </th>
5378 <th>
5379 Native Type
5380 </th>
5381 </tr>
5382 </thead>
5383 <tbody>
5384 <tr>
5385 <td>
5386 <code class=
5387 "cCode">SetBooleanArrayRegion()</code>
5388 </td>
5389 <td>
5390 jbooleanArray
5391 </td>
5392 <td>
5393 jboolean
5394 </td>
5395 </tr>
5396 <tr>
5397 <td>
5398 <code class=
5399 "cCode">SetByteArrayRegion()</code>
5400 </td>
5401 <td>
5402 jbyteArray
5403 </td>
5404 <td>
5405 jbyte
5406 </td>
5407 </tr>
5408 <tr>
5409 <td>
5410 <code class=
5411 "cCode">SetCharArrayRegion()</code>
5412 </td>
5413 <td>
5414 jcharArray
5415 </td>
5416 <td>
5417 jchar
5418 </td>
5419 </tr>
5420 <tr>
5421 <td>
5422 <code class=
5423 "cCode">SetShortArrayRegion()</code>
5424 </td>
5425 <td>
5426 jshortArray
5427 </td>
5428 <td>
5429 jshort
5430 </td>
5431 </tr>
5432 <tr>
5433 <td>
5434 <code class=
5435 "cCode">SetIntArrayRegion()</code>
5436 </td>
5437 <td>
5438 jintArray
5439 </td>
5440 <td>
5441 jint
5442 </td>
5443 </tr>
5444 <tr>
5445 <td>
5446 <code class=
5447 "cCode">SetLongArrayRegion()</code>
5448 </td>
5449 <td>
5450 jlongArray
5451 </td>
5452 <td>
5453 jlong
5454 </td>
5455 </tr>
5456 <tr>
5457 <td>
5458 <code class=
5459 "cCode">SetFloatArrayRegion()</code>
5460 </td>
5461 <td>
5462 jfloatArray
5463 </td>
5464 <td>
5465 jfloat
5466 </td>
5467 </tr>
5468 <tr>
5469 <td>
5470 <code class=
5471 "cCode">SetDoubleArrayRegion()</code>
5472 </td>
5473 <td>
5474 jdoubleArray
5475 </td>
5476 <td>
5477 jdouble
5478 </td>
5479 </tr>
5480 </tbody>
5481 </table>
5482
5483 <h4>LINKAGE:</h4>
5484 <p>Indices in the JNIEnv interface function table.</p>
5485
5486 <table border="1" summary=
5487 "Set<PrimitiveType>ArrayRegion Family of Array Accessor Routines"
5488 >
5489 <caption>Set<PrimitiveType>ArrayRegion Family of Array Accessor Routines</caption>
5490 <thead>
5491 <tr>
5492 <th>
5493
5494 Set<PrimitiveType>ArrayRegion Routine
5495 </th>
5496 <th>
5497 Index
5498 </th>
5499 </tr>
5500 </thead>
5501 <tbody>
5502 <tr>
5503 <td>
5504 <code class=
5505 "cCode">SetBooleanArrayRegion()</code>
5506 </td>
5507 <td>
5508 207
5509 </td>
5510 </tr>
5511 <tr>
5512 <td>
5513 <code class=
5514 "cCode">SetByteArrayRegion()</code>
5515 </td>
5516 <td>
5517 208
5518 </td>
5519 </tr>
5520 <tr>
5521 <td>
5522 <code class=
5523 "cCode">SetCharArrayRegion()</code>
5524 </td>
5525 <td>
5526 209
5527 </td>
5528 </tr>
5529 <tr>
5530 <td>
5531 <code class=
5532 "cCode">SetShortArrayRegion()</code>
5533 </td>
5534 <td>
5535 210
5536 </td>
5537 </tr>
5538 <tr>
5539 <td>
5540 <code class=
5541 "cCode">SetIntArrayRegion()</code>
5542 </td>
5543 <td>
5544 211
5545 </td>
5546 </tr>
5547 <tr>
5548 <td>
5549 <code class=
5550 "cCode">SetLongArrayRegion()</code>
5551 </td>
5552 <td>
5553 212
5554 </td>
5555 </tr>
5556 <tr>
5557 <td>
5558 <code class=
5559 "cCode">SetFloatArrayRegion()</code>
5560 </td>
5561 <td>
5562 213
5563 </td>
5564 </tr>
5565 <tr>
5566 <td>
5567 <code class=
5568 "cCode">SetDoubleArrayRegion()</code>
5569 </td>
5570 <td>
5571 214
5572 </td>
5573 </tr>
5574 </tbody>
5575 </table>
5576 <p>PARAMETERS:</p>
5577
5578 <p><code>env</code>: the JNI interface
5579 pointer.</p>
5580
5581 <p><code>array</code>: a Java
5582 array.</p>
5583
5584 <p><code>start</code>: the starting
5585 index.</p>
5586 <p><code>len</code>: the number of
5587 elements to be copied.</p>
5588
5589 <p><code>buf</code>: the source
5590 buffer.</p>
5591
5592 <h4>THROWS:</h4>
5593
5594 <p><code class=
5595 "cCode">ArrayIndexOutOfBoundsException</code>: if one of the
5596 indexes in the region is not valid.</p>
5597
5598 <table width="80%" border="1" cellpadding="5"
5599 cellspacing="0" summary="">
5600 <tbody>
5601 <tr>
5602 <td bgcolor="#FFFFCC">
5603
5604 <p><strong>Note</strong>: As of JDK/JRE 1.1, programmers can use
5605 <code>Get/Release<primitivetype>ArrayElements</code>
5606 functions to obtain a pointer to primitive array elements. If the
5607 VM supports pinning, the pointer to the original data is returned;
5608 otherwise, a copy is made.</p>
5609 <p>New functions introduced as of JDK/JRE 1.3 allow native code to
5610 obtain a direct pointer to array elements even if the VM does not
5611 support pinning.</p>
5612 </td>
5613 </tr>
5614 </tbody>
5615 </table>
5616 <h3><a name="GetPrimitiveArrayCritical_ReleasePrimitiveArrayCritical">GetPrimitiveArrayCritical, ReleasePrimitiveArrayCritical</a></h3>
5617 <p><code>void * GetPrimitiveArrayCritical(JNIEnv *env, jarray
5618 array, jboolean *isCopy);<br />
5619 <a name="ReleasePrimitiveArrayCritical" id=
5620 "ReleasePrimitiveArrayCritical"></a> void
5621 ReleasePrimitiveArrayCritical(JNIEnv *env, jarray array, void
5622 *carray, jint mode);</code></p>
5623 <p>The semantics of these two functions are very similar to the
5624 existing <code>Get/Release<primitivetype>ArrayElements</code>
5625 functions. If possible, the VM returns a pointer to the primitive
5626 array; otherwise, a copy is made. <strong>However, there are
5627 significant restrictions on how these functions can be
5628 used.</strong></p>
5629 <p>After calling <code>GetPrimitiveArrayCritical</code>, the native
5630 code should not run for an extended period of time before it calls
5631 <code>ReleasePrimitiveArrayCritical</code>. We must treat the code
5632 inside this pair of functions as running in a "critical region."
5633 Inside a critical region, native code must not call other JNI
5634 functions, or any system call that may cause the current thread to
5635 block and wait for another Java thread. (For example, the current
5636 thread must not call <code>read</code> on a stream being written by
5637 another Java thread.)</p>
5638 <p><strong>These restrictions make it more likely that the native
5639 code will obtain an uncopied version of the array, even if the VM
5640 does not support pinning.</strong> For example, a VM may
5641 temporarily disable garbage collection when the native code is
5642 holding a pointer to an array obtained via
5643 <code>GetPrimitiveArrayCritical</code>.</p>
5644 <p>Multiple pairs of <code>GetPrimtiveArrayCritical</code> and
5645 <code>ReleasePrimitiveArrayCritical</code> may be nested. For
5646 example:</p>
5647 <pre class="codeblock">
5648 jint len = (*env)->GetArrayLength(env, arr1);
5649 jbyte *a1 = (*env)->GetPrimitiveArrayCritical(env, arr1, 0);
5650 jbyte *a2 = (*env)->GetPrimitiveArrayCritical(env, arr2, 0);
5651 /* We need to check in case the VM tried to make a copy. */
5652 if (a1 == NULL || a2 == NULL) {
5653 ... /* out of memory exception thrown */
5654 }
5655 memcpy(a1, a2, len);
5656 (*env)->ReleasePrimitiveArrayCritical(env, arr2, a2, 0);
5657 (*env)->ReleasePrimitiveArrayCritical(env, arr1, a1, 0);
5658 </pre>
5659 <p>Note that <code>GetPrimitiveArrayCritical</code> might still
5660 make a copy of the array if the VM internally represents arrays in
5661 a different format. Therefore we need to check its return value
5662 against <code>NULL</code> for possible out of memory situations.
5663 <a name="stringops"></a></p>
5664 <h4>LINKAGE (GetPrimitiveArrayCritical):</h4>
5665 <p>Linkage Index 222 in the JNIEnv interface
5666 function table.</p>
5667 <h4>LINKAGE (ReleasePrimitiveArrayCritical):</h4>
5668 <p>Linkage Index 223 in the JNIEnv interface
5669 function table.</p>
5670 <h4>SINCE:</h4>
5671 <p>JDK/JRE 1.2</p>
5672 <!-- ******************************************************** -->
5673 <h2><a name="registering_native_methods">Registering Native Methods</a></h2>
5674
5675 <h3><a name="RegisterNatives">RegisterNatives</a></h3>
5676
5677 <p><code>jint RegisterNatives(JNIEnv
5678 *env, jclass clazz,<br />
5679 const JNINativeMethod *methods, jint nMethods);</code></p>
5680
5681 <p>Registers native methods with the class specified
5682 by the <code>clazz</code> argument. The <code class=
5683 "cCode">methods</code> parameter specifies an array of <code class=
5684 "cCode">JNINativeMethod</code> structures that contain the names,
5685 signatures, and function pointers of the native methods. The
5686 <code>name</code> and <code class=
5687 "cCode">signature</code> fields of the JNINativeMethod structure
5688 are pointers to modified UTF-8 strings. The <code class=
5689 "cCode">nMethods</code> parameter specifies the number of native
5690 methods in the array. The <code class=
5691 "cCode">JNINativeMethod</code> structure is defined as follows:</p>
5692
5693 <pre class="codeblock">
5694 typedef struct {
5695
5696 char *name;
5697
5698 char *signature;
5699
5700 void *fnPtr;
5701
5702 } JNINativeMethod;
5703
5704 </pre>
5705
5706 <p>The function pointers nominally must have the
5707 following signature:</p>
5708
5709 <pre class="codeblock">
5710 <code class=
5711 "cCode">ReturnType (*fnPtr)(JNIEnv *env, jobject objectOrClass, ...);</code>
5712
5713 </pre>
5714
5715 <h4>LINKAGE:</h4>
5716 <p>Index 215 in the JNIEnv interface function
5717 table.</p>
5718 <h4>PARAMETERS:</h4>
5719
5720 <p><code>env</code>: the JNI interface
5721 pointer.</p>
5722
5723 <p><code>clazz</code>: a Java class
5724 object.</p>
5725
5726 <p><code>methods</code>: the native
5727 methods in the class.</p>
5728
5729 <p><code>nMethods</code>: the number of
5730 native methods in the class.</p>
5731
5732 <h4>RETURNS:</h4>
5733
5734 <p>Returns “0” on success; returns a
5735 negative value on failure.</p>
5736
5737 <h4>THROWS:</h4>
5738
5739 <p><code>NoSuchMethodError</code>: if a
5740 specified method cannot be found or if the method is not
5741 native.</p>
5742
5743 <h3><a name="UnregisterNatives">UnregisterNatives</a></h3>
5744
5745 <p><code>jint UnregisterNatives(JNIEnv
5746 *env, jclass clazz);</code></p>
5747
5748 <p>Unregisters native methods of a class. The class
5749 goes back to the state before it was linked or registered with its
5750 native method functions.</p>
5751
5752 <p>This function should not be used in normal native
5753 code. Instead, it provides special programs a way to reload and
5754 relink native libraries.</p>
5755
5756 <h4>LINKAGE:</h4>
5757 Index 216 in the JNIEnv interface function table.
5758 <h4>PARAMETERS:</h4>
5759
5760 <p><code>env</code>: the JNI interface
5761 pointer.</p>
5762
5763 <p><code>clazz</code>: a Java class
5764 object.</p>
5765
5766 <h4>RETURNS:</h4>
5767
5768 <p>Returns “0” on success; returns a
5769 negative value on failure.</p>
5770
5771 <!-- ******************************************************** -->
5772 <h2><a name="monitor_operations">Monitor Operations</a></h2>
5773
5774 <h3><a name="MonitorEnter">MonitorEnter</a></h3>
5775
5776 <p><code>jint MonitorEnter(JNIEnv *env,
5777 jobject obj);</code></p>
5778
5779 <p>Enters the monitor associated with the underlying
5780 Java object referred to by <code>obj</code>.</p>
5781 Enters the monitor associated with the object referred to by obj.
5782 The <code>obj</code> reference must not be <code>NULL</code>.
5783 <p>Each Java object has a monitor associated with it.
5784 If the current thread already owns the monitor associated with
5785 <code>obj</code>, it increments a counter in the
5786 monitor indicating the number of times this thread has entered the
5787 monitor. If the monitor associated with <code class=
5788 "cCode">obj</code> is not owned by any thread, the current thread
5789 becomes the owner of the monitor, setting the entry count of this
5790 monitor to 1. If another thread already owns the monitor associated
5791 with <code>obj</code>, the current thread waits until
5792 the monitor is released, then tries again to gain ownership.</p>
5793 <p>A monitor entered through a <code>MonitorEnter</code> JNI
5794 function call cannot be exited using the <code>monitorexit</code>
5795 Java virtual machine instruction or a synchronized method return. A
5796 <code>MonitorEnter</code> JNI function call and a
5797 <code>monitorenter</code> Java virtual machine instruction may race
5798 to enter the monitor associated with the same object.</p>
5799 <p>To avoid deadlocks, a monitor entered through a
5800 <code>MonitorEnter</code> JNI function call must be exited using
5801 the <code>MonitorExit</code> JNI call, unless the
5802 <code>DetachCurrentThread</code> call is used to implicitly release
5803 JNI monitors.</p>
5804
5805 <h4>LINKAGE:</h4>
5806 Index 217 in the JNIEnv interface function table.
5807 <h4>PARAMETERS:</h4>
5808
5809 <p><code>env</code>: the JNI interface
5810 pointer.</p>
5811
5812 <p><code>obj</code>: a normal Java
5813 object or class object.</p>
5814
5815 <h4>RETURNS:</h4>
5816
5817 <p>Returns “0” on success; returns a
5818 negative value on failure.</p>
5819
5820 <h3><a name="MonitorExit">MonitorExit</a></h3>
5821
5822 <p><code>jint MonitorExit(JNIEnv *env,
5823 jobject obj);</code></p>
5824
5825 <p>The current thread must be the owner of the
5826 monitor associated with the underlying Java object referred to by
5827 <code>obj</code>. The thread decrements the counter
5828 indicating the number of times it has entered this monitor. If the
5829 value of the counter becomes zero, the current thread releases the
5830 monitor.</p>
5831 <p>Native code must not use <code>MonitorExit</code> to exit a
5832 monitor entered through a synchronized method or a
5833 <code>monitorenter</code> Java virtual machine instruction.</p>
5834
5835 <h4>LINKAGE:</h4>
5836 Index 218 in the JNIEnv interface function table.
5837 <h4>PARAMETERS:</h4>
5838
5839 <p><code>env</code>: the JNI interface
5840 pointer.</p>
5841
5842 <p><code>obj</code>: a normal Java
5843 object or class object.</p>
5844
5845 <h4>RETURNS:</h4>
5846
5847 <p>Returns “0” on success; returns a
5848 negative value on failure.</p>
5849
5850 <h4>EXCEPTIONS:</h4>
5851
5852 <p><code>IllegalMonitorStateException</code>: if the
5853 current thread does not own the monitor.</p>
5854
5855 <!-- ******************************************************** -->
5856 <h2><a name="nio_support">NIO Support</a></h2>
5857 <p>The NIO-related entry points allow native code to access
5858 <code>java.nio</code> <em>direct buffers</em>. The contents of a
5859 direct buffer can, potentially, reside in native memory outside of
5860 the ordinary garbage-collected heap. For information about direct
5861 buffers, please see <a href="../../io/index.html">New I/O APIs</a>
5862 and the specification of the <a href=
5863 "../../../../api/java/nio/ByteBuffer.html"><tt>java.nio.ByteBuffer</tt></a>
5864 class.</p>
5865 Three new functions introduced in JDK/JRE 1.4 allow JNI code to
5866 create, examine, and manipulate direct buffers:
5867 <ul>
5868 <li><a href=
5869 "#NewDirectByteBuffer"><code>NewDirectByteBuffer</code></a></li>
5870 <li><a href=
5871 "#GetDirectBufferAddress"><code>GetDirectBufferAddress</code></a></li>
5872 <li><a href=
5873 "#GetDirectBufferCapacity"><code>GetDirectBufferCapacity</code></a></li>
5874 </ul>
5875 <p>Every implementation of the Java virtual machine must support
5876 these functions, but not every implementation is required to
5877 support JNI access to direct buffers. If a JVM does not support
5878 such access then the <tt>NewDirectByteBuffer</tt> and
5879 <tt>GetDirectBufferAddress</tt> functions must always return
5880 <tt>NULL</tt>, and the <tt>GetDirectBufferCapacity</tt> function
5881 must always return <tt>-1</tt>. If a JVM <em>does</em> support such
5882 access then these three functions must be implemented to return the
5883 appropriate values.</p>
5884
5885 <h3><a name="NewDirectByteBuffer">NewDirectByteBuffer</a></h3>
5886
5887 <p><tt>jobject NewDirectByteBuffer(JNIEnv* env, void* address,
5888 jlong capacity);</tt></p>
5889 <p>Allocates and returns a direct <tt>java.nio.ByteBuffer</tt>
5890 referring to the block of memory starting at the memory address
5891 <tt>address</tt> and extending <tt>capacity</tt> bytes.</p>
5892 <p>Native code that calls this function and returns the resulting
5893 byte-buffer object to Java-level code should ensure that the buffer
5894 refers to a valid region of memory that is accessible for reading
5895 and, if appropriate, writing. An attempt to access an invalid
5896 memory location from Java code will either return an arbitrary
5897 value, have no visible effect, or cause an unspecified exception to
5898 be thrown.</p>
5899 <h4>LINKAGE:</h4>
5900 <p>Index 229 in the JNIEnv interface function
5901 table.</p>
5902 <h4>PARAMETERS:</h4>
5903 <p><tt>env</tt>: the <tt>JNIEnv</tt> interface pointer</p>
5904 <p><tt>address</tt>: the starting address of the memory region
5905 (must not be <tt>NULL</tt>)</p>
5906 <p><tt>capacity</tt>: the size in bytes of the memory region (must
5907 be positive)</p>
5908 <h4>RETURNS:</h4>
5909 <p>Returns a local reference to the newly-instantiated
5910 <tt>java.nio.ByteBuffer</tt> object. Returns <tt>NULL</tt> if an
5911 exception occurs, or if JNI access to direct buffers is not
5912 supported by this virtual machine.</p>
5913 <h4>EXCEPTIONS:</h4>
5914 <p><tt>OutOfMemoryError</tt>: if allocation of the
5915 <tt>ByteBuffer</tt> object fails</p>
5916 <h4>SINCE:</h4>
5917 <p>JDK/JRE 1.4</p>
5918
5919 <h3><a name="GetDirectBufferAddress">GetDirectBufferAddress</a></h3>
5920 <p><tt>void* GetDirectBufferAddress(JNIEnv* env, jobject
5921 buf);</tt></p>
5922
5923
5924 <p>Fetches and returns the starting address of the memory region
5925 referenced by the given direct <tt>java.nio.Buffer</tt>.</p>
5926 <p>This function allows native code to access the same memory
5927 region that is accessible to Java code via the buffer object.</p>
5928 <h4>LINKAGE:</h4>
5929 <p>Index 230 in the JNIEnv interface function table.</p>
5930
5931
5932 <h4>PARAMETERS:</h4>
5933
5934
5935 <p><tt>env</tt>: the <tt>JNIEnv</tt> interface pointer</p>
5936 <p><tt>buf</tt>: a direct <tt>java.nio.Buffer</tt> object (must not
5937 be <tt>NULL</tt>)</p>
5938
5939
5940 <h4>RETURNS:</h4>
5941
5942
5943 <p>Returns the starting address of the memory region referenced by
5944 the buffer. Returns <tt>NULL</tt> if the memory region is
5945 undefined, if the given object is not a direct
5946 <tt>java.nio.Buffer</tt>, or if JNI access to direct buffers is not
5947 supported by this virtual machine.</p>
5948 <h4>SINCE:</h4>
5949 <p>JDK/JRE 1.4</p>
5950
5951 <h3><a name="GetDirectBufferCapacity">GetDirectBufferCapacity</a></h3>
5952 <p><tt>jlong GetDirectBufferCapacity(JNIEnv* env, jobject
5953 buf);</tt></p>
5954 <p>Fetches and returns the capacity of the memory region referenced
5955 by the given direct <tt>java.nio.Buffer</tt>. The capacity is the
5956 number of <i>elements</i> that the memory region contains.</p>
5957 <h4>LINKAGE:</h4>
5958 <p>Index 231 in the JNIEnv interface function
5959 table.</p>
5960
5961
5962 <h4>PARAMETERS:</h4>
5963
5964
5965 <p><tt>env</tt>: the <tt>JNIEnv</tt> interface pointer</p>
5966 <p><tt>buf</tt>: a direct <tt>java.nio.Buffer</tt> object (must not
5967 be <tt>NULL</tt>)</p>
5968
5969
5970 <h4>RETURNS:</h4>
5971
5972
5973 <p>Returns the capacity of the memory region associated with the
5974 buffer. Returns <tt>-1</tt> if the given object is not a direct
5975 <tt>java.nio.Buffer</tt>, if the object is an unaligned view buffer
5976 and the processor architecture does not support unaligned access,
5977 or if JNI access to direct buffers is not supported by this virtual
5978 machine.</p>
5979 <h4>SINCE:</h4>
5980 <p>JDK/JRE 1.4</p>
5981 <!-- ******************************************************** -->
5982 <h2><a name="reflection_support">Reflection Support</a></h2>
5983 <p>Programmers can use the JNI to call Java methods or access Java
5984 fields if they know the name and type of the methods or fields. The
5985 Java Core Reflection API allows programmers to introspect Java
5986 classes at runtime. JNI provides a set of conversion functions
5987 between field and method IDs used in the JNI to field and method
5988 objects used in the Java Core Reflection API.</p>
5989
5990 <h3><a name="FromReflectedMethod">FromReflectedMethod</a></h3>
5991 <p><code>jmethodID FromReflectedMethod(JNIEnv *env, jobject
5992 method);</code></p>
5993 <p>Converts a <code>java.lang.reflect.Method</code> or
5994 <code>java.lang.reflect.Constructor</code> object to a method
5995 ID.</p>
5996 <h4>LINKAGE:</h4>
5997 <p>Index 7 in the JNIEnv interface function
5998 table.</p>
5999 <h4>SINCE:</h4>
6000 <p>JDK/JRE 1.2</p>
6001 <h3><a name="FromReflectedField">FromReflectedField</a></h3>
6002 <p><code>jfieldID FromReflectedField(JNIEnv *env, jobject
6003 field);</code></p>
6004 <p>Converts a <code>java.lang.reflect.Field</code> to a field
6005 ID.</p>
6006 <h4>LINKAGE:</h4>
6007 <p>Index 8 in the JNIEnv interface function table.</p>
6008 <h4>SINCE:</h4>
6009 <p>JDK/JRE 1.2</p>
6010 <h3><a name="ToReflectedMethod">ToReflectedMethod</a></h3>
6011 <p><code>jobject ToReflectedMethod(JNIEnv *env, jclass cls,<br />
6012 jmethodID methodID, jboolean isStatic);</code></p>
6013 <p>Converts a method ID derived from <code>cls</code> to a
6014 <code>java.lang.reflect.Method</code> or
6015 <code>java.lang.reflect.Constructor</code> object.
6016 <code>isStatic</code> must be set to <code class=
6017 "cCode">JNI_TRUE</code> if the method ID refers to a static field,
6018 and <code>JNI_FALSE</code> otherwise.</p>
6019 <p>Throws <code>OutOfMemoryError</code> and returns 0 if fails.</p>
6020 <h4>LINKAGE:</h4>
6021 <p>Index 9 in the JNIEnv interface function
6022 table.</p>
6023 <h4>SINCE:</h4>
6024 <p>JDK/JRE 1.2</p>
6025 <h3><a name="ToReflectedField">ToReflectedField</a></h3>
6026 <p><code>jobject ToReflectedField(JNIEnv *env, jclass cls,<br />
6027 jfieldID fieldID, jboolean isStatic);</code></p>
6028 <p>Converts a field ID derived from <code>cls</code> to a
6029 <code>java.lang.reflect.Field</code> object. <code>isStatic</code>
6030 must be set to <code>JNI_TRUE</code> if
6031 <code>fieldID</code> refers to a static field, and <code class=
6032 "cCode">JNI_FALSE</code> otherwise.</p>
6033 <p>Throws <code>OutOfMemoryError</code> and returns 0 if fails.</p>
6034 <h4>LINKAGE:</h4>
6035 <p>Index 12 in the JNIEnv interface function
6036 table.</p>
6037 <h4>SINCE:</h4>
6038 <p>JDK/JRE 1.2</p>
6039 <a name="invo"></a>
6040 <!-- ******************************************************** -->
6041 <h2><a name="java_vm_interface">Java VM Interface</a></h2>
6042
6043 <h3><a name="GetJavaVM">GetJavaVM</a></h3>
6044
6045 <p><code>jint GetJavaVM(JNIEnv *env,
6046 JavaVM **vm);</code></p>
6047
6048 <p>Returns the Java VM interface (used in the
6049 Invocation API) associated with the current thread. The result is
6050 placed at the location pointed to by the second argument,
6051 <code>vm</code>.</p>
6052
6053 <h4>LINKAGE:</h4>
6054 <p>Index 219 in the JNIEnv interface function
6055 table.</p>
6056 <h4>PARAMETERS:</h4>
6057
6058 <p><code>env</code>: the JNI interface
6059 pointer.</p>
6060
6061 <p><code>vm</code>: a pointer to where
6062 the result should be placed.</p>
6063
6064 <h4>RETURNS:</h4>
6065
6066 <p>Returns “0” on success; returns a
6067 negative value on failure.</p>
6068
6069 <table width="100%" summary="">
6070 <tbody>
6071 <tr>
6072 <td><a accesskey="c" href=
6073 "../../jni/spec/jniTOC.html">Contents</a> | <a accesskey="p" href=
6074 "../../jni/spec/types.html">Previous</a> | <a accesskey="n" href=
6075 "../../jni/spec/invocation.html">Next</a></td>
6076 <td></td>
6077 </tr>
6078 </tbody>
6079 </table>
6080 </body>
6081 </html>