QJniEnvironment Class

Documentation des fonctions membres

QJniEnvironment::QJniEnvironment()

Crée un nouvel objet JNI Environment et associe le thread actuel à la machine virtuelle Java.

[noexcept] QJniEnvironment::~QJniEnvironment()

Détache le thread actif de la machine virtuelle Java et détruit l'objet ` QJniEnvironment `. Cela effacera toute exception en attente en appelant la méthode ` checkAndClearExceptions()`.

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

Nettoie toutes les exceptions en attente, soit de manière silencieuse, soit en affichant la trace de la pile, selon la valeur de ` outputMode`.

Contrairement à ` QJniObject`, qui gère les exceptions en interne, si vous effectuez des appels JNI directement via ` JNIEnv`, vous devez effacer toute exception potentielle après l’appel à l’aide de cette fonction. Pour plus d’informations sur les appels ` JNIEnv ` susceptibles de lever une exception, consultez la section Fonctions JNI.

Renvoie ` true ` lorsqu’une exception en attente a été effacée.

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

Nettoie toutes les exceptions en attente pour env, soit de manière silencieuse, soit en affichant la trace de la pile, selon la valeur de outputMode. Cela s'avère utile lorsque vous disposez déjà d'un pointeur JNIEnv, par exemple dans l'implémentation d'une fonction native.

Contrairement à ` QJniObject`, qui gère les exceptions en interne, si vous effectuez des appels JNI directement via ` JNIEnv`, vous devez effacer 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, consultez la section Fonctions JNI.

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

jclass QJniEnvironment::findClass(const char *className)

Recherche « className » à l'aide de tous les chargeurs de classes disponibles. Qt sur Android utilise un chargeur de classes personnalisé pour charger tous les fichiers .jar ; il est nécessaire de l'utiliser pour trouver les classes créées par ce chargeur, car celles-ci ne sont pas visibles avec le chargeur de classes par défaut.

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

Cette fonction peut notamment servir à rechercher une classe afin d’appeler une méthode JNI qui prend un ` jclass` en paramètre. Cela peut s’avérer utile lors de l’exécution de plusieurs appels JNI sur le même objet de classe, ce qui peut être légèrement plus rapide que d’utiliser un nom de classe à chaque appel. De plus, 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 `, puis appelle 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 un champ membre d'une classe clazz. Le champ est spécifié par son fieldName. La signature du champ est déduite à partir du paramètre de modèle.

Renvoie l’ID du champ ou nullptr si le champ est introuvable.

Cette fonction a été introduite dans Qt 6.4.

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

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

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

Cette méthode peut notamment servir à rechercher des champs de classe et à mettre en cache leurs identifiants, afin de pouvoir les utiliser ultérieurement pour lire ou modifier ces 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 une méthode d'instance d'une classe clazz. La méthode est spécifiée par son methodName; la signature est déduite à partir des paramètres de modèle.

Renvoie l'ID de la méthode ou nullptr si la méthode est introuvable.

Cette fonction a été introduite dans Qt 6.4.

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

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

Renvoie l'ID de la méthode ou nullptr si la méthode est introuvable.

Cette méthode peut notamment servir à rechercher des méthodes de classe et à mettre en cache leurs identifiants, afin de pouvoir les utiliser ultérieurement pour appeler ces 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 un champ statique d'une classe clazz. Le champ est spécifié par son fieldName. La signature du champ est déduite à partir 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 un champ statique d'une classe clazz. Le champ est spécifié par son fieldName et son signature.

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

Cette méthode peut notamment servir à rechercher des champs de classe et à mettre en cache leurs identifiants, afin de pouvoir les utiliser ultérieurement pour lire ou modifier ces 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 une méthode d'instance d'une classe clazz. La méthode est spécifiée par son methodName; la signature est déduite à partir des paramètres de modèle.

Renvoie l'ID de la méthode ou nullptr si la méthode est introuvable.

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 une méthode statique d'une classe clazz. La méthode est identifiée par son methodName et son signature.

Renvoie l'ID de la méthode ou nullptr si la méthode est introuvable.

Cette méthode peut notamment servir à rechercher des méthodes de classe et à mettre en cache leurs identifiants, afin de pouvoir les utiliser ultérieurement pour appeler ces 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 correspondant au thread actuel.

Le thread actuel sera associé à la machine virtuelle 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 machine virtuelle Java (VM) pour le processus en cours. Bien qu'il soit théoriquement possible d'avoir plusieurs machines virtuelles 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 dans methods avec la classe Java représentée par Class, et indique si l'enregistrement a abouti.

Le type ` Class ` doit être déclaré dans l’espace de noms ` QtJniTypes ` à l’aide de la macro ` Q_DECLARE_JNI_CLASS `. Les fonctions implémentées en tant que fonctions libres C ou C++ doivent être déclarées à l’aide de l’une des macros ` Q_DECLARE_JNI_NATIVE_METHOD `, puis 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 implémentées en tant que fonctions membres statiques d’une 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`. Renvoie ` true ` si l'enregistrement a 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. Renvoie true si l'enregistrement réussit, sinon false.

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

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

Renvoie ` true ` si l'enregistrement a réussi, sinon ` false`.

Chaque élément du tableau `methods` 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 conduit au lancement de l'exception « 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.