1 /*
2 * Copyright (c) 1997, 2016, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 #ifndef JNI_UTIL_H
27 #define JNI_UTIL_H
28
29 #include "jni.h"
30 #include "jlong.h"
31
32 #ifdef __cplusplus
33 extern "C" {
34 #endif
35
36 /*
37 * This file contains utility functions that can be implemented in pure JNI.
38 *
39 * Caution: Callers of functions declared in this file should be
40 * particularly aware of the fact that these functions are convenience
41 * functions, and as such are often compound operations, each one of
42 * which may throw an exception. Therefore, the functions this file
43 * will often return silently if an exception has occurred, and callers
44 * must check for exception themselves.
45 */
46
47 /* Throw a Java exception by name. Similar to SignalError. */
48 JNIEXPORT void JNICALL
49 JNU_ThrowByName(JNIEnv *env, const char *name, const char *msg);
50
51 /* Throw common exceptions */
52 JNIEXPORT void JNICALL
53 JNU_ThrowNullPointerException(JNIEnv *env, const char *msg);
54
55 JNIEXPORT void JNICALL
56 JNU_ThrowArrayIndexOutOfBoundsException(JNIEnv *env, const char *msg);
57
58 JNIEXPORT void JNICALL
59 JNU_ThrowOutOfMemoryError(JNIEnv *env, const char *msg);
60
61 JNIEXPORT void JNICALL
62 JNU_ThrowIllegalArgumentException(JNIEnv *env, const char *msg);
63
64 JNIEXPORT void JNICALL
65 JNU_ThrowIllegalAccessError(JNIEnv *env, const char *msg);
66
67 JNIEXPORT void JNICALL
68 JNU_ThrowIllegalAccessException(JNIEnv *env, const char *msg);
69
70 JNIEXPORT void JNICALL
71 JNU_ThrowInternalError(JNIEnv *env, const char *msg);
72
73 JNIEXPORT void JNICALL
74 JNU_ThrowIOException(JNIEnv *env, const char *msg);
75
76 JNIEXPORT void JNICALL
77 JNU_ThrowNoSuchFieldException(JNIEnv *env, const char *msg);
78
79 JNIEXPORT void JNICALL
80 JNU_ThrowNoSuchMethodException(JNIEnv *env, const char *msg);
81
82 JNIEXPORT void JNICALL
83 JNU_ThrowClassNotFoundException(JNIEnv *env, const char *msg);
84
85 JNIEXPORT void JNICALL
86 JNU_ThrowNumberFormatException(JNIEnv *env, const char *msg);
87
88 JNIEXPORT void JNICALL
89 JNU_ThrowNoSuchFieldError(JNIEnv *env, const char *msg);
90
91 JNIEXPORT void JNICALL
92 JNU_ThrowNoSuchMethodError(JNIEnv *env, const char *msg);
93
94 JNIEXPORT void JNICALL
95 JNU_ThrowStringIndexOutOfBoundsException(JNIEnv *env, const char *msg);
96
97 JNIEXPORT void JNICALL
98 JNU_ThrowInstantiationException(JNIEnv *env, const char *msg);
99
100 /*
101 * Throw an exception by name, using the string returned by
102 * getLastErrorString for the detail string. If the last-error
103 * string is NULL, use the given default detail string.
104 */
105 JNIEXPORT void JNICALL
106 JNU_ThrowByNameWithLastError(JNIEnv *env, const char *name,
107 const char *defaultDetail);
108
109 /*
110 * Throw an exception by name, using a given message and the string
111 * returned by getLastErrorString to construct the detail string.
112 */
113 JNIEXPORT void JNICALL
114 JNU_ThrowByNameWithMessageAndLastError
115 (JNIEnv *env, const char *name, const char *message);
116
117 /*
118 * Convenience method.
119 * Call JNU_ThrowByNameWithLastError for java.io.IOException.
120 */
121 JNIEXPORT void JNICALL
122 JNU_ThrowIOExceptionWithLastError(JNIEnv *env, const char *defaultDetail);
123
124 /* Convert between Java strings and i18n C strings */
125 JNIEXPORT jstring
126 NewStringPlatform(JNIEnv *env, const char *str);
127
128 JNIEXPORT const char *
129 GetStringPlatformChars(JNIEnv *env, jstring jstr, jboolean *isCopy);
130
131 JNIEXPORT jstring JNICALL
132 JNU_NewStringPlatform(JNIEnv *env, const char *str);
133
134 JNIEXPORT const char * JNICALL
135 JNU_GetStringPlatformChars(JNIEnv *env, jstring jstr, jboolean *isCopy);
136
137 JNIEXPORT void JNICALL
138 JNU_ReleaseStringPlatformChars(JNIEnv *env, jstring jstr, const char *str);
139
140 /* Class constants */
141 JNIEXPORT jclass JNICALL
142 JNU_ClassString(JNIEnv *env);
143
144 JNIEXPORT jclass JNICALL
145 JNU_ClassClass(JNIEnv *env);
146
147 JNIEXPORT jclass JNICALL
148 JNU_ClassObject(JNIEnv *env);
149
150 JNIEXPORT jclass JNICALL
151 JNU_ClassThrowable(JNIEnv *env);
152
153 /* Copy count number of arguments from src to dst. Array bounds
154 * and ArrayStoreException are checked.
155 */
156 JNIEXPORT jint JNICALL
157 JNU_CopyObjectArray(JNIEnv *env, jobjectArray dst, jobjectArray src,
158 jint count);
159
160 /* Invoke a object-returning static method, based on class name,
161 * method name, and signature string.
162 *
163 * The caller should check for exceptions by setting hasException
164 * argument. If the caller is not interested in whether an exception
165 * has occurred, pass in NULL.
166 */
167 JNIEXPORT jvalue JNICALL
168 JNU_CallStaticMethodByName(JNIEnv *env,
169 jboolean *hasException,
170 const char *class_name,
171 const char *name,
172 const char *signature,
173 ...);
174
175 /* Invoke an instance method by name.
176 */
177 JNIEXPORT jvalue JNICALL
178 JNU_CallMethodByName(JNIEnv *env,
179 jboolean *hasException,
180 jobject obj,
181 const char *name,
182 const char *signature,
183 ...);
184
185 JNIEXPORT jvalue JNICALL
186 JNU_CallMethodByNameV(JNIEnv *env,
187 jboolean *hasException,
188 jobject obj,
189 const char *name,
190 const char *signature,
191 va_list args);
192
193 /* Construct a new object of class, specifying the class by name,
194 * and specififying which constructor to run and what arguments to
195 * pass to it.
196 *
197 * The method will return an initialized instance if successful.
198 * It will return NULL if an error has occurred (for example if
199 * it ran out of memory) and the appropriate Java exception will
200 * have been thrown.
201 */
202 JNIEXPORT jobject JNICALL
203 JNU_NewObjectByName(JNIEnv *env, const char *class_name,
204 const char *constructor_sig, ...);
205
206 /* returns:
207 * 0: object is not an instance of the class named by classname.
208 * 1: object is an instance of the class named by classname.
209 * -1: the class named by classname cannot be found. An exception
210 * has been thrown.
211 */
212 JNIEXPORT jint JNICALL
213 JNU_IsInstanceOfByName(JNIEnv *env, jobject object, char *classname);
214
215
216 /* Get or set class and instance fields.
217 * Note that set functions take a variable number of arguments,
218 * but only one argument of the appropriate type can be passed.
219 * For example, to set an integer field i to 100:
220 *
221 * JNU_SetFieldByName(env, &exc, obj, "i", "I", 100);
222 *
223 * To set a float field f to 12.3:
224 *
225 * JNU_SetFieldByName(env, &exc, obj, "f", "F", 12.3);
226 *
227 * The caller should check for exceptions by setting hasException
228 * argument. If the caller is not interested in whether an exception
229 * has occurred, pass in NULL.
230 */
231 JNIEXPORT jvalue JNICALL
232 JNU_GetFieldByName(JNIEnv *env,
233 jboolean *hasException,
234 jobject obj,
235 const char *name,
236 const char *sig);
237 JNIEXPORT void JNICALL
238 JNU_SetFieldByName(JNIEnv *env,
239 jboolean *hasException,
240 jobject obj,
241 const char *name,
242 const char *sig,
243 ...);
244
245 JNIEXPORT jvalue JNICALL
246 JNU_GetStaticFieldByName(JNIEnv *env,
247 jboolean *hasException,
248 const char *classname,
249 const char *name,
250 const char *sig);
251 JNIEXPORT void JNICALL
252 JNU_SetStaticFieldByName(JNIEnv *env,
253 jboolean *hasException,
254 const char *classname,
255 const char *name,
256 const char *sig,
257 ...);
258
259
260 /*
261 * Calls the .equals method.
262 */
263 JNIEXPORT jboolean JNICALL
264 JNU_Equals(JNIEnv *env, jobject object1, jobject object2);
265
266
267 /************************************************************************
268 * Thread calls
269 *
270 * Convenience thread-related calls on the java.lang.Object class.
271 */
272
273 JNIEXPORT void JNICALL
274 JNU_MonitorWait(JNIEnv *env, jobject object, jlong timeout);
275
276 JNIEXPORT void JNICALL
277 JNU_Notify(JNIEnv *env, jobject object);
278
279 JNIEXPORT void JNICALL
280 JNU_NotifyAll(JNIEnv *env, jobject object);
281
282
283 /************************************************************************
284 * Miscellaneous utilities used by the class libraries
285 */
286
287 #define IS_NULL(obj) ((obj) == NULL)
288 #define JNU_IsNull(env,obj) ((obj) == NULL)
289
290 /************************************************************************
291 * Miscellaneous utilities used by the class libraries to return from
292 * a function if a value is NULL or an exception is pending.
293 */
294
295 #define CHECK_NULL(x) \
296 do { \
297 if ((x) == NULL) { \
298 return; \
299 } \
300 } while (0) \
301
302 #define CHECK_NULL_RETURN(x, y) \
303 do { \
304 if ((x) == NULL) { \
305 return (y); \
306 } \
307 } while (0) \
308
309 #ifdef __cplusplus
310 #define JNU_CHECK_EXCEPTION(env) \
311 do { \
312 if ((env)->ExceptionCheck()) { \
313 return; \
314 } \
315 } while (0) \
316
317 #define JNU_CHECK_EXCEPTION_RETURN(env, y) \
318 do { \
319 if ((env)->ExceptionCheck()) { \
320 return (y); \
321 } \
322 } while (0)
323 #else
324 #define JNU_CHECK_EXCEPTION(env) \
325 do { \
326 if ((*env)->ExceptionCheck(env)) { \
327 return; \
328 } \
329 } while (0) \
330
331 #define JNU_CHECK_EXCEPTION_RETURN(env, y) \
332 do { \
333 if ((*env)->ExceptionCheck(env)) { \
334 return (y); \
335 } \
336 } while (0)
337 #endif /* __cplusplus */
338 /************************************************************************
339 * Debugging utilities
340 */
341
342 JNIEXPORT void JNICALL
343 JNU_PrintString(JNIEnv *env, char *hdr, jstring string);
344
345 JNIEXPORT void JNICALL
346 JNU_PrintClass(JNIEnv *env, char *hdr, jobject object);
347
348 JNIEXPORT jstring JNICALL
349 JNU_ToString(JNIEnv *env, jobject object);
350
351 /*
352 * Package shorthand for use by native libraries
353 */
354 #define JNU_JAVAPKG "java/lang/"
355 #define JNU_JAVAIOPKG "java/io/"
356 #define JNU_JAVANETPKG "java/net/"
357
358 /*
359 * Check if the current thread is attached to the VM, and returns
360 * the JNIEnv of the specified version if the thread is attached.
361 *
362 * If the current thread is not attached, this function returns 0.
363 *
364 * If the current thread is attached, this function returns the
365 * JNI environment, or returns (void *)JNI_ERR if the specified
366 * version is not supported.
367 */
368 JNIEXPORT void * JNICALL
369 JNU_GetEnv(JavaVM *vm, jint version);
370
371 /*
372 * Warning free access to pointers stored in Java long fields.
373 */
374 #define JNU_GetLongFieldAsPtr(env,obj,id) \
375 (jlong_to_ptr((*(env))->GetLongField((env),(obj),(id))))
376 #define JNU_SetLongFieldFromPtr(env,obj,id,val) \
377 (*(env))->SetLongField((env),(obj),(id),ptr_to_jlong(val))
378
379 /*
380 * Internal use only.
381 */
382 enum {
383 NO_ENCODING_YET = 0, /* "sun.jnu.encoding" not yet set */
384 NO_FAST_ENCODING, /* Platform encoding is not fast */
385 FAST_8859_1, /* ISO-8859-1 */
386 FAST_CP1252, /* MS-DOS Cp1252 */
387 FAST_646_US /* US-ASCII : ISO646-US */
388 };
389
390 int getFastEncoding();
391
392 void initializeEncoding();
393
394 void* getProcessHandle();
395
396 void buildJniFunctionName(const char *sym, const char *cname,
397 char *jniEntryName);
398
399 extern size_t getLastErrorString(char *buf, size_t len);
400 extern int getErrorString(int err, char *buf, size_t len);
401
402 #ifdef STATIC_BUILD
403 /* Macros for handling declaration of static/dynamic
404 * JNI library Load/Unload functions
405 *
406 * Use DEF_JNI_On{Un}Load when you want a static and non-static entry points.
407 * Use DEF_STATIC_JNI_On{Un}Load when you only want a static one.
408 *
409 * LIBRARY_NAME must be set to the name of the library
410 */
411
412 /* These three macros are needed to get proper concatenation of
413 * the LIBRARY_NAME
414 *
415 * NOTE: LIBRARY_NAME must be set for static builds.
416 */
417 #define ADD_LIB_NAME3(name, lib) name ## lib
418 #define ADD_LIB_NAME2(name, lib) ADD_LIB_NAME3(name, lib)
419 #define ADD_LIB_NAME(entry) ADD_LIB_NAME2(entry, LIBRARY_NAME)
420
421 #define DEF_JNI_OnLoad \
422 ADD_LIB_NAME(JNI_OnLoad_)(JavaVM *vm, void *reserved) \
423 { \
424 jint JNICALL ADD_LIB_NAME(JNI_OnLoad_dynamic_)(JavaVM *vm, void *reserved); \
425 ADD_LIB_NAME(JNI_OnLoad_dynamic_)(vm, reserved); \
426 return JNI_VERSION_1_8; \
427 } \
428 jint JNICALL ADD_LIB_NAME(JNI_OnLoad_dynamic_)
429
430 #define DEF_STATIC_JNI_OnLoad \
431 JNIEXPORT jint JNICALL ADD_LIB_NAME(JNI_OnLoad_)(JavaVM *vm, void *reserved) { \
432 return JNI_VERSION_1_8; \
433 }
434
435 #define DEF_JNI_OnUnload \
436 ADD_LIB_NAME(JNI_OnUnload_)(JavaVM *vm, void *reserved) \
437 { \
438 void JNICALL ADD_LIB_NAME(JNI_OnUnload_dynamic_)(JavaVM *vm, void *reserved); \
439 ADD_LIB_NAME(JNI_OnUnload_dynamic_)(vm, reserved); \
440 } \
441 void JNICALL ADD_LIB_NAME(JNI_OnUnload_dynamic_)
442
443 #define DEF_STATIC_JNI_OnUnload \
444 ADD_LIB_NAME(JNI_OnUnload_)
445
446 #else
447
448 #define DEF_JNI_OnLoad JNI_OnLoad
449 #define DEF_STATIC_JNI_OnLoad
450 #define DEF_JNI_OnUnload JNI_OnUnload
451 #define DEF_STATIC_JNI_OnUnload
452 #endif
453
454 #ifdef STATIC_BUILD
455 /* Macros for handling declaration of static/dynamic
456 * Agent library Load/Attach/Unload functions
457 *
458 * Use DEF_Agent_OnLoad, DEF_Agent_OnAttach or DEF_Agent_OnUnload
459 * when you want both static and non-static entry points.
460 * Use DEF_STATIC_Agent_OnLoad, DEF_STATIC_Agent_OnAttach or
461 * DEF_STATIC_Agent_OnUnload when you only want a static one.
462 *
463 * LIBRARY_NAME must be set to the name of the library for static builds.
464 */
465
466 #define DEF_Agent_OnLoad \
467 ADD_LIB_NAME(Agent_OnLoad_)(JavaVM *vm, char *options, void *reserved) \
468 { \
469 jint JNICALL ADD_LIB_NAME(Agent_OnLoad_dynamic_)(JavaVM *vm, char *options, void *reserved); \
470 return ADD_LIB_NAME(Agent_OnLoad_dynamic_)(vm, options, reserved); \
471 } \
472 jint JNICALL ADD_LIB_NAME(Agent_OnLoad_dynamic_)
473
474 #define DEF_STATIC_Agent_OnLoad \
475 JNIEXPORT jint JNICALL ADD_LIB_NAME(Agent_OnLoad_)(JavaVM *vm, char *options, void *reserved) { \
476 return JNI_FALSE; \
477 }
478
479 #define DEF_Agent_OnAttach \
480 ADD_LIB_NAME(Agent_OnAttach_)(JavaVM *vm, char *options, void *reserved) \
481 { \
482 jint JNICALL ADD_LIB_NAME(Agent_OnAttach_dynamic_)(JavaVM *vm, char *options, void *reserved); \
483 return ADD_LIB_NAME(Agent_OnAttach_dynamic_)(vm, options, reserved); \
484 } \
485 jint JNICALL ADD_LIB_NAME(Agent_OnAttach_dynamic_)
486
487 #define DEF_STATIC_Agent_OnAttach \
488 JNIEXPORT jint JNICALL ADD_LIB_NAME(Agent_OnLoad_)(JavaVM *vm, char *options, void *reserved) { \
489 return JNI_FALSE; \
490 }
491
492 #define DEF_Agent_OnUnload \
493 ADD_LIB_NAME(Agent_OnUnload_)(JavaVM *vm) \
494 { \
495 void JNICALL ADD_LIB_NAME(Agent_OnUnload_dynamic_)(JavaVM *vm); \
496 ADD_LIB_NAME(Agent_OnUnload_dynamic_)(vm); \
497 } \
498 void JNICALL ADD_LIB_NAME(Agent_OnUnload_dynamic_)
499
500 #define DEF_STATIC_Agent_OnUnload \
501 ADD_LIB_NAME(Agent_OnUnload_)
502
503 #else
504 #define DEF_Agent_OnLoad Agent_OnLoad
505 #define DEF_Agent_OnAttach Agent_OnAttach
506 #define DEF_Agent_OnUnload Agent_OnUnload
507 #define DEF_STATIC_Agent_OnLoad
508 #define DEF_STATIC_Agent_OnAttach
509 #define DEF_STATIC_Agent_OnUnload
510 #endif
511
512 #ifdef __cplusplus
513 } /* extern "C" */
514 #endif /* __cplusplus */
515
516 #endif /* JNI_UTIL_H */