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)
This is an overloaded function.
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 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)
This is an overloaded function.
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 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.