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)

`env` に対して保留中の例外を、outputMode の設定に応じて、静かに処理するか、スタックトレースを報告して処理します。これは、ネイティブ関数の実装など、すでに `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` によって指定されます。フィールドのシグネチャは、テンプレートパラメータから推論されます。

フィールドが見つからない場合はフィールド ID または `nullptr ` を返します。

この関数は Qt 6.4 で導入されました。

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

クラス `clazz` のメンバーフィールドを検索します。フィールドは、fieldName およびsignature によって指定されます。

フィールドが見つかった場合はフィールドの ID を返し、見つからない場合は `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 によって指定されます。

メソッドが見つかった場合はそのメソッドIDを返し、見つからない場合はnullptr を返します。

このメソッドのユースケースとして、クラスメソッドを検索し、その ID をキャッシュしておくことが挙げられます。これにより、後でそのメソッドを呼び出す際に利用できます。

この関数は Qt 6.2 で導入されました。

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

clazz クラスの静的フィールドを検索します。フィールドは、そのfieldName によって指定されます。フィールドのシグネチャは、テンプレートパラメータから推論されます。

フィールドが見つかった場合はフィールド ID を返し、見つからない場合は `nullptr ` を返します。

この関数は Qt 6.4 で導入されました。

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

clazz クラスの静的フィールドを検索します。このフィールドは、fieldName およびsignature によって指定されます。

フィールドが見つかった場合はフィールド ID を返し、見つからない場合は `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インターフェースを返します。1つのプロセスにつき複数のJava VMが存在する可能性はありますが、Androidでは1つしか許可されていません。

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` を返します。

methods配列の各要素は、以下の構成となっています：

• 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 ポインタへのアクセスを提供します。