jni_util.h

/*
 * Copyright (c) 1997, 2024, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation. Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

#ifndefJNI_UTIL_H
#defineJNI_UTIL_H

#include"jni.h"
#include"jni_util_md.h"
#include"jlong.h"

#ifdef__cplusplus
extern"C" {
#endif

/*
 * This file contains utility functions that can be implemented in pure JNI.
 *
 * Caution: Callers of functions declared in this file should be
 * particularly aware of the fact that these functions are convenience
 * functions, and as such are often compound operations, each one of
 * which may throw an exception. Therefore, the functions this file
 * will often return silently if an exception has occurred, and callers
 * must check for exception themselves.
 */

/* Throw a Java exception by name. Similar to SignalError. */
JNIEXPORTvoidJNICALL
JNU_ThrowByName(JNIEnv*env, constchar*name, constchar*msg);

/* Throw common exceptions */
JNIEXPORTvoidJNICALL
JNU_ThrowNullPointerException(JNIEnv*env, constchar*msg);

JNIEXPORTvoidJNICALL
JNU_ThrowArrayIndexOutOfBoundsException(JNIEnv*env, constchar*msg);

JNIEXPORTvoidJNICALL
JNU_ThrowOutOfMemoryError(JNIEnv*env, constchar*msg);

JNIEXPORTvoidJNICALL
JNU_ThrowIllegalArgumentException(JNIEnv*env, constchar*msg);

JNIEXPORTvoidJNICALL
JNU_ThrowInternalError(JNIEnv*env, constchar*msg);

JNIEXPORTvoidJNICALL
JNU_ThrowIOException(JNIEnv*env, constchar*msg);

JNIEXPORTvoidJNICALL
JNU_ThrowClassNotFoundException(JNIEnv*env, constchar*msg);

/* Throw an exception by name, using the string returned by
 * getLastErrorString for the detail string. If the last-error
 * string is NULL, use the given default detail string.
 */
JNIEXPORTvoidJNICALL
JNU_ThrowByNameWithLastError(JNIEnv*env, constchar*name,
constchar*defaultDetail);

/* Throw an exception by name, using a given message and the string
 * returned by getLastErrorString to construct the detail string.
 */
JNIEXPORTvoidJNICALL
JNU_ThrowByNameWithMessageAndLastError
 (JNIEnv*env, constchar*name, constchar*message);

/* Throw an IOException, using the last-error string for the detail
 * string. If the last-error string is NULL, use the given default
 * detail string.
 */
JNIEXPORTvoidJNICALL
JNU_ThrowIOExceptionWithLastError(JNIEnv*env, constchar*defaultDetail);

JNIEXPORTvoidJNICALL
JNU_ThrowIOExceptionWithMessageAndLastError(JNIEnv*env, constchar*message);

/* Convert between Java strings and i18n C strings */
JNIEXPORTconstchar*
GetStringPlatformChars(JNIEnv*env, jstringjstr, jboolean*isCopy);

/* Convert between Java strings and i18n C strings
 * Performs additional sanity checks on converted string
 * such as presence of null characters which are not allowed.
 * NULL may be returned with IllegalArgumentException pending
 */
JNIEXPORTconstchar*
GetStringPlatformCharsStrict(JNIEnv*env, jstringjstr, jboolean*isCopy);

JNIEXPORTjstringJNICALL
JNU_NewStringPlatform(JNIEnv*env, constchar*str);

/* Convert between Java strings and i18n C strings
 * Performs additional sanity checks on converted string
 * such as presence of null characters which are not allowed.
 * NULL may be returned with IllegalArgumentException pending
 */
JNIEXPORTconstchar*JNICALL
JNU_GetStringPlatformCharsStrict(JNIEnv*env, jstringjstr, jboolean*isCopy);

/* Convert between Java strings and i18n C strings
 * Deprecated: Use JNU_GetStringPlatformCharsStrict
 */
JNIEXPORTconstchar*JNICALL
JNU_GetStringPlatformChars(JNIEnv*env, jstringjstr, jboolean*isCopy);

JNIEXPORTvoidJNICALL
JNU_ReleaseStringPlatformChars(JNIEnv*env, jstringjstr, constchar*str);

/* Class constants */
JNIEXPORTjclassJNICALL
JNU_ClassString(JNIEnv*env);

/* Copy count number of arguments from src to dst. Array bounds
 * and ArrayStoreException are checked.
 */
JNIEXPORTjintJNICALL
JNU_CopyObjectArray(JNIEnv*env, jobjectArraydst, jobjectArraysrc,
jintcount);

/* Invoke a object-returning static method, based on class name,
 * method name, and signature string.
 *
 * The caller should check for exceptions by setting hasException
 * argument. If the caller is not interested in whether an exception
 * has occurred, pass in NULL.
 */
JNIEXPORTjvalueJNICALL
JNU_CallStaticMethodByName(JNIEnv*env,
jboolean*hasException,
constchar*class_name,
constchar*name,
constchar*signature,
 ...);

/* Invoke an instance method by name.
 */
JNIEXPORTjvalueJNICALL
JNU_CallMethodByName(JNIEnv*env,
jboolean*hasException,
jobjectobj,
constchar*name,
constchar*signature,
 ...);

JNIEXPORTjvalueJNICALL
JNU_CallMethodByNameV(JNIEnv*env,
jboolean*hasException,
jobjectobj,
constchar*name,
constchar*signature,
va_listargs);

/* Construct a new object of class, specifying the class by name,
 * and specififying which constructor to run and what arguments to
 * pass to it.
 *
 * The method will return an initialized instance if successful.
 * It will return NULL if an error has occurred (for example if
 * it ran out of memory) and the appropriate Java exception will
 * have been thrown.
 */
JNIEXPORTjobjectJNICALL
JNU_NewObjectByName(JNIEnv*env, constchar*class_name,
constchar*constructor_sig, ...);

/* returns:
 * 0: object is not an instance of the class named by classname.
 * 1: object is an instance of the class named by classname.
 * -1: the class named by classname cannot be found. An exception
 * has been thrown.
 */
JNIEXPORTjintJNICALL
JNU_IsInstanceOfByName(JNIEnv*env, jobjectobject, constchar*classname);


/* Get or set class and instance fields.
 * Note that set functions take a variable number of arguments,
 * but only one argument of the appropriate type can be passed.
 * For example, to set an integer field i to 100:
 *
 * JNU_SetFieldByName(env, &exc, obj, "i", "I", 100);
 *
 * To set a float field f to 12.3:
 *
 * JNU_SetFieldByName(env, &exc, obj, "f", "F", 12.3);
 *
 * The caller should check for exceptions by setting hasException
 * argument. If the caller is not interested in whether an exception
 * has occurred, pass in NULL.
 */
JNIEXPORTjvalueJNICALL
JNU_GetFieldByName(JNIEnv*env,
jboolean*hasException,
jobjectobj,
constchar*name,
constchar*sig);
JNIEXPORTvoidJNICALL
JNU_SetFieldByName(JNIEnv*env,
jboolean*hasException,
jobjectobj,
constchar*name,
constchar*sig,
 ...);

JNIEXPORTjvalueJNICALL
JNU_GetStaticFieldByName(JNIEnv*env,
jboolean*hasException,
constchar*classname,
constchar*name,
constchar*sig);


/************************************************************************
 * Miscellaneous utilities used by the class libraries
 */

#defineIS_NULL(obj) ((obj) == NULL)
#defineJNU_IsNull(env,obj) ((obj) == NULL)

/************************************************************************
 * Miscellaneous utilities used by the class libraries to return from
 * a function if a value is NULL or an exception is pending.
 */

#defineCHECK_NULL(x) \
 do { \
 if ((x) == NULL) { \
 return; \
 } \
 } while (0) \

#defineCHECK_NULL_THROW_NPE(env, x, msg) \
 do { \
 if ((x) == NULL) { \
 JNU_ThrowNullPointerException((env), (msg));\
 return; \
 } \
 } while(0) \

#defineCHECK_NULL_THROW_NPE_RETURN(env, x, msg, z)\
 do { \
 if ((x) == NULL) { \
 JNU_ThrowNullPointerException((env), (msg));\
 return (z); \
 } \
 } while(0) \

#defineCHECK_NULL_RETURN(x, y) \
 do { \
 if ((x) == NULL) { \
 return (y); \
 } \
 } while (0) \

#ifdef__cplusplus
#defineJNU_CHECK_EXCEPTION(env) \
 do { \
 if ((env)->ExceptionCheck()) { \
 return; \
 } \
 } while (0) \

#defineJNU_CHECK_EXCEPTION_RETURN(env, y) \
 do { \
 if ((env)->ExceptionCheck()) { \
 return (y); \
 } \
 } while (0)
#else
#defineJNU_CHECK_EXCEPTION(env) \
 do { \
 if ((*env)->ExceptionCheck(env)) { \
 return; \
 } \
 } while (0) \

#defineJNU_CHECK_EXCEPTION_RETURN(env, y) \
 do { \
 if ((*env)->ExceptionCheck(env)) { \
 return (y); \
 } \
 } while (0)
#endif/* __cplusplus */

/************************************************************************
 * Debugging utilities
 */

JNIEXPORTjstringJNICALL
JNU_ToString(JNIEnv*env, jobjectobject);


/*
 * Package shorthand for use by native libraries
 */
#defineJNU_JAVAPKG "java/lang/"
#defineJNU_JAVAIOPKG "java/io/"
#defineJNU_JAVANETPKG "java/net/"

/*
 * Check if the current thread is attached to the VM, and returns
 * the JNIEnv of the specified version if the thread is attached.
 *
 * If the current thread is not attached, this function returns 0.
 *
 * If the current thread is attached, this function returns the
 * JNI environment, or returns (void *)JNI_ERR if the specified
 * version is not supported.
 */
JNIEXPORTvoid*JNICALL
JNU_GetEnv(JavaVM*vm, jintversion);

/*
 * Warning free access to pointers stored in Java long fields.
 */
#defineJNU_GetLongFieldAsPtr(env,obj,id) \
 (jlong_to_ptr((*(env))->GetLongField((env),(obj),(id))))
#defineJNU_SetLongFieldFromPtr(env,obj,id,val) \
 (*(env))->SetLongField((env),(obj),(id),ptr_to_jlong(val))

/*
 * Internal use only.
 */
enum {
NO_ENCODING_YET=0, /* "sun.jnu.encoding" not yet set */
NO_FAST_ENCODING, /* Platform encoding is not fast */
FAST_8859_1, /* ISO-8859-1 */
FAST_CP1252, /* MS-DOS Cp1252 */
FAST_646_US, /* US-ASCII : ISO646-US */
FAST_UTF_8
};

JNIEXPORTvoidInitializeEncoding(JNIEnv*env, constchar*name);

void*getProcessHandle();

jstringgetLastErrorString(JNIEnv*env);

JNIEXPORTintJNICALL
getErrorString(interr, char*buf, size_tlen);

#ifdefSTATIC_BUILD
/* Macros for handling declaration of static/dynamic
 * JNI library Load/Unload functions
 *
 * Use DEF_JNI_On{Un}Load when you want a static and non-static entry points.
 * Use DEF_STATIC_JNI_On{Un}Load when you only want a static one.
 *
 * LIBRARY_NAME must be set to the name of the library
 */

/* These three macros are needed to get proper concatenation of
 * the LIBRARY_NAME
 *
 * NOTE: LIBRARY_NAME must be set for static builds.
 */
#defineADD_LIB_NAME3(name, lib) name ## lib
#defineADD_LIB_NAME2(name, lib) ADD_LIB_NAME3(name, lib)
#defineADD_LIB_NAME(entry) ADD_LIB_NAME2(entry, LIBRARY_NAME)

#defineDEF_JNI_OnLoad \
ADD_LIB_NAME(JNI_OnLoad_)(JavaVM *vm, void *reserved) \
{ \
 jint JNICALL ADD_LIB_NAME(JNI_OnLoad_dynamic_)(JavaVM *vm, void *reserved); \
 ADD_LIB_NAME(JNI_OnLoad_dynamic_)(vm, reserved); \
 return JNI_VERSION_1_8; \
} \
jint JNICALL ADD_LIB_NAME(JNI_OnLoad_dynamic_)

#defineDEF_STATIC_JNI_OnLoad \
JNIEXPORT jint JNICALL ADD_LIB_NAME(JNI_OnLoad_)(JavaVM *vm, void *reserved) { \
 return JNI_VERSION_1_8; \
}

#defineDEF_JNI_OnUnload \
ADD_LIB_NAME(JNI_OnUnload_)(JavaVM *vm, void *reserved) \
{ \
 void JNICALL ADD_LIB_NAME(JNI_OnUnload_dynamic_)(JavaVM *vm, void *reserved); \
 ADD_LIB_NAME(JNI_OnUnload_dynamic_)(vm, reserved); \
} \
void JNICALL ADD_LIB_NAME(JNI_OnUnload_dynamic_)

#defineDEF_STATIC_JNI_OnUnload \
ADD_LIB_NAME(JNI_OnUnload_)

#else

#defineDEF_JNI_OnLoad JNI_OnLoad
#defineDEF_STATIC_JNI_OnLoad
#defineDEF_JNI_OnUnload JNI_OnUnload
#defineDEF_STATIC_JNI_OnUnload
#endif

#ifdefSTATIC_BUILD
/* Macros for handling declaration of static/dynamic
 * Agent library Load/Attach/Unload functions
 *
 * Use DEF_Agent_OnLoad, DEF_Agent_OnAttach or DEF_Agent_OnUnload
 * when you want both static and non-static entry points.
 * Use DEF_STATIC_Agent_OnLoad, DEF_STATIC_Agent_OnAttach or
 * DEF_STATIC_Agent_OnUnload when you only want a static one.
 *
 * LIBRARY_NAME must be set to the name of the library for static builds.
 */

#defineDEF_Agent_OnLoad \
ADD_LIB_NAME(Agent_OnLoad_)(JavaVM *vm, char *options, void *reserved) \
{ \
 jint JNICALL ADD_LIB_NAME(Agent_OnLoad_dynamic_)(JavaVM *vm, char *options, void *reserved); \
 return ADD_LIB_NAME(Agent_OnLoad_dynamic_)(vm, options, reserved); \
} \
jint JNICALL ADD_LIB_NAME(Agent_OnLoad_dynamic_)

#defineDEF_STATIC_Agent_OnLoad \
JNIEXPORT jint JNICALL ADD_LIB_NAME(Agent_OnLoad_)(JavaVM *vm, char *options, void *reserved) { \
 return JNI_FALSE; \
}

#defineDEF_Agent_OnAttach \
ADD_LIB_NAME(Agent_OnAttach_)(JavaVM *vm, char *options, void *reserved) \
{ \
 jint JNICALL ADD_LIB_NAME(Agent_OnAttach_dynamic_)(JavaVM *vm, char *options, void *reserved); \
 return ADD_LIB_NAME(Agent_OnAttach_dynamic_)(vm, options, reserved); \
} \
jint JNICALL ADD_LIB_NAME(Agent_OnAttach_dynamic_)

#defineDEF_STATIC_Agent_OnAttach \
JNIEXPORT jint JNICALL ADD_LIB_NAME(Agent_OnLoad_)(JavaVM *vm, char *options, void *reserved) { \
 return JNI_FALSE; \
}

#defineDEF_Agent_OnUnload \
ADD_LIB_NAME(Agent_OnUnload_)(JavaVM *vm) \
{ \
 void JNICALL ADD_LIB_NAME(Agent_OnUnload_dynamic_)(JavaVM *vm); \
 ADD_LIB_NAME(Agent_OnUnload_dynamic_)(vm); \
} \
void JNICALL ADD_LIB_NAME(Agent_OnUnload_dynamic_)

#defineDEF_STATIC_Agent_OnUnload \
ADD_LIB_NAME(Agent_OnUnload_)

#else
#defineDEF_Agent_OnLoad Agent_OnLoad
#defineDEF_Agent_OnAttach Agent_OnAttach
#defineDEF_Agent_OnUnload Agent_OnUnload
#defineDEF_STATIC_Agent_OnLoad
#defineDEF_STATIC_Agent_OnAttach
#defineDEF_STATIC_Agent_OnUnload
#endif

#ifdef__cplusplus
} /* extern "C" */
#endif/* __cplusplus */

#endif/* JNI_UTIL_H */