QJniEnvironment Class

Documentation des fonctions membres

QJniEnvironment::QJniEnvironment()

Construit un nouvel objet Environnement JNI et rattache le thread actuel à la VM Java.

[noexcept] QJniEnvironment::~QJniEnvironment()

Détache le thread actuel de la VM Java et détruit l'objet QJniEnvironment. Ceci effacera toute exception en attente en appelant checkAndClearExceptions().

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

Efface toutes les exceptions en attente, soit silencieusement, soit en rapportant la trace de la pile, en fonction de outputMode.

Contrairement à QJniObject, qui gère les exceptions en interne, si vous faites des appels JNI directement via JNIEnv, vous devez supprimer toutes les exceptions potentielles après l'appel à l'aide de cette fonction. Pour plus d'informations sur les appels JNIEnv susceptibles de lever une exception, voir Fonctions JNI.

Renvoie true lorsqu'une exception en attente a été levée.

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

Efface toutes les exceptions en attente pour env, soit silencieusement, soit en rapportant la trace de pile, en fonction de outputMode. Cela est utile lorsque vous avez déjà un pointeur JNIEnv, comme dans l'implémentation d'une fonction native.

Contrairement à QJniObject, qui gère les exceptions en interne, si vous faites des appels JNI directement via JNIEnv, vous devez supprimer toutes les exceptions potentielles après l'appel à l'aide de cette fonction. Pour plus d'informations sur les appels à JNIEnv qui peuvent lever une exception, voir Fonctions JNI.

Renvoie true lorsqu'une exception en attente a été levée.

jclass QJniEnvironment::findClass(const char *className)

Recherche className à l'aide de tous les chargeurs de classe disponibles. Qt on Android utilise un chargeur de classe personnalisé pour charger tous les fichiers .jar et il doit être utilisé pour trouver toutes les classes qui sont créées par ce chargeur de classe parce que ces classes ne sont pas visibles lors de l'utilisation du chargeur de classe par défaut.

Renvoie le pointeur de classe ou null si className n'est pas trouvé.

Un cas d'utilisation de cette fonction est la recherche d'une classe pour appeler une méthode JNI qui prend un jclass. Cela peut être utile pour effectuer plusieurs appels JNI sur le même objet de classe, ce qui peut être un peu plus rapide que l'utilisation d'un nom de classe dans chaque appel. En outre, cet appel recherche d'abord les classes mises en cache en interne avant d'effectuer un appel JNI, et renvoie une telle classe si elle est trouvée. L'extrait de code suivant crée une instance de la classe CustomClass et appelle ensuite la méthode printFromJava():

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)

Recherche d'un champ membre d'une classe clazz. Le champ est spécifié par son fieldName. La signature du champ est déduite du paramètre de modèle.

Renvoie l'ID du champ ou nullptr si le champ n'est pas trouvé.

Cette fonction a été introduite dans Qt 6.4.

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

Recherche d'un champ membre d'une classe clazz. Le champ est spécifié par ses fieldName et signature.

Retourne l'ID du champ ou nullptr si le champ n'est pas trouvé.

Un cas d'utilisation de cette méthode est la recherche de champs de classe et la mise en cache de leurs identifiants, de sorte qu'ils puissent être utilisés ultérieurement pour obtenir/mettre en place les champs.

Cette fonction a été introduite dans Qt 6.2.

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

Recherche d'une méthode d'instance d'une classe clazz. La méthode est spécifiée par son methodName, la signature est déduite des paramètres du modèle.

Renvoie l'ID de la méthode ou nullptr si la méthode n'est pas trouvée.

Cette fonction a été introduite dans Qt 6.4.

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

Recherche d'une méthode d'instance d'une classe clazz. La méthode est spécifiée par ses methodName et signature.

Elle renvoie l'ID de la méthode ou nullptr si la méthode n'est pas trouvée.

Un cas d'utilisation de cette méthode est la recherche de méthodes de classe et la mise en cache de leurs identifiants, de sorte qu'ils puissent être utilisés ultérieurement pour appeler les méthodes.

Cette fonction a été introduite dans Qt 6.2.

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

Recherche d'un champ statique d'une classe clazz. Le champ est spécifié par son fieldName. La signature du champ est déduite du paramètre de modèle.

Renvoie l'ID du champ ou nullptr si le champ n'est pas trouvé.

Cette fonction a été introduite dans Qt 6.4.

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

Recherche d'un champ statique d'une classe clazz. Le champ est spécifié par ses fieldName et signature.

Retourne l'ID du champ ou nullptr si le champ n'est pas trouvé.

Un cas d'utilisation de cette méthode est la recherche de champs de classe et la mise en cache de leurs identifiants, de sorte qu'ils puissent être utilisés ultérieurement pour obtenir/mettre en place les champs.

Cette fonction a été introduite dans Qt 6.2.

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

Recherche d'une méthode d'instance d'une classe clazz. La méthode est spécifiée par son methodName, la signature est déduite des paramètres du modèle.

Renvoie l'ID de la méthode ou nullptr si la méthode n'est pas trouvée.

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

Cette fonction a été introduite dans Qt 6.4.

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

Recherche d'une méthode statique d'une classe clazz. La méthode est spécifiée par ses methodName et signature.

Elle renvoie l'ID de la méthode ou nullptr si la méthode n'est pas trouvée.

Un cas d'utilisation de cette méthode est la recherche de méthodes de classe et la mise en cache de leurs identifiants, de sorte qu'ils puissent être utilisés ultérieurement pour appeler les méthodes.

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

Cette fonction a été introduite dans Qt 6.2.

[static] JNIEnv *QJniEnvironment::getJniEnv()

Renvoie le pointeur JNIEnv pour le thread en cours.

Le thread courant sera attaché à la VM Java.

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

Renvoie true si cette instance contient un objet JNIEnv valide.

Cette fonction a été introduite dans Qt 6.2.

[static] JavaVM *QJniEnvironment::javaVM()

Renvoie l'interface de la VM Java pour le processus en cours. Bien qu'il soit possible d'avoir plusieurs VM Java par processus, Android n'en autorise qu'une seule.

JNIEnv *QJniEnvironment::jniEnv() const

Renvoie le pointeur JNIEnv de l'environnement JNI.

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

Enregistre les méthodes Java de methods avec la classe Java représentée par Class, et indique si l'enregistrement a réussi.

Le type Class doit être déclaré dans l'espace de noms QtJniTypes à l'aide de la macro Q_DECLARE_JNI_CLASS. Les fonctions mises en œuvre en tant que fonctions C ou C++ libres doivent être déclarées à l'aide de l'une des macros Q_DECLARE_JNI_NATIVE_METHOD et transmises à l'enregistrement à l'aide de la macro Q_JNI_NATIVE_METHOD.

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

Pour les fonctions qui sont implémentées en tant que fonctions statiques de membre de classe, utilisez plutôt la macro 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)

Enregistre les méthodes des fonctions natives dans methods pour la classe Java className. Retourne true si l'enregistrement est réussi, sinon false.

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

Enregistre les méthodes des fonctions natives dans methods pour la classe Java clazz. Retourne true si l'enregistrement est réussi, sinon false.

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

Enregistre les méthodes Java dans le tableau methods de taille size, chacune pouvant appeler des fonctions C++ natives de la classe className. Ces méthodes doivent être enregistrées avant toute tentative d'appel.

Retourne true si l'enregistrement est réussi, sinon false.

Chaque élément du tableau de méthodes se compose de

• le nom de la méthode Java
• la signature de la méthode
• Les fonctions C++ qui seront exécutées

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)

Cette surcharge utilise une instance de jclass précédemment mise en cache 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)

Renvoie la trace de la pile qui a entraîné l'envoi de exception.

JNIEnv &QJniEnvironment::operator*() const

Renvoie l'objet JNIEnv de l'environnement JNI.

JNIEnv *QJniEnvironment::operator->() const

Permet d'accéder au pointeur JNIEnv de l'environnement JNI.