QJniEnvironment Class
La clase QJniEnvironment permite acceder al entorno JNI (JNIEnv). Más información...
| Encabezado: | #include <QJniEnvironment> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake: | QT += core |
| Desde: | Qt 6.1 |
Tipos públicos
| enum class | OutputMode { Silent, Verbose } |
Funciones públicas
| QJniEnvironment() | |
| ~QJniEnvironment() | |
| bool | checkAndClearExceptions(QJniEnvironment::OutputMode outputMode = OutputMode::Verbose) |
| jclass | findClass(const char *className) |
(since 6.4) jfieldID | findField(jclass clazz, const char *fieldName) |
(since 6.2) jfieldID | findField(jclass clazz, const char *fieldName, const char *signature) |
(since 6.4) jmethodID | findMethod(jclass clazz, const char *methodName) |
(since 6.2) jmethodID | findMethod(jclass clazz, const char *methodName, const char *signature) |
(since 6.4) jfieldID | findStaticField(jclass clazz, const char *fieldName) |
(since 6.2) jfieldID | findStaticField(jclass clazz, const char *fieldName, const char *signature) |
(since 6.4) jmethodID | findStaticMethod(jclass clazz, const char *methodName) |
(since 6.2) jmethodID | findStaticMethod(jclass clazz, const char *methodName, const char *signature) |
(since 6.2) bool | isValid() const |
| JNIEnv * | jniEnv() const |
| bool | registerNativeMethods(std::initializer_list<JNINativeMethod> methods) |
| bool | registerNativeMethods(const char *className, std::initializer_list<JNINativeMethod> methods) |
| bool | registerNativeMethods(jclass clazz, std::initializer_list<JNINativeMethod> methods) |
| bool | registerNativeMethods(const char *className, const JNINativeMethod[] methods, int size) |
| bool | registerNativeMethods(jclass clazz, const JNINativeMethod[] methods, int size) |
| JNIEnv & | operator*() const |
| JNIEnv * | operator->() const |
Miembros públicos estáticos
| bool | checkAndClearExceptions(JNIEnv *env, QJniEnvironment::OutputMode outputMode = OutputMode::Verbose) |
| JNIEnv * | getJniEnv() |
| JavaVM * | javaVM() |
| QStringList | stackTrace(int exception) |
Descripción detallada
Al utilizar JNI, la clase `JNIEnv ` es un puntero a una tabla de funciones y a una función miembro para cada función JNI que se accede de forma indirecta a través de la tabla. ` JNIEnv ` proporciona la mayoría de las funciones JNI. Cada función nativa de C++ recibe un ` JNIEnv ` como primer argumento. El entorno JNI no se puede compartir entre subprocesos.
Dado que JNIEnv no realiza muchas comprobaciones de errores, como la comprobación y la limpieza de excepciones, QJniEnvironment te permite hacerlo fácilmente.
Para obtener más información sobre JNIEnv, consulta Java: Tabla de funciones de interfaz.
Nota: Esta API se ha diseñado y probado para su uso con Android. No se ha probado en otras plataformas.
Documentación sobre los tipos de miembros
enum class QJniEnvironment::OutputMode
| Constante | Valor | Descripción |
|---|---|---|
QJniEnvironment::OutputMode::Silent | 0 | Las excepciones se eliminan de forma silenciosa |
QJniEnvironment::OutputMode::Verbose | 1 | Imprime las excepciones y su traza de pila como un error en un flujo de stderr. |
Documentación de funciones de miembro
QJniEnvironment::QJniEnvironment()
Crea un nuevo objeto «JNI Environment» y vincula el hilo actual a la máquina virtual de Java.
[noexcept] QJniEnvironment::~QJniEnvironment()
Desvincula el hilo actual de la máquina virtual de Java y destruye el objeto ` QJniEnvironment `. Esto eliminará cualquier excepción pendiente mediante la llamada a ` checkAndClearExceptions()`.
bool QJniEnvironment::checkAndClearExceptions(QJniEnvironment::OutputMode outputMode = OutputMode::Verbose)
Limpia cualquier excepción pendiente, ya sea de forma silenciosa o mostrando el seguimiento de la pila, dependiendo de la propiedad ` outputMode`.
A diferencia de ` QJniObject`, que gestiona las excepciones internamente, si se realizan llamadas JNI directamente a través de ` JNIEnv`, es necesario limpiar cualquier excepción potencial tras la llamada utilizando esta función. Para obtener más información sobre las llamadas ` JNIEnv ` que pueden lanzar una excepción, consulte Funciones JNI.
Devuelve ` true ` cuando se ha eliminado una excepción pendiente.
[static] bool QJniEnvironment::checkAndClearExceptions(JNIEnv *env, QJniEnvironment::OutputMode outputMode = OutputMode::Verbose)
Limpia cualquier excepción pendiente de env, ya sea de forma silenciosa o mostrando el seguimiento de la pila, dependiendo de outputMode. Esto resulta útil cuando ya se dispone de un puntero JNIEnv, como en la implementación de una función nativa.
A diferencia de ` QJniObject`, que gestiona las excepciones internamente, si se realizan llamadas JNI directamente a través de ` JNIEnv`, es necesario borrar cualquier excepción potencial tras la llamada utilizando esta función. Para obtener más información sobre las llamadas ` JNIEnv ` que pueden lanzar una excepción, consulte Funciones JNI.
Devuelve ` true ` cuando se ha eliminado una excepción pendiente.
jclass QJniEnvironment::findClass(const char *className)
Busca « className » utilizando todos los cargadores de clases disponibles. Qt en Android utiliza un cargador de clases personalizado para cargar todos los archivos .jar, y es necesario utilizarlo para encontrar cualquier clase creada por dicho cargador, ya que estas clases no son visibles cuando se utiliza el cargador de clases predeterminado.
Devuelve el puntero a la clase o null si no se encuentra className.
Un caso de uso de esta función es la búsqueda de una clase para llamar a un método JNI que tome un jclass. Esto puede resultar útil al realizar múltiples llamadas JNI sobre el mismo objeto de clase, lo que puede resultar algo más rápido que utilizar un nombre de clase en cada llamada. Además, esta llamada busca primero las clases almacenadas en la caché interna 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, a continuación, 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>());Nota: Esta llamada devuelve una referencia global al objeto de clase procedente de las clases almacenadas en la caché interna.
[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 a partir del parámetro de 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 su fieldName y su signature.
Devuelve el ID del campo o nullptr si no se encuentra el campo.
Un caso de uso de este método es buscar campos de clase y almacenar sus ID en caché, para poder utilizarlos posteriormente a la hora de obtener o establecer los valores de dichos 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 a partir de los parámetros de 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 su methodName y su signature.
Devuelve el ID del método o nullptr si no se encuentra el método.
Un caso de uso de este método es buscar métodos de clase y almacenar sus ID en caché, para poder utilizarlos posteriormente a la hora de llamar a dichos 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 a partir del parámetro de 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 su fieldName y su signature.
Devuelve el ID del campo o nullptr si no se encuentra el campo.
Un caso de uso de este método es buscar campos de clase y almacenar en caché sus ID, para poder utilizarlos posteriormente a la hora de obtener o establecer los valores de dichos 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 a partir de los parámetros de 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 su methodName y su signature.
Devuelve el identificador del método o nullptr si no se encuentra el método.
Un caso de uso de este método es la búsqueda de métodos de clase y el almacenamiento en caché de sus ID, para poder utilizarlos posteriormente a la hora de llamar a dichos 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 hilo actual.
El hilo actual quedará vinculado a la máquina virtual de Java.
[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 de la máquina virtual de Java (Java VM) del proceso actual. Aunque podría haber varias máquinas virtuales de Java por proceso, Android solo 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 mediante 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 que se implementan como funciones miembro estáticas de una 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)
});Esta es una función sobrecargada.
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 realiza correctamente; en caso contrario, devuelve false.
Esta es una función sobrecargada.
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 realiza correctamente; en caso contrario, devuelve false.
Esta es una función sobrecargada.
bool QJniEnvironment::registerNativeMethods(const char *className, const JNINativeMethod[] methods, int size)
Registra los métodos Java del array methods, de tamaño size, cada uno de los cuales puede llamar a funciones nativas de C++ de la clase className. Estos métodos deben registrarse antes de intentar llamarlos.
Devuelve true si el registro se realiza correctamente; en caso contrario, devuelve false.
Cada elemento de la matriz de métodos consta de:
- El nombre del método Java
- La firma del método
- Las funciones de 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);Se trata de una función sobrecargada.
bool QJniEnvironment::registerNativeMethods(jclass clazz, const JNINativeMethod[] methods, int size)
Esta sobrecarga utiliza una instancia de `jclass` almacenada previamente en la 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);Se trata de una función sobrecargada.
[static] QStringList QJniEnvironment::stackTrace(int exception)
Devuelve la traza de pila que provocó que se lanzara la excepción « exception ».
JNIEnv &QJniEnvironment::operator*() const
Devuelve el objeto ` JNIEnv ` del entorno JNI.
JNIEnv *QJniEnvironment::operator->() const
Proporciona acceso al puntero « JNIEnv » del entorno JNI.
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.