- Qt 6.9
- Qt Core
- QtJniTypes Namespace
- Qt 6.9.3 Reference Documentation

# QtJniTypes Namespace

The QtJniTypes namespace declares C++ types that correspond to Java types. More...

Header: | `#include <QtJniTypes>`
CMake: | `find_package(Qt6 REQUIRED COMPONENTS Core)` `target_link_libraries(mytarget PRIVATE Qt6::Core)`
qmake: | `QT += core`
Since: | Qt 6.8

## Macros

`(since 6.8)` | Q_DECLARE_JNI_CLASS(Type, JavaSignature)
`(since 6.8)` | Q_DECLARE_JNI_NATIVE_METHOD(Method)
`(since 6.8)` | Q_DECLARE_JNI_NATIVE_METHOD(Method, JavaName)
`(since 6.8)` | Q_DECLARE_JNI_NATIVE_METHOD_IN_CURRENT_SCOPE(Method)
`(since 6.8)` | Q_DECLARE_JNI_NATIVE_METHOD_IN_CURRENT_SCOPE(Method, JavaName)
`(since 6.8)` | Q_JNI_NATIVE_METHOD(Method)
`(since 6.8)` | Q_JNI_NATIVE_SCOPED_METHOD(Method, Scope)

## Detailed Description

The Java Native Interface framework enables native C or C++ code to call Java APIs, and to register native C or C++ functions that Java code should be able to call with the JVM. In Qt, the QJniObject and QJniEnvironment types provide convenient wrappers for using JNI.

Since the Java language, similar to C++, supports overloading, functions need to be specified including their entire signature string. This is complex, repetitive, and error prone, especially when functions take several parameters. QJniObject provides variadic template APIs that can deduce the signature string for a function call at compile time, based on the C++ types passed into the template. For this to work, the mapping of those C++ types to their corresponding JNI string needs to be known at compile time.

Qt implements this mapping for the standard JNI types. By using the Q_DECLARE_JNI_CLASS macro, the mapping can be extended for arbitrary Java types.

See also Q_DECLARE_JNI_CLASS, Q_DECLARE_JNI_NATIVE_METHOD, and Q_JNI_NATIVE_METHOD.

## Macro Documentation

### `[since 6.8]` Q_DECLARE_JNI_CLASS(Type, JavaSignature)

Declares a C++ type Type in the QtJniTypes namespace that wraps the Java class JavaSignature. The Java class name in JavaSignature needs to be fully qualified, using `/` as the separator.

     Q_DECLARE_JNI_CLASS(File, "java/io/File")
     Q_DECLARE_JNI_CLASS(FileWriter, "java/io/FileWriter")

The C++ classes `QtJniTypes::File` and `QtJniTypes::FileWriter` are then QJniObject-like types that can be used to instantiate the corresponding Java class, to call methods, and to pass such instances through QJniObject variadic template methods with automatic, compile-time signature deduction.

     using namespace QtJniTypes;

     File file("path/to/file"); // instantiates the java.io.File type in Java
     if (file.callMethod<bool>("createNewFile")) {
         FileWriter writer(file); // instantiates a java.io.FileWriter that operates on file
         writer.callMethod("write", 42);
     }

In addition to the QJniObject API, those C++ classes also have a static `registerNativeMethods` member function that can be used like this:

     QtJniTypes::File::registerNativeMethods({
         Q_JNI_NATIVE_METHOD(freeFunction)
     });

This macro was introduced in Qt 6.8.

See also Q_DECLARE_JNI_NATIVE_METHOD and Q_JNI_NATIVE_METHOD.

### `[since 6.8]` Q_DECLARE_JNI_NATIVE_METHOD(Method)

Declares the free C or C++ function Method as a native method. The method can later be registered with the JNI framework using QJniEnvironment::registerNativeMethod() with the help of the Q_JNI_NATIVE_METHOD macro.

     // C++ side

     Q_DECLARE_JNI_CLASS(MyJavaType, "my/java/Type")

     static void nativeFunction(JNIEnv *env, jobject thiz, jlong id)
     {
         // ...
     }
     Q_DECLARE_JNI_NATIVE_METHOD(nativeFunction)

     Q_DECL_EXPORT jint JNICALL JNI_OnLoad(JavaVM *vm, void *reserved)
     {
         QJniEnvironment env;
         env.registerNativeMethods<QtJniTypes::MyJavaType>({
             Q_JNI_NATIVE_METHOD(nativeFunction)
         });
     }

     // Java side
     public class MyJavaType
     {
         native public nativeFunction(long id);
     }

This macro was introduced in Qt 6.8.

See also Q_JNI_NATIVE_METHOD and Q_DECLARE_JNI_NATIVE_METHOD_IN_CURRENT_SCOPE.

### `[since 6.8]` Q_DECLARE_JNI_NATIVE_METHOD(Method, JavaName)

Declares the free C or C++ function Method as a native method that's available in Java as JavaName. The method can later be registered with the JNI framework using QJniEnvironment::registerNativeMethod() with the help of the Q_JNI_NATIVE_METHOD macro.

This is an overloaded function.

This macro was introduced in Qt 6.8.

See also Q_JNI_NATIVE_METHOD and Q_DECLARE_JNI_NATIVE_METHOD_IN_CURRENT_SCOPE.

### `[since 6.8]` Q_DECLARE_JNI_NATIVE_METHOD_IN_CURRENT_SCOPE(Method)

Declares the C++ static class member function Method as a native method. The method can later be registered with the JNI framework using QJniEnvironment::registerNativeMethod() with the help of the Q_JNI_NATIVE_SCOPED_METHOD macro.

     class NativeHandler
     {
         // ...
     private:
         static void handleChange(JNIEnv*, jobject, jlong id);
         Q_DECLARE_JNI_NATIVE_METHOD_IN_CURRENT_SCOPE(handleChange)
     };

     \dots
     QJniEnvironment env;
     env.registerNativeMethods<QtJniTypes::MyJavaType>({
         Q_JNI_NATIVE_SCOPED_METHOD(handleChange, NativeHandler)
     });

This macro was introduced in Qt 6.8.

See also Q_DECLARE_JNI_NATIVE_METHOD and Q_JNI_NATIVE_SCOPED_METHOD.

### `[since 6.8]` Q_DECLARE_JNI_NATIVE_METHOD_IN_CURRENT_SCOPE(Method, JavaName)

Declares the C++ static class member function Method as a native method that's available in Java as JavaName. The method can later be registered with the JNI framework using QJniEnvironment::registerNativeMethod() with the help of the Q_JNI_NATIVE_METHOD macro.

This is an overloaded function.

This macro was introduced in Qt 6.8.

See also Q_DECLARE_JNI_NATIVE_METHOD and Q_JNI_NATIVE_SCOPED_METHOD.

### `[since 6.8]` Q_JNI_NATIVE_METHOD(Method)

Makes the previously declared native method Method available for registration with the JNI framework. Use this macro when registering the method with JNI using QJniEnvironment::registerNativeMethod().

     Q_DECL_EXPORT jint JNICALL JNI_OnLoad(JavaVM *vm, void *reserved)
     {
         QJniEnvironment env;
         env.registerNativeMethods<QtJniTypes::MyJavaType>({
             Q_JNI_NATIVE_METHOD(nativeFunction)
         });
     }

This macro was introduced in Qt 6.8.

See also Q_DECLARE_JNI_NATIVE_METHOD.

### `[since 6.8]` Q_JNI_NATIVE_SCOPED_METHOD(Method, Scope)

Makes the previously declared native method Method in scope Scope available for registration with the JNI framework. Use this macro when registering the method with JNI using QJniEnvironment::registerNativeMethod().

This macro was introduced in Qt 6.8.

See also Q_JNI_NATIVE_METHOD and Q_DECLARE_JNI_NATIVE_METHOD_IN_CURRENT_SCOPE.