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 /************************************************************************
283  * Debugging utilities
284  */
285 
286 JNIEXPORT void JNICALL
287 JNU_PrintString(JNIEnv *env, char *hdr, jstring string);
288 
289 JNIEXPORT void JNICALL
290 JNU_PrintClass(JNIEnv *env, char *hdr, jobject object);
291 
292 JNIEXPORT jstring JNICALL
293 JNU_ToString(JNIEnv *env, jobject object);
294 
295 /*
296  * Package shorthand for use by native libraries
297  */
298 #define JNU_JAVAPKG         "java/lang/"
299 #define JNU_JAVAIOPKG       "java/io/"
300 #define JNU_JAVANETPKG      "java/net/"
301 
302 /*
303  * Check if the current thread is attached to the VM, and returns
304  * the JNIEnv of the specified version if the thread is attached.
305  *
306  * If the current thread is not attached, this function returns 0.
307  *
308  * If the current thread is attached, this function returns the
309  * JNI environment, or returns (void *)JNI_ERR if the specified
310  * version is not supported.
311  */
312 JNIEXPORT void * JNICALL
313 JNU_GetEnv(JavaVM *vm, jint version);
314 
315 /*
316  * Warning free access to pointers stored in Java long fields.
317  */
318 #define JNU_GetLongFieldAsPtr(env,obj,id) \
319     (jlong_to_ptr((*(env))->GetLongField((env),(obj),(id))))
320 #define JNU_SetLongFieldFromPtr(env,obj,id,val) \
321     (*(env))->SetLongField((env),(obj),(id),ptr_to_jlong(val))
322 
323 /*
324  * Internal use only.
325  */
326 enum {
327     NO_ENCODING_YET = 0,        /* "sun.jnu.encoding" not yet set */
328     NO_FAST_ENCODING,           /* Platform encoding is not fast */
329     FAST_8859_1,                /* ISO-8859-1 */
330     FAST_CP1252,                /* MS-DOS Cp1252 */
331     FAST_646_US                 /* US-ASCII : ISO646-US */
332 };
333 
334 jstring nativeNewStringPlatform(JNIEnv *env, const char *str);
335 
336 const char* nativeGetStringPlatformChars(JNIEnv *env, jstring jstr, jboolean *isCopy);
337 
338 // Android added : Faster method to convert strings to / from their platform
339 // representation.
340 void nativeReleaseStringPlatformChars(JNIEnv *env, jstring jstr, const char *chars);
341 
342 int getFastEncoding();
343 
344 void initializeEncoding();
345 
346 
347 #ifdef __cplusplus
348 } /* extern "C" */
349 #endif /* __cplusplus */
350 
351 #endif /* JNI_UTIL_H */
352