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 supertypes 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 or interface 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 supertypes.</p>
2416
2417 <p><em class="cEmphasis">CallNonvirtual<type>Method</em> routines are the mechanism for invoking <em>"default interface methods"</em> introduced in Java 8.</p>
2418
2419 <h4>CallNonvirtual<type>Method
2420 Routines</h4>
2421
2422 <p>Programmers place all arguments that are to be
2423 passed to the method immediately following the <code class=
2424 "cCode">methodID</code> argument. The <em class=
2425 "cEmphasis">CallNonvirtual<type>Method</em> routine accepts
2426 these arguments and passes them to the Java method that the
2427 programmer wishes to invoke.</p>
2428
2429 <h4>CallNonvirtual<type>MethodA
2430 Routines</h4>
2431
2432 <p>Programmers place all arguments to the method in
2433 an <code>args</code> array of <code class=
2434 "cCode">jvalues</code> that immediately follows the <code class=
2435 "cCode">methodID</code> argument. The <em class=
2436 "cEmphasis">CallNonvirtual<type>MethodA</em> routine accepts
2437 the arguments in this array, and, in turn, passes them to the Java
2438 method that the programmer wishes to invoke.</p>
2439
2440 <h4>CallNonvirtual<type>MethodV
2441 Routines</h4>
2442
2443 <p>Programmers place all arguments to the method in
2444 an <code>args</code> argument of type <code class=
2445 "cCode">va_list</code> that immediately follows the <code class=
2446 "cCode">methodID</code> argument. The <em class=
2447 "cEmphasis">CallNonvirtualMethodV</em> routine accepts the
2448 arguments, and, in turn, passes them to the Java method that the
2449 programmer wishes to invoke.</p>
2450
2451 <p>The following table describes each of the method
2452 calling routines according to their result type. You should replace
2453 <em>type</em> in <em class=
2454 "cEmphasis">CallNonvirtual<type>Method</em> with the Java
2455 type of the method, or use one of the actual method calling routine
2456 names from the table, and replace <em class=
2457 "cEmphasis">NativeType</em> with the corresponding native type for
2458 that routine.</p>
2459
2460 <table border="1" summary=
2461 "CallNonvirtual<type> Method Routines">
2462 <caption>CallNonvirtual<type>Method Routines</caption>
2463 <thead>
2464 <tr>
2465 <th>
2466
2467 CallNonvirtual<type>Method Routine Name
2468 </th>
2469 <th>
2470 Native Type
2471 </th>
2472 </tr>
2473 </thead>
2474 <tbody>
2475 <tr>
2476 <td>
2477 <code class=
2478 "cCode">CallNonvirtualVoidMethod()</code>
2479
2480 <code class=
2481 "cCode">CallNonvirtualVoidMethodA()</code>
2482
2483 <code class=
2484 "cCode">CallNonvirtualVoidMethodV()</code>
2485 </td>
2486 <td>
2487 void
2488 </td>
2489 </tr>
2490 <tr>
2491 <td>
2492 <code class=
2493 "cCode">CallNonvirtualObjectMethod()</code>
2494
2495 <code class=
2496 "cCode">CallNonvirtualObjectMethodA()</code>
2497
2498 <code class=
2499 "cCode">CallNonvirtualObjectMethodV()</code>
2500 </td>
2501 <td>
2502 jobject
2503 </td>
2504 </tr>
2505 <tr>
2506 <td>
2507 <code class=
2508 "cCode">CallNonvirtualBooleanMethod()</code>
2509
2510 <code class=
2511 "cCode">CallNonvirtualBooleanMethodA()</code>
2512
2513 <code class=
2514 "cCode">CallNonvirtualBooleanMethodV()</code>
2515 </td>
2516 <td>
2517 jboolean
2518 </td>
2519 </tr>
2520 <tr>
2521 <td>
2522 <code class=
2523 "cCode">CallNonvirtualByteMethod()</code>
2524
2525 <code class=
2526 "cCode">CallNonvirtualByteMethodA()</code>
2527
2528 <code class=
2529 "cCode">CallNonvirtualByteMethodV()</code>
2530 </td>
2531 <td>
2532 jbyte
2533 </td>
2534 </tr>
2535 <tr>
2536 <td>
2537 <code class=
2538 "cCode">CallNonvirtualCharMethod()</code>
2539
2540 <code class=
2541 "cCode">CallNonvirtualCharMethodA()</code>
2542
2543 <code class=
2544 "cCode">CallNonvirtualCharMethodV()</code>
2545 </td>
2546 <td>
2547 jchar
2548 </td>
2549 </tr>
2550 <tr>
2551 <td>
2552 <code class=
2553 "cCode">CallNonvirtualShortMethod()</code>
2554
2555 <code class=
2556 "cCode">CallNonvirtualShortMethodA()</code>
2557
2558 <code class=
2559 "cCode">CallNonvirtualShortMethodV()</code>
2560 </td>
2561 <td>
2562 jshort
2563 </td>
2564 </tr>
2565 <tr>
2566 <td>
2567 <code class=
2568 "cCode">CallNonvirtualIntMethod()</code>
2569
2570 <code class=
2571 "cCode">CallNonvirtualIntMethodA()</code>
2572
2573 <code class=
2574 "cCode">CallNonvirtualIntMethodV()</code>
2575 </td>
2576 <td>
2577 jint
2578 </td>
2579 </tr>
2580 <tr>
2581 <td>
2582 <code class=
2583 "cCode">CallNonvirtualLongMethod()</code>
2584
2585 <code class=
2586 "cCode">CallNonvirtualLongMethodA()</code>
2587
2588 <code class=
2589 "cCode">CallNonvirtualLongMethodV()</code>
2590 </td>
2591 <td>
2592 jlong
2593 </td>
2594 </tr>
2595 <tr>
2596 <td>
2597 <code class=
2598 "cCode">CallNonvirtualFloatMethod()</code>
2599
2600 <code class=
2601 "cCode">CallNonvirtualFloatMethodA()</code>
2602
2603 <code class=
2604 "cCode">CallNonvirtualFloatMethodV()</code>
2605 </td>
2606 <td>
2607 jfloat
2608 </td>
2609 </tr>
2610 <tr>
2611 <td>
2612 <code class=
2613 "cCode">CallNonvirtualDoubleMethod()</code>
2614
2615 <code class=
2616 "cCode">CallNonvirtualDoubleMethodA()</code>
2617
2618 <code class=
2619 "cCode">CallNonvirtualDoubleMethodV()</code>
2620 </td>
2621 <td>
2622 jdouble
2623 </td>
2624 </tr>
2625 </tbody>
2626 </table>
2627
2628
2629
2630 <h4>LINKAGE:</h4>
2631 <p>Indices in the JNIEnv interface function table.</p>
2632
2633 <table border="1" summary=
2634 "CallNonvirtual<type> Method Routines">
2635 <caption>CallNonvirtual<type>Method Routines</caption>
2636 <thead>
2637 <tr>
2638 <th>
2639
2640 CallNonvirtual<type>Method Routine Name
2641 </th>
2642 <th>
2643 Index
2644 </th>
2645 </tr>
2646 </thead>
2647 <tbody>
2648 <tr>
2649 <td>
2650 <code class=
2651 "cCode">CallNonvirtualVoidMethod()</code>
2652 <code class=
2653 "cCode">CallNonvirtualVoidMethodA()</code>
2654 <code class=
2655 "cCode">CallNonvirtualVoidMethodV()</code>
2656 </td>
2657 <td>91<br />
2658 93<br />
2659 92</td>
2660 </tr>
2661 <tr>
2662 <td>
2663 <code class=
2664 "cCode">CallNonvirtualObjectMethod()</code>
2665 <code class=
2666 "cCode">CallNonvirtualObjectMethodA()</code>
2667 <code class=
2668 "cCode">CallNonvirtualObjectMethodV()</code>
2669 </td>
2670 <td>64<br />
2671 66<br />
2672 65</td>
2673 </tr>
2674 <tr>
2675 <td>
2676 <code class=
2677 "cCode">CallNonvirtualBooleanMethod()</code>
2678 <code class=
2679 "cCode">CallNonvirtualBooleanMethodA()</code>
2680 <code class=
2681 "cCode">CallNonvirtualBooleanMethodV()</code>
2682 </td>
2683 <td>67<br />
2684 69<br />
2685 68</td>
2686 </tr>
2687 <tr>
2688 <td>
2689 <code class=
2690 "cCode">CallNonvirtualByteMethod()</code>
2691 <code class=
2692 "cCode">CallNonvirtualByteMethodA()</code>
2693 <code class=
2694 "cCode">CallNonvirtualByteMethodV()</code>
2695 </td>
2696 <td>70<br />
2697 72<br />
2698 71</td>
2699 </tr>
2700 <tr>
2701 <td>
2702 <code class=
2703 "cCode">CallNonvirtualCharMethod()</code>
2704 <code class=
2705 "cCode">CallNonvirtualCharMethodA()</code>
2706 <code class=
2707 "cCode">CallNonvirtualCharMethodV()</code>
2708 </td>
2709 <td>73<br />
2710 75<br />
2711 74</td>
2712 </tr>
2713 <tr>
2714 <td>
2715 <code class=
2716 "cCode">CallNonvirtualShortMethod()</code>
2717 <code class=
2718 "cCode">CallNonvirtualShortMethodA()</code>
2719 <code class=
2720 "cCode">CallNonvirtualShortMethodV()</code>
2721 </td>
2722 <td>76<br />
2723 78<br />
2724 77</td>
2725 </tr>
2726 <tr>
2727 <td>
2728 <code class=
2729 "cCode">CallNonvirtualIntMethod()</code>
2730 <code class=
2731 "cCode">CallNonvirtualIntMethodA()</code>
2732 <code class=
2733 "cCode">CallNonvirtualIntMethodV()</code>
2734 </td>
2735 <td>79<br />
2736 81<br />
2737 80</td>
2738 </tr>
2739 <tr>
2740 <td>
2741 <code class=
2742 "cCode">CallNonvirtualLongMethod()</code>
2743 <code class=
2744 "cCode">CallNonvirtualLongMethodA()</code>
2745 <code class=
2746 "cCode">CallNonvirtualLongMethodV()</code>
2747 </td>
2748 <td>82<br />
2749 84<br />
2750 83</td>
2751 </tr>
2752 <tr>
2753 <td>
2754 <code class=
2755 "cCode">CallNonvirtualFloatMethod()</code>
2756 <code class=
2757 "cCode">CallNonvirtualFloatMethodA()</code>
2758 <code class=
2759 "cCode">CallNonvirtualFloatMethodV()</code>
2760 </td>
2761 <td>85<br />
2762 87<br />
2763 86</td>
2764 </tr>
2765 <tr>
2766 <td>
2767 <code class=
2768 "cCode">CallNonvirtualDoubleMethod()</code>
2769 <code class=
2770 "cCode">CallNonvirtualDoubleMethodA()</code>
2771 <code class=
2772 "cCode">CallNonvirtualDoubleMethodV()</code>
2773 </td>
2774 <td>88<br />
2775 90<br />
2776 89</td>
2777 </tr>
2778 </tbody>
2779 </table>
2780 <h4>PARAMETERS:</h4>
2781
2782 <p><code>env</code>: the JNI interface
2783 pointer.</p>
2784
2785 <p><code>clazz:</code> <code class=
2786 "cCode">a</code> Java class.</p>
2787
2788 <p><code>obj</code>: a Java object.</p>
2789
2790 <p><code>methodID</code>: a method
2791 ID.</p>
2792
2793 <h4>Additional Parameter for
2794 CallNonvirtual<type>Method Routines:</h4>
2795
2796 <p>arguments to the Java method.</p>
2797
2798 <h4>Additional Parameter for
2799 CallNonvirtual<type>MethodA Routines:</h4>
2800
2801 <p><code>args</code>: an array of
2802 arguments.</p>
2803
2804 <h4>Additional Parameter for
2805 CallNonvirtual<type>MethodV Routines:</h4>
2806
2807 <p><code>args</code>: a <code class=
2808 "cCode">va_list</code> of arguments.</p>
2809
2810 <h4>RETURNS:</h4>
2811
2812 <p>Returns the result of calling the Java
2813 method.</p>
2814
2815 <h4>THROWS:</h4>
2816
2817 <p>Exceptions raised during the execution of the Java
2818 method.</p>
2819
2820 <!-- ******************************************************** -->
2821 <h2><a name="accessing_static_fields">Accessing Static Fields</a></h2>
2822
2823 <h3><a name="GetStaticFieldID">GetStaticFieldID</a></h3>
2824
2825 <p><code>jfieldID
2826 GetStaticFieldID(JNIEnv *env, jclass clazz,<br />
2827 const char *name, const char *sig);</code></p>
2828
2829 <p>Returns the field ID for a static field of a
2830 class. The field is specified by its name and signature. The
2831 <em>GetStatic<type>Field</em> and
2832 <em>SetStatic<type>Field</em> families of
2833 accessor functions use field IDs to retrieve static fields.</p>
2834
2835 <p><code>GetStaticFieldID()</code>
2836 causes an uninitialized class to be initialized.</p>
2837
2838 <h4>LINKAGE:</h4>
2839 <p>Index 144 in the JNIEnv interface function table.</p>
2840 <h4>PARAMETERS:</h4>
2841
2842 <p><code>env</code>: the JNI interface
2843 pointer.</p>
2844
2845 <p><code>clazz</code>: a Java class
2846 object.</p>
2847
2848 <p><code>name</code>: the static field
2849 name in a 0-terminated modified UTF-8 string.</p>
2850
2851 <p><code>sig</code>: the field
2852 signature in a 0-terminated modified UTF-8 string.</p>
2853
2854 <h4>RETURNS:</h4>
2855
2856 <p>Returns a field ID, or <code class=
2857 "cCode">NULL</code> if the specified static field cannot be
2858 found.</p>
2859
2860 <h4>THROWS:</h4>
2861
2862 <p><code>NoSuchFieldError</code>: if
2863 the specified static field cannot be found.</p>
2864
2865 <p><code class=
2866 "cCode">ExceptionInInitializerError</code>: if the class
2867 initializer fails due to an exception.</p>
2868
2869 <p><code>OutOfMemoryError</code>: if
2870 the system runs out of memory.</p>
2871
2872 <h3><a name="GetStatic_type_Field_routines">GetStatic<type>Field Routines</a></h3>
2873
2874 <p><em>NativeType</em> <em class=
2875 "cEmphasis">GetStatic<type>Field</em><code class=
2876 "cCode">(JNIEnv *env, jclass clazz,<br />
2877 jfieldID fieldID);</code></p>
2878
2879 <p>This family of accessor routines returns the value
2880 of a static field of an object. The field to access is specified by
2881 a field ID, which is obtained by calling <code class=
2882 "cCode">GetStaticFieldID()</code>.</p>
2883
2884 <p>The following table describes the family of get
2885 routine names and result types. You should replace <em class=
2886 "cEmphasis">type</em> in <em class=
2887 "cEmphasis">GetStatic<type>Field</em> with the Java type of
2888 the field, or one of the actual static field accessor routine names
2889 from the table, and replace <em>NativeType</em>
2890 with the corresponding native type for that routine.</p>
2891
2892
2893
2894 <table border="1" summary=
2895 "GetStatic<type>Field Family of Accessor Routines">
2896 <caption>GetStatic<type>Field Family of Accessor Routines</caption>
2897 <thead>
2898 <tr>
2899 <th>
2900
2901 GetStatic<type>Field Routine Name
2902 </th>
2903 <th>
2904 Native Type
2905 </th>
2906 </tr>
2907 </thead>
2908 <tbody>
2909 <tr>
2910 <td>
2911 <code class=
2912 "cCode">GetStaticObjectField</code><code class=
2913 "cCode">()</code>
2914 </td>
2915 <td>
2916 jobject
2917 </td>
2918 </tr>
2919 <tr>
2920 <td>
2921 <code class=
2922 "cCode">GetStaticBooleanField</code><code class=
2923 "cCode">()</code>
2924 </td>
2925 <td>
2926 jboolean
2927 </td>
2928 </tr>
2929 <tr>
2930 <td>
2931 <code class=
2932 "cCode">GetStaticByteField</code><code class=
2933 "cCode">()</code>
2934 </td>
2935 <td>
2936 jbyte
2937 </td>
2938 </tr>
2939 <tr>
2940 <td>
2941 <code class=
2942 "cCode">GetStaticCharField</code><code class=
2943 "cCode">()</code>
2944 </td>
2945 <td>
2946 jchar
2947 </td>
2948 </tr>
2949 <tr>
2950 <td>
2951 <code class=
2952 "cCode">GetStaticShortField</code><code class=
2953 "cCode">()</code>
2954 </td>
2955 <td>
2956 jshort
2957 </td>
2958 </tr>
2959 <tr>
2960 <td>
2961 <code class=
2962 "cCode">GetStaticIntField</code><code>()</code>
2963 </td>
2964 <td>
2965 jint
2966 </td>
2967 </tr>
2968 <tr>
2969 <td>
2970 <code class=
2971 "cCode">GetStaticLongField</code><code class=
2972 "cCode">()</code>
2973 </td>
2974 <td>
2975 jlong
2976 </td>
2977 </tr>
2978 <tr>
2979 <td>
2980 <code class=
2981 "cCode">GetStaticFloatField</code><code class=
2982 "cCode">()</code>
2983 </td>
2984 <td>
2985 jfloat
2986 </td>
2987 </tr>
2988 <tr>
2989 <td>
2990 <code class=
2991 "cCode">GetStaticDoubleField</code><code class=
2992 "cCode">()</code>
2993 </td>
2994 <td>
2995 jdouble
2996 </td>
2997 </tr>
2998 </tbody>
2999 </table>
3000
3001
3002
3003 <h4>LINKAGE:</h4>
3004 <p>Indices in the JNIEnv interface function table.</p>
3005
3006 <table border="1" summary=
3007 "GetStatic<type>Field Family of Accessor Routines">
3008 <caption>GetStatic<type>Field Family of Accessor Routines</caption>
3009 <thead>
3010 <tr>
3011 <th>
3012
3013 GetStatic<type>Field Routine Name
3014 </th>
3015 <th>
3016 Index
3017 </th>
3018 </tr>
3019 </thead>
3020 <tbody>
3021 <tr>
3022 <td>
3023 <code class=
3024 "cCode">GetStaticObjectField</code><code class=
3025 "cCode">()</code>
3026 </td>
3027 <td>145</td>
3028 </tr>
3029 <tr>
3030 <td>
3031 <code class=
3032 "cCode">GetStaticBooleanField</code><code class=
3033 "cCode">()</code>
3034 </td>
3035 <td>146</td>
3036 </tr>
3037 <tr>
3038 <td>
3039 <code class=
3040 "cCode">GetStaticByteField</code><code class=
3041 "cCode">()</code>
3042 </td>
3043 <td>147</td>
3044 </tr>
3045 <tr>
3046 <td>
3047 <code class=
3048 "cCode">GetStaticCharField</code><code class=
3049 "cCode">()</code>
3050 </td>
3051 <td>148</td>
3052 </tr>
3053 <tr>
3054 <td>
3055 <code class=
3056 "cCode">GetStaticShortField</code><code class=
3057 "cCode">()</code>
3058 </td>
3059 <td>149</td>
3060 </tr>
3061 <tr>
3062 <td>
3063 <code class=
3064 "cCode">GetStaticIntField</code><code>()</code>
3065 </td>
3066 <td>150</td>
3067 </tr>
3068 <tr>
3069 <td>
3070 <code class=
3071 "cCode">GetStaticLongField</code><code class=
3072 "cCode">()</code>
3073 </td>
3074 <td>151</td>
3075 </tr>
3076 <tr>
3077 <td>
3078 <code class=
3079 "cCode">GetStaticFloatField</code><code class=
3080 "cCode">()</code>
3081 </td>
3082 <td>152</td>
3083 </tr>
3084 <tr>
3085 <td>
3086 <code class=
3087 "cCode">GetStaticDoubleField</code><code class=
3088 "cCode">()</code>
3089 </td>
3090 <td>153</td>
3091 </tr>
3092 </tbody>
3093 </table>
3094 <h4>PARAMETERS:</h4>
3095
3096 <p><code>env</code>: the JNI interface
3097 pointer.</p>
3098
3099 <p><code>clazz</code>: a Java class
3100 object.</p>
3101
3102 <p><code>fieldID</code>: a static field
3103 ID.</p>
3104
3105 <h4>RETURNS:</h4>
3106
3107 <p>Returns the content of the static field.</p>
3108
3109 <h3><a name="SetStatic_type_Field_routines">SetStatic<type>Field Routines</a></h3>
3110
3111 <p><code>void</code> <em class=
3112 "cEmphasis">SetStatic<type>Field</em><code class=
3113 "cCode">(JNIEnv *env, jclass clazz,<br />
3114 jfieldID fieldID,</code> <em>NativeType</em>
3115 <code>value);</code></p>
3116
3117 <p>This family of accessor routines sets the value of
3118 a static field of an object. The field to access is specified by a
3119 field ID, which is obtained by calling <code class=
3120 "cCode">GetStaticFieldID()</code>.</p>
3121
3122 <p>The following table describes the set routine name
3123 and value types. You should replace <em>type</em>
3124 in <em>SetStatic<type>Field</em> with the
3125 Java type of the field, or one of the actual set static field
3126 routine names from the table, and replace <em class=
3127 "cEmphasis">NativeType</em> with the corresponding native type for
3128 that routine.</p>
3129
3130
3131 <table border="1" summary=
3132 "SetStatic<type>Field Family of Accessor Routines">
3133 <caption>SetStatic<type>Field Family of Accessor Routines</caption>
3134 <thead>
3135 <tr>
3136 <th>
3137
3138 SetStatic<type>Field Routine Name
3139 </th>
3140 <th>
3141 NativeType
3142 </th>
3143 </tr>
3144 </thead>
3145 <tbody>
3146 <tr>
3147 <td>
3148 <code class=
3149 "cCode">SetStaticObjectField</code><code class=
3150 "cCode">()</code>
3151 </td>
3152 <td>
3153 jobject
3154 </td>
3155 </tr>
3156 <tr>
3157 <td>
3158 <code class=
3159 "cCode">SetStaticBooleanField</code><code class=
3160 "cCode">()</code>
3161 </td>
3162 <td>
3163 jboolean
3164 </td>
3165 </tr>
3166 <tr>
3167 <td>
3168 <code class=
3169 "cCode">SetStaticByteField</code><code class=
3170 "cCode">()</code>
3171 </td>
3172 <td>
3173 jbyte
3174 </td>
3175 </tr>
3176 <tr>
3177 <td>
3178 <code class=
3179 "cCode">SetStaticCharField</code><code class=
3180 "cCode">()</code>
3181 </td>
3182 <td>
3183 jchar
3184 </td>
3185 </tr>
3186 <tr>
3187 <td>
3188 <code class=
3189 "cCode">SetStaticShortField</code><code class=
3190 "cCode">()</code>
3191 </td>
3192 <td>
3193 jshort
3194 </td>
3195 </tr>
3196 <tr>
3197 <td>
3198 <code class=
3199 "cCode">SetStaticIntField</code><code>()</code>
3200 </td>
3201 <td>
3202 jint
3203 </td>
3204 </tr>
3205 <tr>
3206 <td>
3207 <code class=
3208 "cCode">SetStaticLongField</code><code class=
3209 "cCode">()</code>
3210 </td>
3211 <td>
3212 jlong
3213 </td>
3214 </tr>
3215 <tr>
3216 <td>
3217 <code class=
3218 "cCode">SetStaticFloatField</code><code class=
3219 "cCode">()</code>
3220 </td>
3221 <td>
3222 jfloat
3223 </td>
3224 </tr>
3225 <tr>
3226 <td>
3227 <code class=
3228 "cCode">SetStaticDoubleField</code><code class=
3229 "cCode">()</code>
3230 </td>
3231 <td>
3232 jdouble
3233 </td>
3234 </tr>
3235 </tbody>
3236 </table>
3237
3238
3239
3240 <h4>LINKAGE:</h4>
3241 <p>Indices in the JNIEnv interface function table.</p>
3242
3243
3244 <table border="1" summary=
3245 "SetStatic<type>Field Family of Accessor Routines">
3246 <caption>SetStatic<type>Field Family of Accessor Routines</caption>
3247 <thead>
3248 <tr>
3249 <th>
3250
3251 SetStatic<type>Field Routine Name
3252 </th>
3253 <th>
3254 Index
3255 </th>
3256 </tr>
3257 </thead>
3258 <tbody>
3259 <tr>
3260 <td>
3261 <code class=
3262 "cCode">SetStaticObjectField</code><code class=
3263 "cCode">()</code>
3264 </td>
3265 <td>154</td>
3266 </tr>
3267 <tr>
3268 <td>
3269 <code class=
3270 "cCode">SetStaticBooleanField</code><code class=
3271 "cCode">()</code>
3272 </td>
3273 <td>155</td>
3274 </tr>
3275 <tr>
3276 <td>
3277 <code class=
3278 "cCode">SetStaticByteField</code><code class=
3279 "cCode">()</code>
3280 </td>
3281 <td>156</td>
3282 </tr>
3283 <tr>
3284 <td>
3285 <code class=
3286 "cCode">SetStaticCharField</code><code class=
3287 "cCode">()</code>
3288 </td>
3289 <td>157</td>
3290 </tr>
3291 <tr>
3292 <td>
3293 <code class=
3294 "cCode">SetStaticShortField</code><code class=
3295 "cCode">()</code>
3296 </td>
3297 <td>158</td>
3298 </tr>
3299 <tr>
3300 <td>
3301 <code class=
3302 "cCode">SetStaticIntField</code><code>()</code>
3303 </td>
3304 <td>159</td>
3305 </tr>
3306 <tr>
3307 <td>
3308 <code class=
3309 "cCode">SetStaticLongField</code><code class=
3310 "cCode">()</code>
3311 </td>
3312 <td>160</td>
3313 </tr>
3314 <tr>
3315 <td>
3316 <code class=
3317 "cCode">SetStaticFloatField</code><code class=
3318 "cCode">()</code>
3319 </td>
3320 <td>161</td>
3321 </tr>
3322 <tr>
3323 <td>
3324 <code class=
3325 "cCode">SetStaticDoubleField</code><code class=
3326 "cCode">()</code>
3327 </td>
3328 <td>162</td>
3329 </tr>
3330 </tbody>
3331 </table>
3332 <h4>PARAMETERS:</h4>
3333
3334 <p><code>env</code>: the JNI interface
3335 pointer.</p>
3336
3337 <p><code>clazz</code>: a Java class
3338 object.</p>
3339
3340 <p><code>fieldID</code>: a static field
3341 ID.</p>
3342
3343 <p><code>value</code>: the new value of
3344 the field.</p>
3345
3346 <!-- ******************************************************** -->
3347 <h2><a name="calling_static_methods">Calling Static Methods</a></h2>
3348
3349 <h3><a name="GetStaticMethodID">GetStaticMethodID</a></h3>
3350
3351 <p><code>jmethodID
3352 GetStaticMethodID(JNIEnv *env, jclass clazz,<br />
3353 const char *name, const char *sig);</code></p>
3354
3355 <p>Returns the method ID for a static method of a
3356 class. The method is specified by its name and signature.</p>
3357
3358 <p><code>GetStaticMethodID()</code>
3359 causes an uninitialized class to be initialized.</p>
3360
3361 <h4>LINKAGE:</h4>
3362 Index 113 in the JNIEnv interface function table.
3363 <h4>PARAMETERS:</h4>
3364
3365 <p><code>env</code>: the JNI interface
3366 pointer.</p>
3367
3368 <p><code>clazz</code>: a Java class
3369 object.</p>
3370
3371 <p><code>name</code>: the static method
3372 name in a 0-terminated modified UTF-8 string.</p>
3373
3374 <p><code>sig</code>: the method
3375 signature in a 0-terminated modified UTF-8 string.</p>
3376
3377 <h4>RETURNS:</h4>
3378
3379 <p>Returns a method ID, or <code class=
3380 "cCode">NULL</code> if the operation fails.</p>
3381
3382 <h4>THROWS:</h4>
3383
3384 <p><code>NoSuchMethodError</code>: if
3385 the specified static method cannot be found.</p>
3386
3387 <p><code class=
3388 "cCode">ExceptionInInitializerError</code>: if the class
3389 initializer fails due to an exception.</p>
3390
3391 <p><code>OutOfMemoryError</code>: if
3392 the system runs out of memory.</p>
3393
3394 <h3><a name="CallStatic_type_Method_routines">CallStatic<type>Method Routines, CallStatic<type>MethodA Routines, CallStatic<type>MethodV Routines</a></h3>
3395
3396 <p><em>NativeType</em> <em class=
3397 "cEmphasis">CallStatic<type>Method</em><code class=
3398 "cCode">(JNIEnv *env, jclass clazz,<br />
3399 jmethodID methodID, ...);</code></p>
3400
3401 <p><em>NativeType</em> <em class=
3402 "cEmphasis">CallStatic<type>MethodA</em><code class=
3403 "cCode">(JNIEnv *env, jclass clazz,<br />
3404 jmethodID methodID, jvalue *args);</code></p>
3405
3406 <p><em>NativeType</em> <em class=
3407 "cEmphasis">CallStatic<type>MethodV</em><code class=
3408 "cCode">(JNIEnv *env, jclass clazz,<br />
3409 jmethodID methodID, va_list args);</code></p>
3410
3411 <p>This family of operations invokes a static method
3412 on a Java object, according to the specified method ID. The
3413 <code>methodID</code> argument must be obtained by
3414 calling <code>GetStaticMethodID</code><code class=
3415 "cCode">()</code>.</p>
3416
3417 <p>The method ID must be derived from <code class=
3418 "cCode">clazz</code>, not from one of its superclasses.</p>
3419
3420 <h4>CallStatic<type>Method Routines</h4>
3421
3422 <p>Programmers should place all arguments that are to
3423 be passed to the method immediately following the <code class=
3424 "cCode">methodID</code> argument. The <em class=
3425 "cEmphasis">CallStatic<type>Method</em> routine accepts these
3426 arguments and passes them to the Java method that the programmer
3427 wishes to invoke.</p>
3428
3429 <h4>CallStatic<type>MethodA Routines</h4>
3430
3431 <p>Programmers should place all arguments to the
3432 method in an <code>args</code> array of <code class=
3433 "cCode">jvalues</code> that immediately follows the <code class=
3434 "cCode">methodID</code> argument. The <em class=
3435 "cEmphasis">CallStaticMethodA</em> routine accepts the arguments in
3436 this array, and, in turn, passes them to the Java method that the
3437 programmer wishes to invoke.</p>
3438
3439 <h4>CallStatic<type>MethodV Routines</h4>
3440
3441 <p>Programmers should place all arguments to the
3442 method in an <code>args</code> argument of type
3443 <code>va_list</code> that immediately follows the
3444 <code>methodID</code> argument. The <em class=
3445 "cEmphasis">CallStaticMethodV</em> routine accepts the arguments,
3446 and, in turn, passes them to the Java method that the programmer
3447 wishes to invoke.</p>
3448
3449 <p>The following table describes each of the method
3450 calling routines according to their result types. You should
3451 replace <em>type</em> in <em class=
3452 "cEmphasis">CallStatic<type>Method</em> with the Java type of
3453 the method, or one of the actual method calling routine names from
3454 the table, and replace <em>NativeType</em> with
3455 the corresponding native type for that routine.</p>
3456
3457
3458 <table border="1" summary=
3459 "CallStatic<type>Method Calling Routines">
3460 <caption>CallStatic<type>Method Calling Routines</caption>
3461 <thead>
3462 <tr>
3463 <th>
3464
3465 CallStatic<type>Method Routine Name
3466 </th>
3467 <th>
3468 Native Type
3469 </th>
3470 </tr>
3471 </thead>
3472 <tbody>
3473 <tr>
3474 <td>
3475 <code class=
3476 "cCode">CallStaticVoidMethod</code><code class=
3477 "cCode">()</code>
3478
3479 <code class=
3480 "cCode">CallStaticVoidMethodA</code><code class=
3481 "cCode">()</code>
3482
3483 <code class=
3484 "cCode">CallStaticVoidMethod</code><code class=
3485 "cCode">V()</code>
3486 </td>
3487 <td>
3488 void
3489 </td>
3490 </tr>
3491 <tr>
3492 <td>
3493 <code class=
3494 "cCode">CallStaticObjectMethod</code><code class=
3495 "cCode">()</code>
3496
3497 <code class=
3498 "cCode">CallStaticObjectMethod</code><code class=
3499 "cCode">A()</code>
3500
3501 <code class=
3502 "cCode">CallStaticObjectMethod</code><code class=
3503 "cCode">V()</code>
3504 </td>
3505 <td>
3506 jobject
3507 </td>
3508 </tr>
3509 <tr>
3510 <td>
3511 <code class=
3512 "cCode">CallStaticBooleanMethod</code><code class=
3513 "cCode">()</code>
3514
3515 <code class=
3516 "cCode">CallStaticBooleanMethod</code><code class=
3517 "cCode">A()</code>
3518
3519 <code class=
3520 "cCode">CallStaticBooleanMethod</code><code class=
3521 "cCode">V()</code>
3522 </td>
3523 <td>
3524 jboolean
3525 </td>
3526 </tr>
3527 <tr>
3528 <td>
3529 <code class=
3530 "cCode">CallStaticByteMethod</code><code class=
3531 "cCode">()</code>
3532
3533 <code class=
3534 "cCode">CallStaticByteMethod</code><code class=
3535 "cCode">A()</code>
3536
3537 <code class=
3538 "cCode">CallStaticByteMethod</code><code class=
3539 "cCode">V()</code>
3540 </td>
3541 <td>
3542 jbyte
3543 </td>
3544 </tr>
3545 <tr>
3546 <td>
3547 <code class=
3548 "cCode">CallStaticCharMethod</code><code class=
3549 "cCode">()</code>
3550
3551 <code class=
3552 "cCode">CallStaticCharMethod</code><code class=
3553 "cCode">A()</code>
3554
3555 <code class=
3556 "cCode">CallStaticCharMethod</code><code class=
3557 "cCode">V()</code>
3558 </td>
3559 <td>
3560 jchar
3561 </td>
3562 </tr>
3563 <tr>
3564 <td>
3565 <code class=
3566 "cCode">CallStaticShortMethod</code><code class=
3567 "cCode">()</code>
3568
3569 <code class=
3570 "cCode">CallStaticShortMethod</code><code class=
3571 "cCode">A()</code>
3572
3573 <code class=
3574 "cCode">CallStaticShortMethod</code><code class=
3575 "cCode">V()</code>
3576 </td>
3577 <td>
3578 jshort
3579 </td>
3580 </tr>
3581 <tr>
3582 <td>
3583 <code class=
3584 "cCode">CallStaticIntMethod</code><code class=
3585 "cCode">()</code>
3586
3587 <code class=
3588 "cCode">CallStaticIntMethod</code><code class=
3589 "cCode">A()</code>
3590
3591 <code class=
3592 "cCode">CallStaticIntMethod</code><code class=
3593 "cCode">V()</code>
3594 </td>
3595 <td>
3596 jint
3597 </td>
3598 </tr>
3599 <tr>
3600 <td>
3601 <code class=
3602 "cCode">CallStaticLongMethod</code><code class=
3603 "cCode">()</code>
3604
3605 <code class=
3606 "cCode">CallStaticLongMethod</code><code class=
3607 "cCode">A()</code>
3608
3609 <code class=
3610 "cCode">CallStaticLongMethod</code><code class=
3611 "cCode">V()</code>
3612 </td>
3613 <td>
3614 jlong
3615 </td>
3616 </tr>
3617 <tr>
3618 <td>
3619 <code class=
3620 "cCode">CallStaticFloatMethod</code><code class=
3621 "cCode">()</code>
3622
3623 <code class=
3624 "cCode">CallStaticFloatMethod</code><code class=
3625 "cCode">A()</code>
3626
3627 <code class=
3628 "cCode">CallStaticFloatMethod</code><code class=
3629 "cCode">V()</code>
3630 </td>
3631 <td>
3632 jfloat
3633 </td>
3634 </tr>
3635 <tr>
3636 <td>
3637 <code class=
3638 "cCode">CallStaticDoubleMethod</code><code class=
3639 "cCode">()</code>
3640
3641 <code class=
3642 "cCode">CallStaticDoubleMethod</code><code class=
3643 "cCode">A()</code>
3644
3645 <code class=
3646 "cCode">CallStaticDoubleMethod</code><code class=
3647 "cCode">V()</code>
3648 </td>
3649 <td>
3650 jdouble
3651 </td>
3652 </tr>
3653 </tbody>
3654 </table>
3655
3656
3657
3658 <h4>LINKAGE:</h4>
3659 <p>Indices in the JNIEnv interface function table.</p>
3660
3661 <table border="1" summary=
3662 "CallStatic<type>Method Calling Routines">
3663 <caption>CallStatic<type>Method Calling Routines</caption>
3664 <thead>
3665 <tr>
3666 <th>
3667
3668 CallStatic<type>Method Routine Name
3669 </th>
3670 <th>
3671 Index
3672 </th>
3673 </tr>
3674 </thead>
3675 <tbody>
3676 <tr>
3677 <td>
3678 <code class=
3679 "cCode">CallStaticVoidMethod</code><code class=
3680 "cCode">()</code>
3681 <code class=
3682 "cCode">CallStaticVoidMethodA</code><code class=
3683 "cCode">()</code>
3684 <code class=
3685 "cCode">CallStaticVoidMethod</code><code class=
3686 "cCode">V()</code>
3687 </td>
3688 <td>141<br />
3689 143<br />
3690 142</td>
3691 </tr>
3692 <tr>
3693 <td>
3694 <code class=
3695 "cCode">CallStaticObjectMethod</code><code class=
3696 "cCode">()</code>
3697 <code class=
3698 "cCode">CallStaticObjectMethod</code><code class=
3699 "cCode">A()</code>
3700 <code class=
3701 "cCode">CallStaticObjectMethod</code><code class=
3702 "cCode">V()</code>
3703 </td>
3704 <td>114<br />
3705 116<br />
3706 115</td>
3707 </tr>
3708 <tr>
3709 <td>
3710 <code class=
3711 "cCode">CallStaticBooleanMethod</code><code class=
3712 "cCode">()</code>
3713 <code class=
3714 "cCode">CallStaticBooleanMethod</code><code class=
3715 "cCode">A()</code>
3716 <code class=
3717 "cCode">CallStaticBooleanMethod</code><code class=
3718 "cCode">V()</code>
3719 </td>
3720 <td>117<br />
3721 119<br />
3722 118</td>
3723 </tr>
3724 <tr>
3725 <td>
3726 <code class=
3727 "cCode">CallStaticByteMethod</code><code class=
3728 "cCode">()</code>
3729 <code class=
3730 "cCode">CallStaticByteMethod</code><code class=
3731 "cCode">A()</code>
3732 <code class=
3733 "cCode">CallStaticByteMethod</code><code class=
3734 "cCode">V()</code>
3735 </td>
3736 <td>120<br />
3737 122<br />
3738 121</td>
3739 </tr>
3740 <tr>
3741 <td>
3742 <code class=
3743 "cCode">CallStaticCharMethod</code><code class=
3744 "cCode">()</code>
3745 <code class=
3746 "cCode">CallStaticCharMethod</code><code class=
3747 "cCode">A()</code>
3748 <code class=
3749 "cCode">CallStaticCharMethod</code><code class=
3750 "cCode">V()</code>
3751 </td>
3752 <td>123<br />
3753 125<br />
3754 124</td>
3755 </tr>
3756 <tr>
3757 <td>
3758 <code class=
3759 "cCode">CallStaticShortMethod</code><code class=
3760 "cCode">()</code>
3761 <code class=
3762 "cCode">CallStaticShortMethod</code><code class=
3763 "cCode">A()</code>
3764 <code class=
3765 "cCode">CallStaticShortMethod</code><code class=
3766 "cCode">V()</code>
3767 </td>
3768 <td>126<br />
3769 128<br />
3770 127</td>
3771 </tr>
3772 <tr>
3773 <td>
3774 <code class=
3775 "cCode">CallStaticIntMethod</code><code class=
3776 "cCode">()</code>
3777 <code class=
3778 "cCode">CallStaticIntMethod</code><code class=
3779 "cCode">A()</code>
3780 <code class=
3781 "cCode">CallStaticIntMethod</code><code class=
3782 "cCode">V()</code>
3783 </td>
3784 <td>129<br />
3785 131<br />
3786 130</td>
3787 </tr>
3788 <tr>
3789 <td>
3790 <code class=
3791 "cCode">CallStaticLongMethod</code><code class=
3792 "cCode">()</code>
3793 <code class=
3794 "cCode">CallStaticLongMethod</code><code class=
3795 "cCode">A()</code>
3796 <code class=
3797 "cCode">CallStaticLongMethod</code><code class=
3798 "cCode">V()</code>
3799 </td>
3800 <td>132<br />
3801 134<br />
3802 133</td>
3803 </tr>
3804 <tr>
3805 <td>
3806 <code class=
3807 "cCode">CallStaticFloatMethod</code><code class=
3808 "cCode">()</code>
3809 <code class=
3810 "cCode">CallStaticFloatMethod</code><code class=
3811 "cCode">A()</code>
3812 <code class=
3813 "cCode">CallStaticFloatMethod</code><code class=
3814 "cCode">V()</code>
3815 </td>
3816 <td>135<br />
3817 137<br />
3818 136</td>
3819 </tr>
3820 <tr>
3821 <td>
3822 <code class=
3823 "cCode">CallStaticDoubleMethod</code><code class=
3824 "cCode">()</code>
3825 <code class=
3826 "cCode">CallStaticDoubleMethod</code><code class=
3827 "cCode">A()</code>
3828 <code class=
3829 "cCode">CallStaticDoubleMethod</code><code class=
3830 "cCode">V()</code>
3831 </td>
3832 <td>138<br />
3833 140<br />
3834 139</td>
3835 </tr>
3836 </tbody>
3837 </table>
3838 <h4>PARAMETERS:</h4>
3839
3840 <p><code>env</code>: the JNI interface
3841 pointer.</p>
3842
3843 <p><code>clazz</code>: a Java class
3844 object.</p>
3845
3846 <p><code>methodID</code>: a static
3847 method ID.</p>
3848
3849 <h4>Additional Parameter for
3850 CallStatic<type>Method Routines:</h4>
3851
3852 <p>arguments to the static method.</p>
3853
3854 <h4>Additional Parameter for
3855 CallStatic<type>MethodA Routines:</h4>
3856
3857 <p><code>args</code>: an array of
3858 arguments.</p>
3859
3860 <h4>Additional Parameter for
3861 CallStatic<type>MethodV Routines:</h4>
3862
3863 <p><code>args</code>: a <code class=
3864 "cCode">va_list</code> of arguments.</p>
3865
3866 <h4>RETURNS:</h4>
3867
3868 <p>Returns the result of calling the static Java
3869 method.</p>
3870
3871 <h4>THROWS:</h4>
3872
3873 <p><code>Exceptions raised during the
3874 execution of the Java method.</code></p>
3875 <!-- ******************************************************** -->
3876 <h2><a name="string_operations">String Operations</a></h2>
3877
3878 <h3><a name="NewString">NewString</a></h3>
3879
3880 <p><code>jstring NewString(JNIEnv *env,
3881 const jchar *unicodeChars,<br />
3882 jsize len);</code></p>
3883
3884 <p>Constructs a new <code class=
3885 "cCode">java.lang.String</code> object from an array of Unicode
3886 characters.</p>
3887
3888 <h4>LINKAGE:</h4>
3889 Index 163 in the JNIEnv interface function table.
3890 <h4>PARAMETERS:</h4>
3891
3892 <p><code>env</code>: the JNI interface
3893 pointer.</p>
3894
3895 <p><code>unicodeChars</code>: pointer
3896 to a Unicode string.</p>
3897
3898 <p><code>len</code>: length of the
3899 Unicode string.</p>
3900
3901 <h4>RETURNS:</h4>
3902
3903 <p>Returns a Java string object, or <code class=
3904 "cCode">NULL</code> if the string cannot be constructed.</p>
3905
3906 <h4>THROWS:</h4>
3907
3908 <p><code>OutOfMemoryError</code>: if
3909 the system runs out of memory.</p>
3910
3911 <h3><a name="GetStringLength">GetStringLength</a></h3>
3912
3913 <p><code>jsize GetStringLength(JNIEnv
3914 *env, jstring string);</code></p>
3915
3916 <p>Returns the length (the count of Unicode
3917 characters) of a Java string.</p>
3918
3919 <h4>LINKAGE:</h4>
3920 Index 164 in the JNIEnv interface function table.
3921 <h4>PARAMETERS:</h4>
3922
3923 <p><code>env</code>: the JNI interface
3924 pointer.</p>
3925
3926 <p><code>string</code>: a Java string
3927 object.</p>
3928
3929 <h4>RETURNS:</h4>
3930
3931 <p>Returns the length of the Java string.</p>
3932
3933 <h3><a name="GetStringChars">GetStringChars</a></h3>
3934
3935 <p><code>const jchar *
3936 GetStringChars(JNIEnv *env, jstring string,<br />
3937 jboolean *isCopy);</code></p>
3938
3939 <p>Returns a pointer to the array of Unicode
3940 characters of the string. This pointer is valid until <code class=
3941 "cCode">ReleaseStringChars()</code> is called.</p>
3942
3943 <p>If <code>isCopy</code> is not
3944 <code>NULL</code>, then <code class=
3945 "cCode">*isCopy</code> is set to <code class=
3946 "cCode">JNI_TRUE</code> if a copy is made; or it is set to
3947 <code>JNI_FALSE</code> if no copy is made.</p>
3948
3949 <h4>LINKAGE:</h4>
3950 Index 165 in the JNIEnv interface function table.
3951 <h4>PARAMETERS:</h4>
3952
3953 <p><code>env</code>: the JNI interface
3954 pointer.</p>
3955
3956 <p><code>string</code>: a Java string
3957 object.</p>
3958
3959 <p><code>isCopy</code>: a pointer to a
3960 boolean.</p>
3961
3962 <h4>RETURNS:</h4>
3963
3964 <p>Returns a pointer to a Unicode string, or
3965 <code>NULL</code> if the operation fails.</p>
3966
3967 <h3><a name="ReleaseStringChars">ReleaseStringChars</a></h3>
3968
3969 <p><code>void ReleaseStringChars(JNIEnv
3970 *env, jstring string,<br />
3971 const jchar *chars);</code></p>
3972
3973 <p>Informs the VM that the native code no longer
3974 needs access to <code>chars</code>. The <code class=
3975 "cCode">chars</code> argument is a pointer obtained from
3976 <code>string</code> using <code class=
3977 "cCode">GetStringChars()</code>.</p>
3978
3979 <h4>LINKAGE:</h4>
3980 Index 166 in the JNIEnv interface function table.
3981 <h4>PARAMETERS:</h4>
3982
3983 <p><code>env</code>: the JNI interface
3984 pointer.</p>
3985
3986 <p><code>string</code>: a Java string
3987 object.</p>
3988
3989 <p><code>chars</code>: a pointer to a
3990 Unicode string.</p>
3991
3992 <h3><a name="NewStringUTF">NewStringUTF</a></h3>
3993
3994 <p><code>jstring NewStringUTF(JNIEnv
3995 *env, const char *bytes);</code></p>
3996
3997 <p>Constructs a new <code class=
3998 "cCode">java.lang.String</code> object from an array of characters
3999 in modified UTF-8 encoding.</p>
4000
4001 <h4>LINKAGE:</h4>
4002 Index 167 in the JNIEnv interface function table.
4003 <h4>PARAMETERS:</h4>
4004
4005 <p><code>env</code>: the JNI interface
4006 pointer.</p>
4007
4008 <p><code>bytes</code>: the pointer to a
4009 modified UTF-8 string.</p>
4010
4011 <h4>RETURNS:</h4>
4012
4013 <p>Returns a Java string object, or <code class=
4014 "cCode">NULL</code> if the string cannot be constructed.</p>
4015
4016 <h4>THROWS:</h4>
4017
4018 <p><code>OutOfMemoryError</code>: if
4019 the system runs out of memory.</p>
4020
4021 <h3><a name="GetStringUTFLength">GetStringUTFLength</a></h3>
4022
4023 <p><code>jsize
4024 GetStringUTFLength(JNIEnv *env, jstring string);</code></p>
4025
4026 <p>Returns the length in bytes of the modified UTF-8
4027 representation of a string.</p>
4028
4029 <h4>LINKAGE:</h4>
4030 Index 168 in the JNIEnv interface function table.
4031 <h4>PARAMETERS:</h4>
4032
4033 <p><code>env</code>: the JNI interface
4034 pointer.</p>
4035
4036 <p><code>string</code>: a Java string
4037 object.</p>
4038
4039 <h4>RETURNS:</h4>
4040
4041 <p>Returns the UTF-8 length of the string.</p>
4042
4043 <h3><a name="GetStringUTFChars">GetStringUTFChars</a></h3>
4044
4045 <p><code>const char *
4046 GetStringUTFChars(JNIEnv *env, jstring string,<br />
4047 jboolean *isCopy);</code></p>
4048
4049 <p>Returns a pointer to an array of bytes
4050 representing the string in modified UTF-8 encoding. This array is
4051 valid until it is released by <code class=
4052 "cCode">ReleaseStringUTFChars()</code>.</p>
4053
4054 <p>If <code>isCopy</code> is not
4055 <code>NULL</code>, then <code class=
4056 "cCode">*isCopy</code> is set to <code class=
4057 "cCode">JNI_TRUE</code> if a copy is made; or it is set to
4058 <code>JNI_FALSE</code> if no copy is made.</p>
4059
4060 <h4>LINKAGE:</h4>
4061 Index 169 in the JNIEnv interface function table.
4062 <h4>PARAMETERS:</h4>
4063
4064 <p><code>env</code>: the JNI interface
4065 pointer.</p>
4066
4067 <p><code>string</code>: a Java string
4068 object.</p>
4069
4070 <p><code>isCopy</code>: a pointer to a
4071 boolean.</p>
4072
4073 <h4>RETURNS:</h4>
4074
4075 <p>Returns a pointer to a modified UTF-8 string, or
4076 <code>NULL</code> if the operation fails.</p>
4077
4078 <h3><a name="ReleaseStringUTFChars">ReleaseStringUTFChars</a></h3>
4079
4080 <p><code>void
4081 ReleaseStringUTFChars(JNIEnv *env, jstring string,<br />
4082 const char *utf);</code></p>
4083
4084 <p>Informs the VM that the native code no longer
4085 needs access to <code>utf</code>. The <code class=
4086 "cCode">utf</code> argument is a pointer derived from <code class=
4087 "cCode">string</code> using <code class=
4088 "cCode">GetStringUTFChars()</code>.</p>
4089
4090 <h4>LINKAGE:</h4>
4091 Index 170 in the JNIEnv interface function table.
4092 <h4>PARAMETERS:</h4>
4093
4094 <p><code>env</code>: the JNI interface
4095 pointer.</p>
4096
4097 <p><code>string</code>: a Java string
4098 object.</p>
4099
4100 <p><code>utf</code>: a pointer to a
4101 modified UTF-8 string.</p>
4102
4103
4104 <p><strong>Note</strong>: In JDK/JRE 1.1, programmers can get primitive array elements in
4105 a user-supplied buffer. As of JDK/JRE 1.2 additional set of
4106 functions are provided allowing native code to obtain characters in
4107 Unicode (UTF-16) or modified UTF-8 encoding in a user-supplied
4108 buffer. See the functions below.</p>
4109
4110 <h3><a name="GetStringRegion">GetStringRegion</a></h3>
4111 <p><code>void GetStringRegion(JNIEnv *env, jstring str, jsize
4112 start, jsize len, jchar *buf);</code></p>
4113 <p>Copies <code>len</code> number of Unicode characters beginning
4114 at offset <code>start</code> to the given buffer
4115 <code>buf</code>.</p>
4116 <p>Throws <code>StringIndexOutOfBoundsException</code> on index
4117 overflow.</p>
4118 <h4>LINKAGE:</h4>
4119 Index 220 in the JNIEnv interface function table.
4120 <h4>SINCE:</h4>
4121 <p>JDK/JRE 1.2</p>
4122 <h3><a name="GetStringUTFRegion">GetStringUTFRegion</a></h3>
4123 <p>< <code>void GetStringUTFRegion(JNIEnv *env, jstring str,
4124 jsize start, jsize len, char *buf);</code></p>
4125 <p>Translates <code>len</code> number of Unicode characters
4126 beginning at offset <code>start</code> into modified UTF-8 encoding
4127 and place the result in the given buffer <code>buf</code>.</p>
4128 <p>Throws <code>StringIndexOutOfBoundsException</code> on index
4129 overflow.</p>
4130 <h4>LINKAGE:</h4>
4131 Index 221 in the JNIEnv interface function table.
4132 <h4>SINCE:</h4>
4133 <p>JDK/JRE 1.2</p>
4134 <h3><a name="GetStringCritical_ReleaseStringCritical">GetStringCritical, ReleaseStringCritical</a></h3>
4135 <p><code>const jchar * GetStringCritical(JNIEnv *env, jstring
4136 string, jboolean *isCopy);<br />
4137 void ReleaseStringCritical(JNIEnv *env, jstring string, const jchar
4138 *carray);</code></p>
4139 <p>The semantics of these two functions are similar to the existing
4140 <code>Get/ReleaseStringChars</code> functions. If possible, the VM
4141 returns a pointer to string elements; otherwise, a copy is made.
4142 <strong>However, there are significant restrictions on how these
4143 functions can be used.</strong> In a code segment enclosed by
4144 <code>Get/ReleaseStringCritical</code> calls, the native code must
4145 not issue arbitrary JNI calls, or cause the current thread to
4146 block.</p>
4147 <p>The restrictions on <code>Get/ReleaseStringCritical</code> are
4148 similar to those on
4149 <code>Get/ReleasePrimitiveArrayCritical</code>.</p>
4150 <h4>LINKAGE (GetStringCritical):</h4>
4151 Index 224 in the JNIEnv interface function table.
4152 <h4>LINKAGE (ReleaseStingCritical):</h4>
4153 Index 225 in the JNIEnv interface function table.
4154 <h4>SINCE:</h4>
4155 <p>JDK/JRE 1.2</p>
4156 <a name="reflection"></a>
4157 <!-- ******************************************************** -->
4158 <h2><a name="array_operations">Array Operations</a></h2>
4159
4160 <h3><a name="GetArrayLength">GetArrayLength</a></h3>
4161
4162 <p><code>jsize GetArrayLength(JNIEnv
4163 *env, jarray array);</code></p>
4164
4165 <p>Returns the number of elements in the array.</p>
4166
4167 <h4>LINKAGE:</h4>
4168 Index 171 in the JNIEnv interface function table.
4169 <h4>PARAMETERS:</h4>
4170
4171 <p><code>env</code>: the JNI interface
4172 pointer.</p>
4173
4174 <p><code>array</code>: a Java array
4175 object.</p>
4176
4177 <h4>RETURNS:</h4>
4178
4179 <p>Returns the length of the array.</p>
4180
4181 <h3><a name="NewObjectArray">NewObjectArray</a></h3>
4182
4183 <p><code>jobjectArray
4184 NewObjectArray(JNIEnv *env, jsize length,<br />
4185 jclass elementClass, jobject initialElement);</code></p>
4186
4187 <p>Constructs a new array holding objects in class
4188 <code>elementClass</code>. All elements are initially
4189 set to <code>initialElement</code>.</p>
4190
4191 <h4>LINKAGE:</h4>
4192 Index 172 in the JNIEnv interface function table.
4193 <h4>PARAMETERS:</h4>
4194
4195 <p><code>env</code>: the JNI interface
4196 pointer.</p>
4197
4198 <p><code>length</code>: array size.</p>
4199
4200 <p><code>elementClass</code>: array
4201 element class.</p>
4202
4203 <p><code>initialElement</code>:
4204 initialization value.</p>
4205
4206 <h4>RETURNS:</h4>
4207
4208 <p>Returns a Java array object, or <code class=
4209 "cCode">NULL</code> if the array cannot be constructed.</p>
4210
4211 <h4>THROWS:</h4>
4212
4213 <p><code>OutOfMemoryError</code>: if
4214 the system runs out of memory.</p>
4215
4216 <h3><a name="GetObjectArrayElement">GetObjectArrayElement</a></h3>
4217
4218 <p><code>jobject
4219 GetObjectArrayElement(JNIEnv *env,<br />
4220 jobjectArray array, jsize index);</code></p>
4221
4222 <p>Returns an element of an <code class=
4223 "cCode">Object</code> array.</p>
4224
4225 <h4>LINKAGE:</h4>
4226 Index 173 in the JNIEnv interface function table.
4227 <h4>PARAMETERS:</h4>
4228
4229 <p><code>env</code>: the JNI interface
4230 pointer.</p>
4231
4232 <p><code>array</code>: a Java
4233 array.</p>
4234
4235 <p><code>index</code>: array index.</p>
4236
4237 <h4>RETURNS:</h4>
4238
4239 <p>Returns a Java object.</p>
4240
4241 <h4>THROWS:</h4>
4242
4243 <p><code class=
4244 "cCode">ArrayIndexOutOfBoundsException</code>: if <code class=
4245 "cCode">index</code> does not specify a valid index in the
4246 array.</p>
4247
4248 <h3><a name="SetObjectArrayElement">SetObjectArrayElement</a></h3>
4249
4250 <p><code>void
4251 SetObjectArrayElement(JNIEnv *env, jobjectArray array,<br />
4252 jsize index, jobject value);</code></p>
4253
4254 <p>Sets an element of an <code class=
4255 "cCode">Object</code> array.</p>
4256
4257 <h4>LINKAGE:</h4>
4258 Index 174 in the JNIEnv interface function table.
4259 <h4>PARAMETERS:</h4>
4260
4261 <p><code>env</code>: the JNI interface
4262 pointer.</p>
4263
4264 <p><code>array</code>: a Java
4265 array.</p>
4266
4267 <p><code>index</code>: array index.</p>
4268
4269 <p><code>value</code>: the new
4270 value.</p>
4271
4272 <h4>THROWS:</h4>
4273
4274 <p><code class=
4275 "cCode">ArrayIndexOutOfBoundsException</code>: if <code class=
4276 "cCode">index</code> does not specify a valid index in the
4277 array.</p>
4278
4279 <p><code>ArrayStoreException</code>: if
4280 the class of <code>value</code> is not a subclass of
4281 the element class of the array.</p>
4282
4283 <h3><a name="New_PrimitiveType_Array_routines">New<PrimitiveType>Array Routines</a></h3>
4284
4285 <p><em>ArrayType</em> <em class=
4286 "cEmphasis">New<PrimitiveType>Array</em><code class=
4287 "cCode">(JNIEnv *env, jsize length);</code></p>
4288
4289 <p>A family of operations used to construct a new
4290 primitive array object. The following table
4291 describes the specific primitive array constructors. You should
4292 replace <em>New<PrimitiveType>Array</em>
4293 with one of the actual primitive array constructor routine names
4294 from this table, and replace ArrayType with the
4295 corresponding array type for that routine.</p>
4296
4297
4298
4299 <table border="1" summary=
4300 "New<PrimitiveType>Array Family of Array Constructors">
4301 <caption>New<PrimitiveType>Array Family of Array Constructors</caption>
4302 <thead>
4303 <tr>
4304 <th>
4305
4306 New<PrimitiveType>Array Routines
4307 </th>
4308 <th>
4309 Array Type
4310 </th>
4311 </tr>
4312 </thead>
4313 <tbody>
4314 <tr>
4315 <td>
4316 <code class=
4317 "cCode">NewBooleanArray()</code>
4318 </td>
4319 <td>
4320 jbooleanArray
4321 </td>
4322 </tr>
4323 <tr>
4324 <td>
4325 <code class=
4326 "cCode">NewByteArray()</code>
4327 </td>
4328 <td>
4329 jbyteArray
4330 </td>
4331 </tr>
4332 <tr>
4333 <td>
4334 <code class=
4335 "cCode">NewCharArray()</code>
4336 </td>
4337 <td>
4338 jcharArray
4339 </td>
4340 </tr>
4341 <tr>
4342 <td>
4343 <code class=
4344 "cCode">NewShortArray()</code>
4345 </td>
4346 <td>
4347 jshortArray
4348 </td>
4349 </tr>
4350 <tr>
4351 <td>
4352 <code class=
4353 "cCode">NewIntArray()</code>
4354 </td>
4355 <td>
4356 jintArray
4357 </td>
4358 </tr>
4359 <tr>
4360 <td>
4361 <code class=
4362 "cCode">NewLongArray()</code>
4363 </td>
4364 <td>
4365 jlongArray
4366 </td>
4367 </tr>
4368 <tr>
4369 <td>
4370 <code class=
4371 "cCode">NewFloatArray()</code>
4372 </td>
4373 <td>
4374 jfloatArray
4375 </td>
4376 </tr>
4377 <tr>
4378 <td>
4379 <code class=
4380 "cCode">NewDoubleArray()</code>
4381 </td>
4382 <td>
4383 jdoubleArray
4384 </td>
4385 </tr>
4386 </tbody>
4387 </table>
4388
4389
4390
4391 <h4>LINKAGE:</h4>
4392 <p>Indices in the JNIEnv interface function table.</p>
4393 <table border="1" summary=
4394 "New<PrimitiveType>Array Family of Array Constructors">
4395 <caption>New<PrimitiveType>Array Family of Array Constructors</caption>
4396 <thead>
4397 <tr>
4398 <th>
4399
4400 New<PrimitiveType>Array Routines
4401 </th>
4402 <th>
4403 Index
4404 </th>
4405 </tr>
4406 </thead>
4407 <tbody>
4408 <tr>
4409 <td>
4410 <code class=
4411 "cCode">NewBooleanArray()</code>
4412 </td>
4413 <td>
4414 175
4415 </td>
4416 </tr>
4417 <tr>
4418 <td>
4419 <code class=
4420 "cCode">NewByteArray()</code>
4421 </td>
4422 <td>
4423 176
4424 </td>
4425 </tr>
4426 <tr>
4427 <td>
4428 <code class=
4429 "cCode">NewCharArray()</code>
4430 </td>
4431 <td>
4432 177
4433 </td>
4434 </tr>
4435 <tr>
4436 <td>
4437 <code class=
4438 "cCode">NewShortArray()</code>
4439 </td>
4440 <td>
4441 178
4442 </td>
4443 </tr>
4444 <tr>
4445 <td>
4446 <code class=
4447 "cCode">NewIntArray()</code>
4448 </td>
4449 <td>
4450 179
4451 </td>
4452 </tr>
4453 <tr>
4454 <td>
4455 <code class=
4456 "cCode">NewLongArray()</code>
4457 </td>
4458 <td>
4459 180
4460 </td>
4461 </tr>
4462 <tr>
4463 <td>
4464 <code class=
4465 "cCode">NewFloatArray()</code>
4466 </td>
4467 <td>
4468 181
4469 </td>
4470 </tr>
4471 <tr>
4472 <td>
4473 <code class=
4474 "cCode">NewDoubleArray()</code>
4475 </td>
4476 <td>
4477 182
4478 </td>
4479 </tr>
4480 </tbody>
4481 </table>
4482 <h4>PARAMETERS:</h4>
4483
4484 <p><code>env</code>: the JNI interface
4485 pointer.</p>
4486
4487 <p><code>length</code>: the array
4488 length.</p>
4489
4490 <h4>RETURNS:</h4>
4491
4492 <p>Returns a Java array, or <code class=
4493 "cCode">NULL</code> if the array cannot be constructed.</p>
4494
4495 <h3><a name="Get_PrimitiveType_ArrayElements_routines">Get<PrimitiveType>ArrayElements Routines</a></h3>
4496
4497 <p><em>NativeType</em> <code class=
4498 "cCode">*</code><em class=
4499 "cEmphasis">Get<PrimitiveType>ArrayElements</em><code style=
4500 "font-style: normal;">(JNIEnv *env,<br /></code>
4501 <code style="font-style: italic;">ArrayType</code>
4502 <code>array, jboolean *isCopy);</code></p>
4503
4504 <p>A family of functions that returns the body of the
4505 primitive array. The result is valid until the corresponding
4506 <em style="font-style: italic;" class=
4507 "cEmphasis">Release</em><code style="font-style: italic;" class=
4508 "cCode"><</code><em style="font-style: italic;" class=
4509 "cEmphasis">PrimitiveType</em><code style="font-style: italic;"
4510 class="cCode">></code><em>ArrayElements()</em>
4511 function is called. S<em>ince the returned array
4512 may be a copy of the Java array, changes made to the returned array
4513 will not necessarily be reflected in the original</em> <code style=
4514 "font-style: normal;">array</code> <em style=
4515 "font-style: italic;">until</em> <code style=
4516 "font-style: italic;" class=
4517 "cCode">Release<PrimitiveType>ArrayElements()</code>
4518 <em>is called.</em></p>
4519
4520 <p>If <code>isCopy</code> is not
4521 <code>NULL</code>, then <code class=
4522 "cCode">*isCopy</code> is set to <code class=
4523 "cCode">JNI_TRUE</code> if a copy is made; or it is set to
4524 <code>JNI_FALSE</code> if no copy is made.</p>
4525
4526 <p>The following table describes the specific
4527 primitive array element accessors. You should make the following
4528 substitutions:</p>
4529
4530
4531 <ul>
4532 <li>Replace <em class=
4533 "cEmphasis">Get<PrimitiveType>ArrayElements</em> with one of
4534 the actual primitive element accessor routine names from the following
4535 table.</li>
4536 <li>Replace ArrayType with the corresponding array type.</li>
4537 <li>Replace <em>NativeType</em> with the
4538 corresponding native type for that routine.</li>
4539 </ul>
4540
4541
4542
4543 <p>Regardless of how boolean arrays are represented
4544 in the Java VM, <code class=
4545 "cCode">GetBooleanArrayElements()</code> always returns a pointer
4546 to <code>jbooleans</code>, with each byte denoting an
4547 element (the unpacked representation). All arrays of other types
4548 are guaranteed to be contiguous in memory.</p>
4549
4550
4551 <table border="1" summary=
4552 "Get<PrimitiveType>ArrayElements Family of Accessor Routines">
4553 <caption>Get<PrimitiveType>ArrayElements Family of Accessor
4554 Routines</caption>
4555 <thead>
4556 <tr>
4557 <th>
4558
4559 Get<PrimitiveType>ArrayElements Routines
4560 </th>
4561 <th>
4562 Array Type
4563 </th>
4564 <th>
4565 Native Type
4566 </th>
4567 </tr>
4568 </thead>
4569 <tbody>
4570 <tr>
4571 <td>
4572 <code class=
4573 "cCode">GetBooleanArrayElements()</code>
4574 </td>
4575 <td>
4576 jbooleanArray
4577 </td>
4578 <td>
4579 jboolean
4580 </td>
4581 </tr>
4582 <tr>
4583 <td>
4584 <code class=
4585 "cCode">GetByteArrayElements()</code>
4586 </td>
4587 <td>
4588 jbyteArray
4589 </td>
4590 <td>
4591 jbyte
4592 </td>
4593 </tr>
4594 <tr>
4595 <td>
4596 <code class=
4597 "cCode">GetCharArrayElements()</code>
4598 </td>
4599 <td>
4600 jcharArray
4601 </td>
4602 <td>
4603 jchar
4604 </td>
4605 </tr>
4606 <tr>
4607 <td>
4608 <code class=
4609 "cCode">GetShortArrayElements()</code>
4610 </td>
4611 <td>
4612 jshortArray
4613 </td>
4614 <td>
4615 jshort
4616 </td>
4617 </tr>
4618 <tr>
4619 <td>
4620 <code class=
4621 "cCode">GetIntArrayElements()</code>
4622 </td>
4623 <td>
4624 jintArray
4625 </td>
4626 <td>
4627 jint
4628 </td>
4629 </tr>
4630 <tr>
4631 <td>
4632 <code class=
4633 "cCode">GetLongArrayElements()</code>
4634 </td>
4635 <td>
4636 jlongArray
4637 </td>
4638 <td>
4639 jlong
4640 </td>
4641 </tr>
4642 <tr>
4643 <td>
4644 <code class=
4645 "cCode">GetFloatArrayElements()</code>
4646 </td>
4647 <td>
4648 jfloatArray
4649 </td>
4650 <td>
4651 jfloat
4652 </td>
4653 </tr>
4654 <tr>
4655 <td>
4656 <code class=
4657 "cCode">GetDoubleArrayElements()</code>
4658 </td>
4659 <td>
4660 jdoubleArray
4661 </td>
4662 <td>
4663 jdouble
4664 </td>
4665 </tr>
4666 </tbody>
4667 </table>
4668
4669
4670
4671 <h4>LINKAGE:</h4>
4672 <p>Indices in the JNIEnv interface function table.</p>
4673 <table border="1" summary="Get<PrimitiveType>ArrayElements Family of Accessor Routines">
4674 <caption>Get<PrimitiveType>ArrayElements Family of Accessor
4675 Routines</caption>
4676 <thead>
4677 <tr>
4678 <th>
4679
4680 Get<PrimitiveType>ArrayElements Routines
4681 </th>
4682 <th>
4683 Index
4684 </th>
4685 </tr>
4686 </thead>
4687 <tbody>
4688 <tr>
4689 <td>
4690 <code class=
4691 "cCode">GetBooleanArrayElements()</code>
4692 </td>
4693 <td>
4694 183
4695 </td>
4696 </tr>
4697 <tr>
4698 <td>
4699 <code class=
4700 "cCode">GetByteArrayElements()</code>
4701 </td>
4702 <td>
4703 184
4704 </td>
4705 </tr>
4706 <tr>
4707 <td>
4708 <code class=
4709 "cCode">GetCharArrayElements()</code>
4710 </td>
4711 <td>
4712 185
4713 </td>
4714 </tr>
4715 <tr>
4716 <td>
4717 <code class=
4718 "cCode">GetShortArrayElements()</code>
4719 </td>
4720 <td>
4721 186
4722 </td>
4723 </tr>
4724 <tr>
4725 <td>
4726 <code class=
4727 "cCode">GetIntArrayElements()</code>
4728 </td>
4729 <td>
4730 187
4731 </td>
4732 </tr>
4733 <tr>
4734 <td>
4735 <code class=
4736 "cCode">GetLongArrayElements()</code>
4737 </td>
4738 <td>
4739 188
4740 </td>
4741 </tr>
4742 <tr>
4743 <td>
4744 <code class=
4745 "cCode">GetFloatArrayElements()</code>
4746 </td>
4747 <td>
4748 189
4749 </td>
4750 </tr>
4751 <tr>
4752 <td>
4753 <code class=
4754 "cCode">GetDoubleArrayElements()</code>
4755 </td>
4756 <td>
4757 190
4758 </td>
4759 </tr>
4760 </tbody>
4761 </table>
4762 <h4>PARAMETERS:</h4>
4763
4764 <p><code>env</code>: the JNI interface
4765 pointer.</p>
4766
4767 <p><code>array</code>: a Java string
4768 object.</p>
4769
4770 <p><code>isCopy</code>: a pointer to a
4771 boolean.</p>
4772
4773 <h4>RETURNS:</h4>
4774
4775 <p>Returns a pointer to the array elements, or
4776 <code>NULL</code> if the operation fails.</p>
4777
4778 <h3><a name="Release_PrimitiveType_ArrayElements_routines">Release<PrimitiveType>ArrayElements Routines</a></h3>
4779
4780 <p><code>void</code> <em class=
4781 "cEmphasis">Release<PrimitiveType>ArrayElements</em><code style="font-style: normal;"
4782 class="cCode">(JNIEnv *env,<br /></code> <code style=
4783 "font-style: italic;">ArrayType</code> <code class=
4784 "cCode">array,</code> <em>NativeType</em>
4785 <code>*elems, jint mode);</code></p>
4786
4787 <p>A family of functions that informs the VM that the
4788 native code no longer needs access to <code class=
4789 "cCode">elems</code>. The <code>elems</code> argument
4790 is a pointer derived from <code>array</code> using
4791 the corresponding <em>Get</em><code class=
4792 "cCode"><</code><em class=
4793 "cEmphasis">PrimitiveType</em><code class=
4794 "cCode">></code><em>ArrayElements()</em>
4795 function. If necessary, this function copies back all changes made
4796 to <code>elems</code> to the original array.</p>
4797
4798 <p>The <code>mode</code> argument
4799 provides information on how the array buffer should be released.
4800 <code>mode</code> has no effect if <code class=
4801 "cCode">elems</code> is not a copy of the elements in <code class=
4802 "cCode">array</code>. Otherwise, <code>mode</code>
4803 has the following impact, as shown in the following table:</p>
4804
4805 <table border="1" summary=
4806 "Primitive Array Release Modes">
4807 <caption>Primitive Array Release
4808 Modes</caption>
4809 <thead>
4810 <tr>
4811 <th>
4812 mode
4813 </th>
4814 <th>
4815 actions
4816 </th>
4817 </tr>
4818 </thead>
4819 <tbody>
4820 <tr>
4821 <td>
4822 <code>0</code>
4823 </td>
4824 <td>
4825 copy back the content and free the
4826 <code>elems</code> buffer
4827 </td>
4828 </tr>
4829 <tr>
4830 <td>
4831 <code>JNI_COMMIT</code>
4832 </td>
4833 <td>
4834 copy back the content but do not free the
4835 <code>elems</code> buffer
4836 </td>
4837 </tr>
4838 <tr>
4839 <td>
4840 <code>JNI_ABORT</code>
4841 </td>
4842 <td>
4843 free the buffer without copying back the
4844 possible changes
4845 </td>
4846 </tr>
4847 </tbody>
4848 </table>
4849
4850
4851
4852 <p>In most cases, programmers pass “0” to
4853 the <code>mode</code> argument to ensure consistent
4854 behavior for both pinned and copied arrays. The other options give
4855 the programmer more control over memory management and should be
4856 used with extreme care.</p>
4857
4858 <p>The next table describes the specific routines
4859 that comprise the family of primitive array disposers. You should
4860 make the following substitutions:</p>
4861
4862
4863 <ul>
4864 <li>Replace <em>Release<PrimitiveType>ArrayElements</em> with one
4865 of the actual primitive array disposer routine names from the following table.</li>
4866 <li>Replace ArrayType with the corresponding array type.</li>
4867 <li>Replace <em>NativeType</em> with the
4868 corresponding native type for that routine.</li>
4869 </ul>
4870
4871 <table border="1" summary=
4872 "Release<PrimitiveType>ArrayElements Family of Array Routines">
4873 <caption>Release<PrimitiveType>ArrayElements Family of Array
4874 Routines</caption>
4875 <thead>
4876 <tr>
4877 <th>
4878
4879 Release<PrimitiveType>ArrayElements Routines
4880 </th>
4881 <th>
4882 Array Type
4883 </th>
4884 <th>
4885 Native Type
4886 </th>
4887 </tr>
4888 </thead>
4889 <tbody>
4890 <tr>
4891 <td>
4892 <code class=
4893 "cCode">ReleaseBooleanArrayElements()</code>
4894 </td>
4895 <td>
4896 jbooleanArray
4897 </td>
4898 <td>
4899 jboolean
4900 </td>
4901 </tr>
4902 <tr>
4903 <td>
4904 <code class=
4905 "cCode">ReleaseByteArrayElements()</code>
4906 </td>
4907 <td>
4908 jbyteArray
4909 </td>
4910 <td>
4911 jbyte
4912 </td>
4913 </tr>
4914 <tr>
4915 <td>
4916 <code class=
4917 "cCode">ReleaseCharArrayElements()</code>
4918 </td>
4919 <td>
4920 jcharArray
4921 </td>
4922 <td>
4923 jchar
4924 </td>
4925 </tr>
4926 <tr>
4927 <td>
4928 <code class=
4929 "cCode">ReleaseShortArrayElements()</code>
4930 </td>
4931 <td>
4932 jshortArray
4933 </td>
4934 <td>
4935 jshort
4936 </td>
4937 </tr>
4938 <tr>
4939 <td>
4940 <code class=
4941 "cCode">ReleaseIntArrayElements()</code>
4942 </td>
4943 <td>
4944 jintArray
4945 </td>
4946 <td>
4947 jint
4948 </td>
4949 </tr>
4950 <tr>
4951 <td>
4952 <code class=
4953 "cCode">ReleaseLongArrayElements()</code>
4954 </td>
4955 <td>
4956 jlongArray
4957 </td>
4958 <td>
4959 jlong
4960 </td>
4961 </tr>
4962 <tr>
4963 <td>
4964 <code class=
4965 "cCode">ReleaseFloatArrayElements()</code>
4966 </td>
4967 <td>
4968 jfloatArray
4969 </td>
4970 <td>
4971 jfloat
4972 </td>
4973 </tr>
4974 <tr>
4975 <td>
4976 <code class=
4977 "cCode">ReleaseDoubleArrayElements()</code>
4978 </td>
4979 <td>
4980 jdoubleArray
4981 </td>
4982 <td>
4983 jdouble
4984 </td>
4985 </tr>
4986 </tbody>
4987 </table>
4988
4989
4990
4991 <h4>LINKAGE:</h4>
4992 <p>Indices in the JNIEnv interface function table.</p>
4993 <table border="1" summary="Release<PrimitiveType>ArrayElements Family of Array Routines">
4994 <caption>Release<PrimitiveType>ArrayElements Family of Array
4995 Routines</caption>
4996 <thead>
4997 <tr>
4998 <th>
4999
5000 Release<PrimitiveType>ArrayElements Routines
5001 </th>
5002 <th>
5003 Index
5004 </th>
5005 </tr>
5006 </thead>
5007 <tbody>
5008 <tr>
5009 <td>
5010 <code class=
5011 "cCode">ReleaseBooleanArrayElements()</code>
5012 </td>
5013 <td>
5014 191
5015 </td>
5016 </tr>
5017 <tr>
5018 <td>
5019 <code class=
5020 "cCode">ReleaseByteArrayElements()</code>
5021 </td>
5022 <td>
5023 192
5024 </td>
5025 </tr>
5026 <tr>
5027 <td>
5028 <code class=
5029 "cCode">ReleaseCharArrayElements()</code>
5030 </td>
5031 <td>
5032 193
5033 </td>
5034 </tr>
5035 <tr>
5036 <td>
5037 <code class=
5038 "cCode">ReleaseShortArrayElements()</code>
5039 </td>
5040 <td>
5041 194
5042 </td>
5043 </tr>
5044 <tr>
5045 <td>
5046 <code class=
5047 "cCode">ReleaseIntArrayElements()</code>
5048 </td>
5049 <td>
5050 195
5051 </td>
5052 </tr>
5053 <tr>
5054 <td>
5055 <code class=
5056 "cCode">ReleaseLongArrayElements()</code>
5057 </td>
5058 <td>
5059 196
5060 </td>
5061 </tr>
5062 <tr>
5063 <td>
5064 <code class=
5065 "cCode">ReleaseFloatArrayElements()</code>
5066 </td>
5067 <td>
5068 197
5069 </td>
5070 </tr>
5071 <tr>
5072 <td>
5073 <code class=
5074 "cCode">ReleaseDoubleArrayElements()</code>
5075 </td>
5076 <td>
5077 198
5078 </td>
5079 </tr>
5080 </tbody>
5081 </table>
5082 <h4>PARAMETERS:</h4>
5083
5084 <p><code>env</code>: the JNI interface
5085 pointer.</p>
5086
5087 <p><code>array</code>: a Java array
5088 object.</p>
5089
5090 <p><code>elems</code>: a pointer to
5091 array elements.</p>
5092
5093 <p><code>mode</code>: the release
5094 mode.</p>
5095
5096 <h3><a name="Get_PrimitiveType_ArrayRegion_routines">Get<PrimitiveType>ArrayRegion Routines</a></h3>
5097
5098 <p><em>void</em> <em class=
5099 "cEmphasis">Get<PrimitiveType>ArrayRegion</em><code class=
5100 "cCode">(JNIEnv *env,</code> <em>ArrayType</em>
5101 <code>array,<br />
5102 jsize start, jsize len,</code> <em class=
5103 "cEmphasis">NativeType</em> <code>*buf);</code></p>
5104
5105 <p>A family of functions that copies a region of a
5106 primitive array into a buffer.</p>
5107
5108 <p>The following table describes the specific
5109 primitive array element accessors. You should do the following
5110 substitutions:</p>
5111
5112
5113 <ul>
5114 <li>Replace <em>Get<PrimitiveType>ArrayRegion</em> with one of
5115 the actual primitive element accessor routine names from the following table.</li>
5116 <li>Replace <em>ArrayType</em> with the
5117 corresponding array type.</li>
5118 <li>Replace <em>NativeType</em> with the
5119 corresponding native type for that routine.</li>
5120 </ul>
5121
5122
5123
5124
5125 <table border="1" summary="Get<PrimitiveType>ArrayRegion Family of Array Accessor Routines">
5126 <caption>Get<PrimitiveType>ArrayRegion Family of Array Accessor Routines</caption>
5127 <thead>
5128 <tr>
5129 <th>Get<PrimitiveType>ArrayRegion Routine</th>
5130 <th>Array Type</th>
5131 <th>Native Type</th>
5132 </tr>
5133 </thead>
5134 <tbody>
5135 <tr>
5136 <td><code>GetBooleanArrayRegion()</code></td>
5137 <td>jbooleanArray</td>
5138 <td>jboolean</td>
5139 </tr>
5140 <tr>
5141 <td><code>GetByteArrayRegion()</code>
5142 </td>
5143 <td>
5144 jbyteArray
5145 </td>
5146 <td>
5147 jbyte
5148 </td>
5149 </tr>
5150 <tr>
5151 <td>
5152 <code class=
5153 "cCode">GetCharArrayRegion()</code>
5154 </td>
5155 <td>
5156 jcharArray
5157 </td>
5158 <td>
5159 jchar
5160 </td>
5161 </tr>
5162 <tr>
5163 <td>
5164 <code class=
5165 "cCode">GetShortArrayRegion()</code>
5166 </td>
5167 <td>
5168 jshortArray
5169 </td>
5170 <td>
5171 jhort
5172 </td>
5173 </tr>
5174 <tr>
5175 <td>
5176 <code class=
5177 "cCode">GetIntArrayRegion()</code>
5178 </td>
5179 <td>
5180 jintArray
5181 </td>
5182 <td>
5183 jint
5184 </td>
5185 </tr>
5186 <tr>
5187 <td>
5188 <code class=
5189 "cCode">GetLongArrayRegion()</code>
5190 </td>
5191 <td>
5192 jlongArray
5193 </td>
5194 <td>
5195 jlong
5196 </td>
5197 </tr>
5198 <tr>
5199 <td>
5200 <code class=
5201 "cCode">GetFloatArrayRegion()</code>
5202 </td>
5203 <td>
5204 jfloatArray
5205 </td>
5206 <td>
5207 jloat
5208 </td>
5209 </tr>
5210 <tr>
5211 <td>
5212 <code class=
5213 "cCode">GetDoubleArrayRegion()</code>
5214 </td>
5215 <td>
5216 jdoubleArray
5217 </td>
5218 <td>
5219 jdouble
5220 </td>
5221 </tr>
5222 </tbody>
5223 </table>
5224
5225
5226
5227 <h4>LINKAGE:</h4>
5228 <p>Indices in the JNIEnv interface function table.</p>
5229 <table border="1" summary=
5230 "Get<PrimitiveType>ArrayRegion Family of Array Accessor Routines"
5231 >
5232 <caption>Get<PrimitiveType>ArrayRegion Family of Array Accessor
5233 Routines</caption>
5234 <thead>
5235 <tr>
5236 <th>
5237
5238 Get<PrimitiveType>ArrayRegion Routine
5239 </th>
5240 <th>
5241 Index
5242 </th>
5243 </tr>
5244 </thead>
5245 <tbody>
5246 <tr>
5247 <td>
5248 <code class=
5249 "cCode">GetBooleanArrayRegion()</code>
5250 </td>
5251 <td>
5252 199
5253 </td>
5254 </tr>
5255 <tr>
5256 <td>
5257 <code class=
5258 "cCode">GetByteArrayRegion()</code>
5259 </td>
5260 <td>
5261 200
5262 </td>
5263 </tr>
5264 <tr>
5265 <td>
5266 <code class=
5267 "cCode">GetCharArrayRegion()</code>
5268 </td>
5269 <td>
5270 201
5271 </td>
5272 </tr>
5273 <tr>
5274 <td>
5275 <code class=
5276 "cCode">GetShortArrayRegion()</code>
5277 </td>
5278 <td>
5279 202
5280 </td>
5281 </tr>
5282 <tr>
5283 <td>
5284 <code class=
5285 "cCode">GetIntArrayRegion()</code>
5286 </td>
5287 <td>
5288 203
5289 </td>
5290 </tr>
5291 <tr>
5292 <td>
5293 <code class=
5294 "cCode">GetLongArrayRegion()</code>
5295 </td>
5296 <td>
5297 204
5298 </td>
5299 </tr>
5300 <tr>
5301 <td>
5302 <code class=
5303 "cCode">GetFloatArrayRegion()</code>
5304 </td>
5305 <td>
5306 205
5307 </td>
5308 </tr>
5309 <tr>
5310 <td>
5311 <code class=
5312 "cCode">GetDoubleArrayRegion()</code>
5313 </td>
5314 <td>
5315 206
5316 </td>
5317 </tr>
5318 </tbody>
5319 </table>
5320 <h4>PARAMETERS:</h4>
5321
5322 <p><code>env</code>: the JNI interface
5323 pointer.</p>
5324
5325 <p><code>array</code>: a Java
5326 array.</p>
5327
5328 <p><code>start</code>: the starting
5329 index.</p>
5330
5331 <p><code>len</code>: the number of
5332 elements to be copied.</p>
5333
5334 <p><code>buf</code>: the destination
5335 buffer.</p>
5336
5337 <h4>THROWS:</h4>
5338
5339 <p><code class=
5340 "cCode">ArrayIndexOutOfBoundsException</code>: if one of the
5341 indexes in the region is not valid.</p>
5342
5343 <h3><a name="Set_PrimitiveType_ArrayRegion_routines">Set<PrimitiveType>ArrayRegion Routines</a></h3>
5344
5345 <p><code>void</code> <em class=
5346 "cEmphasis">Set<PrimitiveType>ArrayRegion</em><code class=
5347 "cCode">(JNIEnv *env,</code> <em>ArrayType</em>
5348 <code>array,<br />
5349 jsize start, jsize len,</code> const <em class=
5350 "cEmphasis">NativeType</em> <code>*buf);</code></p>
5351
5352 <p>A family of functions that copies back a region of
5353 a primitive array from a buffer.</p>
5354
5355 <p>The following table describes the specific
5356 primitive array element accessors. You should make the following
5357 replacements:</p>
5358
5359
5360 <ul>
5361 <li>Replace <em>Set<PrimitiveType>ArrayRegion</em> with one of the actual primitive element accessor routine names from the following table.</li>
5362 <li>Replace ArrayType with the corresponding array type.</li>
5363 <li>Replace <em>NativeType</em> with the corresponding native type for that routine.</li>
5364 </ul>
5365
5366 <table border="1" summary=
5367 "Set<PrimitiveType>ArrayRegion Family of Array Accessor Routines"
5368 >
5369 <caption>Set<PrimitiveType>ArrayRegion Family of Array Accessor
5370 Routines</caption>
5371 <thead>
5372 <tr>
5373 <th>
5374
5375 Set<PrimitiveType>ArrayRegion Routine
5376 </th>
5377 <th>
5378 Array Type
5379 </th>
5380 <th>
5381 Native Type
5382 </th>
5383 </tr>
5384 </thead>
5385 <tbody>
5386 <tr>
5387 <td>
5388 <code class=
5389 "cCode">SetBooleanArrayRegion()</code>
5390 </td>
5391 <td>
5392 jbooleanArray
5393 </td>
5394 <td>
5395 jboolean
5396 </td>
5397 </tr>
5398 <tr>
5399 <td>
5400 <code class=
5401 "cCode">SetByteArrayRegion()</code>
5402 </td>
5403 <td>
5404 jbyteArray
5405 </td>
5406 <td>
5407 jbyte
5408 </td>
5409 </tr>
5410 <tr>
5411 <td>
5412 <code class=
5413 "cCode">SetCharArrayRegion()</code>
5414 </td>
5415 <td>
5416 jcharArray
5417 </td>
5418 <td>
5419 jchar
5420 </td>
5421 </tr>
5422 <tr>
5423 <td>
5424 <code class=
5425 "cCode">SetShortArrayRegion()</code>
5426 </td>
5427 <td>
5428 jshortArray
5429 </td>
5430 <td>
5431 jshort
5432 </td>
5433 </tr>
5434 <tr>
5435 <td>
5436 <code class=
5437 "cCode">SetIntArrayRegion()</code>
5438 </td>
5439 <td>
5440 jintArray
5441 </td>
5442 <td>
5443 jint
5444 </td>
5445 </tr>
5446 <tr>
5447 <td>
5448 <code class=
5449 "cCode">SetLongArrayRegion()</code>
5450 </td>
5451 <td>
5452 jlongArray
5453 </td>
5454 <td>
5455 jlong
5456 </td>
5457 </tr>
5458 <tr>
5459 <td>
5460 <code class=
5461 "cCode">SetFloatArrayRegion()</code>
5462 </td>
5463 <td>
5464 jfloatArray
5465 </td>
5466 <td>
5467 jfloat
5468 </td>
5469 </tr>
5470 <tr>
5471 <td>
5472 <code class=
5473 "cCode">SetDoubleArrayRegion()</code>
5474 </td>
5475 <td>
5476 jdoubleArray
5477 </td>
5478 <td>
5479 jdouble
5480 </td>
5481 </tr>
5482 </tbody>
5483 </table>
5484
5485 <h4>LINKAGE:</h4>
5486 <p>Indices in the JNIEnv interface function table.</p>
5487
5488 <table border="1" summary=
5489 "Set<PrimitiveType>ArrayRegion Family of Array Accessor Routines"
5490 >
5491 <caption>Set<PrimitiveType>ArrayRegion Family of Array Accessor Routines</caption>
5492 <thead>
5493 <tr>
5494 <th>
5495
5496 Set<PrimitiveType>ArrayRegion Routine
5497 </th>
5498 <th>
5499 Index
5500 </th>
5501 </tr>
5502 </thead>
5503 <tbody>
5504 <tr>
5505 <td>
5506 <code class=
5507 "cCode">SetBooleanArrayRegion()</code>
5508 </td>
5509 <td>
5510 207
5511 </td>
5512 </tr>
5513 <tr>
5514 <td>
5515 <code class=
5516 "cCode">SetByteArrayRegion()</code>
5517 </td>
5518 <td>
5519 208
5520 </td>
5521 </tr>
5522 <tr>
5523 <td>
5524 <code class=
5525 "cCode">SetCharArrayRegion()</code>
5526 </td>
5527 <td>
5528 209
5529 </td>
5530 </tr>
5531 <tr>
5532 <td>
5533 <code class=
5534 "cCode">SetShortArrayRegion()</code>
5535 </td>
5536 <td>
5537 210
5538 </td>
5539 </tr>
5540 <tr>
5541 <td>
5542 <code class=
5543 "cCode">SetIntArrayRegion()</code>
5544 </td>
5545 <td>
5546 211
5547 </td>
5548 </tr>
5549 <tr>
5550 <td>
5551 <code class=
5552 "cCode">SetLongArrayRegion()</code>
5553 </td>
5554 <td>
5555 212
5556 </td>
5557 </tr>
5558 <tr>
5559 <td>
5560 <code class=
5561 "cCode">SetFloatArrayRegion()</code>
5562 </td>
5563 <td>
5564 213
5565 </td>
5566 </tr>
5567 <tr>
5568 <td>
5569 <code class=
5570 "cCode">SetDoubleArrayRegion()</code>
5571 </td>
5572 <td>
5573 214
5574 </td>
5575 </tr>
5576 </tbody>
5577 </table>
5578 <p>PARAMETERS:</p>
5579
5580 <p><code>env</code>: the JNI interface
5581 pointer.</p>
5582
5583 <p><code>array</code>: a Java
5584 array.</p>
5585
5586 <p><code>start</code>: the starting
5587 index.</p>
5588 <p><code>len</code>: the number of
5589 elements to be copied.</p>
5590
5591 <p><code>buf</code>: the source
5592 buffer.</p>
5593
5594 <h4>THROWS:</h4>
5595
5596 <p><code class=
5597 "cCode">ArrayIndexOutOfBoundsException</code>: if one of the
5598 indexes in the region is not valid.</p>
5599
5600 <table width="80%" border="1" cellpadding="5"
5601 cellspacing="0" summary="">
5602 <tbody>
5603 <tr>
5604 <td bgcolor="#FFFFCC">
5605
5606 <p><strong>Note</strong>: As of JDK/JRE 1.1, programmers can use
5607 <code>Get/Release<primitivetype>ArrayElements</code>
5608 functions to obtain a pointer to primitive array elements. If the
5609 VM supports pinning, the pointer to the original data is returned;
5610 otherwise, a copy is made.</p>
5611 <p>New functions introduced as of JDK/JRE 1.3 allow native code to
5612 obtain a direct pointer to array elements even if the VM does not
5613 support pinning.</p>
5614 </td>
5615 </tr>
5616 </tbody>
5617 </table>
5618 <h3><a name="GetPrimitiveArrayCritical_ReleasePrimitiveArrayCritical">GetPrimitiveArrayCritical, ReleasePrimitiveArrayCritical</a></h3>
5619 <p><code>void * GetPrimitiveArrayCritical(JNIEnv *env, jarray
5620 array, jboolean *isCopy);<br />
5621 <a name="ReleasePrimitiveArrayCritical" id=
5622 "ReleasePrimitiveArrayCritical"></a> void
5623 ReleasePrimitiveArrayCritical(JNIEnv *env, jarray array, void
5624 *carray, jint mode);</code></p>
5625 <p>The semantics of these two functions are very similar to the
5626 existing <code>Get/Release<primitivetype>ArrayElements</code>
5627 functions. If possible, the VM returns a pointer to the primitive
5628 array; otherwise, a copy is made. <strong>However, there are
5629 significant restrictions on how these functions can be
5630 used.</strong></p>
5631 <p>After calling <code>GetPrimitiveArrayCritical</code>, the native
5632 code should not run for an extended period of time before it calls
5633 <code>ReleasePrimitiveArrayCritical</code>. We must treat the code
5634 inside this pair of functions as running in a "critical region."
5635 Inside a critical region, native code must not call other JNI
5636 functions, or any system call that may cause the current thread to
5637 block and wait for another Java thread. (For example, the current
5638 thread must not call <code>read</code> on a stream being written by
5639 another Java thread.)</p>
5640 <p><strong>These restrictions make it more likely that the native
5641 code will obtain an uncopied version of the array, even if the VM
5642 does not support pinning.</strong> For example, a VM may
5643 temporarily disable garbage collection when the native code is
5644 holding a pointer to an array obtained via
5645 <code>GetPrimitiveArrayCritical</code>.</p>
5646 <p>Multiple pairs of <code>GetPrimtiveArrayCritical</code> and
5647 <code>ReleasePrimitiveArrayCritical</code> may be nested. For
5648 example:</p>
5649 <pre class="codeblock">
5650 jint len = (*env)->GetArrayLength(env, arr1);
5651 jbyte *a1 = (*env)->GetPrimitiveArrayCritical(env, arr1, 0);
5652 jbyte *a2 = (*env)->GetPrimitiveArrayCritical(env, arr2, 0);
5653 /* We need to check in case the VM tried to make a copy. */
5654 if (a1 == NULL || a2 == NULL) {
5655 ... /* out of memory exception thrown */
5656 }
5657 memcpy(a1, a2, len);
5658 (*env)->ReleasePrimitiveArrayCritical(env, arr2, a2, 0);
5659 (*env)->ReleasePrimitiveArrayCritical(env, arr1, a1, 0);
5660 </pre>
5661 <p>Note that <code>GetPrimitiveArrayCritical</code> might still
5662 make a copy of the array if the VM internally represents arrays in
5663 a different format. Therefore we need to check its return value
5664 against <code>NULL</code> for possible out of memory situations.
5665 <a name="stringops"></a></p>
5666 <h4>LINKAGE (GetPrimitiveArrayCritical):</h4>
5667 <p>Linkage Index 222 in the JNIEnv interface
5668 function table.</p>
5669 <h4>LINKAGE (ReleasePrimitiveArrayCritical):</h4>
5670 <p>Linkage Index 223 in the JNIEnv interface
5671 function table.</p>
5672 <h4>SINCE:</h4>
5673 <p>JDK/JRE 1.2</p>
5674 <!-- ******************************************************** -->
5675 <h2><a name="registering_native_methods">Registering Native Methods</a></h2>
5676
5677 <h3><a name="RegisterNatives">RegisterNatives</a></h3>
5678
5679 <p><code>jint RegisterNatives(JNIEnv
5680 *env, jclass clazz,<br />
5681 const JNINativeMethod *methods, jint nMethods);</code></p>
5682
5683 <p>Registers native methods with the class specified
5684 by the <code>clazz</code> argument. The <code class=
5685 "cCode">methods</code> parameter specifies an array of <code class=
5686 "cCode">JNINativeMethod</code> structures that contain the names,
5687 signatures, and function pointers of the native methods. The
5688 <code>name</code> and <code class=
5689 "cCode">signature</code> fields of the JNINativeMethod structure
5690 are pointers to modified UTF-8 strings. The <code class=
5691 "cCode">nMethods</code> parameter specifies the number of native
5692 methods in the array. The <code class=
5693 "cCode">JNINativeMethod</code> structure is defined as follows:</p>
5694
5695 <pre class="codeblock">
5696 typedef struct {
5697
5698 char *name;
5699
5700 char *signature;
5701
5702 void *fnPtr;
5703
5704 } JNINativeMethod;
5705
5706 </pre>
5707
5708 <p>The function pointers nominally must have the
5709 following signature:</p>
5710
5711 <pre class="codeblock">
5712 <code class=
5713 "cCode">ReturnType (*fnPtr)(JNIEnv *env, jobject objectOrClass, ...);</code>
5714
5715 </pre>
5716
5717 <h4>LINKAGE:</h4>
5718 <p>Index 215 in the JNIEnv interface function
5719 table.</p>
5720 <h4>PARAMETERS:</h4>
5721
5722 <p><code>env</code>: the JNI interface
5723 pointer.</p>
5724
5725 <p><code>clazz</code>: a Java class
5726 object.</p>
5727
5728 <p><code>methods</code>: the native
5729 methods in the class.</p>
5730
5731 <p><code>nMethods</code>: the number of
5732 native methods in the class.</p>
5733
5734 <h4>RETURNS:</h4>
5735
5736 <p>Returns “0” on success; returns a
5737 negative value on failure.</p>
5738
5739 <h4>THROWS:</h4>
5740
5741 <p><code>NoSuchMethodError</code>: if a
5742 specified method cannot be found or if the method is not
5743 native.</p>
5744
5745 <h3><a name="UnregisterNatives">UnregisterNatives</a></h3>
5746
5747 <p><code>jint UnregisterNatives(JNIEnv
5748 *env, jclass clazz);</code></p>
5749
5750 <p>Unregisters native methods of a class. The class
5751 goes back to the state before it was linked or registered with its
5752 native method functions.</p>
5753
5754 <p>This function should not be used in normal native
5755 code. Instead, it provides special programs a way to reload and
5756 relink native libraries.</p>
5757
5758 <h4>LINKAGE:</h4>
5759 Index 216 in the JNIEnv interface function table.
5760 <h4>PARAMETERS:</h4>
5761
5762 <p><code>env</code>: the JNI interface
5763 pointer.</p>
5764
5765 <p><code>clazz</code>: a Java class
5766 object.</p>
5767
5768 <h4>RETURNS:</h4>
5769
5770 <p>Returns “0” on success; returns a
5771 negative value on failure.</p>
5772
5773 <!-- ******************************************************** -->
5774 <h2><a name="monitor_operations">Monitor Operations</a></h2>
5775
5776 <h3><a name="MonitorEnter">MonitorEnter</a></h3>
5777
5778 <p><code>jint MonitorEnter(JNIEnv *env,
5779 jobject obj);</code></p>
5780
5781 <p>Enters the monitor associated with the underlying
5782 Java object referred to by <code>obj</code>.</p>
5783 Enters the monitor associated with the object referred to by obj.
5784 The <code>obj</code> reference must not be <code>NULL</code>.
5785 <p>Each Java object has a monitor associated with it.
5786 If the current thread already owns the monitor associated with
5787 <code>obj</code>, it increments a counter in the
5788 monitor indicating the number of times this thread has entered the
5789 monitor. If the monitor associated with <code class=
5790 "cCode">obj</code> is not owned by any thread, the current thread
5791 becomes the owner of the monitor, setting the entry count of this
5792 monitor to 1. If another thread already owns the monitor associated
5793 with <code>obj</code>, the current thread waits until
5794 the monitor is released, then tries again to gain ownership.</p>
5795 <p>A monitor entered through a <code>MonitorEnter</code> JNI
5796 function call cannot be exited using the <code>monitorexit</code>
5797 Java virtual machine instruction or a synchronized method return. A
5798 <code>MonitorEnter</code> JNI function call and a
5799 <code>monitorenter</code> Java virtual machine instruction may race
5800 to enter the monitor associated with the same object.</p>
5801 <p>To avoid deadlocks, a monitor entered through a
5802 <code>MonitorEnter</code> JNI function call must be exited using
5803 the <code>MonitorExit</code> JNI call, unless the
5804 <code>DetachCurrentThread</code> call is used to implicitly release
5805 JNI monitors.</p>
5806
5807 <h4>LINKAGE:</h4>
5808 Index 217 in the JNIEnv interface function table.
5809 <h4>PARAMETERS:</h4>
5810
5811 <p><code>env</code>: the JNI interface
5812 pointer.</p>
5813
5814 <p><code>obj</code>: a normal Java
5815 object or class object.</p>
5816
5817 <h4>RETURNS:</h4>
5818
5819 <p>Returns “0” on success; returns a
5820 negative value on failure.</p>
5821
5822 <h3><a name="MonitorExit">MonitorExit</a></h3>
5823
5824 <p><code>jint MonitorExit(JNIEnv *env,
5825 jobject obj);</code></p>
5826
5827 <p>The current thread must be the owner of the
5828 monitor associated with the underlying Java object referred to by
5829 <code>obj</code>. The thread decrements the counter
5830 indicating the number of times it has entered this monitor. If the
5831 value of the counter becomes zero, the current thread releases the
5832 monitor.</p>
5833 <p>Native code must not use <code>MonitorExit</code> to exit a
5834 monitor entered through a synchronized method or a
5835 <code>monitorenter</code> Java virtual machine instruction.</p>
5836
5837 <h4>LINKAGE:</h4>
5838 Index 218 in the JNIEnv interface function table.
5839 <h4>PARAMETERS:</h4>
5840
5841 <p><code>env</code>: the JNI interface
5842 pointer.</p>
5843
5844 <p><code>obj</code>: a normal Java
5845 object or class object.</p>
5846
5847 <h4>RETURNS:</h4>
5848
5849 <p>Returns “0” on success; returns a
5850 negative value on failure.</p>
5851
5852 <h4>EXCEPTIONS:</h4>
5853
5854 <p><code>IllegalMonitorStateException</code>: if the
5855 current thread does not own the monitor.</p>
5856
5857 <!-- ******************************************************** -->
5858 <h2><a name="nio_support">NIO Support</a></h2>
5859 <p>The NIO-related entry points allow native code to access
5860 <code>java.nio</code> <em>direct buffers</em>. The contents of a
5861 direct buffer can, potentially, reside in native memory outside of
5862 the ordinary garbage-collected heap. For information about direct
5863 buffers, please see <a href="../../io/index.html">New I/O APIs</a>
5864 and the specification of the <a href=
5865 "../../../../api/java/nio/ByteBuffer.html"><tt>java.nio.ByteBuffer</tt></a>
5866 class.</p>
5867 Three new functions introduced in JDK/JRE 1.4 allow JNI code to
5868 create, examine, and manipulate direct buffers:
5869 <ul>
5870 <li><a href=
5871 "#NewDirectByteBuffer"><code>NewDirectByteBuffer</code></a></li>
5872 <li><a href=
5873 "#GetDirectBufferAddress"><code>GetDirectBufferAddress</code></a></li>
5874 <li><a href=
5875 "#GetDirectBufferCapacity"><code>GetDirectBufferCapacity</code></a></li>
5876 </ul>
5877 <p>Every implementation of the Java virtual machine must support
5878 these functions, but not every implementation is required to
5879 support JNI access to direct buffers. If a JVM does not support
5880 such access then the <tt>NewDirectByteBuffer</tt> and
5881 <tt>GetDirectBufferAddress</tt> functions must always return
5882 <tt>NULL</tt>, and the <tt>GetDirectBufferCapacity</tt> function
5883 must always return <tt>-1</tt>. If a JVM <em>does</em> support such
5884 access then these three functions must be implemented to return the
5885 appropriate values.</p>
5886
5887 <h3><a name="NewDirectByteBuffer">NewDirectByteBuffer</a></h3>
5888
5889 <p><tt>jobject NewDirectByteBuffer(JNIEnv* env, void* address,
5890 jlong capacity);</tt></p>
5891 <p>Allocates and returns a direct <tt>java.nio.ByteBuffer</tt>
5892 referring to the block of memory starting at the memory address
5893 <tt>address</tt> and extending <tt>capacity</tt> bytes.</p>
5894 <p>Native code that calls this function and returns the resulting
5895 byte-buffer object to Java-level code should ensure that the buffer
5896 refers to a valid region of memory that is accessible for reading
5897 and, if appropriate, writing. An attempt to access an invalid
5898 memory location from Java code will either return an arbitrary
5899 value, have no visible effect, or cause an unspecified exception to
5900 be thrown.</p>
5901 <h4>LINKAGE:</h4>
5902 <p>Index 229 in the JNIEnv interface function
5903 table.</p>
5904 <h4>PARAMETERS:</h4>
5905 <p><tt>env</tt>: the <tt>JNIEnv</tt> interface pointer</p>
5906 <p><tt>address</tt>: the starting address of the memory region
5907 (must not be <tt>NULL</tt>)</p>
5908 <p><tt>capacity</tt>: the size in bytes of the memory region (must
5909 be positive)</p>
5910 <h4>RETURNS:</h4>
5911 <p>Returns a local reference to the newly-instantiated
5912 <tt>java.nio.ByteBuffer</tt> object. Returns <tt>NULL</tt> if an
5913 exception occurs, or if JNI access to direct buffers is not
5914 supported by this virtual machine.</p>
5915 <h4>EXCEPTIONS:</h4>
5916 <p><tt>OutOfMemoryError</tt>: if allocation of the
5917 <tt>ByteBuffer</tt> object fails</p>
5918 <h4>SINCE:</h4>
5919 <p>JDK/JRE 1.4</p>
5920
5921 <h3><a name="GetDirectBufferAddress">GetDirectBufferAddress</a></h3>
5922 <p><tt>void* GetDirectBufferAddress(JNIEnv* env, jobject
5923 buf);</tt></p>
5924
5925
5926 <p>Fetches and returns the starting address of the memory region
5927 referenced by the given direct <tt>java.nio.Buffer</tt>.</p>
5928 <p>This function allows native code to access the same memory
5929 region that is accessible to Java code via the buffer object.</p>
5930 <h4>LINKAGE:</h4>
5931 <p>Index 230 in the JNIEnv interface function table.</p>
5932
5933
5934 <h4>PARAMETERS:</h4>
5935
5936
5937 <p><tt>env</tt>: the <tt>JNIEnv</tt> interface pointer</p>
5938 <p><tt>buf</tt>: a direct <tt>java.nio.Buffer</tt> object (must not
5939 be <tt>NULL</tt>)</p>
5940
5941
5942 <h4>RETURNS:</h4>
5943
5944
5945 <p>Returns the starting address of the memory region referenced by
5946 the buffer. Returns <tt>NULL</tt> if the memory region is
5947 undefined, if the given object is not a direct
5948 <tt>java.nio.Buffer</tt>, or if JNI access to direct buffers is not
5949 supported by this virtual machine.</p>
5950 <h4>SINCE:</h4>
5951 <p>JDK/JRE 1.4</p>
5952
5953 <h3><a name="GetDirectBufferCapacity">GetDirectBufferCapacity</a></h3>
5954 <p><tt>jlong GetDirectBufferCapacity(JNIEnv* env, jobject
5955 buf);</tt></p>
5956 <p>Fetches and returns the capacity of the memory region referenced
5957 by the given direct <tt>java.nio.Buffer</tt>. The capacity is the
5958 number of <i>elements</i> that the memory region contains.</p>
5959 <h4>LINKAGE:</h4>
5960 <p>Index 231 in the JNIEnv interface function
5961 table.</p>
5962
5963
5964 <h4>PARAMETERS:</h4>
5965
5966
5967 <p><tt>env</tt>: the <tt>JNIEnv</tt> interface pointer</p>
5968 <p><tt>buf</tt>: a direct <tt>java.nio.Buffer</tt> object (must not
5969 be <tt>NULL</tt>)</p>
5970
5971
5972 <h4>RETURNS:</h4>
5973
5974
5975 <p>Returns the capacity of the memory region associated with the
5976 buffer. Returns <tt>-1</tt> if the given object is not a direct
5977 <tt>java.nio.Buffer</tt>, if the object is an unaligned view buffer
5978 and the processor architecture does not support unaligned access,
5979 or if JNI access to direct buffers is not supported by this virtual
5980 machine.</p>
5981 <h4>SINCE:</h4>
5982 <p>JDK/JRE 1.4</p>
5983 <!-- ******************************************************** -->
5984 <h2><a name="reflection_support">Reflection Support</a></h2>
5985 <p>Programmers can use the JNI to call Java methods or access Java
5986 fields if they know the name and type of the methods or fields. The
5987 Java Core Reflection API allows programmers to introspect Java
5988 classes at runtime. JNI provides a set of conversion functions
5989 between field and method IDs used in the JNI to field and method
5990 objects used in the Java Core Reflection API.</p>
5991
5992 <h3><a name="FromReflectedMethod">FromReflectedMethod</a></h3>
5993 <p><code>jmethodID FromReflectedMethod(JNIEnv *env, jobject
5994 method);</code></p>
5995 <p>Converts a <code>java.lang.reflect.Method</code> or
5996 <code>java.lang.reflect.Constructor</code> object to a method
5997 ID.</p>
5998 <h4>LINKAGE:</h4>
5999 <p>Index 7 in the JNIEnv interface function
6000 table.</p>
6001 <h4>SINCE:</h4>
6002 <p>JDK/JRE 1.2</p>
6003 <h3><a name="FromReflectedField">FromReflectedField</a></h3>
6004 <p><code>jfieldID FromReflectedField(JNIEnv *env, jobject
6005 field);</code></p>
6006 <p>Converts a <code>java.lang.reflect.Field</code> to a field
6007 ID.</p>
6008 <h4>LINKAGE:</h4>
6009 <p>Index 8 in the JNIEnv interface function table.</p>
6010 <h4>SINCE:</h4>
6011 <p>JDK/JRE 1.2</p>
6012 <h3><a name="ToReflectedMethod">ToReflectedMethod</a></h3>
6013 <p><code>jobject ToReflectedMethod(JNIEnv *env, jclass cls,<br />
6014 jmethodID methodID, jboolean isStatic);</code></p>
6015 <p>Converts a method ID derived from <code>cls</code> to a
6016 <code>java.lang.reflect.Method</code> or
6017 <code>java.lang.reflect.Constructor</code> object.
6018 <code>isStatic</code> must be set to <code class=
6019 "cCode">JNI_TRUE</code> if the method ID refers to a static field,
6020 and <code>JNI_FALSE</code> otherwise.</p>
6021 <p>Throws <code>OutOfMemoryError</code> and returns 0 if fails.</p>
6022 <h4>LINKAGE:</h4>
6023 <p>Index 9 in the JNIEnv interface function
6024 table.</p>
6025 <h4>SINCE:</h4>
6026 <p>JDK/JRE 1.2</p>
6027 <h3><a name="ToReflectedField">ToReflectedField</a></h3>
6028 <p><code>jobject ToReflectedField(JNIEnv *env, jclass cls,<br />
6029 jfieldID fieldID, jboolean isStatic);</code></p>
6030 <p>Converts a field ID derived from <code>cls</code> to a
6031 <code>java.lang.reflect.Field</code> object. <code>isStatic</code>
6032 must be set to <code>JNI_TRUE</code> if
6033 <code>fieldID</code> refers to a static field, and <code class=
6034 "cCode">JNI_FALSE</code> otherwise.</p>
6035 <p>Throws <code>OutOfMemoryError</code> and returns 0 if fails.</p>
6036 <h4>LINKAGE:</h4>
6037 <p>Index 12 in the JNIEnv interface function
6038 table.</p>
6039 <h4>SINCE:</h4>
6040 <p>JDK/JRE 1.2</p>
6041 <a name="invo"></a>
6042 <!-- ******************************************************** -->
6043 <h2><a name="java_vm_interface">Java VM Interface</a></h2>
6044
6045 <h3><a name="GetJavaVM">GetJavaVM</a></h3>
6046
6047 <p><code>jint GetJavaVM(JNIEnv *env,
6048 JavaVM **vm);</code></p>
6049
6050 <p>Returns the Java VM interface (used in the
6051 Invocation API) associated with the current thread. The result is
6052 placed at the location pointed to by the second argument,
6053 <code>vm</code>.</p>
6054
6055 <h4>LINKAGE:</h4>
6056 <p>Index 219 in the JNIEnv interface function
6057 table.</p>
6058 <h4>PARAMETERS:</h4>
6059
6060 <p><code>env</code>: the JNI interface
6061 pointer.</p>
6062
6063 <p><code>vm</code>: a pointer to where
6064 the result should be placed.</p>
6065
6066 <h4>RETURNS:</h4>
6067
6068 <p>Returns “0” on success; returns a
6069 negative value on failure.</p>
6070
6071 <table width="100%" summary="">
6072 <tbody>
6073 <tr>
6074 <td><a accesskey="c" href=
6075 "../../jni/spec/jniTOC.html">Contents</a> | <a accesskey="p" href=
6076 "../../jni/spec/types.html">Previous</a> | <a accesskey="n" href=
6077 "../../jni/spec/invocation.html">Next</a></td>
6078 <td></td>
6079 </tr>
6080 </tbody>
6081 </table>
6082 </body>
6083 </html>