native/IdeaWin32/jni_util.h

   1 /*
   2  * Copyright 1997-2004 Sun Microsystems, Inc.  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.  Sun designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
  22  * CA 95054 USA or visit www.sun.com if you need additional information or
  23  * have any 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 char* nativeGetStringPlatformChars(JNIEnv *env, jstring jstr, jboolean *isCopy);
 337
 338 int getFastEncoding();
 339
 340 void initializeEncoding();
 341
 342
 343 #ifdef __cplusplus
 344 } /* extern "C" */
 345 #endif /* __cplusplus */
 346
 347 #endif /* JNI_UTIL_H */