1 /*
2  * Copyright (c) 1997, 2004, 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 occured, 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 /* Throw an exception by name, using the string returned by
101  * JVM_LastErrorString for the detail string.  If the last-error
102  * string is NULL, use the given default detail string.
103  */
104 JNIEXPORT void JNICALL
105 JNU_ThrowByNameWithLastError(JNIEnv *env, const char *name,
106                              const char *defaultMessage);
107 
108 /* Throw an IOException, using the last-error string for the detail
109  * string.  If the last-error string is NULL, use the given default
110  * detail string.
111  */
112 JNIEXPORT void JNICALL
113 JNU_ThrowIOExceptionWithLastError(JNIEnv *env, const char *defaultDetail);
114 
115 /* Convert between Java strings and i18n C strings */
116 JNIEXPORT jstring
117 NewStringPlatform(JNIEnv *env, const char *str);
118 
119 JNIEXPORT const char *
120 GetStringPlatformChars(JNIEnv *env, jstring jstr, jboolean *isCopy);
121 
122 JNIEXPORT jstring JNICALL
123 JNU_NewStringPlatform(JNIEnv *env, const char *str);
124 
125 JNIEXPORT const char * JNICALL
126 JNU_GetStringPlatformChars(JNIEnv *env, jstring jstr, jboolean *isCopy);
127 
128 JNIEXPORT void JNICALL
129 JNU_ReleaseStringPlatformChars(JNIEnv *env, jstring jstr, const char *str);
130 
131 /* Class constants */
132 JNIEXPORT jclass JNICALL
133 JNU_ClassString(JNIEnv *env);
134 
135 JNIEXPORT jclass JNICALL
136 JNU_ClassClass(JNIEnv *env);
137 
138 JNIEXPORT jclass JNICALL
139 JNU_ClassObject(JNIEnv *env);
140 
141 JNIEXPORT jclass JNICALL
142 JNU_ClassThrowable(JNIEnv *env);
143 
144 /* Copy count number of arguments from src to dst. Array bounds
145  * and ArrayStoreException are checked.
146  */
147 JNIEXPORT jint JNICALL
148 JNU_CopyObjectArray(JNIEnv *env, jobjectArray dst, jobjectArray src,
149                     jint count);
150 
151 /* Invoke a object-returning static method, based on class name,
152  * method name, and signature string.
153  *
154  * The caller should check for exceptions by setting hasException
155  * argument. If the caller is not interested in whether an exception
156  * has occurred, pass in NULL.
157  */
158 JNIEXPORT jvalue JNICALL
159 JNU_CallStaticMethodByName(JNIEnv *env,
160                            jboolean *hasException,
161                            const char *class_name,
162                            const char *name,
163                            const char *signature,
164                            ...);
165 
166 /* Invoke an instance method by name.
167  */
168 JNIEXPORT jvalue JNICALL
169 JNU_CallMethodByName(JNIEnv *env,
170                      jboolean *hasException,
171                      jobject obj,
172                      const char *name,
173                      const char *signature,
174                      ...);
175 
176 JNIEXPORT jvalue JNICALL
177 JNU_CallMethodByNameV(JNIEnv *env,
178                       jboolean *hasException,
179                       jobject obj,
180                       const char *name,
181                       const char *signature,
182                       va_list args);
183 
184 /* Construct a new object of class, specifying the class by name,
185  * and specififying which constructor to run and what arguments to
186  * pass to it.
187  *
188  * The method will return an initialized instance if successful.
189  * It will return NULL if an error has occured (for example if
190  * it ran out of memory) and the appropriate Java exception will
191  * have been thrown.
192  */
193 JNIEXPORT jobject JNICALL
194 JNU_NewObjectByName(JNIEnv *env, const char *class_name,
195                     const char *constructor_sig, ...);
196 
197 /* returns:
198  * 0: object is not an instance of the class named by classname.
199  * 1: object is an instance of the class named by classname.
200  * -1: the class named by classname cannot be found. An exception
201  * has been thrown.
202  */
203 JNIEXPORT jint JNICALL
204 JNU_IsInstanceOfByName(JNIEnv *env, jobject object, char *classname);
205 
206 
207 /* Get or set class and instance fields.
208  * Note that set functions take a variable number of arguments,
209  * but only one argument of the appropriate type can be passed.
210  * For example, to set an integer field i to 100:
211  *
212  * JNU_SetFieldByName(env, &exc, obj, "i", "I", 100);
213  *
214  * To set a float field f to 12.3:
215  *
216  * JNU_SetFieldByName(env, &exc, obj, "f", "F", 12.3);
217  *
218  * The caller should check for exceptions by setting hasException
219  * argument. If the caller is not interested in whether an exception
220  * has occurred, pass in NULL.
221  */
222 JNIEXPORT jvalue JNICALL
223 JNU_GetFieldByName(JNIEnv *env,
224                    jboolean *hasException,
225                    jobject obj,
226                    const char *name,
227                    const char *sig);
228 JNIEXPORT void JNICALL
229 JNU_SetFieldByName(JNIEnv *env,
230                    jboolean *hasException,
231                    jobject obj,
232                    const char *name,
233                    const char *sig,
234                    ...);
235 
236 JNIEXPORT jvalue JNICALL
237 JNU_GetStaticFieldByName(JNIEnv *env,
238                          jboolean *hasException,
239                          const char *classname,
240                          const char *name,
241                          const char *sig);
242 JNIEXPORT void JNICALL
243 JNU_SetStaticFieldByName(JNIEnv *env,
244                          jboolean *hasException,
245                          const char *classname,
246                          const char *name,
247                          const char *sig,
248                          ...);
249 
250 
251 /*
252  * Calls the .equals method.
253  */
254 JNIEXPORT jboolean JNICALL
255 JNU_Equals(JNIEnv *env, jobject object1, jobject object2);
256 
257 
258 /************************************************************************
259  * Thread calls
260  *
261  * Convenience thread-related calls on the java.lang.Object class.
262  */
263 
264 JNIEXPORT void JNICALL
265 JNU_MonitorWait(JNIEnv *env, jobject object, jlong timeout);
266 
267 JNIEXPORT void JNICALL
268 JNU_Notify(JNIEnv *env, jobject object);
269 
270 JNIEXPORT void JNICALL
271 JNU_NotifyAll(JNIEnv *env, jobject object);
272 
273 
274 /************************************************************************
275  * Miscellaneous utilities used by the class libraries
276  */
277 
278 #define IS_NULL(obj) ((obj) == NULL)
279 #define JNU_IsNull(env,obj) ((obj) == NULL)
280 
281 /************************************************************************
282  * Miscellaneous utilities used by the class libraries to return from
283  * a function if a value is NULL or an exception is pending.
284  */
285 
286 #define CHECK_NULL(x)                           \
287     do {                                        \
288         if ((x) == NULL) {                      \
289             return;                             \
290         }                                       \
291     } while (0)                                 \
292 
293 #define CHECK_NULL_RETURN(x, y)                 \
294     do {                                        \
295         if ((x) == NULL) {                      \
296             return (y);                         \
297         }                                       \
298     } while (0)                                 \
299 
300 
301 /************************************************************************
302  * Debugging utilities
303  */
304 
305 JNIEXPORT void JNICALL
306 JNU_PrintString(JNIEnv *env, char *hdr, jstring string);
307 
308 JNIEXPORT void JNICALL
309 JNU_PrintClass(JNIEnv *env, char *hdr, jobject object);
310 
311 JNIEXPORT jstring JNICALL
312 JNU_ToString(JNIEnv *env, jobject object);
313 
314 /*
315  * Package shorthand for use by native libraries
316  */
317 #define JNU_JAVAPKG         "java/lang/"
318 #define JNU_JAVAIOPKG       "java/io/"
319 #define JNU_JAVANETPKG      "java/net/"
320 
321 /*
322  * Check if the current thread is attached to the VM, and returns
323  * the JNIEnv of the specified version if the thread is attached.
324  *
325  * If the current thread is not attached, this function returns 0.
326  *
327  * If the current thread is attached, this function returns the
328  * JNI environment, or returns (void *)JNI_ERR if the specified
329  * version is not supported.
330  */
331 JNIEXPORT void * JNICALL
332 JNU_GetEnv(JavaVM *vm, jint version);
333 
334 /*
335  * Warning free access to pointers stored in Java long fields.
336  */
337 #define JNU_GetLongFieldAsPtr(env,obj,id) \
338     (jlong_to_ptr((*(env))->GetLongField((env),(obj),(id))))
339 #define JNU_SetLongFieldFromPtr(env,obj,id,val) \
340     (*(env))->SetLongField((env),(obj),(id),ptr_to_jlong(val))
341 
342 /*
343  * Internal use only.
344  */
345 enum {
346     NO_ENCODING_YET = 0,        /* "sun.jnu.encoding" not yet set */
347     NO_FAST_ENCODING,           /* Platform encoding is not fast */
348     FAST_8859_1,                /* ISO-8859-1 */
349     FAST_CP1252,                /* MS-DOS Cp1252 */
350     FAST_646_US                 /* US-ASCII : ISO646-US */
351 };
352 
353 jstring nativeNewStringPlatform(JNIEnv *env, const char *str);
354 
355 const char* nativeGetStringPlatformChars(JNIEnv *env, jstring jstr, jboolean *isCopy);
356 
357 // Android added : Faster method to convert strings to / from their platform
358 // representation.
359 void nativeReleaseStringPlatformChars(JNIEnv *env, jstring jstr, const char *chars);
360 
361 int getFastEncoding();
362 
363 void initializeEncoding();
364 
365 extern int getErrorString(int err, char *buf, size_t len);
366 
367 #ifdef __cplusplus
368 } /* extern "C" */
369 #endif /* __cplusplus */
370 
371 #endif /* JNI_UTIL_H */
372