QJniEnvironment Class

Dokumentation der Member-Funktionen

QJniEnvironment::QJniEnvironment()

Erstellt ein neues JNI-Environment-Objekt und bindet den aktuellen Thread an die Java-VM.

[noexcept] QJniEnvironment::~QJniEnvironment()

Trennt den aktuellen Thread von der Java-VM und löscht das Objekt „ QJniEnvironment “. Dadurch werden alle ausstehenden Ausnahmen durch den Aufruf von „ checkAndClearExceptions()“ zurückgesetzt.

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

Beseitigt alle ausstehenden Ausnahmen entweder stillschweigend oder unter Ausgabe eines Stack-Backtraces, je nach der Einstellung von ` outputMode`.

Im Gegensatz zu ` QJniObject`, das Ausnahmen intern behandelt, müssen Sie bei direkten JNI-Aufrufen über ` JNIEnv` eventuelle Ausnahmen nach dem Aufruf mithilfe dieser Funktion zurücksetzen. Weitere Informationen zu ` JNIEnv `-Aufrufen, die eine Ausnahme auslösen können, finden Sie unter „JNI-Funktionen“.

Gibt ` true ` zurück, wenn eine ausstehende Ausnahme zurückgesetzt wurde.

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

Räumt alle ausstehenden Ausnahmen für ` env` auf – je nach der Einstellung von ` outputMode` entweder ohne Meldung oder mit Ausgabe des Stack-Backtraces. Dies ist nützlich, wenn Sie bereits über einen ` JNIEnv `-Zeiger verfügen, beispielsweise in der Implementierung einer nativen Funktion.

Im Gegensatz zu ` QJniObject`, das Ausnahmen intern verarbeitet, müssen Sie bei direkten JNI-Aufrufen über ` JNIEnv` etwaige potenzielle Ausnahmen nach dem Aufruf mithilfe dieser Funktion bereinigen. Weitere Informationen zu ` JNIEnv `-Aufrufen, die eine Ausnahme auslösen können, finden Sie unter „JNI-Funktionen“.

Gibt ` true ` zurück, wenn eine ausstehende Ausnahme zurückgesetzt wurde.

jclass QJniEnvironment::findClass(const char *className)

Sucht unter Verwendung aller verfügbaren Klassenlader nach „ className “. Qt auf Android verwendet einen benutzerdefinierten Klassenlader zum Laden aller .jar-Dateien, und dieser muss verwendet werden, um alle Klassen zu finden, die von diesem Klassenlader erstellt wurden, 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 ein ` jclass`-Objekt als Argument benötigt. Dies kann nützlich sein, wenn mehrere JNI-Aufrufe für dasselbe Klassenobjekt erfolgen, was etwas schneller sein kann, als bei jedem Aufruf den Klassennamen anzugeben. Zudem sucht dieser Aufruf vor der Ausführung eines JNI-Aufrufs zunächst nach intern zwischengespeicherten Klassen und gibt eine solche Klasse zurück, falls sie gefunden wird. Der folgende Codeausschnitt erstellt eine Instanz der Klasse „ CustomClass “ und ruft anschließend 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 “, falls 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 Member-Feld einer Klasse clazz. Das Feld wird durch seine fieldName und signature angegeben.

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

Ein Anwendungsfall für diese Methode ist die Suche nach Klassenfeldern und das Zwischenspeichern ihrer IDs, damit diese später zum Abrufen bzw. 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 ihren methodName angegeben, die Signatur wird aus den Template-Parametern abgeleitet.

Gibt die Methoden-ID zurück oder „ nullptr “, falls 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 zurück oder „ nullptr “, falls die Methode nicht gefunden wird.

Ein Anwendungsfall für diese Methode ist die Suche nach Klassenmethoden und das Zwischenspeichern ihrer IDs, damit diese später zum 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 oder „ nullptr “ zurück, 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 zurück oder „ nullptr “, falls das Feld nicht gefunden wird.

Ein Anwendungsfall für diese Methode ist die Suche nach Klassenfeldern und das Zwischenspeichern ihrer IDs, damit diese später zum Abrufen bzw. 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 ihren „ methodName “ angegeben, die Signatur wird aus den Template-Parametern abgeleitet.

Gibt die Methoden-ID oder ` nullptr ` zurück, 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 der Klasse „ clazz “. Die Methode wird durch ihren „ methodName “ und ihren „ signature “ angegeben.

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

Ein Anwendungsfall für diese Methode ist die Suche nach Klassenmethoden und das Zwischenspeichern ihrer IDs, damit diese später zum 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 an die Java-VM angehängt.

[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 pro Prozess möglicherweise mehrere Java-VMs vorhanden sein könnten, lässt Android nur eine zu.

JNIEnv *QJniEnvironment::jniEnv() const

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

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

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

Der Typ „ Class “ muss innerhalb des Namensraums „ QtJniTypes “ mithilfe des Makros „ Q_DECLARE_JNI_CLASS “ deklariert werden. Funktionen, die als freie C- oder C++-Funktionen implementiert sind, müssen mithilfe eines der Makros „ Q_DECLARE_JNI_NATIVE_METHOD “ deklariert und mithilfe des Makros „ Q_JNI_NATIVE_METHOD “ 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 Klassenmitgliedsfunktionen implementiert sind, verwenden Sie stattdessen das Makro „ 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)

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)

Registriert die Methoden der nativen Funktionen 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)

Registriert die Java-Methoden im Array ` methods ` der Größe ` size`, von denen jede native C++-Funktionen aus 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 Array „methods“ besteht aus:

• dem Java-Methodennamen
• Methodensignatur
• Die C++-Funktionen, die ausgeführt werden

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)

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

[static] QStringList QJniEnvironment::stackTrace(int exception)

Gibt den Stack-Trace zurück, der zum Auslösen des Ausnahmes „ exception “ geführt hat.

JNIEnv &QJniEnvironment::operator*() const

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

JNIEnv *QJniEnvironment::operator->() const

Bietet Zugriff auf den Zeiger „ JNIEnv “ der JNI-Umgebung.