QJniEnvironment Class

Dokumentation der Mitgliedsfunktionen

QJniEnvironment::QJniEnvironment()

Konstruiert ein neues JNI-Umgebungsobjekt und bindet den aktuellen Thread an die Java VM.

[noexcept] QJniEnvironment::~QJniEnvironment()

Trennt den aktuellen Thread von der Java VM und zerstört das Objekt QJniEnvironment. Dadurch werden alle anstehenden Ausnahmen durch den Aufruf von checkAndClearExceptions() gelöscht.

bool QJniEnvironment::checkAndClearExceptions(QJniEnvironment::OutputMode outputMode = OutputMode::Verbose)

Löscht alle anstehenden Ausnahmen entweder im Stillen oder meldet einen Stack-Backtrace, je nach outputMode.

Im Gegensatz zu QJniObject, das Ausnahmen intern behandelt, müssen Sie, wenn Sie JNI-Aufrufe direkt über JNIEnv tätigen, alle potenziellen Ausnahmen nach dem Aufruf mit dieser Funktion löschen. Für weitere Informationen über JNIEnv Aufrufe, die eine Ausnahme auslösen können, siehe JNI-Funktionen.

Gibt true zurück, wenn eine anstehende Ausnahme gelöscht wurde.

[static] bool QJniEnvironment::checkAndClearExceptions(JNIEnv *env, QJniEnvironment::OutputMode outputMode = OutputMode::Verbose)

Löscht alle anstehenden Ausnahmen für env, entweder stillschweigend oder mit Stack-Backtrace, je nach outputMode. Dies ist nützlich, wenn Sie bereits einen JNIEnv -Zeiger haben, wie in einer nativen Funktionsimplementierung.

Im Gegensatz zu QJniObject, das Ausnahmen intern behandelt, müssen Sie, wenn Sie JNI-Aufrufe direkt über JNIEnv tätigen, alle potenziellen Ausnahmen nach dem Aufruf mit dieser Funktion löschen. Für weitere Informationen über JNIEnv Aufrufe, die eine Ausnahme auslösen können, siehe JNI-Funktionen.

Gibt true zurück, wenn eine anstehende Ausnahme gelöscht wurde.

jclass QJniEnvironment::findClass(const char *className)

Sucht nach className unter Verwendung aller verfügbaren Klassenlader. Qt auf Android verwendet einen benutzerdefinierten Klassenlader, um alle .jar-Dateien zu laden, und dieser muss verwendet werden, um alle Klassen zu finden, die von diesem Klassenlader erstellt werden, da diese Klassen bei Verwendung des Standard-Klassenladers nicht sichtbar sind.

Gibt den Klassenzeiger zurück oder null, wenn className nicht gefunden wird.

Ein Anwendungsfall für diese Funktion ist die Suche nach einer Klasse, um eine JNI-Methode aufzurufen, die eine jclass benötigt. Dies kann nützlich sein, wenn mehrere JNI-Aufrufe für dasselbe Klassenobjekt durchgeführt werden, was etwas schneller sein kann als die Verwendung eines Klassennamens bei jedem Aufruf. Außerdem sucht dieser Aufruf zuerst nach intern zwischengespeicherten Klassen, bevor er einen JNI-Aufruf durchführt, und gibt eine solche Klasse zurück, wenn sie gefunden wurde. Der folgende Codeschnipsel erzeugt eine Instanz der Klasse CustomClass und ruft dann die Methode printFromJava() auf:

QJniEnvironment env;
jclass javaClass = env.findClass("org/qtproject/example/android/CustomClass");
QJniObject javaMessage = QJniObject::fromString("findClass example");
QJniObject::callStaticMethod<void>(javaClass, "printFromJava",
                                   "(Ljava/lang/String;)V", javaMessage.object<jstring>());

[since 6.4] template <typename T> jfieldID QJniEnvironment::findField(jclass clazz, const char *fieldName)

Sucht nach einem Mitgliedsfeld einer Klasse clazz. Das Feld wird durch seine fieldName angegeben. Die Signatur des Feldes wird aus dem Template-Parameter abgeleitet.

Gibt die Feld-ID zurück oder nullptr, wenn das Feld nicht gefunden wird.

Diese Funktion wurde in Qt 6.4 eingeführt.

[since 6.2] jfieldID QJniEnvironment::findField(jclass clazz, const char *fieldName, const char *signature)

Sucht nach einem Mitgliedsfeld einer Klasse clazz. Das Feld wird durch seine fieldName und signature angegeben.

Gibt die Feld-ID oder nullptr zurück, wenn das Feld nicht gefunden wird.

Ein Anwendungsfall für diese Methode ist die Suche nach Klassenfeldern und das Zwischenspeichern ihrer IDs, so dass sie später zum Abrufen/Setzen der Felder verwendet werden können.

Diese Funktion wurde in Qt 6.2 eingeführt.

[since 6.4] template <typename... Args> jmethodID QJniEnvironment::findMethod(jclass clazz, const char *methodName)

Sucht nach einer Instanzmethode einer Klasse clazz. Die Methode wird durch ihre methodName angegeben, die Signatur wird aus den Template-Parametern abgeleitet.

Gibt die Methoden-ID zurück oder nullptr, wenn die Methode nicht gefunden wird.

Diese Funktion wurde in Qt 6.4 eingeführt.

[since 6.2] jmethodID QJniEnvironment::findMethod(jclass clazz, const char *methodName, const char *signature)

Sucht nach einer Instanzmethode einer Klasse clazz. Die Methode wird durch ihre methodName und signature angegeben.

Gibt die Methoden-ID oder nullptr zurück, wenn die Methode nicht gefunden wird.

Ein Anwendungsfall für diese Methode ist die Suche nach Klassenmethoden und das Zwischenspeichern ihrer IDs, so dass sie später für den Aufruf der Methoden verwendet werden können.

Diese Funktion wurde in Qt 6.2 eingeführt.

[since 6.4] template <typename T> jfieldID QJniEnvironment::findStaticField(jclass clazz, const char *fieldName)

Sucht nach einem statischen Feld einer Klasse clazz. Das Feld wird durch seine fieldName angegeben. Die Signatur des Feldes wird aus dem Template-Parameter abgeleitet.

Gibt die Feld-ID zurück oder nullptr, wenn das Feld nicht gefunden wird.

Diese Funktion wurde in Qt 6.4 eingeführt.

[since 6.2] jfieldID QJniEnvironment::findStaticField(jclass clazz, const char *fieldName, const char *signature)

Sucht nach einem statischen Feld einer Klasse clazz. Das Feld wird durch seine fieldName und signature angegeben.

Gibt die Feld-ID oder nullptr zurück, wenn das Feld nicht gefunden wird.

Ein Anwendungsfall für diese Methode ist die Suche nach Klassenfeldern und das Zwischenspeichern ihrer IDs, so dass sie später zum Abrufen/Setzen der Felder verwendet werden können.

Diese Funktion wurde in Qt 6.2 eingeführt.

[since 6.4] template <typename... Args> jmethodID QJniEnvironment::findStaticMethod(jclass clazz, const char *methodName)

Sucht nach einer Instanzmethode einer Klasse clazz. Die Methode wird durch ihre methodName angegeben, die Signatur wird aus den Template-Parametern abgeleitet.

Gibt die Methoden-ID zurück oder nullptr, wenn die Methode nicht gefunden wird.

QJniEnvironment env;
jclass javaClass = env.findClass("org/qtproject/example/android/CustomClass");
jmethodID methodId = env.findStaticMethod<void, jstring>(javaClass, "staticJavaMethod");
QJniObject javaMessage = QJniObject::fromString("findStaticMethod example");
QJniObject::callStaticMethod<void>(javaClass,
                                   methodId,
                                   javaMessage.object<jstring>());

Diese Funktion wurde in Qt 6.4 eingeführt.

[since 6.2] jmethodID QJniEnvironment::findStaticMethod(jclass clazz, const char *methodName, const char *signature)

Sucht nach einer statischen Methode einer Klasse clazz. Die Methode wird durch ihre methodName und signature angegeben.

Gibt die Methoden-ID oder nullptr zurück, wenn die Methode nicht gefunden wird.

Ein Anwendungsfall für diese Methode ist die Suche nach Klassenmethoden und das Zwischenspeichern ihrer IDs, so dass sie später für den Aufruf der Methoden verwendet werden können.

QJniEnvironment env;
jclass javaClass = env.findClass("org/qtproject/example/android/CustomClass");
jmethodID methodId = env.findStaticMethod(javaClass,
                                          "staticJavaMethod",
                                          "(Ljava/lang/String;)V");
QJniObject javaMessage = QJniObject::fromString("findStaticMethod example");
QJniObject::callStaticMethod<void>(javaClass,
                                   methodId,
                                   javaMessage.object<jstring>());

Diese Funktion wurde in Qt 6.2 eingeführt.

[static] JNIEnv *QJniEnvironment::getJniEnv()

Gibt den JNIEnv-Zeiger für den aktuellen Thread zurück.

Der aktuelle Thread wird mit der Java VM verbunden.

[since 6.2] bool QJniEnvironment::isValid() const

Gibt true zurück, wenn diese Instanz ein gültiges JNIEnv-Objekt enthält.

Diese Funktion wurde in Qt 6.2 eingeführt.

[static] JavaVM *QJniEnvironment::javaVM()

Gibt die Java VM-Schnittstelle für den aktuellen Prozess zurück. Obwohl es möglich sein könnte, mehrere Java VMs pro Prozess zu haben, erlaubt Android nur eine.

JNIEnv *QJniEnvironment::jniEnv() const

Gibt den Zeiger der JNI-Umgebung JNIEnv zurück.

template <typename Class> bool QJniEnvironment::registerNativeMethods(std::initializer_list<JNINativeMethod> methods)

Dies ist eine überladene Funktion.

Registriert die Java-Methoden in methods mit der Java-Klasse, die durch Class repräsentiert wird, und gibt zurück, ob die Registrierung erfolgreich war.

Der Typ Class muss im Namespace QtJniTypes mit dem Makro Q_DECLARE_JNI_CLASS deklariert werden. Funktionen, die als freie C- oder C++-Funktionen implementiert sind, müssen mit einem der Q_DECLARE_JNI_NATIVE_METHOD Makros deklariert und mit dem Q_JNI_NATIVE_METHOD Makro an die Registrierung übergeben werden.

// 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);
}

Für Funktionen, die als statische Klassenfunktionen implementiert sind, verwenden Sie stattdessen das macros for scoped functions.

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)
});

bool QJniEnvironment::registerNativeMethods(const char *className, std::initializer_list<JNINativeMethod> methods)

Dies ist eine überladene Funktion.

Registriert die nativen Funktionsmethoden in methods für die Java-Klasse className. Gibt true zurück, wenn die Registrierung erfolgreich war, andernfalls false.

bool QJniEnvironment::registerNativeMethods(jclass clazz, std::initializer_list<JNINativeMethod> methods)

Dies ist eine überladene Funktion.

Registriert die nativen Funktionsmethoden in methods für die Java-Klasse clazz. Gibt true zurück, wenn die Registrierung erfolgreich war, andernfalls false.

bool QJniEnvironment::registerNativeMethods(const char *className, const JNINativeMethod[] methods, int size)

Dies ist eine überladene Funktion.

Registriert die Java-Methoden in dem Array methods der Größe size, von denen jede native C++-Funktionen der Klasse className aufrufen kann. Diese Methoden müssen registriert werden, bevor versucht wird, sie aufzurufen.

Gibt true zurück, wenn die Registrierung erfolgreich war, andernfalls false.

Jedes Element im Methoden-Array besteht aus:

• dem Namen der Java-Methode
• Signatur der Methode
• Die C++-Funktionen, die ausgeführt werden sollen

const JNINativeMethod methods[] =
                        {{"callNativeOne", "(I)V", reinterpret_cast<void *>(fromJavaOne)},
                        {"callNativeTwo", "(I)V", reinterpret_cast<void *>(fromJavaTwo)}};
QJniEnvironment env;
env.registerNativeMethods("org/qtproject/android/TestJavaClass", methods, 2);

bool QJniEnvironment::registerNativeMethods(jclass clazz, const JNINativeMethod[] methods, int size)

Dies ist eine überladene Funktion.

Diese Überladung verwendet eine zuvor zwischengespeicherte jclass-Instanz clazz.

JNINativeMethod methods[] {{"callNativeOne", "(I)V", reinterpret_cast<void *>(fromJavaOne)},
                           {"callNativeTwo", "(I)V", reinterpret_cast<void *>(fromJavaTwo)}};
QJniEnvironment env;
jclass clazz = env.findClass("org/qtproject/android/TestJavaClass");
env.registerNativeMethods(clazz, methods, 2);

JNIEnv &QJniEnvironment::operator*() const

Gibt das JNIEnv Objekt der JNI-Umgebung zurück.

JNIEnv *QJniEnvironment::operator->() const

Ermöglicht den Zugriff auf den Zeiger JNIEnv der JNI-Umgebung.