QJniEnvironment Class

Documentación de las funciones miembro

QJniEnvironment::QJniEnvironment()

Construye un nuevo objeto Entorno JNI y adjunta el subproceso actual a la Java VM.

[noexcept] QJniEnvironment::~QJniEnvironment()

Desconecta el hilo actual de la Java VM y destruye el objeto QJniEnvironment. Esto borrará cualquier excepción pendiente llamando a checkAndClearExceptions().

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

Limpia cualquier excepción pendiente, ya sea silenciosamente o informando del seguimiento de la pila, dependiendo de outputMode.

A diferencia de QJniObject, que maneja las excepciones internamente, si realizas llamadas JNI directamente a través de JNIEnv, necesitas limpiar cualquier excepción potencial después de la llamada utilizando esta función. Para más información sobre las llamadas a JNIEnv que pueden lanzar una excepción, véase Funciones JNI.

Devuelve true cuando se borra una excepción pendiente.

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

Limpia cualquier excepción pendiente para env, ya sea silenciosamente o reportando el stack backtrace, dependiendo del outputMode. Esto es útil cuando ya se tiene un puntero JNIEnv como en la implementación de una función nativa.

En contraste con QJniObject, que maneja las excepciones internamente, si haces llamadas JNI directamente a través de JNIEnv, necesitas borrar cualquier excepción potencial después de la llamada usando esta función. Para más información sobre las llamadas a JNIEnv que pueden lanzar una excepción, consulte Funciones JNI.

Devuelve true cuando se borra una excepción pendiente.

jclass QJniEnvironment::findClass(const char *className)

Busca className utilizando todos los cargadores de clases disponibles. Qt en Android usa un cargador de clases personalizado para cargar todos los archivos .jar y debe ser usado para encontrar cualquier clase que sea creada por ese cargador de clases porque estas clases no son visibles cuando se usa el cargador de clases por defecto.

Devuelve el puntero de la clase o null si no se encuentra className.

Un caso de uso para esta función es buscar una clase para llamar a un método JNI que toma un jclass. Esto puede ser útil cuando se hacen múltiples llamadas JNI en el mismo objeto de clase que puede ser un poco más rápido que usar un nombre de clase en cada llamada. Además, esta llamada busca primero las clases almacenadas internamente en caché antes de realizar una llamada JNI, y devuelve dicha clase si la encuentra. El siguiente fragmento de código crea una instancia de la clase CustomClass y luego llama al método 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)

Busca un campo miembro de una clase clazz. El campo se especifica mediante su fieldName. La firma del campo se deduce del parámetro de la plantilla.

Devuelve el ID del campo o nullptr si no se encuentra el campo.

Esta función se introdujo en Qt 6.4.

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

Busca un campo miembro de una clase clazz. El campo se especifica mediante fieldName y signature.

Devuelve el ID del campo o nullptr si no se encuentra el campo.

Un caso de uso para este método es la búsqueda de campos de clase y el almacenamiento en caché de sus IDs, de modo que puedan ser utilizados más tarde para obtener/establecer los campos.

Esta función se introdujo en Qt 6.2.

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

Busca un método de instancia de una clase clazz. El método se especifica mediante su methodName, la firma se deduce de los parámetros de la plantilla.

Devuelve el ID del método o nullptr si no se encuentra el método.

Esta función se introdujo en Qt 6.4.

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

Busca un método de instancia de una clase clazz. El método se especifica mediante methodName y signature.

Devuelve el ID del método o nullptr si no se encuentra el método.

Un caso de uso para este método es la búsqueda de métodos de clase y el almacenamiento en caché de sus IDs, de modo que puedan ser utilizados posteriormente para llamar a los métodos.

Esta función se introdujo en Qt 6.2.

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

Busca un campo estático de una clase clazz. El campo se especifica mediante su fieldName. La firma del campo se deduce del parámetro de la plantilla.

Devuelve el ID del campo o nullptr si no se encuentra el campo.

Esta función se introdujo en Qt 6.4.

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

Busca un campo estático de una clase clazz. El campo se especifica mediante fieldName y signature.

Devuelve el ID del campo o nullptr si no se encuentra el campo.

Un caso de uso para este método es la búsqueda de campos de clase y el almacenamiento en caché de sus IDs, de modo que puedan ser utilizados más tarde para obtener/establecer los campos.

Esta función se introdujo en Qt 6.2.

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

Busca un método de instancia de una clase clazz. El método se especifica mediante su methodName, la firma se deduce de los parámetros de la plantilla.

Devuelve el ID del método o nullptr si no se encuentra el método.

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

Esta función se introdujo en Qt 6.4.

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

Busca un método estático de una clase clazz. El método se especifica mediante methodName y signature.

Devuelve el ID del método o nullptr si no se encuentra el método.

Un caso de uso para este método es la búsqueda de métodos de clase y el almacenamiento en caché de sus IDs, de modo que puedan ser utilizados posteriormente para llamar a los métodos.

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

Esta función se introdujo en Qt 6.2.

[static] JNIEnv *QJniEnvironment::getJniEnv()

Devuelve el puntero JNIEnv del subproceso actual.

El hilo actual se adjuntará a la Java VM.

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

Devuelve true si esta instancia contiene un objeto JNIEnv válido.

Esta función se introdujo en Qt 6.2.

[static] JavaVM *QJniEnvironment::javaVM()

Devuelve la interfaz Java VM para el proceso actual. Aunque podría ser posible tener múltiples Java VMs por proceso, Android sólo permite una.

JNIEnv *QJniEnvironment::jniEnv() const

Devuelve el puntero JNIEnv del entorno JNI.

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

Registra los métodos Java en methods con la clase Java representada por Class, y devuelve si el registro se ha realizado correctamente.

El tipo Class debe declararse dentro del espacio de nombres QtJniTypes utilizando la macro Q_DECLARE_JNI_CLASS. Las funciones implementadas como funciones libres de C o C++ deben declararse utilizando una de las macros Q_DECLARE_JNI_NATIVE_METHOD, y pasarse al registro utilizando 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);
}

Para las funciones implementadas como funciones estáticas de clase, utilice en su lugar 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)

Registra los métodos de las funciones nativas en methods para la clase Java className. Devuelve true si el registro se ha realizado correctamente, en caso contrario false.

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

Registra los métodos de las funciones nativas en methods para la clase Java clazz. Devuelve true si el registro se ha realizado correctamente, en caso contrario false.

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

Registra los métodos Java en el array methods de tamaño size, cada uno de los cuales puede llamar a funciones nativas C++ de la clase className. Estos métodos deben ser registrados antes de cualquier intento de llamarlos.

Devuelve true si el registro se ha realizado correctamente, en caso contrario false.

Cada elemento de la matriz de métodos consta de:

• El nombre del método Java
• La firma del método
• Las funciones C++ que se ejecutarán

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)

Esta sobrecarga utiliza una instancia de jclass previamente almacenada en caché 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)

Devuelve el seguimiento de pila que dio lugar al lanzamiento de exception.

JNIEnv &QJniEnvironment::operator*() const

Devuelve el objeto JNIEnv del entorno JNI.

JNIEnv *QJniEnvironment::operator->() const

Proporciona acceso al puntero JNIEnv del entorno JNI.