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