This section is used as a reference section for JNI functions. It provides a complete list of all JNI features, as well as the exact layout of the JNI function table.

Note the use of the term “must” to describe limitations on JNI programmers. For example, when you see that a JNI function must accept a non-NULL object, it is your responsibility to ensure that NULL is not passed to that JNI function. Therefore, the JNI implementation does not need to perform NULL pointer checking in this JNI function.

Part of this section is adapted from Netscape’s JRI documentation.

Reference materials are grouped according to their usage. The reference section consists of the following functional areas:

• Version information
• A Class action
• abnormal
• Global and local references
• Weak global reference
• The object operation
• Access the fields of the object
• Calling instance methods
• Accessing static fields
• Calling static methods
• String manipulation
• An array of operating
• Register local methods
• Monitor the operation
• NIO support
• Reflection support
• The JVM interface

Table of interface functions

Each function can be accessed at a fixed offset with the JNIEnv argument. The JNIEnv type is a pointer to a structure that holds Pointers to all JNI functions. It is defined as follows:

typedef const struct JNINativeInterface *JNIEnv; 
Copy the code

The VM initialization menu is shown in the following code. Note that the first three entries are reserved for future compatibility with COM. In addition, we kept some additional NULL entries near the beginning of the function table, so that, for example, future class-related JNI operations could be added after FindClass rather than at the end of the table.

Note that the function table can be shared among all JNI interface Pointers.

const struct JNINativeInterface ... = {

    NULL,
    NULL,
    NULL,
    NULL,
    GetVersion,

    DefineClass,
    FindClass,

    FromReflectedMethod,
    FromReflectedField,
    ToReflectedMethod,

    GetSuperclass,
    IsAssignableFrom,

    ToReflectedField,

    Throw,
    ThrowNew,
    ExceptionOccurred,
    ExceptionDescribe,
    ExceptionClear,
    FatalError,

    PushLocalFrame,
    PopLocalFrame,

    NewGlobalRef,
    DeleteGlobalRef,
    DeleteLocalRef,
    IsSameObject,
    NewLocalRef,
    EnsureLocalCapacity,

    AllocObject,
    NewObject,
    NewObjectV,
    NewObjectA,

    GetObjectClass,
    IsInstanceOf,

    GetMethodID,

    CallObjectMethod,
    CallObjectMethodV,
    CallObjectMethodA,
    CallBooleanMethod,
    CallBooleanMethodV,
    CallBooleanMethodA,
    CallByteMethod,
    CallByteMethodV,
    CallByteMethodA,
    CallCharMethod,
    CallCharMethodV,
    CallCharMethodA,
    CallShortMethod,
    CallShortMethodV,
    CallShortMethodA,
    CallIntMethod,
    CallIntMethodV,
    CallIntMethodA,
    CallLongMethod,
    CallLongMethodV,
    CallLongMethodA,
    CallFloatMethod,
    CallFloatMethodV,
    CallFloatMethodA,
    CallDoubleMethod,
    CallDoubleMethodV,
    CallDoubleMethodA,
    CallVoidMethod,
    CallVoidMethodV,
    CallVoidMethodA,

    CallNonvirtualObjectMethod,
    CallNonvirtualObjectMethodV,
    CallNonvirtualObjectMethodA,
    CallNonvirtualBooleanMethod,
    CallNonvirtualBooleanMethodV,
    CallNonvirtualBooleanMethodA,
    CallNonvirtualByteMethod,
    CallNonvirtualByteMethodV,
    CallNonvirtualByteMethodA,
    CallNonvirtualCharMethod,
    CallNonvirtualCharMethodV,
    CallNonvirtualCharMethodA,
    CallNonvirtualShortMethod,
    CallNonvirtualShortMethodV,
    CallNonvirtualShortMethodA,
    CallNonvirtualIntMethod,
    CallNonvirtualIntMethodV,
    CallNonvirtualIntMethodA,
    CallNonvirtualLongMethod,
    CallNonvirtualLongMethodV,
    CallNonvirtualLongMethodA,
    CallNonvirtualFloatMethod,
    CallNonvirtualFloatMethodV,
    CallNonvirtualFloatMethodA,
    CallNonvirtualDoubleMethod,
    CallNonvirtualDoubleMethodV,
    CallNonvirtualDoubleMethodA,
    CallNonvirtualVoidMethod,
    CallNonvirtualVoidMethodV,
    CallNonvirtualVoidMethodA,

    GetFieldID,

    GetObjectField,
    GetBooleanField,
    GetByteField,
    GetCharField,
    GetShortField,
    GetIntField,
    GetLongField,
    GetFloatField,
    GetDoubleField,
    SetObjectField,
    SetBooleanField,
    SetByteField,
    SetCharField,
    SetShortField,
    SetIntField,
    SetLongField,
    SetFloatField,
    SetDoubleField,

    GetStaticMethodID,

    CallStaticObjectMethod,
    CallStaticObjectMethodV,
    CallStaticObjectMethodA,
    CallStaticBooleanMethod,
    CallStaticBooleanMethodV,
    CallStaticBooleanMethodA,
    CallStaticByteMethod,
    CallStaticByteMethodV,
    CallStaticByteMethodA,
    CallStaticCharMethod,
    CallStaticCharMethodV,
    CallStaticCharMethodA,
    CallStaticShortMethod,
    CallStaticShortMethodV,
    CallStaticShortMethodA,
    CallStaticIntMethod,
    CallStaticIntMethodV,
    CallStaticIntMethodA,
    CallStaticLongMethod,
    CallStaticLongMethodV,
    CallStaticLongMethodA,
    CallStaticFloatMethod,
    CallStaticFloatMethodV,
    CallStaticFloatMethodA,
    CallStaticDoubleMethod,
    CallStaticDoubleMethodV,
    CallStaticDoubleMethodA,
    CallStaticVoidMethod,
    CallStaticVoidMethodV,
    CallStaticVoidMethodA,

    GetStaticFieldID,

    GetStaticObjectField,
    GetStaticBooleanField,
    GetStaticByteField,
    GetStaticCharField,
    GetStaticShortField,
    GetStaticIntField,
    GetStaticLongField,
    GetStaticFloatField,
    GetStaticDoubleField,

    SetStaticObjectField,
    SetStaticBooleanField,
    SetStaticByteField,
    SetStaticCharField,
    SetStaticShortField,
    SetStaticIntField,
    SetStaticLongField,
    SetStaticFloatField,
    SetStaticDoubleField,

    NewString,

    GetStringLength,
    GetStringChars,
    ReleaseStringChars,

    NewStringUTF,
    GetStringUTFLength,
    GetStringUTFChars,
    ReleaseStringUTFChars,

    GetArrayLength,

    NewObjectArray,
    GetObjectArrayElement,
    SetObjectArrayElement,

    NewBooleanArray,
    NewByteArray,
    NewCharArray,
    NewShortArray,
    NewIntArray,
    NewLongArray,
    NewFloatArray,
    NewDoubleArray,

    GetBooleanArrayElements,
    GetByteArrayElements,
    GetCharArrayElements,
    GetShortArrayElements,
    GetIntArrayElements,
    GetLongArrayElements,
    GetFloatArrayElements,
    GetDoubleArrayElements,

    ReleaseBooleanArrayElements,
    ReleaseByteArrayElements,
    ReleaseCharArrayElements,
    ReleaseShortArrayElements,
    ReleaseIntArrayElements,
    ReleaseLongArrayElements,
    ReleaseFloatArrayElements,
    ReleaseDoubleArrayElements,

    GetBooleanArrayRegion,
    GetByteArrayRegion,
    GetCharArrayRegion,
    GetShortArrayRegion,
    GetIntArrayRegion,
    GetLongArrayRegion,
    GetFloatArrayRegion,
    GetDoubleArrayRegion,
    SetBooleanArrayRegion,
    SetByteArrayRegion,
    SetCharArrayRegion,
    SetShortArrayRegion,
    SetIntArrayRegion,
    SetLongArrayRegion,
    SetFloatArrayRegion,
    SetDoubleArrayRegion,

    RegisterNatives,
    UnregisterNatives,

    MonitorEnter,
    MonitorExit,

    GetJavaVM,

    GetStringRegion,
    GetStringUTFRegion,

    GetPrimitiveArrayCritical,
    ReleasePrimitiveArrayCritical,

    GetStringCritical,
    ReleaseStringCritical,

    NewWeakGlobalRef,
    DeleteWeakGlobalRef,

    ExceptionCheck,

    NewDirectByteBuffer,
    GetDirectBufferAddress,
    GetDirectBufferCapacity,

    GetObjectRefType
  };
Copy the code

Version information

jint GetVersion(JNIEnv *env);
Copy the code

#define JNI_VERSION_1_1 0x00010001
#define JNI_VERSION_1_2 0x00010002

/* Error codes */
#define JNI_EDETACHED    (-2)              /* thread detached from the VM */
#define JNI_EVERSION     (-3)              /* JNI version error 
Copy the code

#define JNI_VERSION_1_4 0x00010004
Copy the code

#define JNI_VERSION_1_6 0x00010006
Copy the code

Class operation

3.1 DefineClass

jclass DefineClass(JNIEnv *env, const char *name, jobject loader,
const jbyte *buf, jsize bufLen);
Copy the code

3.2 FindClass

jclass FindClass(JNIEnv *env, const char *name);
Copy the code

In JDK 1.1, this function loads a locally defined class. It searches the directories and zip files specified by the CLASSPATH environment variable for classes with the specified name.

Starting with Java 2 SDK version 1.2, the Java security model allows non-system classes to load and invoke native methods. FindClass locates the classloader associated with the current local method; That is, a classloader for a class that declares local methods. If the local method belongs to a system class, no classloader is involved. Otherwise, the appropriate class loader is called to load and link the specified class.

As of version 1.2 of the Java 2 SDK, when FindClass is called through the call interface, there is no current native method or its associated classloader. In this case, use this. GetSystemClassLoader results. This is the class loader created by the virtual machine for the application and is able to locate classes listed in the java.class.path property.

The name parameter is a fully qualified class name or array type signature. For example, the fully qualified class name of the java.lang.String class is: “Java /lang/String”

The array type signature of java.lang.Object [] is: “[Ljava/lang/Object;”

LINKAGE:

Index 6 in the JNIEnv interface function table.

PARAMETERS:

Env: JNI interface pointer.

Name: Fully qualified class name (that is, package name, separated by a “/” followed by the class name). Returns the array class if the name begins with a “[” (array signature character). The string is encoded in the modified UTF-8 encoding.

RETURNS:

Returns the class object from the fully qualified name, or NULL if the class cannot be found.

THROWS:

ClassFormatError: If class data does not specify a valid class.

ClassCircularityError: If the class or interface is its own superclass or superinterface.

NoClassDefFoundError: If the definition of the requested class or interface is not found.

OutOfMemoryError: If the system is out of memory.

3.3 GetSuperclass

jclass GetSuperclass(JNIEnv *env, jclass clazz);
Copy the code

3.4 IsAssignableFrom

jboolean IsAssignableFrom(JNIEnv *env, jclass clazz1, jclass clazz2);
Copy the code

Determines whether objects of CLazz1 can be safely converted to clazz2.

LINKAGE:

Index 11 in the JNIEnv interface function table.

PARAMETERS:

Env: JNI interface pointer.

Clazz1: The first class parameter.

Clazz2: The second class parameter.

RETURNS:

JNI_TRUE is returned if any of the following conditions are met:

• The first and second class arguments refer to the same Java class.
• The first class is a subclass of the second.
• The first class has the second class as one of its interfaces.

Four, abnormal

4.1 Throw

jint Throw(JNIEnv *env, jthrowable obj);
Copy the code

Causes a java.lang.Throwable object to be thrown.

LINKAGE:

Index 13 in the JNIEnv interface function table.

PARAMETERS:

Env: JNI interface pointer.

Obj: a java.lang.Throwable object.

RETURNS:

Returns 0 on success; Negative on failure.

THROWS:

Java.lang.Throwable object obj.

4.2 ThrowNew

jint ThrowNew(JNIEnv *env, jclass clazz, const char *message);
Copy the code

4.3 ExceptionOccurred

jthrowable ExceptionOccurred(JNIEnv *env);
Copy the code

Determines whether an exception is thrown. Exceptions are thrown until the native code calls ExceptionClear() or Java code handles the exception.

LINKAGE:

Index 15 in the JNIEnv interface function table.

PARAMETERS:

Env: JNI interface pointer.

RETURNS:

Returns the exception object currently being thrown, or NULL if no exception is currently being thrown.

4.4 ExceptionDescribe

void ExceptionDescribe(JNIEnv *env);
Copy the code

4.5 ExceptionClear

void ExceptionClear(JNIEnv *env);
Copy the code

Clears any exceptions that are currently being thrown. This routine is invalid if no exception is currently thrown.

LINKAGE:

Index 17 in the JNIEnv interface function table.

PARAMETERS:

Env: JNI interface pointer.

4.6 a FatalError

void FatalError(JNIEnv *env, const char *msg);
Copy the code

4.7 ExceptionCheck

We introduced a convenience function to check for pending exceptions without creating a local reference to the exception object.

jboolean ExceptionCheck(JNIEnv *env);
Copy the code

Return JNI_TRUE if there is a pending exception; Otherwise, JNI_FALSE is returned.

LINKAGE:

Index 228 in the JNIEnv interface function table.

SINCE:

The JDK/JRE 1.2

Global and local references

5.1 Global Reference

5.1.1 NewGlobalRef

jobject NewGlobalRef(JNIEnv *env, jobject obj);
Copy the code

5.1.2 DeleteGlobalRef

void DeleteGlobalRef(JNIEnv *env, jobject globalRef);
Copy the code

Delete the global reference pointed to by globalRef.

LINKAGE:

Index 22 in the JNIEnv interface function table.

PARAMETERS:

Env: JNI interface pointer.

GlobalRef: Global reference.

5.2 Local Reference

5.2.1 DeleteLocalRef

void DeleteLocalRef(JNIEnv *env, jobject localRef);
Copy the code

Delete the local reference pointed to by localRef.

LINKAGE:

Index 23 in the JNIEnv interface function table.

PARAMETERS:

Env: JNI interface pointer.

LocalRef: local reference.

Please note that

JDK/JRE 1.1 provides the above DeleteLocalRef function for programmers to manually remove local references. For example, if native code iterates through a potentially large array of objects and uses one element in each iteration, it is best to remove local references to array elements that are no longer in use before creating new local references in the next iteration.

Starting with JDK/JRE 1.2, there is an additional set of functions for local reference lifecycle management. These are the four functions listed below.

5.2.2 EnsureLocalCapacity

jint EnsureLocalCapacity(JNIEnv *env, jint capacity);
Copy the code

5.2.3 requires PushLocalFrame

jint PushLocalFrame(JNIEnv *env, jint capacity);
Copy the code

Create a new local reference framework where at least a given number of local references can be created. Returns 0 on success and a negative number and a pending OutOfMemoryError on failure.

Note that local references that were created in the previous local frame are still valid in the current local frame.

LINKAGE:

Index 19 in the JNIEnv interface function table.

SINCE:

The JDK/JRE 1.2

5.2.4 PopLocalFrame

jobject PopLocalFrame(JNIEnv *env, jobject result);
Copy the code

5.2.5 NewLocalRef

jobject NewLocalRef(JNIEnv *env, jobject ref);
Copy the code

Creates a new local reference to an object that references the same object as ref. A given reference can be global or local. If ref references NULL, NULL is returned.

LINKAGE:

Index 25 in the JNIEnv interface function table.

SINCE:

The JDK/JRE 1.2

Weak global references

6.1 NewWeakGlobalRef

jweak NewWeakGlobalRef(JNIEnv *env, jobject obj);
Copy the code

Create a new weak global reference. If obj references NULL, or the VM is out of memory, null is returned. If the VM is out of memory, an OutOfMemoryError is thrown.

LINKAGE:

Index 226 in the JNIEnv interface function table.

SINCE:

The JDK/JRE 1.2

6.2 DeleteWeakGlobalRef

void DeleteWeakGlobalRef(JNIEnv *env, jweak obj);
Copy the code

7. Object operation

7.1 AllocObject

jobject AllocObject(JNIEnv *env, jclass clazz);
Copy the code

7.2 NewObject, NewObjectA NewObjectV

jobject NewObject(JNIEnv *env, jclass clazz, jmethodID methodID, ...) ; jobject NewObjectA(JNIEnv *env, jclass clazz, jmethodID methodID, const jvalue *args); jobject NewObjectV(JNIEnv *env, jclass clazz, jmethodID methodID, va_list args);Copy the code

Construct a new Java object. The method ID indicates which constructor method to call. This ID must be obtained by calling GetMethodID() with the method name and return type void (V). Clazz arguments cannot reference array classes.

NewObject

The programmer passes all the arguments to the constructor immediately after the methodID argument. NewObject() takes these parameters and passes them to the Java methods the programmer wants to call.

LINKAGE:

Index 28 in the JNIEnv interface function table.

NewObjectA

The programmer puts all the arguments passed to the constructor in the args array of jValues, which follows the methodID argument. NewObjectA() takes the arguments in this array and passes them to the Java methods the programmer wants to call.

LINKAGE:

Index 30 in the JNIEnv interface function table.

NewObjectV

The programmer puts all the arguments passed to the constructor in the args argument of type va_list, which follows methodID. NewObjectV() takes these arguments and passes them to the Java methods the programmer wants to call.

LINKAGE:

Index 29 in the JNIEnv interface function table.

PARAMETERS:

Env: JNI interface pointer.

Clazz: a Java class object.

MethodID: methodID of the constructor.

Additional arguments to NewObject: arguments to the constructor.

Additional arguments to NewObjectA: args: array of constructor arguments.

Additional arguments to NewObjectV: args: va_list of arguments to the constructor.

RETURNS:

Returns a Java object, or NULL if it cannot be constructed.

THROWS:

InstantiationException: If the class is an interface or abstract class

OutOfMemoryError: If the system is out of memory.

Any exceptions thrown by the constructor.

7.3 GetObjectClass

jclass GetObjectClass(JNIEnv *env, jobject obj);
Copy the code

7.4 GetObjectRefType

jobjectRefType GetObjectRefType(JNIEnv* env, jobject obj);
Copy the code

Returns the type of the object referenced by the obj argument. The obj argument can be a local, global, or weak global reference.

LINKAGE:

Index 232 in the JNIEnv interface function table.

PARAMETERS:

Env: JNI interface pointer.

Obj: local, global, or weak global reference.

Vm: Virtual machine instance from which the interface will be retrieved.

Env: a pointer to the current thread’s JNI interface pointer.

Version: JNI version of the request.

RETURNS:

The GetObjectRefType function returns one of the following enumerated values defined as jobjectRefType:

JNIInvalidRefType = 0,
JNILocalRefType = 1,
JNIGlobalRefType = 2,
JNIWeakGlobalRefType = 3
Copy the code

If the argument obj is a weak global reference type, the return will be JNIWeakGlobalRefType.

If the argument obj is a global reference type, the return value will be JNIGlobalRefType.

If the argument obj is a local reference type, the return will be JNILocalRefType.

If the obj argument is not a valid reference, the return value of this function will be JNIInvalidRefType.

An invalid reference is one that is not a valid handle. That is, the obj pointer address does not point to a location in memory allocated from the Ref creation function or returned from the JNI function.

Therefore,NULL will be an invalid reference, and GetObjectRefType(env,NULL) will return JNIInvalidRefType.

A NULL reference (a reference to NULL), on the other hand, returns the reference type at which the NULL reference was originally created.

Cannot use GetObjectRefType on deleted references.

Because references are typically implemented as Pointers to in-memory data structures that may be reused by any reference allocation service in the VM, once deleted, you do not specify what value GetObjectRefType will return.

SINCE:

The JDK/JRE 1.6

7.5 IsInstanceOf

jboolean IsInstanceOf(JNIEnv *env, jobject obj, jclass clazz);
Copy the code

7.6 IsSameObject

jboolean IsSameObject(JNIEnv *env, jobject ref1, jobject ref2);
Copy the code

Tests whether two references refer to the same Java object.

LINKAGE:

Index 24 in the JNIEnv interface function table.

PARAMETERS:

Env: JNI interface pointer.

Ref1: A Java object.

Ref2: A Java object.

RETURNS:

If ref1 and ref2 reference the same Java object, return JNI_TRUE, or NULL for both; Otherwise, JNI_FALSE is returned.

Access the fields of the object

8.1 GetFieldID

jfieldID GetFieldID(JNIEnv *env, jclass clazz, const char *name, const char *sig);
Copy the code

Returns the field ID of an instance (non-static) field of the class. The field is specified by its name and signature. The GetField and SetField families of visitor functions use field ids to retrieve object fields.

GetFieldID() causes an uninitialized class to be initialized.

GetFieldID() cannot be used to get the length field of the array. Use GetArrayLength() instead.

LINKAGE:

Index 94 in the JNIEnv interface function table.

PARAMETERS:

Env: JNI interface pointer.

Clazz: a Java class object.

Name: name of a field in a modified UTF-8 string ending with 0.

Sig: field signature in a modified UTF-8 character string ending with 0.

RETURNS:

Returns the field ID, or NULL on failure.

THROWS:

NoSuchFieldError: if the specified field cannot be found.

ExceptionInInitializerError: if a class initialization program because of abnormal and failure.

OutOfMemoryError: If the system is out of memory.

8.2 the GetField series

NativeType Get<type>Field(JNIEnv *env, jobject obj, jfieldID fieldID);
Copy the code

8.3 SetField series

void Set<type>Field(JNIEnv *env, jobject obj, jfieldID fieldID, NativeType value);
Copy the code

This family of accessor routines sets the value of an instance (non-static) field of an object. The field to access is specified by the field ID obtained by calling GetFieldID().

The following table describes SetField routine names and value types. You should either replace type in SetField with the Java type of the field, or use an actual routine name in the table, and replace NativeType with the corresponding NativeType of that routine.

Table -SetField series of accessor routines

LINKAGE:

JNIEnv index in the interface function table.

Table -SetField series of accessor routines

PARAMETERS:

Env: JNI interface pointer.

Obj: a Java object (cannot be NULL).

FieldID: indicates a valid fieldID.

Value: indicates the new value of the field.

9. Call instance methods

9.1 GetMethodID

jmethodID GetMethodID(JNIEnv *env, jclass clazz, const char *name, const char *sig);
Copy the code

Returns the method ID of an instance (non-static) method of a class or interface. Methods can be defined in a clazz superclass and inherited by Clazz. A method is determined by its name and signature.

GetMethodID() causes an uninitialized class to be initialized.

To get the constructor’s method ID, provide it as the method name and use void(V) as the return type.

LINKAGE:

Index 33 in the JNIEnv interface function table.

PARAMETERS:

Env: JNI interface pointer.

Clazz: a Java class object.

Name: method name in a modified UTF-8 string ending in 0.

Sig: method signature in modified UTF-8 string ending in 0.

RETURNS:

Returns the method ID, or NULL if the specified method is not found.

THROWS:

NoSuchMethodError: if the specified method cannot be found.

ExceptionInInitializerError: if a class initialization program because of abnormal and failure.

OutOfMemoryError: If the system is out of memory.

9.2 CallMethod, CallMethodA, CallMethodV

NativeType Call<type>Method(JNIEnv *env, jobject obj, jmethodID methodID, ...) ; NativeType Call<type>MethodA(JNIEnv *env, jobject obj, jmethodID methodID, const jvalue *args); NativeType Call<type>MethodV(JNIEnv *env, jobject obj, jmethodID methodID, va_list args);Copy the code

9.3 CallNonvirtualMethod, CallNonvirtualMethodA, CallNonvirtualMethodV

NativeType CallNonvirtual<type>Method(JNIEnv *env, jobject obj, jclass clazz, jmethodID methodID, ...) ; NativeType CallNonvirtual<type>MethodA(JNIEnv *env, jobject obj, jclass clazz, jmethodID methodID, const jvalue *args); NativeType CallNonvirtual<type>MethodV(JNIEnv *env, jobject obj, jclass clazz, jmethodID methodID, va_list args);Copy the code

These families of operations invoke instance (non-static) methods on Java objects based on the specified class and method ID. The methodID parameter must be obtained by calling GetMethodID () on the clazz class.

The CallNonvirtualMethod family routines are different from the CallMethod family routines. The CallMethod routine calls the method based on the class of the object, while the CallNonvirtualMethod routine calls the method based on the class specified by the Clazz parameter, getting the method ID from that class. The method ID must be obtained from the object’s actual class or one of its superclasses.

CallNonvirtualMethod routines

The programmer passes all the parameters to the method immediately after the methodID argument. The CallNonvirtualMethod routine takes these parameters and passes them to the Java methods the programmer wishes to invoke.

CallNonvirtualMethodA routines

The programmer places all of the method’s arguments in the ARgs array of JValues immediately after the methodID argument. The CallNonvirtualMethodA routine takes the arguments in this array and passes them to the Java methods the programmer wants to call.

CallNonvirtualMethodV routines

The programmer puts all of the method’s arguments in an args argument of type va_list immediately after the methodID argument. The CallNonvirtualMethodV routine takes the parameters and passes them to the Java methods the programmer wants to call.

The following table describes each method call routine by result type. You should either replace type in CallNonvirtualMethod with the Java type of the method, or call one of the routine names with the actual method in the table, and replace NativeType with the corresponding NativeType of that routine.

Table – CallNonvirtualMethod routines

LINKAGE:

JNIEnv index in the interface function table.

Table – CallNonvirtualMethod routines

PARAMETERS:

Env: JNI interface pointer.

Clazz: A Java class.

Obj: A Java object.

MethodID: indicates the ID of a method.

Additional arguments to the CallNonvirtualMethod routine: Arguments to the Java method.

Additional arguments to the CallNonvirtualMethodA routine: args: a set of arguments.

Additional arguments to the CallNonvirtualMethodV routine: args: a va_list of arguments.

RETURNS:

Returns the result of calling a Java method.

THROWS:

An exception thrown during execution of a Java method.

Access static fields

10.1 GetStaticFieldID

jfieldID GetStaticFieldID(JNIEnv *env, jclass clazz, const char *name, const char *sig);
Copy the code

Returns the field ID of the static field of the class. Fields are specified by their name and signature. The GetStaticField and SetStaticField families of accessor functions retrieve static fields using field IDS.

GetStaticFieldID() causes an uninitialized class to be initialized.

LINKAGE:

Index 144 in the JNIEnv interface function table.

PARAMETERS:

Env: JNI interface pointer.

Clazz: a Java class object.

Name: static field name in a modified UTF-8 string ending with 0.

Sig: field signature in a modified UTF-8 string ending with 0.

RETURNS:

Returns the field ID, or NULL if the specified static field is not found.

THROWS:

NoSuchFieldError: if the specified static field cannot be found.

ExceptionInInitializerError: if a class initialization program because of abnormal and failure.

OutOfMemoryError: If the system is out of memory.

10.2 GetStaticField

NativeType GetStatic<type>Field(JNIEnv *env, jclass clazz, jfieldID fieldID);
Copy the code

10.3 SetStaticField

void SetStatic<type>Field(JNIEnv *env, jclass clazz, jfieldID fieldID, NativeType value);
Copy the code

Such accessor routines set the values of the static fields of the object. The field to access is specified by the field ID, which is obtained by calling GetStaticFieldID().

The following table describes the routine names and value types that are set. You should replace the type in SetStaticField with the Java type of that field, or one of the actual static field routine names set in the table, and replace NativeType with the corresponding local type of that routine.

LINKAGE:

JNIEnv index in the interface function table.

PARAMETERS:

Env: JNI interface pointer.

Clazz: a Java class object.

FieldID: static fieldID.

Value: indicates the new value of the field.

Call static methods

11.1 GetStaticMethodID

jmethodID GetStaticMethodID(JNIEnv *env, jclass clazz, const char *name, const char *sig);
Copy the code

Returns the method ID of the static method of the class. A method is specified by its name and signature. GetStaticMethodID() causes an uninitialized class to be initialized.

LINKAGE:

Index 113 in the JNIEnv interface function table.

PARAMETERS:

Env: JNI interface pointer.

Clazz: Java class object.

Name: Static method name in a modified UTF-8 string ending in 0.

Sig: method signature in a modified UTF-8 string ending in 0.

RETURNS:

Returns the method ID, or NULL on failure.

THROWS:

NoSuchMethodError: If the specified static method cannot be found.

ExceptionInInitializerError: if a class initializer failure due to abnormal.

OutOfMemoryError: If the system runs out of memory.

11.2 CallStaticMethod, CallStaticMethodA, and CallStaticMethodV

NativeType CallStatic<type>Method(JNIEnv *env, jclass clazz, jmethodID methodID, ...) ; NativeType CallStatic<type>MethodA(JNIEnv *env, jclass clazz, jmethodID methodID, jvalue *args); NativeType CallStatic<type>MethodV(JNIEnv *env, jclass clazz, jmethodID methodID, va_list args);Copy the code

String manipulation

12.1 NewString

jstring NewString(JNIEnv *env, const jchar *unicodeChars, jsize len);
Copy the code

12.2 GetStringLength

jsize GetStringLength(JNIEnv *env, jstring string);
Copy the code

Returns the length of the Java string (number of Unicode characters).

LINKAGE:

Index 164 in the JNIEnv interface function table.

PARAMETERS:

Env: JNI interface pointer.

String: Java string object.

RETURNS:

Returns the length of a Java string.

12.3 GetStringChars

const jchar * GetStringChars(JNIEnv *env, jstring string, jboolean *isCopy);
Copy the code

12.4 ReleaseStringChars

void ReleaseStringChars(JNIEnv *env, jstring string, const jchar *chars);
Copy the code

Notifies the VM that native code no longer needs to access characters. The chars argument is a pointer to a string using GetStringChars().

LINKAGE:

Index 166 in the JNIEnv interface function table.

PARAMETERS:

Env: JNI interface pointer.

String: Java string object.

Chars: Pointer to a Unicode string.

12.5 NewStringUTF

jstring NewStringUTF(JNIEnv *env, const char *bytes);
Copy the code

12.6 GetStringUTFLength

jsize GetStringUTFLength(JNIEnv *env, jstring string);
Copy the code

Returns the length of the modified UTF-8 representation of the string in bytes.

LINKAGE:

Index 168 in the JNIEnv interface function table.

PARAMETERS:

Env: JNI interface pointer.

String: Java string object.

RETURNS:

Returns the UTF-8 length of the string.

12.7 GetStringUTFChars

const char * GetStringUTFChars(JNIEnv *env, jstring string, jboolean *isCopy);
Copy the code

12.8 ReleaseStringUTFChars

void ReleaseStringUTFChars(JNIEnv *env, jstring string, const char *utf);
Copy the code

Notifies the VM that native code no longer needs to access UTF. The UTf argument is a pointer derived from a string using GetStringUTFChars().

LINKAGE:

Index 170 in the JNIEnv interface function table.

PARAMETERS:

Env: JNI interface pointer.

String: Java string object.

Utf: pointer to the modified UTF-8 string.

Pay attention to

In JDK/JRE 1.1, programmers can retrieve raw array elements in user-supplied buffers. Starting with JDK/JRE 1.2, an additional set of features is provided to allow native code to retrieve Unicode (UTF-16) or modified UTF-8 encoded characters in user-provided buffers. See the following features.

12.9 GetStringRegion

void GetStringRegion(JNIEnv *env, jstring str, jsize start, jsize len, jchar *buf);
Copy the code

12.10 GetStringUTFRegion

void GetStringUTFRegion(JNIEnv *env, jstring str, jsize start, jsize len, char *buf);
Copy the code

Converts the Len number of Unicode characters starting at the offset to the modified UTF-8 encoding and places the result in the given buffer buF.

Raise StringIndexOutOfBoundsException index overflow.

LINKAGE:

Index 221 in the JNIEnv interface function table.

SINCE:

The JDK/JRE 1.2

12.11 GetStringCritical, ReleaseStringCritical

const jchar * GetStringCritical(JNIEnv *env, jstring string, jboolean *isCopy);
void ReleaseStringCritical(JNIEnv *env, jstring string, const jchar *carray);
Copy the code

Array manipulation

13.1 GetArrayLength

jsize GetArrayLength(JNIEnv *env, jarray array);
Copy the code

13.2 NewObjectArray

jobjectArray NewObjectArray(JNIEnv *env, jsize length, jclass elementClass, jobject initialElement);
Copy the code

Construct a new array containing objects in class elementClass. All elements are initially set to initialElement.

LINKAGE:

Index 172 in the JNIEnv interface function table.

PARAMETERS:

Env: JNI interface pointer.

Length: indicates the size of the array.

ElementClass: array elementClass.

InitialElement: Initializes the value.

RETURNS:

Returns a Java array object, or NULL if the array cannot be constructed.

THROWS:

OutOfMemoryError: If the system is out of memory.

13.3 GetObjectArrayElement

jobject GetObjectArrayElement(JNIEnv *env, jobjectArray array, jsize index);
Copy the code

13.4 SetObjectArrayElement

void SetObjectArrayElement(JNIEnv *env, jobjectArray array, jsize index, jobject value);
Copy the code

Sets the elements of the Object array.

LINKAGE:

Index 174 in the JNIEnv interface function table.

PARAMETERS:

Env: JNI interface pointer.

Array: a Java array.

Index: indicates the array index.

Value: indicates the new value.

THROWS:

ArrayIndexOutOfBoundsException: if the index is not specified in the effective index in the array.

ArrayStoreException: If the value’s class is not a subclass of the element class of the array.

13.5 NewArray

ArrayType New<PrimitiveType>Array(JNIEnv *env, jsize length);
Copy the code

13.6 GetArrayElements

NativeType *Get<PrimitiveType>ArrayElements(JNIEnv *env, ArrayType array, jboolean *isCopy);
Copy the code

A series of functions that return the body of the basic array. The results are valid until the corresponding ReleaseArrayElements() function is called. Because the returned array may be a copy of a Java array, changes made to the returned array before ReleaseArrayElements() is called are not necessarily reflected in the original array.

If isCopy is not NULL, and if a copy is made, *isCopy is set to JNI_TRUE; If there is no replication, set it to JNI_FALSE.

The following table describes the specific accessors for primitive array elements. You should make the following substitution:

• Replace GetArrayElements with an actual original element accessor routine name in the table below.
• Replace ArrayType with the corresponding ArrayType.
• Replace NativeType with the corresponding NativeType of the routine.

Regardless of how Boolean arrays are represented in the JVM, GetBooleanArrayElements() always returns a pointer to JBooleans, one element per byte (unpacked representation). All arrays of other types are guaranteed to be contiguous in memory.

LINKAGE:

JNIEnv index in the interface function table.

PARAMETERS:

Env: JNI interface pointer.

Array: a Java string object.

IsCopy: pointer to a Boolean value.

RETURNS:

Returns a pointer to an array element, or NULL on failure.

13.7 ReleaseArrayElements

void Release<PrimitiveType>ArrayElements(JNIEnv *env, ArrayType array, NativeType *elems, jint mode);
Copy the code

13.8 GetArrayRegion

void Get<PrimitiveType>ArrayRegion(JNIEnv *env, ArrayType array, jsize start, jsize len, NativeType *buf);
Copy the code

A set of functions that copy a region of the original array into a buffer.

The following table describes the specific accessors for primitive array elements. You should make the following substitutions:

• Replace GetArrayRegion with an actual original element accessor routine name in the table below.
• Replace ArrayType with the corresponding ArrayType.
• Replace NativeType with the corresponding NativeType of the routine.

LINKAGE:

JNIEnv index in the interface function table.

PARAMETERS:

Env: JNI interface pointer.

Array: a Java array.

Start: indicates the start index.

Len: Number of elements to copy.

Buf: target buffer.

THROWS:

ArrayIndexOutOfBoundsException: if an index of the area of the invalid.

13.9 SetArrayRegion

void Set<PrimitiveType>ArrayRegion(JNIEnv *env, ArrayType array, jsize start, jsize len, const NativeType *buf);
Copy the code

13.10 GetPrimitiveArrayCritical, ReleasePrimitiveArrayCritical

void * GetPrimitiveArrayCritical(JNIEnv *env, jarray array, jboolean *isCopy);
void ReleasePrimitiveArrayCritical(JNIEnv *env, jarray array, void *carray, jint mode);
Copy the code

The semantics of these two functions are very similar to the existing Get/ReleaseArrayElements functions. If possible, the VM returns a pointer to the original array; Otherwise, copy. However, there are significant limitations on how these functions can be used.

After calling GetPrimitiveArrayCritical, native code before calling ReleasePrimitiveArrayCritical shouldn’t run for a long time. We must think of the code in this pair of functions as running in a “critical region.” In critical areas, native code cannot call other JNI functions, nor can it call any system calls that might cause the current thread to block and wait for another Java thread. (For example, the current thread cannot call read on a stream that another Java thread is writing to.)

These limitations make it more likely that native code will get an uncopied version of the array, even if the VM does not support fixation. For example, when the local code holds a pointer to the array is acquired by GetPrimitiveArrayCritical, VM can temporarily disable garbage collection.

Can be nested to GetPrimtiveArrayCritical and ReleasePrimitiveArrayCritical more. Such as:

jint len = (*env)->GetArrayLength(env, arr1); jbyte *a1 = (*env)->GetPrimitiveArrayCritical(env, arr1, 0); jbyte *a2 = (*env)->GetPrimitiveArrayCritical(env, arr2, 0); /* We need to check if the VM is trying to make a copy. */ if (a1 == NULL || a2 == NULL) { ... /* memcpy(a1, a2, len); (*env)->ReleasePrimitiveArrayCritical(env, arr2, a2, 0); (*env)->ReleasePrimitiveArrayCritical(env, arr1, a1, 0);Copy the code

Please note that if the VM internal representation array of different formats, the GetPrimitiveArrayCritical might still have to generate a copy of the array. Therefore, we need to check whether the return value is NULL for possible out-of-memory situations.

LINKAGE (GetPrimitiveArrayCritical):

Link index 222 in the JNIEnv interface function table.

LINKAGE (ReleasePrimitiveArrayCritical):

The link index in the JNIEnv interface function table is 223.

SINCE:

The JDK/JRE 1.2

14. Register local methods

14.1 RegisterNatives

jint RegisterNatives(JNIEnv *env, jclass clazz, const JNINativeMethod *methods, jint nMethods);
Copy the code

Register local methods with the class specified by the Clazz parameter. The methods argument specifies an array of JNINativeMethod structures that contain the name, signature, and function pointer of the local method. The name and signature fields of the JNINativeMethod structure are Pointers to the modified UTF-8 string. The nMethods argument specifies the number of local methods in the array. JNINativeMethod structure is defined as follows:

typedef struct { 

    char *name; 

    char *signature; 

    void *fnPtr; 

} JNINativeMethod; 
Copy the code

Function Pointers must nominally have the following signature:

ReturnType (*fnPtr)(JNIEnv *env, jobject objectOrClass, ...) ;Copy the code

LINKAGE:

Index 215 in the JNIEnv interface function table.

PARAMETERS:

Env: JNI interface pointer.

Clazz: a Java class object.

Methods: local methods in a class.

NMethods: The number of local methods in a class.

RETURNS:

Returns “0” on success; Returns a negative value on failure.

THROWS:

NoSuchMethodError: if the specified method cannot be found or the method is not local.

14.2 UnregisterNatives

jint UnregisterNatives(JNIEnv *env, jclass clazz);
Copy the code

15. Monitor Operation

15.1 MonitorEnter

jint MonitorEnter(JNIEnv *env, jobject obj);
Copy the code

15.2 MonitorExit

jint MonitorExit(JNIEnv *env, jobject obj);
Copy the code

The current thread must be the owner of the monitor associated with the underlying Java object referenced by OBJ. A thread decrement counter indicating how many times it has entered the monitor. If the value of the counter becomes zero, the current thread releases the monitor.

Native code may not use MonitorExit to exit a monitor entered through the synchronized method or monitorenter Java virtual machine directive.

LINKAGE:

Index 218 in the JNIEnv interface function table.

PARAMETERS:

Env: JNI interface pointer.

Obj: Plain Java object or class object.

RETURNS:

Returns “0” on success; Returns a negative value on failure.

EXCEPTIONS:

Does not have any monitor IllegalMonitorStateException if the current thread.

16. NIO support

16.1 NewDirectByteBuffer

jobject NewDirectByteBuffer(JNIEnv* env, void* address, jlong capacity);
Copy the code

Allocate and return a direct java.nio.byteBuffer, which refers to a chunk of memory starting at address and extending capacity bytes.

Native code that calls this function and returns the generated byte-buffer object to Java-level code should ensure that the buffer references a valid region of memory available for reading and is written when appropriate. Attempting to access an invalid memory location from Java code returns an arbitrary value with no visible effect, or causes an unspecified exception to be thrown.

LINKAGE:

Index 229 in the JNIEnv interface function table.

PARAMETERS:

Env: indicates the JNIEnv interface pointer

Address: start address of memory area (cannot be NULL)

Capacity: Size of memory area (in bytes) (must be positive)

RETURNS:

Returns a local reference to the newly instantiated java.nio.byteBuffer object. If an exception occurs, or the virtual machine does not support JNI access to the direct buffer, NULL is returned.

EXCEPTIONS:

OutOfMemoryError: If the allocation of a ByteBuffer object fails

SINCE:

The JDK/JRE 1.4

16.2 GetDirectBufferAddress

void* GetDirectBufferAddress(JNIEnv* env, jobject buf);
Copy the code

16.3 GetDirectBufferCapacity

jlong GetDirectBufferCapacity(JNIEnv* env, jobject buf);
Copy the code

Gets and returns the capacity of the memory region referenced by the given direct java.nio.buffer. Capacity is the number of elements contained in a memory area.

LINKAGE:

Index 231 in the JNIEnv interface function table.

PARAMETERS:

Env: indicates the JNIEnv interface pointer

Buf: a direct java.nio.Buffer object (cannot be NULL)

RETURNS:

Returns the capacity of the memory region associated with the buffer. Returns -1 if the given object is not direct java.nio.buffer, if the object is an unaligned view Buffer and the processor architecture does not support unaligned access, or if the virtual machine does not support JNI access to the direct Buffer.

SINCE:

The JDK/JRE 1.4

Reflection support

17.1 FromReflectedMethod

jmethodID FromReflectedMethod(JNIEnv *env, jobject method);
Copy the code

The Java. Lang. Reflect the Method or Java. Lang. Reflect. The Constructor object into a Method ID.

LINKAGE:

Index 7 in the JNIEnv interface function table.

SINCE:

The JDK/JRE 1.2

17.2 FromReflectedField

jfieldID FromReflectedField(JNIEnv *env, jobject field);
Copy the code

17.3 ToReflectedMethod

jobject ToReflectedMethod(JNIEnv *env, jclass cls, jmethodID methodID, jboolean isStatic);
Copy the code

Converts from CLS derived Method ID to Java. Lang. Reflect. The Method or Java. Lang. Reflect. The Constructor objects. If the method ID references a static field, isStatic must be set to JNI_TRUE, otherwise JNI_FALSE.

Throws OutOfMemoryError, or returns 0 on failure.

LINKAGE:

Index 9 in the JNIEnv interface function table.

SINCE:

The JDK/JRE 1.2

17.4 ToReflectedField

jobject ToReflectedField(JNIEnv *env, jclass cls, jfieldID fieldID, jboolean isStatic);
Copy the code

JVM interface

18.1 GetJavaVM

jint GetJavaVM(JNIEnv *env, JavaVM **vm);
Copy the code