QJniEnvironment Class

멤버 함수 문서

QJniEnvironment::QJniEnvironment()

새로운 JNI Environment 객체를 생성하고, 현재 스레드를 Java VM에 연결합니다.

[noexcept] QJniEnvironment::~QJniEnvironment()

현재 스레드를 Java VM에서 분리하고 ` QJniEnvironment ` 객체를 소멸시킵니다. 이 작업은 ` checkAndClearExceptions()`를 호출하여 보류 중인 모든 예외를 해제합니다.

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

outputMode 에 따라 보류 중인 예외를 조용히 처리하거나 스택 백트레이스를 보고합니다.

예외를 내부적으로 처리하는 ` QJniObject`와 달리, ` JNIEnv`를 통해 JNI 호출을 직접 수행하는 경우, 호출 후 이 함수를 사용하여 발생할 수 있는 예외를 모두 해제해야 합니다. 예외를 발생시킬 수 있는 ` JNIEnv ` 호출에 대한 자세한 내용은 JNI 함수를 참조하십시오.

보류 중인 예외가 처리되면 true 를 반환합니다.

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

outputMode 에 따라, env 에 대한 보류 중인 예외를 조용히 처리하거나 스택 백트레이스를 보고하며 정리합니다. 이는 네이티브 함수 구현과 같이 이미 JNIEnv 포인터가 있는 경우에 유용합니다.

예외를 내부적으로 처리하는 ` QJniObject`와 달리, ` JNIEnv`를 통해 JNI 호출을 직접 수행하는 경우, 호출 후 이 함수를 사용하여 발생할 수 있는 예외를 모두 해제해야 합니다. 예외를 발생시킬 수 있는 ` JNIEnv ` 호출에 대한 자세한 내용은 JNI 함수를 참조하십시오.

보류 중인 예외가 해제되면 true 를 반환합니다.

jclass QJniEnvironment::findClass(const char *className)

사용 가능한 모든 클래스 로더를 사용하여 ` className `를 검색합니다. Android용 Qt는 모든 .jar 파일을 로드하기 위해 사용자 정의 클래스 로더를 사용하며, 해당 클래스 로더에 의해 생성된 클래스를 찾으려면 이 사용자 정의 클래스 로더를 반드시 사용해야 합니다. 기본 클래스 로더를 사용할 경우 이러한 클래스는 표시되지 않기 때문입니다.

className 를 찾으면 클래스 포인터를 반환하고, 찾지 못하면 null을 반환합니다.

이 함수의 사용 사례 중 하나는 jclass 를 인수로 받는 JNI 메서드를 호출하기 위해 클래스를 검색하는 것입니다. 이는 동일한 클래스 객체에 대해 여러 번 JNI 호출을 수행할 때 유용하며, 호출할 때마다 클래스 이름을 사용하는 것보다 약간 더 빠를 수 있습니다. 또한, 이 호출은 JNI 호출을 수행하기 전에 먼저 내부적으로 캐시된 클래스를 검색하며, 발견되면 해당 클래스를 반환합니다. 다음 코드 조각은 CustomClass 클래스의 인스턴스를 생성한 다음 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)

clazz 클래스의 멤버 필드를 검색합니다. 필드는 fieldName 로 지정됩니다. 필드의 시그니처는 템플릿 매개변수에서 추론됩니다.

필드를 반환하거나, 필드를 찾을 수 없는 경우 nullptr 를 반환합니다.

이 함수는 Qt 6.4에서 도입되었습니다.

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

clazz 클래스의 멤버 필드를 검색합니다. 필드는 fieldName 및 signature 로 지정됩니다.

필드를 반환하거나, 필드를 찾을 수 없는 경우 nullptr 를 반환합니다.

이 메서드의 사용 사례로는 클래스 필드를 검색하고 해당 ID를 캐싱하여, 나중에 필드를 가져오거나 설정하는 데 사용할 수 있도록 하는 것입니다.

이 함수는 Qt 6.2에서 도입되었습니다.

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

clazz 클래스의 인스턴스 메서드를 검색합니다. 메서드는 methodName 로 지정되며, 시그니처는 템플릿 매개변수로부터 추론됩니다.

메서드 ID를 반환하며, 메서드를 찾을 수 없는 경우 nullptr 를 반환합니다.

이 함수는 Qt 6.4에서 도입되었습니다.

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

clazz 클래스의 인스턴스 메서드를 검색합니다. 메서드는 methodName 및 signature 로 지정됩니다.

메서드를 반환하거나, 메서드를 찾을 수 없는 경우 nullptr 를 반환합니다.

이 메서드의 사용 사례로는 클래스 메서드를 검색하여 해당 ID를 캐싱해 두었다가, 나중에 메서드 호출에 활용하는 것이 있습니다.

이 함수는 Qt 6.2에서 도입되었습니다.

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

clazz 클래스의 정적 필드를 검색합니다. 필드는 fieldName 로 지정됩니다. 필드의 시그니처는 템플릿 매개변수에서 추론됩니다.

필드를 반환하거나, 필드를 찾을 수 없는 경우 nullptr 를 반환합니다.

이 함수는 Qt 6.4에서 도입되었습니다.

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

clazz 클래스의 정적 필드를 검색합니다. 필드는 fieldName 및 signature 로 지정됩니다.

필드를 반환하거나, 필드를 찾을 수 없는 경우 nullptr 를 반환합니다.

이 메서드의 사용 사례로는 클래스 필드를 검색하고 해당 ID를 캐싱하여, 나중에 필드를 가져오거나 설정하는 데 사용할 수 있도록 하는 것입니다.

이 함수는 Qt 6.2에서 도입되었습니다.

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

clazz 클래스의 인스턴스 메서드를 검색합니다. 메서드는 methodName 로 지정되며, 시그니처는 템플릿 매개변수에서 추론됩니다.

메서드 ID를 반환하며, 메서드를 찾을 수 없는 경우 ` nullptr `을 반환합니다.

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

이 함수는 Qt 6.4에서 도입되었습니다.

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

clazz 클래스의 정적 메서드를 검색합니다. 메서드는 methodName 와 signature 를 통해 지정됩니다.

메서드를 찾으면 메서드 ID를 반환하고, 찾지 못하면 nullptr 를 반환합니다.

이 메서드의 사용 사례로는 클래스 메서드를 검색하고 해당 ID를 캐싱하여, 나중에 메서드 호출에 사용할 수 있도록 하는 것이 있습니다.

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

이 함수는 Qt 6.2에서 도입되었습니다.

[static] JNIEnv *QJniEnvironment::getJniEnv()

현재 스레드에 대한 JNIEnv 포인터를 반환합니다.

현재 스레드는 Java VM에 연결됩니다.

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

이 인스턴스가 유효한 JNIEnv 객체를 보유하고 있는 경우 true 를 반환합니다.

이 함수는 Qt 6.2에서 도입되었습니다.

[static] JavaVM *QJniEnvironment::javaVM()

현재 프로세스에 대한 Java VM 인터페이스를 반환합니다. 프로세스당 여러 개의 Java VM을 가질 수도 있지만, Android에서는 하나만 허용합니다.

JNIEnv *QJniEnvironment::jniEnv() const

JNI 환경의 ` JNIEnv ` 포인터를 반환합니다.

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

methods 에 있는 Java 메서드를 Class 로 표시되는 Java 클래스에 등록하고, 등록이 성공했는지 여부를 반환합니다.

Class 유형은 Q_DECLARE_JNI_CLASS 매크로를 사용하여 QtJniTypes 네임스페이스 내에서 선언되어야 합니다. 자유 C 또는 C++ 함수로 구현된 함수는 Q_DECLARE_JNI_NATIVE_METHOD 매크로 중 하나를 사용하여 선언해야 하며, 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);
}

정적 클래스 멤버 함수로 구현된 함수의 경우, 대신 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)

Java 클래스 ` className`에 대한 네이티브 함수 메서드를 ` methods `에 등록합니다. 등록에 성공하면 ` true `을 반환하고, 그렇지 않으면 ` false`을 반환합니다.

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

Java 클래스 ` clazz`에 대한 네이티브 함수 메서드를 ` methods `에 등록합니다. 등록에 성공하면 ` true `을 반환하고, 그렇지 않으면 ` false`을 반환합니다.

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

size 크기의 배열 methods 에 포함된 Java 메서드들을 등록합니다. 각 메서드는 className 클래스의 네이티브 C++ 함수를 호출할 수 있습니다. 이러한 메서드들은 호출하기 전에 반드시 등록되어야 합니다.

등록에 성공하면 true 을 반환하고, 그렇지 않으면 false 을 반환합니다.

메서드 배열의 각 요소는 다음으로 구성됩니다:

• Java 메서드 이름
• 메서드 시그니처
• 실행될 C++ 함수

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)

이 오버로드는 이전에 캐시된 jclass 인스턴스 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)

exception 예외가 발생하게 된 스택 트레이스를 반환합니다.

JNIEnv &QJniEnvironment::operator*() const

JNI 환경의 ` JNIEnv ` 객체를 반환합니다.

JNIEnv *QJniEnvironment::operator->() const

JNI 환경의 ` JNIEnv ` 포인터에 대한 액세스를 제공합니다.