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