第4章: JNI関数
この章は、JNI関数のリファレンス・セクションです。 この章では、JNIの関数をすべて取り上げます。 また、JNI関数表の配置そのままに記載されています。
この用語の使用は、JNIプログラマの制限事項を説明するものでなければならないことに注意してください。 たとえば、あるJNI関数について、それがNULL以外のオブジェクトを受け取る必要があると説明されている場合、プログラマの責任において、そのJNI関数にNULLを渡さないようにしなければなりません。 それによって、JNI実装の際に、そのJNI関数におけるnullのポインタ・チェックを行う必要がなくなります。 明示的でないときにNULLを渡すと、予期しない例外や致命的なクラッシュが発生する可能性があります。
定義がNULL
を返すことがあり、エラー時に例外をスローする関数は、エラーを示すためにNULL
を返すだけで、例外をスローすることはできません。 たとえば、JNIの実装では、一時的に"メモリー不足"条件が発生すると見なすことがあり、OutOfMemoryError
をスローしたくない場合があります。これは致命的な(JDK API java.lang.Error
documentation: "合理的なアプリケーションがキャッチしようとすべきではない深刻な問題を示しています")と思われるためです。
この章の一部は、NetscapeのJRIドキュメントから転用されています。
参照資料では、関数を用途によってグループ化しています。 参照セクションは、次の機能分野から構成されています。
- インタフェース関数表
- 定数
- バージョン情報
- クラス操作
- モジュールの操作
- スレッド演算
- 例外
- グローバル参照およびローカル参照
- 弱グローバル参照
- オブジェクト・オペレーション
- オブジェクトのフィールドへのアクセス
- インスタンス・メソッドの呼び出し
- staticフィールドへのアクセス
- staticメソッドの呼び出し
- 文字列操作
- 配列操作
- GetArrayLength
- NewObjectArray
- GetObjectArrayElement
- SetObjectArrayElement
- New<PrimitiveType>Arrayルーチン
- Get<PrimitiveType>ArrayElementsルーチン
- Release<PrimitiveType>ArrayElementsルーチン
- Get<PrimitiveType>ArrayRegionルーチン
- Set<PrimitiveType>ArrayRegionルーチン
- GetPrimitiveArrayCritical、ReleasePrimitiveArrayCritical
- ネイティブ・メソッドの登録
- モニター・オペレーション
- NIOのサポート
- リフレクションのサポート
- Java VMインタフェース
インタフェース関数表
各関数は、JNIEnv引数を介して、固定オフセットからアクセスできます。 JNIEnv型は、すべてのJNI関数のポインタを格納する構造体を指すポインタです。 次のように定義されます:
typedef const struct JNINativeInterface *JNIEnv;
VMは、次のコード例に示されているように、関数表を初期化します。 最初の3エントリは、将来のCOMとの互換性のために予約されています。 さらに、関数表の始めの近くにいくつかの追加のNULL
エントリを予約してあるため、たとえば、これから現れるクラス関連のJNI演算は、表の終わりではなくFindClassのあとに追加できます。
関数表は、すべてのJNIインタフェース・ポインタの間で共用されます。
const struct JNINativeInterface ... = {
NULL,
NULL,
NULL,
NULL,
GetVersion,
DefineClass,
FindClass,
FromReflectedMethod,
FromReflectedField,
ToReflectedMethod,
GetSuperclass,
IsAssignableFrom,
ToReflectedField,
Throw,
ThrowNew,
ExceptionOccurred,
ExceptionDescribe,
ExceptionClear,
FatalError,
PushLocalFrame,
PopLocalFrame,
NewGlobalRef,
DeleteGlobalRef,
DeleteLocalRef,
IsSameObject,
NewLocalRef,
EnsureLocalCapacity,
AllocObject,
NewObject,
NewObjectV,
NewObjectA,
GetObjectClass,
IsInstanceOf,
GetMethodID,
CallObjectMethod,
CallObjectMethodV,
CallObjectMethodA,
CallBooleanMethod,
CallBooleanMethodV,
CallBooleanMethodA,
CallByteMethod,
CallByteMethodV,
CallByteMethodA,
CallCharMethod,
CallCharMethodV,
CallCharMethodA,
CallShortMethod,
CallShortMethodV,
CallShortMethodA,
CallIntMethod,
CallIntMethodV,
CallIntMethodA,
CallLongMethod,
CallLongMethodV,
CallLongMethodA,
CallFloatMethod,
CallFloatMethodV,
CallFloatMethodA,
CallDoubleMethod,
CallDoubleMethodV,
CallDoubleMethodA,
CallVoidMethod,
CallVoidMethodV,
CallVoidMethodA,
CallNonvirtualObjectMethod,
CallNonvirtualObjectMethodV,
CallNonvirtualObjectMethodA,
CallNonvirtualBooleanMethod,
CallNonvirtualBooleanMethodV,
CallNonvirtualBooleanMethodA,
CallNonvirtualByteMethod,
CallNonvirtualByteMethodV,
CallNonvirtualByteMethodA,
CallNonvirtualCharMethod,
CallNonvirtualCharMethodV,
CallNonvirtualCharMethodA,
CallNonvirtualShortMethod,
CallNonvirtualShortMethodV,
CallNonvirtualShortMethodA,
CallNonvirtualIntMethod,
CallNonvirtualIntMethodV,
CallNonvirtualIntMethodA,
CallNonvirtualLongMethod,
CallNonvirtualLongMethodV,
CallNonvirtualLongMethodA,
CallNonvirtualFloatMethod,
CallNonvirtualFloatMethodV,
CallNonvirtualFloatMethodA,
CallNonvirtualDoubleMethod,
CallNonvirtualDoubleMethodV,
CallNonvirtualDoubleMethodA,
CallNonvirtualVoidMethod,
CallNonvirtualVoidMethodV,
CallNonvirtualVoidMethodA,
GetFieldID,
GetObjectField,
GetBooleanField,
GetByteField,
GetCharField,
GetShortField,
GetIntField,
GetLongField,
GetFloatField,
GetDoubleField,
SetObjectField,
SetBooleanField,
SetByteField,
SetCharField,
SetShortField,
SetIntField,
SetLongField,
SetFloatField,
SetDoubleField,
GetStaticMethodID,
CallStaticObjectMethod,
CallStaticObjectMethodV,
CallStaticObjectMethodA,
CallStaticBooleanMethod,
CallStaticBooleanMethodV,
CallStaticBooleanMethodA,
CallStaticByteMethod,
CallStaticByteMethodV,
CallStaticByteMethodA,
CallStaticCharMethod,
CallStaticCharMethodV,
CallStaticCharMethodA,
CallStaticShortMethod,
CallStaticShortMethodV,
CallStaticShortMethodA,
CallStaticIntMethod,
CallStaticIntMethodV,
CallStaticIntMethodA,
CallStaticLongMethod,
CallStaticLongMethodV,
CallStaticLongMethodA,
CallStaticFloatMethod,
CallStaticFloatMethodV,
CallStaticFloatMethodA,
CallStaticDoubleMethod,
CallStaticDoubleMethodV,
CallStaticDoubleMethodA,
CallStaticVoidMethod,
CallStaticVoidMethodV,
CallStaticVoidMethodA,
GetStaticFieldID,
GetStaticObjectField,
GetStaticBooleanField,
GetStaticByteField,
GetStaticCharField,
GetStaticShortField,
GetStaticIntField,
GetStaticLongField,
GetStaticFloatField,
GetStaticDoubleField,
SetStaticObjectField,
SetStaticBooleanField,
SetStaticByteField,
SetStaticCharField,
SetStaticShortField,
SetStaticIntField,
SetStaticLongField,
SetStaticFloatField,
SetStaticDoubleField,
NewString,
GetStringLength,
GetStringChars,
ReleaseStringChars,
NewStringUTF,
GetStringUTFLength,
GetStringUTFChars,
ReleaseStringUTFChars,
GetArrayLength,
NewObjectArray,
GetObjectArrayElement,
SetObjectArrayElement,
NewBooleanArray,
NewByteArray,
NewCharArray,
NewShortArray,
NewIntArray,
NewLongArray,
NewFloatArray,
NewDoubleArray,
GetBooleanArrayElements,
GetByteArrayElements,
GetCharArrayElements,
GetShortArrayElements,
GetIntArrayElements,
GetLongArrayElements,
GetFloatArrayElements,
GetDoubleArrayElements,
ReleaseBooleanArrayElements,
ReleaseByteArrayElements,
ReleaseCharArrayElements,
ReleaseShortArrayElements,
ReleaseIntArrayElements,
ReleaseLongArrayElements,
ReleaseFloatArrayElements,
ReleaseDoubleArrayElements,
GetBooleanArrayRegion,
GetByteArrayRegion,
GetCharArrayRegion,
GetShortArrayRegion,
GetIntArrayRegion,
GetLongArrayRegion,
GetFloatArrayRegion,
GetDoubleArrayRegion,
SetBooleanArrayRegion,
SetByteArrayRegion,
SetCharArrayRegion,
SetShortArrayRegion,
SetIntArrayRegion,
SetLongArrayRegion,
SetFloatArrayRegion,
SetDoubleArrayRegion,
RegisterNatives,
UnregisterNatives,
MonitorEnter,
MonitorExit,
GetJavaVM,
GetStringRegion,
GetStringUTFRegion,
GetPrimitiveArrayCritical,
ReleasePrimitiveArrayCritical,
GetStringCritical,
ReleaseStringCritical,
NewWeakGlobalRef,
DeleteWeakGlobalRef,
ExceptionCheck,
NewDirectByteBuffer,
GetDirectBufferAddress,
GetDirectBufferCapacity,
GetObjectRefType,
GetModule,
IsVirtualThread
};
定数
JNI API全体で使用される一般的な定数がいくつかあります。
ブール値
#define JNI_FALSE 0
#define JNI_TRUE 1
リターン・コード
JNI関数の一般的な戻り値定数。
#define JNI_OK 0 /* success */
#define JNI_ERR (-1) /* unknown error */
#define JNI_EDETACHED (-2) /* thread detached from the VM */
#define JNI_EVERSION (-3) /* JNI version error */
#define JNI_ENOMEM (-4) /* not enough memory */
#define JNI_EEXIST (-5) /* VM already created */
#define JNI_EINVAL (-6) /* invalid arguments */
バージョン情報
GetVersion
jint GetVersion(JNIEnv *env);
ネイティブ・メソッド・インタフェースのバージョンを返します。 Java SE Platform 20以降では、JNI_VERSION_20
が返されます。 次の表は、Java SEプラットフォーム(古いバージョンのJNIでは、Java SEプラットフォームの代わりにJDKリリースが使用されています)の各リリースに含まれるJNIのバージョンを示しています:
Java SEプラットフォーム | JNIバージョン |
---|---|
1.1 | JNI_VERSION_1_1 |
1.2 | JNI_VERSION_1_2 |
1.3 | JNI_VERSION_1_2 |
1.4 | JNI_VERSION_1_4 |
5.0 | JNI_VERSION_1_4 |
6 | JNI_VERSION_1_6 |
7 | JNI_VERSION_1_6 |
8 | JNI_VERSION_1_8 |
9 | JNI_VERSION_9 |
10 | JNI_VERSION_10 |
11 | JNI_VERSION_10 |
12 | JNI_VERSION_10 |
13 | JNI_VERSION_10 |
14 | JNI_VERSION_10 |
15 | JNI_VERSION_10 |
16 | JNI_VERSION_10 |
17 | JNI_VERSION_10 |
18 | JNI_VERSION_10 |
19 | JNI_VERSION_19 |
20+ | JNI_VERSION_20 |
リンケージ:
JNIEnvインタフェース関数表のインデックス4。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
戻り値:
メジャー・バージョン番号を高位の16ビットで、マイナー・バージョン番号を下位の16ビットで返します。
バージョン定数
#define JNI_VERSION_1_1 0x00010001
#define JNI_VERSION_1_2 0x00010002
#define JNI_VERSION_1_4 0x00010004
#define JNI_VERSION_1_6 0x00010006
#define JNI_VERSION_1_8 0x00010008
#define JNI_VERSION_9 0x00090000
#define JNI_VERSION_10 0x000a0000
#define JNI_VERSION_19 0x00130000
#define JNI_VERSION_20 0x00140000
クラス操作
DefineClass
jclass DefineClass(JNIEnv *env, const char *name, jobject loader, const jbyte *buf, jsize bufLen);
rawクラス・データのバッファからクラスをロードします。 rawクラス・データを含むバッファは、DefineClass呼出しが戻った後はVMによって参照されません。必要に応じて破棄しても構いません。
リンケージ:
JNIEnvインタフェース関数表のインデックス5。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
name
: 定義されるクラス名またはインタフェース名。 文字列は変更後のUTF-8でエンコードされます。 この値はNULL
であるか、クラス・ファイル・データ内でエンコードされた名前と一致する必要があります。
loader
: 定義されたクラスに割り当てられるクラス・ローダー。 この値は、NULL
であり、"nullのクラス・ローダー" (または"ブートストラップ・クラス・ローダー")を示す。
buf
: .class
ファイル・データを含むバッファ。 NULL
の値はClassFormatError
を引き起こします。
bufLen
: バッファ長。
戻り値:
Javaクラス・オブジェクトを返すか、エラーが発生した場合はNULL
を返します。
例外:
ClassFormatError
: クラス・データが有効なクラスを指定していない場合。
ClassCircularityError
: クラスまたはインタフェースが、それ自体のスーパー・クラスまたはスーパー・インタフェースになる場合。
OutOfMemoryError
: システムがメモリー不足の場合。
SecurityException
: 呼出し側が「java」パッケージ・ツリー内にクラスを定義しようとした場合。
FindClass
jclass FindClass(JNIEnv *env, const char *name);
JDKリリース1.1では、この関数はローカルに定義されたクラスをロードします。 CLASSPATH
環境変数が指定するディレクトリおよびZIPファイルで、指定された名前を持つクラスを検索します。
JDK 1.2以降、Javaセキュリティ・モデルでは、非システム・クラスがネイティブ・メソッドをロードして呼び出すことができます。 FindClass
は、現在のネイティブ・メソッドに関連付けられたクラス・ローダー、つまりネイティブ・メソッドを宣言したクラスのクラス・ローダーを検出します。 ネイティブ・メソッドがシステム・クラスに属する場合、クラス・ローダーは検出されません。 それ以外の場合は、指定されたクラスのロード、リンクおよび初期化を行うために、適切なクラス・ローダーが呼び出されます。
JDK 1.2以降、FindClass
が呼び出しインタフェースを介して呼び出された場合、現在のネイティブ・メソッドまたはそれに関連付けられたクラス・ローダーは存在しません。 この場合、ClassLoader.getSystemClassLoader
の結果が使用されます。 これは、仮想マシンがアプリケーション用に作成するクラス・ローダーであり、java.class.path
プロパティにリストされたクラスを検索できます。
FindClass
がライブラリ・ライフ・サイクル関数フックから呼び出された場合、クラス・ローダーは次のように決定されます:
JNI_OnLoad
とJNI_OnLoad_L
では、ネイティブ・ライブラリをロードしているクラスのクラス・ローダーが使用されますJNI_OnUnload
とJNI_OnUnload_L
の場合、ClassLoader.getSystemClassLoader
が返すクラス・ローダーは(ロード時に使用されたクラス・ローダーが存在しなくなる可能性があるため)
name
引数は、完全修飾クラス名または配列型シグネチャです。 たとえば、java.lang.String
クラスの完全修飾クラス名は次のとおりです。
"java/lang/String"
配列クラスjava.lang.Object[]
の配列型シグニチャは次のとおりです。
"[Ljava/lang/Object;"
リンケージ:
JNIEnvインタフェース関数表のインデックス6。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
name
: 完全修飾クラス名は(つまり、"/
"で区切られたパッケージ名の後にクラス名が続きます)です。 名前が"[
" (配列シグネチャ文字)で始まる場合は、配列クラスを返します。 文字列は変更後のUTF-8でエンコードされます。 NULL
の値により、NoClassDefFoundError
が発生するか、クラッシュする可能性があります。
戻り値:
完全修飾名からクラス・オブジェクトを返すか、クラスが見つからない場合はNULL
を返します。
例外:
ClassFormatError
: クラス・データが有効なクラスを指定していない場合。
ClassCircularityError
: クラスまたはインタフェースが、それ自体のスーパー・クラスまたはスーパー・インタフェースになる場合。
NoClassDefFoundError
: 要求されたクラスまたはインタフェースに対する定義が見つからない場合。
OutOfMemoryError
: システムがメモリー不足の場合。
GetSuperclass
jclass GetSuperclass(JNIEnv *env, jclass clazz);
clazz
がObject
クラス以外のクラスを表す場合、この関数は、clazz
によって指定されたクラスのスーパー・クラスを表すオブジェクトを返します。
clazz
でクラスObject
が指定されている場合、またはclazz
がインタフェースを表す場合、この関数はNULL
を返します。
リンケージ:
JNIEnvインタフェース関数表のインデックス10。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
clazz
: Javaクラス・オブジェクトは、NULL
であってはなりません。
戻り値:
clazz
またはNULL
で表されるクラスのスーパークラスを返します。
IsAssignableFrom
jboolean IsAssignableFrom(JNIEnv *env, jclass clazz1, jclass clazz2);
clazz1
のオブジェクトを安全にclazz2
にキャストできるかどうかを決定します。
リンケージ:
JNIEnvインタフェース関数表のインデックス11。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
clazz1
: 最初のクラス引数は、NULL
であってはなりません。
clazz2
: 2番目のクラス引数は、NULL
であってはなりません。
戻り値:
次のいずれかが真の場合にJNI_TRUE
を返します。
- 最初と2番目のクラス引数が同じJavaクラスを表している。
- 最初のクラスが2番目のクラスのサブクラスである。
- 最初のクラスがそのインタフェースとして2番目のクラスを持っている。
モジュールの操作
GetModule
jobject GetModule(JNIEnv *env, jclass clazz);
クラスがメンバーであるモジュールのjava.lang.Module
オブジェクトを返します。 クラスが名前付きモジュールにない場合、クラスのクラス・ローダーの名前のないモジュールが返されます。 クラスが配列型を表す場合、この関数は要素型のModule
オブジェクトを返します。 クラスがプリミティブ型またはvoid
を表す場合は、java.base
モジュールのModule
オブジェクトが返されます。
リンケージ:
JNIEnvインタフェース関数表の索引233。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
clazz
: Javaクラス・オブジェクトは、NULL
であってはなりません。
戻り値:
クラスまたはインタフェースがメンバーであるモジュールを返します。
導入されたバージョン:
JDK/JRE 9
スレッド演算
IsVirtualThread
jboolean IsVirtualThread(JNIEnv *env, jobject obj);
IsVirtualThreadは、JavaプラットフォームのプレビューAPIです。 プレビュー機能は将来のリリースで削除されるか、Javaプラットフォームの永続的な機能にアップグレードされる可能性があります。
オブジェクトが仮想スレッドであるかどうかをテストします。
リンケージ:
JNIEnvインタフェース関数表の索引234。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
obj
: Javaオブジェクト、場合によってはNULL
の値。
戻り値:
オブジェクトが仮想スレッドである場合はJNI_TRUEを返します。
導入されたバージョン:
JDK/JRE 19
例外
Throw
jint Throw(JNIEnv *env, jthrowable obj);
java.lang.Throwable
オブジェクトがスローされます。
リンケージ:
JNIEnvインタフェース関数表のインデックス13。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
obj
: java.lang.Throwable
オブジェクトは、NULL
であってはなりません。
戻り値:
成功すると「0」を返し、失敗すると負の値を返します。
例外:
java.lang.Throwable
オブジェクトobj
。
ThrowNew
jint ThrowNew(JNIEnv *env, jclass clazz, const char *message);
message
で指定されたメッセージを使用して、指定されたクラスから例外オブジェクトを構築し、その例外をスローします。
リンケージ:
JNIEnvインタフェース関数表のインデックス14。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
clazz
: java.lang.Throwable
のサブクラスは、NULL
であってはなりません。
message
: java.lang.Throwable
オブジェクトの構築に使用されるメッセージ。 文字列は変更後のUTF-8でエンコードされます。 この値はNULL
です。
戻り値:
成功すると「0」を返し、失敗すると負の値を返します。
例外:
新しく構築されたjava.lang.Throwable
オブジェクト。
ExceptionOccurred
jthrowable ExceptionOccurred(JNIEnv *env);
例外がスローされるかどうかを決定します。 例外は、ネイティブ・コードがExceptionClear()
を呼び出すか、またはJavaコードがその例外を処理するまで、スローされた状態を続けます。
リンケージ:
JNIEnvインタフェース関数表のインデックス15。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
戻り値:
現在スローされている例外オブジェクトを返すか、現在スローされている例外がない場合はNULL
を返します。
ExceptionDescribe
void ExceptionDescribe(JNIEnv *env);
システム・エラー報告チャネル(stderr
など)にスタックの例外とバック・トレースを出力します。 保留中の例外は、この関数を呼び出す副作用としてクリアされます。 これは、デバッグのために提供されている便利なルーチンです。
リンケージ:
JNIEnvインタフェース関数表のインデックス16。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
ExceptionClear
void ExceptionClear(JNIEnv *env);
現在スローされている例外があればそれをクリアします。 現在スローされている例外がない場合は、このルーチンは影響を及ぼしません。
リンケージ:
JNIEnvインタフェース関数表のインデックス17。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
FatalError
void FatalError(JNIEnv *env, const char *msg);
致命的エラーを発生させます。VMの回復は期待できません。 この関数は値を返しません。
リンケージ:
JNIEnvインタフェース関数表のインデックス18。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
msg
: エラー・メッセージ。 文字列は変更後のUTF-8でエンコードされます。 NULL
値の可能性があります。
ExceptionCheck
例外オブジェクトへのローカル参照を作成せずに、未処理の例外を確認するための便利な関数を次に示します。
jboolean ExceptionCheck(JNIEnv *env);
未処理の例外がある場合はJNI_TRUE
、ない場合はJNI_FALSE
を返します。
リンケージ:
JNIEnvインタフェース関数表のインデックス228。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
グローバル参照およびローカル参照
Global References
NewGlobalRef
jobject NewGlobalRef(JNIEnv *env, jobject obj);
obj
引数によって参照されたオブジェクトの新しいグローバル参照を作成します。 obj
引数は、グローバル参照またはローカル参照のどちらでも構いません。 グローバル参照は、DeleteGlobalRef()
を呼び出すことによって明示的に破棄する必要があります。
リンケージ:
JNIEnvインタフェース関数表のインデックス21。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
obj
: グローバル参照またはローカル参照。 NULL
の値である可能性があります。この場合、この関数はNULL
を返します。
戻り値:
指定のobj
へのグローバル参照を戻します。
次の場合はNULL
を返すことがあります:
obj
はnull
を参照- システムのメモリーが不足しています
obj
は弱いグローバル参照であり、既にガベージ・コレクションされています
DeleteGlobalRef
void DeleteGlobalRef(JNIEnv *env, jobject globalRef);
globalRef
によって示されたグローバル参照を削除します。
リンケージ:
JNIEnvインタフェース関数表のインデックス22。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
globalRef
: グローバル参照。 NULL
の値である可能性があります。この場合、この関数は何もしません。
Local References
ローカル参照は、ネイティブ・メソッドの呼出し期間中有効です。 ローカル参照は、ネイティブ・メソッドが復帰すると自動的に解放されます。 各ローカル参照は、Java仮想マシンのリソースをいくらか消費します。 プログラマは、ネイティブ・メソッドがローカル参照を過剰に割り当てないように確認する必要があります。 ローカル参照は、ネイティブ・メソッドがJavaに復帰すると自動的に解放されますが、ローカル参照を過剰に割り当てると、ネイティブ・メソッドの実行中にVMがメモリーを使い果たしてしまう可能性があります。
DeleteLocalRef
void DeleteLocalRef(JNIEnv *env, jobject localRef);
localRef
によって示されたローカル参照を削除します。
リンケージ:
JNIEnvインタフェース関数表のインデックス23。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
localRef
: ローカル参照。 ここで渡されたNULL
値の場合、関数は何も行いません。
ノート: JDK/JRE 1.1では、上記のDeleteLocalRef
関数が用意されているため、プログラマは手動でローカル参照を削除できます。 たとえば、ネイティブ・コードがオブジェクトの潜在的に大きな配列を繰返しにより処理し、反復ごとに1つの要素を使用する場合、次の反復で新しいローカル参照が作成される前に、もう使用されない配列要素へのローカル参照を削除するのは良い方法です。 JDK/JRE 1.2では、ローカル参照の有効期間を管理するための関数セットが追加されました。 その関数は次の4つです。
EnsureLocalCapacity
jint EnsureLocalCapacity(JNIEnv *env, jint capacity);
少なくとも指定された数のローカル参照を現在のスレッドで作成できることを保証します。 成功した場合は0を返します。それ以外の場合は負の数を返し、OutOfMemoryError
をスローします。
ネイティブ・メソッドに入る前に、VMは自動的に、少なくとも16のローカル参照の作成を保証します。
下位互換性のためにVMは、保証された容量以上にローカル参照を割り当てます。 (デバッグのサポートとして、VMがユーザーに対し、ローカル参照の作成数が多すぎるという内容の警告を発する場合があります。 JDKでは、プログラマは-verbose:jni
コマンド行オプションを指定して、これらのメッセージを有効にすることができます。) 保証された容量を超えてしまい、これ以上ローカル参照を作成できない場合、VMはFatalError
を呼び出します。
一部のJava Virtual Machineの実装では、最大capacity
を制限することがあります。これにより、関数がエラー(例:JNI_ERR
またはJNI_EINVAL
)を返す可能性があります。 たとえば、HotSpot JVMの実装では、-XX:+MaxJNILocalCapacity
フラグ(default : 65536)が使用されます。
リンケージ:
JNIEnvインタフェース関数表のインデックス26。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
capacity
: 必要なローカル参照の最小数。 0以上にする必要があります。
戻り値:
成功時にJNI_OK
。
導入されたバージョン:
JDK/JRE 1.2
PushLocalFrame
jint PushLocalFrame(JNIEnv *env, jint capacity);
新しいローカル参照フレームを作成します。このフレームに最低限指定された数のローカル参照を作成できます。 成功した場合は0、失敗した場合は負の数と未処理のOutOfMemoryError
を返します。
前回のローカル・フレームで作成済みのローカル参照は、現在のローカル・フレームでも引き続き有効です。
EnsureLocalCapacity
と同様に、Java Virtual Machineの実装によっては、関数がエラーを返す可能性がある最大capacity
を制限することを選択することがあります。
リンケージ:
JNIEnvインタフェース関数表のインデックス19。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
capacity
: 必要なローカル参照の最小数。 > 0でなければなりません。
戻り値:
成功時にJNI_OK
。
導入されたバージョン:
JDK/JRE 1.2
PopLocalFrame
jobject PopLocalFrame(JNIEnv *env, jobject result);
現在のローカル参照フレームをポップし、すべてのローカル参照を解放し、指定されたresult
オブジェクトに対する前回のローカル参照フレームのローカル参照を返します。
前回のフレームへの参照を返す必要がない場合は、result
としてNULL
を渡してください。
リンケージ:
JNIEnvインタフェース関数表のインデックス20。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
result
: 前のローカル参照フレームに渡されるオブジェクトは、NULL
であってもよい。
戻り値:
指定されたresult
オブジェクトの前のローカル参照フレーム内のローカル参照を返します。指定されたresult
オブジェクトがNULL
だった場合はNULL
を返します。
導入されたバージョン:
JDK/JRE 1.2
NewLocalRef
jobject NewLocalRef(JNIEnv *env, jobject ref);
ref
と同じオブジェクトを参照する新しいローカル参照を作成します。 与えられたref
は、グローバル、ローカル参照、またはNULL
であってもよい。 ref
がnull
を参照している場合は、NULL
を返します。
リンケージ:
JNIEnvインタフェース関数表のインデックス25。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
ref
: 関数が新しいローカル参照を作成するオブジェクトへの参照。 NULL
値の可能性があります。
戻り値:
ref
と同じオブジェクトを参照する新しいローカル参照を返します。
次の場合はNULL
を返すことがあります:
ref
はnull
を参照- システムのメモリーが不足しています
ref
は弱いグローバル参照であり、既にガベージ・コレクションされています
導入されたバージョン:
JDK/JRE 1.2
弱グローバル参照
弱グローバル参照は、特別な種類のグローバル参照です。 通常のグローバル参照と異なり、弱グローバル参照を使用すると、配下のJavaオブジェクトをガベージ・コレクトすることができます。 弱グローバル参照は、グローバルまたはローカル参照が使用されている状況ならどこででも使用できます。
弱いグローバル参照は、Javaファントム参照(java.lang.ref.PhantomReference
)に関連します。 特定のオブジェクトへの弱いグローバル参照は、そのオブジェクトが「ファントム到達可能」 (java.lang.ref
を参照してください)であるかどうかを判断するときに、そのオブジェクトを参照するファントム参照として扱われます。 このような弱いグローバル参照は、機能的にNULL
と同等になります。同じオブジェクトを参照しているPhantomReference
はガベージ・コレクタによってクリアされます。
ガベージ・コレクションはネイティブ・メソッドの実行中に発生することもあるため、弱グローバル参照で参照されているオブジェクトはいつでも解放される可能性があります。 グローバル参照を使用する場合、弱いグローバル参照を使用できますが、機能的にNULL
に同等になることがあるため、これは通常は不適切です。
IsSameObject
を使用すると、脆弱なグローバル参照と、NULL
以外のローカルまたはグローバル参照を比較できます。 オブジェクトが同じ場合、弱いグローバル参照は、他の参照が削除されないかぎり、機能的にNULL
と同等になりません。
IsSameObject
は、弱いグローバル参照をNULL
と比較して、基礎となるオブジェクトが解放されたかどうかを判断する際にも使用できます。 ただし、プログラマは、アイドル・グローバル参照が将来のJNI関数呼出しで(NULL
以外の参照として)を使用する可能性があるかどうかを判断する際には、介在のガベージ・コレクションによって弱いグローバル参照が変更される可能性があるため、このチェックに依存しないでください。
かわりに、JNI関数NewLocalRef
またはNewGlobalRef
のいずれかを使用して、基礎となるオブジェクトに対する(strong)ローカルまたはグローバル参照を取得することをお薦めします。 これらのファンクションは、オブジェクトが解放されるとNULL
を戻します。 そうしないと、新しい参照によって、基礎となるオブジェクトが解放されなくなります。 NULL
以外の新しい参照は、基礎となるオブジェクトへのアクセスに使用でき、そのようなアクセスが不要になった場合に削除できます。
NewWeakGlobalRef
jweak NewWeakGlobalRef(JNIEnv *env, jobject obj);
弱グローバル参照を新規作成します。 弱いグローバル参照は、指定されたオブジェクトのガベージ・コレクションを妨げません。 参照によって参照されるオブジェクトが解放されたかどうかをテストするためにIsSameObject
を使用できます。 obj
がnull
を参照する場合、またはobj
が弱いグローバル参照である場合、またはVMのメモリーが不足している場合は、NULL
を返します。 VMがメモリーを使い果たしてしまった場合は、OutOfMemoryError
がスローされます。
リンケージ:
JNIEnvインタフェース関数表のインデックス226。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
obj
: ためのグローバルな弱参照を作成するオブジェクトです。
戻り値:
指定されたobj
にグローバルな弱参照を返します。
次の場合はNULL
を返すことがあります:
obj
はnull
を参照- システムのメモリーが不足しています
obj
は弱いグローバル参照であり、既にガベージ・コレクションされています
例外:
OutOfMemoryError
システムがメモリー不足の場合。
導入されたバージョン:
JDK/JRE 1.2
DeleteWeakGlobalRef
void DeleteWeakGlobalRef(JNIEnv *env, jweak obj);
渡された弱グローバル参照に必要なVMリソースを削除します。
リンケージ:
JNIEnvインタフェース関数表のインデックス227。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
obj
: 削除するグローバルな弱参照。 この関数は、NULL
を渡すと何もしません。
導入されたバージョン:
JDK/JRE 1.2
オブジェクト・オペレーション
AllocObject
jobject AllocObject(JNIEnv *env, jclass clazz);
新しいJavaオブジェクト「オブジェクトのコンストラクタを呼び出さずに」を割り当てます。 オブジェクトに対する参照を返します。
注意: Java言語仕様、"ファイナライズの実装" (JLS§12.6.1) states : "オブジェクトoは、そのコンストラクタがObject onのコンストラクタを呼び出してその呼び出しが正常に完了するまで、ファイナライズ可能ではありません"。 AllocObject()はコンストラクタを呼び出さないため、この関数で作成されたオブジェクトはファイナライズに適格ではありません。
clazz引数は配列クラスを参照できません。
リンケージ:
JNIEnvインタフェース関数表のインデックス27。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
clazz
: Javaクラス・オブジェクトへの参照で、NULL
であってはなりません。
戻り値:
Javaオブジェクトを返します。オブジェクトを構築できない場合はNULL
を返します。
例外:
InstantiationException
: クラスがインタフェースまたは抽象クラスの場合。
OutOfMemoryError
: システムがメモリー不足の場合。
NewObject、NewObjectA、NewObjectV
jobject NewObject(JNIEnv *env, jclass clazz, jmethodID methodID, ...);
jobject NewObjectA(JNIEnv *env, jclass clazz, jmethodID methodID, const jvalue *args);
jobject NewObjectV(JNIEnv *env, jclass clazz, jmethodID methodID, va_list args);
新しいJavaオブジェクトを構築します。 メソッドIDは、呼び出すべきコンストラクタ・メソッドを表しています。 このIDは、メソッド名として<init>
を、また戻り値の型としてvoid
(V
)を使用してGetMethodID()
を呼び出すことによって取得しなければなりません。
clazz
引数は配列クラスを参照できません。
NewObject
プログラマは、methodID
引数の直後にコンストラクタに渡されるすべての引数を配置します。 NewObject()
は、これらの引数を受け入れて、プログラマが呼び出す必要があるJavaメソッドに渡します。
リンケージ:
JNIEnvインタフェース関数表のインデックス28。
NewObjectA
プログラマは、コンストラクタに渡す引数をすべて、methodID
引数の直後のjvalues
のargs
配列内に置きます。 NewObjectA()
は、この配列内の引数を受け取り、プログラマが呼び出したいJavaメソッドに渡します。
リンケージ:
JNIEnvインタフェース関数表のインデックス30。
NewObjectV
プログラマは、コンストラクタに渡す引数をすべて、methodID
引数の直後のva_list
型のargs
引数に入れます。 NewObjectV()
は、これらの引数を受け取り、プログラマが呼び出したいJavaメソッドに渡します。
リンケージ:
JNIEnvインタフェース関数表のインデックス29。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
clazz
: Javaクラス・オブジェクトへの参照で、NULL
であってはなりません。
methodID
: コンストラクタのメソッドID。
NewObjectに必要な追加パラメータ:
コンストラクタの引数。
NewObjectAに必要な追加パラメータ:
args
: コンストラクタの引数の配列。
NewObjectVに必要な追加パラメータ:
args
: コンストラクタへの引数のva_list
。
戻り値:
Javaオブジェクトを返します。オブジェクトを構築できない場合はNULL
を返します。
例外:
InstantiationException
: クラスがインタフェースまたは抽象クラスの場合。
OutOfMemoryError
: システムがメモリー不足の場合。
コンストラクタによってスローされるすべての例外。
GetObjectClass
jclass GetObjectClass(JNIEnv *env, jobject obj);
オブジェクトのクラスを返します。
リンケージ:
JNIEnvインタフェース関数表のインデックス31。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
obj
: Javaオブジェクトは、NULL
であってはなりません。
戻り値:
Javaクラス・オブジェクトを返します。
GetObjectRefType
jobjectRefType GetObjectRefType(JNIEnv* env, jobject obj);
obj
引数によって参照されるオブジェクトの型を返します。 引き数obj
は、ローカル、グローバルまたは弱いグローバル参照、またはNULL
のいずれかです。
リンケージ:
JNIEnvインタフェース関数表のインデックス232。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
obj
: ローカル、グローバル、または弱いグローバル参照。
戻り値:
関数GetObjectRefType
は、jobjectRefType
として定義されている次の列挙値のいずれかを返します:
JNIInvalidRefType = 0
JNILocalRefType = 1
JNIGlobalRefType = 2
JNIWeakGlobalRefType = 3
引数obj
が弱いグローバル参照型の場合、戻り値はJNIWeakGlobalRefType
になります。
引数obj
がグローバル参照型の場合、戻り値はJNIGlobalRefType
になります。
引数obj
がローカル参照型の場合、戻り値はJNILocalRefType
になります。
obj
引数が有効な参照でない場合、この関数の戻り値はJNIInvalidRefType
になります。
無効な参照とは、有効なハンドルでない参照です。 つまり、obj
ポインタ・アドレスが、いずれかのRef作成関数から割り当てられたメモリー内の位置やJNI関数から返されたメモリー内の位置を指していません。
したがって、NULL
は無効な参照となり、GetObjectRefType(env,NULL)
はJNIInvalidRefType
を返します。
他方、nullを指示する参照であるnull参照は、そのnull参照が最初に作成されたときの参照の型を返します。
GetObjectRefType
は、削除された参照では使用できません。
参照は通常、VMの参照割当てサービスによって再利用できる可能性があるメモリー・データ構造へのポインタとして実装されるため、削除すると、GetObjectRefType
が返す値は指定されません。
導入されたバージョン:
JDK/JRE 1.6
IsInstanceOf
jboolean IsInstanceOf(JNIEnv *env, jobject obj, jclass clazz);
オブジェクトがクラスのインスタンスであるかどうかをチェックします。
リンケージ:
JNIEnvインタフェース関数表のインデックス32。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
obj
: Javaオブジェクト、場合によってはNULL
の値。
clazz
: Javaクラス・オブジェクトは、NULL
であってはなりません。
戻り値:
obj
をclazz
にキャストできる場合はJNI_TRUE
を返し、それ以外の場合はJNI_FALSE
を返します。 NULL
オブジェクトは、どのクラスにもキャストできます。
IsSameObject
jboolean IsSameObject(JNIEnv *env, jobject ref1, jobject ref2);
2つの参照が同じJavaオブジェクトを参照するかどうかをテストします。
リンケージ:
JNIEnvインタフェース関数表のインデックス24。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
ref1
: Javaオブジェクトは、NULL
です。
ref2
: Javaオブジェクトは、NULL
です。
戻り値:
ref1
およびref2
が同じJavaオブジェクトを参照する場合、または両方がNULL
である場合、JNI_TRUE
を返します。それ以外の場合、JNI_FALSE
を返します。
オブジェクトのフィールドへのアクセス
GetFieldID
jfieldID GetFieldID(JNIEnv *env, jclass clazz, const char *name, const char *sig);
クラスのインスタンス(非static)フィールドを表すフィールドIDを返します。 このフィールドは、その名前とシグニチャで指定します。 アクセス用関数のGet<type>FieldファミリとSet<type>Fieldファミリは、フィールドIDを使用してオブジェクト・フィールドを取り出します。
GetFieldID()
によって、まだ初期化されていないクラスが初期化されます。
配列の長さフィールドを取得するためにGetFieldID()
を使用することはできません。 代わりにGetArrayLength()
を使用してください。
リンケージ:
JNIEnvインタフェース関数表のインデックス94。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
clazz
: Javaクラス・オブジェクトは、NULL
であってはなりません。
name
: 0で終了する修正UTF-8文字列内のフィールド名は、NULL
であってはなりません。
sig
: 0で終了する修正UTF-8文字列のフィールド・シグネチャは、NULL
であってはなりません。
戻り値:
フィールドIDを返します。操作が失敗した場合はNULL
を返します。
例外:
NoSuchFieldError
: 指定されたフィールドが見つからない場合。
ExceptionInInitializerError
: クラスの初期化子が例外のために失敗した場合。
OutOfMemoryError
: システムがメモリー不足の場合。
Get<type>Fieldルーチン
NativeType Get<type>Field(JNIEnv *env, jobject obj, jfieldID fieldID);
このアクセス用ルーチンのファミリは、オブジェクトのインスタンス(非static)フィールドの値を返します。 アクセスするフィールドは、GetFieldID()
をコールして取得したフィールドIDによって指定されます。
次の表は、Get<type>Fieldルーチン名と結果タイプを示しています。 Get<type>Field内のtypeをフィールドのJava型と置き換えるか、または表の実際のルーチン名の1つを使用し、かつNativeTypeをそのルーチンに対応するネイティブ型と置き換える必要があります。
Get<type>Fieldルーチン名 | ネイティブ型 |
---|---|
GetObjectField() |
jobject |
GetBooleanField() |
jboolean |
GetByteField() |
jbyte |
GetCharField() |
jchar |
GetShortField() |
jshort |
GetIntField() |
jint |
GetLongField() |
jlong |
GetFloatField() |
jfloat |
GetDoubleField() |
jdouble |
リンケージ:
JNIEnvインタフェース関数表のインデックス:
Get<type>Fieldルーチン名 | 索引 |
---|---|
GetObjectField() |
95 |
GetBooleanField() |
96 |
GetByteField() |
97 |
GetCharField() |
98 |
GetShortField() |
99 |
GetIntField() |
100 |
GetLongField() |
101 |
GetFloatField() |
102 |
GetDoubleField() |
103 |
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
obj
: Javaオブジェクトは、NULL
であってはなりません。
fieldID
: 有効なフィールドID。
戻り値:
フィールドの内容を返します。
Set<type>Fieldルーチン
void
「<type>フィールドの設定」 (JNIEnv *env, jobject obj, jfieldID fieldID,
NativeType value);
このアクセス用ルーチンのファミリは、オブジェクトのインスタンス(非static)フィールドの値を設定します。 アクセスするフィールドは、GetFieldID()
をコールして取得したフィールドIDによって指定されます。
次の表に、Set<type>Fieldルーチン名と値のタイプを示します。 Set<type>Field内のtypeをフィールドのJava型と置き換えるか、または表の実際のルーチン名の1つを使用し、かつNativeTypeをそのルーチンに対応するネイティブ型と置き換える必要があります。
Set<type>Fieldルーチン | ネイティブ型 |
---|---|
SetObjectField() |
jobject |
SetBooleanField() |
jboolean |
SetByteField() |
jbyte |
SetCharField() |
jchar |
SetShortField() |
jshort |
SetIntField() |
jint |
SetLongField() |
jlong |
SetFloatField() |
jfloat |
SetDoubleField() |
jdouble |
リンケージ:
JNIEnvインタフェース関数表のインデックス。
Set<type>Fieldルーチン | 索引 |
---|---|
SetObjectField() |
104 |
SetBooleanField() |
105 |
SetByteField() |
106 |
SetCharField() |
107 |
SetShortField() |
108 |
SetIntField() |
109 |
SetLongField() |
110 |
SetFloatField() |
111 |
SetDoubleField() |
112 |
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
obj
: Javaオブジェクトは、NULL
であってはなりません。
fieldID
: 有効なフィールドID。
value
: フィールドの新しい値。
インスタンス・メソッドの呼び出し
ネイティブ・コードからメソッドを呼び出すときは、メソッドがcaller-sensitiveであるかどうかに注意してください。
GetMethodID
jmethodID GetMethodID(JNIEnv *env, jclass clazz, const char *name, const char *sig);
クラスまたはインタフェースのインスタンス(非static)メソッドを表すメソッドIDを返します。 このメソッドは、clazz
のスーパータイプの1つで定義され、clazz
によって継承されます。 このメソッドは、その名前およびシグニチャによって決定されます。
GetMethodID()
によって、まだ初期化されていないクラスが初期化されます。
コンストラクタのメソッドIDを取得するには、メソッド名として<init>
を指定し、戻り値の型としてvoid
(V
)を指定します。
リンケージ:
JNIEnvインタフェース関数表のインデックス33。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
clazz
: Javaクラス・オブジェクトは、NULL
であってはなりません。
name
: 0で終了する修正UTF-8文字列のメソッド名は、NULL
であってはなりません。
sig
: 0で終了する変更UTF-8文字列のメソッド・シグネチャは、NULL
であってはなりません。
戻り値:
メソッドIDを返します。指定されたメソッドが見つからない場合はNULL
を返します。
例外:
NoSuchMethodError
: 指定されたメソッドが見つからない場合。
ExceptionInInitializerError
: クラスの初期化子が例外のために失敗した場合。
OutOfMemoryError
: システムがメモリー不足の場合。
Call<type>Methodルーチン、Call<type>MethodAルーチン、Call<type>MethodVルーチン
NativeType Call<type>Method(JNIEnv *env, jobject obj, jmethodID methodID, ...);
NativeType Call<type>MethodA(JNIEnv *env, jobject obj, jmethodID methodID, const jvalue *args);
NativeType Call<type>MethodV(JNIEnv *env, jobject obj, jmethodID methodID, va_list args);
これら3種類の演算ファミリは、ネイティブ・メソッドからJavaインスタンス・メソッドを呼び出す際に使用されます。これら3種類のファミリは、呼び出したメソッドにパラメータを渡すメカニズムが異なるだけです。
これらの演算ファミリは、指定されたメソッドIDに従って、Javaオブジェクト上のインスタンス(非static)メソッドを呼び出します。 methodID
引数は、GetMethodID()
をコールして取得する必要があります。
これらの関数を使用してprivateメソッドやコンストラクタを呼び出す場合は、メソッドIDをobj
の実クラスのスーパー・クラスの1つからではなく、実クラス自体から取得する必要があります。
Call<type>Methodルーチン
プログラマは、メソッドに渡されるすべての引数を、methodID
引数の直後に配置します。 Call<type>Methodルーチンは、これらの引数を受け取り、プログラマが呼び出したいJavaメソッドに渡します。
Call<type>MethodAルーチン
プログラマは、メソッドへのすべての引数を、methodID
引数の直後に続くjvalues
のargs
配列に配置します。 Call<type>MethodAルーチンは、この配列内の引数を受け取り、プログラマが呼び出したいJavaメソッドに渡します。
Call<type>MethodVルーチン
プログラマは、methodID
引数の直後に続くva_list
型のargs
引数に、メソッドへのすべての引数を配置します。 Call<type>MethodVルーチンは、これらの引数を受け取り、プログラマが呼び出したいJavaメソッドに渡します。
次の表には、メソッド呼出しルーチンのそれぞれがその結果の型に応じて示されています。 Call<type>Method内のtypeを、呼び出しているメソッドのJava型と置き換え(または、表の実際のメソッド呼出しルーチン名の1つを使用する)、かつNativeTypeをそのルーチンに対応するネイティブ型と置き換える必要があります。
Call<type>Methodルーチン名 | ネイティブ型 |
---|---|
CallVoidMethod() CallVoidMethodA() CallVoidMethodV() |
void |
CallObjectMethod() CallObjectMethodA() CallObjectMethodV() |
jobject |
CallBooleanMethod() CallBooleanMethodA() CallBooleanMethodV() |
jboolean |
CallByteMethod() CallByteMethodA() CallByteMethodV() |
jbyte |
CallCharMethod() CallCharMethodA() CallCharMethodV() |
jchar |
CallShortMethod() CallShortMethodA() CallShortMethodV() |
jshort |
CallIntMethod() CallIntMethodA() CallIntMethodV() |
jint |
CallLongMethod() CallLongMethodA() CallLongMethodV() |
jlong |
CallFloatMethod() CallFloatMethodA() CallFloatMethodV() |
jfloat |
CallDoubleMethod() CallDoubleMethodA() CallDoubleMethodV() |
jdouble |
リンケージ:
JNIEnvインタフェース関数表のインデックス:
Call<type>Methodルーチン名 | 索引 |
---|---|
CallVoidMethod() CallVoidMethodA() CallVoidMethodV() |
61 63 62 |
CallObjectMethod() CallObjectMethodA() CallObjectMethodV() |
34 36 35 |
CallBooleanMethod() CallBooleanMethodA() CallBooleanMethodV() |
37 39 38 |
CallByteMethod() CallByteMethodA() CallByteMethodV() |
40 42 41 |
CallCharMethod() CallCharMethodA() CallCharMethodV() |
43 45 44 |
CallShortMethod() CallShortMethodA() CallShortMethodV() |
46 48 47 |
CallIntMethod() CallIntMethodA() CallIntMethodV() |
49 51 50 |
CallLongMethod() CallLongMethodA() CallLongMethodV() |
52 54 53 |
CallFloatMethod() CallFloatMethodA() CallFloatMethodV() |
55 57 56 |
CallDoubleMethod() CallDoubleMethodA() CallDoubleMethodV() |
58 60 59 |
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
obj
: Javaオブジェクトは、NULL
であってはなりません。
methodID
: 有効なメソッドID。
Call<type>Methodルーチンに必要な追加パラメータ:
Javaメソッドに対する引数。
Call<type>MethodAルーチンに必要な追加パラメータ:
args
: 引数の配列。
Call<type>MethodVルーチンに必要な追加パラメータ:
args
: 引数のva_list
。
戻り値:
Javaメソッドを呼び出した結果を返します。
例外:
Javaメソッドを実行している間に発生した例外。
CallNonvirtual<type>Methodルーチン、CallNonvirtual<type>MethodAルーチン、CallNonvirtual<type>MethodVルーチン
NativeType CallNonvirtual<type>Method(JNIEnv *env, jobject obj, jclass clazz, jmethodID methodID, ...);
NativeType CallNonvirtual<type>MethodA(JNIEnv *env, jobject obj, jclass clazz, jmethodID methodID, const jvalue *args);
NativeType CallNonvirtual<type>MethodV(JNIEnv *env, jobject obj, jclass clazz, jmethodID methodID, va_list args);
これらの演算ファミリは、指定されたクラスおよびメソッドIDに従って、Javaオブジェクト上のインスタンス(非static)メソッドを呼び出します。 methodID
引数は、クラスclazz
でGetMethodID()
をコールして取得する必要があります。
CallNonvirtual<type>Methodルーチン・ファミリとCall<type>Methodルーチン・ファミリとは異なります。 Call<type>Methodルーチンは、オブジェクトのクラスまたはインタフェースに基づいてメソッドを呼び出します。CallNonvirtual<type>Methodルーチンは、メソッドIDを取得するclazz
パラメータで指定されたクラスに基づいてメソッドを呼び出します。 メソッドIDは、オブジェクトの実際のクラスまたはそのスーパータイプの1つから取得する必要があります。
CallNonvirtual<type>Methodルーチンは、Java 8で導入された"デフォルトのインタフェース・メソッド"を呼び出すためのメカニズムです。
CallNonvirtual<type>Methodルーチン
プログラマは、メソッドに渡されるすべての引数を、methodID
引数の直後に配置します。 CallNonvirtual<type>Methodルーチンは、これらの引数を受け取り、プログラマが呼び出したいJavaメソッドに渡します。
CallNonvirtual<type>MethodAルーチン
プログラマは、メソッドへのすべての引数を、methodID
引数の直後に続くjvalues
のargs
配列に配置します。 CallNonvirtual<type>MethodAルーチンは、この配列内の引数を受け取り、プログラマが呼び出したいJavaメソッドに渡します。
CallNonvirtual<type>MethodVルーチン
プログラマは、methodID
引数の直後に続くva_list
型のargs
引数に、メソッドへのすべての引数を配置します。 CallNonvirtualMethodVルーチンは、これらの引数を受け取り、プログラマが呼び出したいJavaメソッドに渡します。
次の表には、メソッド呼出しルーチンのそれぞれがその結果の型に応じて示されています。 CallNonvirtual<type>Method内のtypeをメソッドのJava型と置き換えるか、または表の実際のメソッド呼出しルーチン名の1つを使用し、かつNativeTypeをそのルーチンに対応するネイティブ型と置き換える必要があります。
CallNonvirtual<type>Methodルーチン名 | ネイティブ型 |
---|---|
CallNonvirtualVoidMethod() CallNonvirtualVoidMethodA() CallNonvirtualVoidMethodV() |
void |
CallNonvirtualObjectMethod() CallNonvirtualObjectMethodA() CallNonvirtualObjectMethodV() |
jobject |
CallNonvirtualBooleanMethod() CallNonvirtualBooleanMethodA() CallNonvirtualBooleanMethodV() |
jboolean |
CallNonvirtualByteMethod() CallNonvirtualByteMethodA() CallNonvirtualByteMethodV() |
jbyte |
CallNonvirtualCharMethod() CallNonvirtualCharMethodA() CallNonvirtualCharMethodV() |
jchar |
CallNonvirtualShortMethod() CallNonvirtualShortMethodA() CallNonvirtualShortMethodV() |
jshort |
CallNonvirtualIntMethod() CallNonvirtualIntMethodA() CallNonvirtualIntMethodV() |
jint |
CallNonvirtualLongMethod() CallNonvirtualLongMethodA() CallNonvirtualLongMethodV() |
jlong |
CallNonvirtualFloatMethod() CallNonvirtualFloatMethodA() CallNonvirtualFloatMethodV() |
jfloat |
CallNonvirtualDoubleMethod() CallNonvirtualDoubleMethodA() CallNonvirtualDoubleMethodV() |
jdouble |
リンケージ:
JNIEnvインタフェース関数表のインデックス。
CallNonvirtual<type>Methodルーチン名 | 索引 |
---|---|
CallNonvirtualVoidMethod() CallNonvirtualVoidMethodA() CallNonvirtualVoidMethodV() |
91 93 92 |
CallNonvirtualObjectMethod() CallNonvirtualObjectMethodA() CallNonvirtualObjectMethodV() |
64 66 65 |
CallNonvirtualBooleanMethod() CallNonvirtualBooleanMethodA() CallNonvirtualBooleanMethodV() |
67 69 68 |
CallNonvirtualByteMethod() CallNonvirtualByteMethodA() CallNonvirtualByteMethodV() |
70 72 71 |
CallNonvirtualCharMethod() CallNonvirtualCharMethodA() CallNonvirtualCharMethodV() |
73 75 74 |
CallNonvirtualShortMethod() CallNonvirtualShortMethodA() CallNonvirtualShortMethodV() |
76 78 77 |
CallNonvirtualIntMethod() CallNonvirtualIntMethodA() CallNonvirtualIntMethodV() |
79 81 80 |
CallNonvirtualLongMethod() CallNonvirtualLongMethodA() CallNonvirtualLongMethodV() |
82 84 83 |
CallNonvirtualFloatMethod() CallNonvirtualFloatMethodA() CallNonvirtualFloatMethodV() |
85 87 86 |
CallNonvirtualDoubleMethod() CallNonvirtualDoubleMethodA() CallNonvirtualDoubleMethodV() |
88 90 89 |
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
clazz
: Javaクラスであり、NULL
であってはなりません。
obj
: Javaオブジェクトは、NULL
であってはなりません。
methodID
: メソッドID。
CallNonvirtual<type>Methodルーチンに必要な追加パラメータ:
Javaメソッドに対する引数。
CallNonvirtual<type>MethodAルーチンに必要な追加パラメータ:
args
: 引数の配列。
CallNonvirtual<type>MethodVルーチンに必要な追加パラメータ:
args
: 引数のva_list
。
戻り値:
Javaメソッドを呼び出した結果を返します。
例外:
Javaメソッドを実行している間に発生した例外。
staticフィールドへのアクセス
GetStaticFieldID
jfieldID GetStaticFieldID(JNIEnv *env, jclass clazz, const char *name, const char *sig);
クラスのstaticフィールドを表すフィールドIDを返します。 このフィールドは、その名前とシグニチャで指定します。 アクセス用関数のGetStatic<type>FieldファミリとSetStatic<type>Fieldファミリは、フィールドIDを使用してstaticフィールドを取り出します。
GetStaticFieldID()
によって、まだ初期化されていないクラスが初期化されます。
リンケージ:
JNIEnvインタフェース関数表のインデックス144。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
clazz
: Javaクラス・オブジェクトは、NULL
であってはなりません。
name
: 0で終了する修正UTF-8文字列内の静的フィールド名は、NULL
であってはなりません。
sig
: 0で終了する修正UTF-8文字列のフィールド・シグネチャは、NULL
であってはなりません。
戻り値:
フィールドIDを返します。指定した静的フィールドが見つからない場合はNULL
を返します。
例外:
NoSuchFieldError
: 指定されたstaticフィールドが見つからない場合。
ExceptionInInitializerError
: クラスの初期化子が例外のために失敗した場合。
OutOfMemoryError
: システムがメモリー不足の場合。
GetStatic<type>Fieldルーチン
NativeType GetStatic<type>Field(JNIEnv *env, jclass clazz, jfieldID fieldID);
このアクセス用ルーチンのファミリは、オブジェクトのstaticフィールドの値を返します。 アクセスするフィールドは、GetStaticFieldID()
をコールして取得されるフィールドIDによって指定されます。
次の表には、getルーチン名のファミリと結果の型が示されています。 GetStatic<type>Field内のtypeをフィールドのJava型と置き換えるか、または表の実際のstaticフィールド・アクセス用ルーチン名の1つを使用し、かつNativeTypeをそのルーチンに対応するネイティブ型と置き換える必要があります。
GetStatic<type>Fieldルーチン名 | ネイティブ型 |
---|---|
GetStaticObjectField() |
jobject |
GetStaticBooleanField() |
jboolean |
GetStaticByteField() |
jbyte |
GetStaticCharField() |
jchar |
GetStaticShortField() |
jshort |
GetStaticIntField() |
jint |
GetStaticLongField() |
jlong |
GetStaticFloatField() |
jfloat |
GetStaticDoubleField() |
jdouble |
リンケージ:
JNIEnvインタフェース関数表のインデックス。
GetStatic<type>Fieldルーチン名 | 索引 |
---|---|
GetStaticObjectField() |
145 |
GetStaticBooleanField() |
146 |
GetStaticByteField() |
147 |
GetStaticCharField() |
148 |
GetStaticShortField() |
149 |
GetStaticIntField() |
150 |
GetStaticLongField() |
151 |
GetStaticFloatField() |
152 |
GetStaticDoubleField() |
153 |
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
clazz
: Javaクラス・オブジェクトは、NULL
であってはなりません。
fieldID
: 有効な静的フィールドID。
戻り値:
staticフィールドの内容を返します。
SetStatic<type>Fieldルーチン
void
SetStatic<type>Field(JNIEnv *env, jclass clazz, jfieldID fieldID,
NativeType value);
このアクセス用ルーチンのファミリは、オブジェクトのstaticフィールドの値を設定します。 アクセスするフィールドは、GetStaticFieldID()
をコールして取得されるフィールドIDによって指定されます。
次の表には、セット・ルーチン名と値の型が示されています。 SetStatic<type>Field内のtypeをフィールドのJava型と置き換えるか、または表の実際のセットstaticフィールド・ルーチン名の1つを使用し、かつNativeTypeをそのルーチンに対応するネイティブ型と置き換える必要があります。
SetStatic<type>Fieldルーチン名 | NativeType |
---|---|
SetStaticObjectField() |
jobject |
SetStaticBooleanField() |
jboolean |
SetStaticByteField() |
jbyte |
SetStaticCharField() |
jchar |
SetStaticShortField() |
jshort |
SetStaticIntField() |
jint |
SetStaticLongField() |
jlong |
SetStaticFloatField() |
jfloat |
SetStaticDoubleField() |
jdouble |
リンケージ:
JNIEnvインタフェース関数表のインデックス。
SetStatic<type>Fieldルーチン名 | 索引 |
---|---|
SetStaticObjectField() |
154 |
SetStaticBooleanField() |
155 |
SetStaticByteField() |
156 |
SetStaticCharField() |
157 |
SetStaticShortField() |
158 |
SetStaticIntField() |
159 |
SetStaticLongField() |
160 |
SetStaticFloatField() |
161 |
SetStaticDoubleField() |
162 |
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
clazz
: Javaクラス・オブジェクトは、NULL
であってはなりません。
fieldID
: 有効な静的フィールドID。
value
: フィールドの新しい値。
staticメソッドの呼び出し
ネイティブ・コードからメソッドを呼び出すときは、メソッドがcaller-sensitiveであるかどうかに注意してください。
GetStaticMethodID
jmethodID GetStaticMethodID(JNIEnv *env, jclass clazz, const char *name, const char *sig);
クラスのstaticメソッドを表すメソッドIDを返します。 このメソッドは、その名前とシグニチャで指定します。
GetStaticMethodID()
によって、まだ初期化されていないクラスが初期化されます。
リンケージ:
JNIEnvインタフェース関数表のインデックス113。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
clazz
: Javaクラス・オブジェクトは、NULL
であってはなりません。
name
: 0で終了する変更されたUTF-8文字列内の静的メソッド名は、NULL
であってはなりません。
sig
: 0で終了する修正UTF-8文字列のメソッド・シグネチャは、NULL
であってはなりません。
戻り値:
メソッドIDを返します。操作が失敗した場合はNULL
を返します。
例外:
NoSuchMethodError
: 指定されたstaticメソッドが見つからない場合。
ExceptionInInitializerError
: クラスの初期化子が例外のために失敗した場合。
OutOfMemoryError
: システムがメモリー不足の場合。
CallStatic<type>Methodルーチン、CallStatic<type>MethodAルーチン、CallStatic<type>MethodVルーチン
NativeType CallStatic<type>Method(JNIEnv *env, jclass clazz, jmethodID methodID, ...);
NativeType CallStatic<type>MethodA(JNIEnv *env, jclass clazz, jmethodID methodID, jvalue *args);
NativeType CallStatic<type>MethodV(JNIEnv *env, jclass clazz, jmethodID methodID, va_list args);
この演算ファミリは、指定されたメソッドIDに従って、Javaオブジェクト上のstaticメソッドを呼び出します。 methodID
引数は、GetStaticMethodID()
をコールして取得する必要があります。
メソッドIDは、スーパークラスの1つではなく、clazz
から導出される必要があります。
CallStatic<type>Methodルーチン
プログラマは、methodID
引数の直後にメソッドに渡されるすべての引数を配置する必要があります。 CallStatic<type>Methodルーチンは、これらの引数を受け取り、プログラマが呼び出したいJavaメソッドに渡します。
CallStatic<type>MethodAルーチン
プログラマは、メソッドへのすべての引数を、methodID
引数の直後に続くjvalues
のargs
配列に配置する必要があります。 CallStaticMethodAルーチンは、この配列内の引数を受け取り、プログラマが呼び出したいJavaメソッドに渡します。
CallStatic<type>MethodVルーチン
プログラマは、メソッドに渡す引数をすべて、methodID
引数の直後のva_list
型のargs
引数に入れます。 CallStaticMethodVルーチンは、これらの引数を受け取り、プログラマが呼び出したいJavaメソッドに渡します。
次の表には、メソッド呼出しルーチンがそれぞれその結果の型によって示されています。 CallStatic<type>Method内のtypeをメソッドのJava型と置き換えるか、または表の実際のメソッド呼出しルーチン名の1つを使用し、かつNativeTypeをそのルーチンに対応するネイティブ型と置き換える必要があります。
CallStatic<type>Methodルーチン名 | ネイティブ型 |
---|---|
CallStaticVoidMethod() CallStaticVoidMethodA() CallStaticVoidMethodV() |
void |
CallStaticObjectMethod() CallStaticObjectMethodA() CallStaticObjectMethodV() |
jobject |
CallStaticBooleanMethod() CallStaticBooleanMethodA() CallStaticBooleanMethodV() |
jboolean |
CallStaticByteMethod() CallStaticByteMethodA() CallStaticByteMethodV() |
jbyte |
CallStaticCharMethod() CallStaticCharMethodA() CallStaticCharMethodV() |
jchar |
CallStaticShortMethod() CallStaticShortMethodA() CallStaticShortMethodV() |
jshort |
CallStaticIntMethod() CallStaticIntMethodA() CallStaticIntMethodV() |
jint |
CallStaticLongMethod() CallStaticLongMethodA() CallStaticLongMethodV() |
jlong |
CallStaticFloatMethod() CallStaticFloatMethodA() CallStaticFloatMethodV() |
jfloat |
CallStaticDoubleMethod() CallStaticDoubleMethodA() CallStaticDoubleMethodV() |
jdouble |
リンケージ:
JNIEnvインタフェース関数表のインデックス。
CallStatic<type>Methodルーチン名 | 索引 |
---|---|
CallStaticVoidMethod() CallStaticVoidMethodA() CallStaticVoidMethodV() |
141 143 142 |
CallStaticObjectMethod() CallStaticObjectMethodA() CallStaticObjectMethodV() |
114 116 115 |
CallStaticBooleanMethod() CallStaticBooleanMethodA() CallStaticBooleanMethodV() |
117 119 118 |
CallStaticByteMethod() CallStaticByteMethodA() CallStaticByteMethodV() |
120 122 121 |
CallStaticCharMethod() CallStaticCharMethodA() CallStaticCharMethodV() |
123 125 124 |
CallStaticShortMethod() CallStaticShortMethodA() CallStaticShortMethodV() |
126 128 127 |
CallStaticIntMethod() CallStaticIntMethodA() CallStaticIntMethodV() |
129 131 130 |
CallStaticLongMethod() CallStaticLongMethodA() CallStaticLongMethodV() |
132 134 133 |
CallStaticFloatMethod() CallStaticFloatMethodA() CallStaticFloatMethodV() |
135 137 136 |
CallStaticDoubleMethod() CallStaticDoubleMethodA() CallStaticDoubleMethodV() |
138 140 139 |
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
clazz
: Javaクラス・オブジェクトは、NULL
であってはなりません。
methodID
: 有効な静的メソッドID。
CallStatic<type>Methodルーチンに必要な追加パラメータ:
staticメソッドの引数。
CallStatic<type>MethodAルーチンに必要な追加パラメータ:
args
: 引数の配列。
CallStatic<type>MethodVルーチンに必要な追加パラメータ:
args
: 引数のva_list
。
戻り値:
static Javaメソッドを呼び出した結果を返します。
例外:
Javaメソッドを実行している間に発生した例外。
文字列操作
この仕様では、JVMがJava文字列を内部的にどのように表現するかについては想定していません。 これらの操作から返される文字列:
GetStringChars()
GetStringUTFChars()
GetStringRegion()
GetStringUTFRegion()
GetStringCritical()
したがって、NULLで終了する必要はありません。 プログラマは、GetStringLength()
またはGetStringUTFLength()
を介してバッファ容量要件を決定することが期待されます。
NewString
jstring NewString(JNIEnv *env, const jchar *unicodeChars, jsize len);
Unicode文字の配列から新しいjava.lang.String
オブジェクトを構築します。
リンケージ:
JNIEnvインタフェース関数表のインデックス163。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
unicodeChars
: Unicode文字列を参照するポインタ。 NULL
の値にすることができます。この場合、len
は0にする必要があります。
len
: Unicode文字列の長さ。 0の場合もあります。
戻り値:
Java文字列オブジェクトを返します。文字列を構築できない場合はNULL
を返します。
例外:
OutOfMemoryError
: システムがメモリー不足の場合。
GetStringLength
jsize GetStringLength(JNIEnv *env, jstring string);
Java文字列の長さ(Unicode文字のカウント)を返します。
リンケージ:
JNIEnvインタフェース関数表のインデックス164。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
string
: Java文字列オブジェクトは、NULL
であってはなりません。
戻り値:
Java文字列の長さを返します。
GetStringChars
const jchar * GetStringChars(JNIEnv *env, jstring string, jboolean *isCopy);
文字列のUnicode文字の配列を参照するポインタを返します。 このポインタは、ReleaseStringChars()
が呼び出されるまで有効です。
isCopy
がNULL
でない場合、コピーが作成された場合は*isCopy
がJNI_TRUE
に設定され、コピーが作成されなかった場合はJNI_FALSE
に設定されます。
リンケージ:
JNIEnvインタフェース関数表のインデックス165。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
string
: Java文字列オブジェクトは、NULL
であってはなりません。
isCopy
: ブール値へのポインタは、NULL
の値になります。
戻り値:
Unicode文字列を参照するポインタを返すか、処理が失敗した場合はNULL
を返します。
ReleaseStringChars
void ReleaseStringChars(JNIEnv *env, jstring string, const jchar *chars);
ネイティブ・コードがchars
にアクセスする必要がなくなったことをVMに知らせます。 chars
引数は、GetStringChars()
を使用してstring
から取得されるポインタです。
リンケージ:
JNIEnvインタフェース関数表のインデックス166。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
string
: Java文字列オブジェクトは、NULL
であってはなりません。
chars
: GetStringChars()
によって以前に返されたUnicode文字列へのポインタ。
NewStringUTF
jstring NewStringUTF(JNIEnv *env, const char *bytes);
変更されたUTF-8エンコーディングの文字配列から新しいjava.lang.String
オブジェクトを構築します。
リンケージ:
JNIEnvインタフェース関数表のインデックス167。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
bytes
: 変更されたUTF-8文字列へのポインタは、NULL
であってはなりません。
戻り値:
Java文字列オブジェクトを返します。文字列を構築できない場合はNULL
を返します。
例外:
OutOfMemoryError
: システムがメモリー不足の場合。
GetStringUTFLength
jsize GetStringUTFLength(JNIEnv *env, jstring string);
文字列の長さを変更後のUTF-8によるバイト数で返します。
リンケージ:
JNIEnvインタフェース関数表のインデックス168。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
string
: Java文字列オブジェクトは、NULL
であってはなりません。
戻り値:
文字列のUTF-8長を返します。
GetStringUTFChars
const char * GetStringUTFChars(JNIEnv *env, jstring string, jboolean *isCopy);
変更後のUTF-8エンコーディングによる文字列を表すバイト配列を参照するポインタを返します。 この配列は、ReleaseStringUTFChars()
によって解放されるまで有効です。
isCopy
がNULL
でない場合、コピーが作成された場合は*isCopy
がJNI_TRUE
に設定され、コピーが作成されなかった場合はJNI_FALSE
に設定されます。
リンケージ:
JNIEnvインタフェース関数表のインデックス169。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
string
: Java文字列オブジェクトは、NULL
であってはなりません。
isCopy
: ブール値へのポインタは、NULL
の値になります。
戻り値:
変更後のUTF-8文字列を参照するポインタを返します。演算に失敗した場合は、NULL
を返します。
ReleaseStringUTFChars
void ReleaseStringUTFChars(JNIEnv *env, jstring string, const char *utf);
ネイティブ・コードがutf
にアクセスする必要がなくなったことをVMに知らせます。 utf
引数は、GetStringUTFChars()
を使用してstring
から導出されたポインタです。
リンケージ:
JNIEnvインタフェース関数表のインデックス170。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
string
: Java文字列オブジェクトは、NULL
であってはなりません。
utf
: 以前はGetStringUTFChars()
によって返された、変更されたUTF-8文字列へのポインタ。
ノート: JDK/JRE 1.1では、プログラマはユーザーが提供するバッファのプリミティブ配列要素を取得できました。 JDK/JRE 1.2では、ネイティブ・コードを使用して、ユーザーが提供するバッファからUnicode (UTF-16)または変更後のUTF-8エンコーディングによる文字を取得できる関数セットを追加されました。 このあとの例を参照してください。
GetStringRegion
void GetStringRegion(JNIEnv *env, jstring str, jsize start, jsize len, jchar *buf);
オフセットstart
で始まるlen
個のUnicode文字を、与えられたバッファbuf
にコピーします。
リンケージ:
JNIEnvインタフェース関数表のインデックス220。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
str
: Java文字列オブジェクトは、NULL
であってはなりません。
start
: コピーする文字列の最初のUnicode文字のインデックス。 ゼロ以上で、文字列の長さが("GetStringLength()
")より小さい値でなければなりません。
len
: コピーするUnicode文字の数。 ゼロ以上でなければならず、"start + len
"は文字列の長さ("GetStringLength()
")より小さくなければなりません。
buf
: 文字列領域をコピーするUnicode文字バッファ。 len
が0より大きい場合は、NULL
であってはなりません。
例外:
StringIndexOutOfBoundsException
: インデックス・オーバーフロー。
導入されたバージョン:
JDK/JRE 1.2
GetStringUTFRegion
void GetStringUTFRegion(JNIEnv *env, jstring str, jsize start, jsize len, char *buf);
オフセットstart
で始まるlen
個のUnicode文字を変更後のUTF-8エンコーディングに変換し、その結果を、指定されたバッファbuf
に置きます。
len
引数には、「ユニコード文字」の数を指定します。 結果の変更されたUTF-8エンコード文字は、指定されたlen
引き数よりも大きい場合があります。 GetStringUTFLength()
を使用して、必要な文字バッファの最大サイズを判断できます。
この仕様では、結果の文字列のコピーをNULLで終了する必要はないので、この関数を使用する前に、strlen()
を安全に実行するために、指定された文字バッファ(e.g. "memset()
")をクリアすることをお勧めします。
リンケージ:
JNIEnvインタフェース関数表のインデックス221。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
str
: Java文字列オブジェクトは、NULL
であってはなりません。
start
: コピーする文字列の最初のUnicode文字のインデックス。 ゼロ以上で、文字列の長さより小さくなければなりません。
len
: コピーするUnicode文字の数。 0より大きくなければならず、"start + len
"は文字列長("GetStringLength()
")より小さくなければなりません。
buf
: 文字列領域をコピーするUnicode文字バッファ。 len
が0より大きい場合は、NULL
であってはなりません。
例外:
StringIndexOutOfBoundsException
: インデックス・オーバーフロー。
導入されたバージョン:
JDK/JRE 1.2
GetStringCritical、ReleaseStringCritical
const jchar * GetStringCritical(JNIEnv *env, jstring string, jboolean *isCopy);
void ReleaseStringCritical(JNIEnv *env, jstring string, const jchar *carray);
これら2つの関数のセマンティックスは、既存のGet/ReleaseStringChars
関数に似ています。 可能な場合には、VMは文字列要素へのポインタを返します。そうでない場合、コピーが作成されます。 ただし、これらの関数の使用方法に関して重要な制限があります。 Get/ReleaseStringCritical
の呼出しによって囲まれるコード・セグメントにおいて、ネイティブ・コードは任意のJNI呼出しを行ったり、現在のスレッドにブロックさせてはなりません。
Get/ReleaseStringCritical
の制限は、Get/ReleasePrimitiveArrayCritical
の制限に似ています。
リンケージ(GetStringCritical):
JNIEnvインタフェース関数表のインデックス224。
リンケージ(ReleaseStingCritical):
JNIEnvインタフェース関数表のインデックス225。
関連項目:
導入されたバージョン:
JDK/JRE 1.2
配列操作
GetArrayLength
jsize GetArrayLength(JNIEnv *env, jarray array);
配列内の要素の数を返します。
リンケージ:
JNIEnvインタフェース関数表のインデックス171。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
array
: Java配列オブジェクトは、NULL
であってはなりません。
戻り値:
配列の長さを返します。
NewObjectArray
jobjectArray NewObjectArray(JNIEnv *env, jsize length, jclass elementClass, jobject initialElement);
クラスelementClass
にオブジェクトを持つ新しい配列を構築します。 要素はすべて、最初はinitialElement
に設定されます。
リンケージ:
JNIEnvインタフェース関数表のインデックス172。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
length
: 配列サイズは、> = 0でなければなりません。
elementClass
: 配列要素クラスであり、NULL
であってはなりません。
initialElement
: 初期値は、NULL
の値であってもよい。
戻り値:
Java配列オブジェクトを返します。配列を構築できない場合はNULL
を返します。
例外:
OutOfMemoryError
: システムがメモリー不足の場合。
GetObjectArrayElement
jobject GetObjectArrayElement(JNIEnv *env, jobjectArray array, jsize index);
Object
配列の要素を返します。
リンケージ:
JNIEnvインタフェース関数表のインデックス173。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
array
: Java配列は、NULL
であってはなりません。
index
: 配列インデックスは、>= 0で配列長が("GetArrayLength()
")より小さい配列でなければなりません。
戻り値:
Javaオブジェクトを返します。
例外:
ArrayIndexOutOfBoundsException
: index
が配列に有効な索引を指定していない場合。
SetObjectArrayElement
void SetObjectArrayElement(JNIEnv *env, jobjectArray array, jsize index, jobject value);
Object
配列の要素を設定します。
リンケージ:
JNIEnvインタフェース関数表のインデックス174。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
array
: Java配列は、NULL
であってはなりません。
index
: 配列インデックスは、>= 0で配列長が("GetArrayLength()
")より小さい配列でなければなりません。
value
: 新しい値は、NULL
値です。
例外:
ArrayIndexOutOfBoundsException
: index
が配列に有効な索引を指定していない場合。
ArrayStoreException
: value
のクラスが、配列の要素クラスのサブクラスではない場合。
New<PrimitiveType>Arrayルーチン
ArrayType New<PrimitiveType>Array(JNIEnv *env, jsize length);
新しいプリミティブ配列オブジェクトを構築するために使用される演算のファミリ。 次の表には、特定のプリミティブ配列コンストラクタが示されています。 New<PrimitiveType>Arrayを、この表の実際のプリミティブ配列コンストラクタ・ルーチン名の1つと置き換え、ArrayTypeをそのルーチンに対応する配列型と置き換える必要があります。
New<PrimitiveType>Arrayルーチン | 配列型 |
---|---|
NewBooleanArray() |
jbooleanArray |
NewByteArray() |
jbyteArray |
NewCharArray() |
jcharArray |
NewShortArray() |
jshortArray |
NewIntArray() |
jintArray |
NewLongArray() |
jlongArray |
NewFloatArray() |
jfloatArray |
NewDoubleArray() |
jdoubleArray |
リンケージ:
JNIEnvインタフェース関数表のインデックス。
New<PrimitiveType>Arrayルーチン | 索引 |
---|---|
NewBooleanArray() |
175 |
NewByteArray() |
176 |
NewCharArray() |
177 |
NewShortArray() |
178 |
NewIntArray() |
179 |
NewLongArray() |
180 |
NewFloatArray() |
181 |
NewDoubleArray() |
182 |
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
length
: 配列の長さは> = 0でなければなりません。
戻り値:
Java配列を返します。配列を構築できない場合はNULL
を返します。
例外:
OutOfMemoryError
: システムがメモリー不足の場合。
Get<PrimitiveType>ArrayElementsルーチン
NativeType *
「<PrimitiveType> ArrayElementsの取得」 (JNIEnv *env,
ArrayType array, jboolean *isCopy);
プリミティブ配列の本体を返す関数のファミリです。 結果は、対応する「リリース<PrimitiveType> ArrayElements()」関数がコールされるまで有効です。 返される配列はJava配列のコピーである可能性があるため、返された配列に対する変更は、Release<PrimitiveType>ArrayElements()が呼び出されるまで必ず元の配列に反映されるとは限りません。
isCopy
がNULL
でない場合、コピーが作成された場合は*isCopy
がJNI_TRUE
に設定され、コピーが作成されなかった場合はJNI_FALSE
に設定されます。
次の表には、特定のプリミティブ配列要素アクセス機能が示されています。 次の置換を行う必要があります。
- Get<PrimitiveType>ArrayElementsを、次の表の実際のプリミティブ要素アクセス用ルーチン名の1つと置き換える。
- ArrayTypeを対応する配列型と置き換える。
- NativeTypeを、そのルーチンに対応するネイティブ型と置き換える。
Java VMでのブール配列の表現方法に関係なく、GetBooleanArrayElements()
は常にjbooleans
へのポインタを返し、各バイトは(展開された表現)要素を示します。 その他の型の配列はすべて、メモリー内で必ず隣接するようになっています。
Get<PrimitiveType>ArrayElementsルーチン | 配列型 | ネイティブ型 |
---|---|---|
GetBooleanArrayElements() |
jbooleanArray | jboolean |
GetByteArrayElements() |
jbyteArray | jbyte |
GetCharArrayElements() |
jcharArray | jchar |
GetShortArrayElements() |
jshortArray | jshort |
GetIntArrayElements() |
jintArray | jint |
GetLongArrayElements() |
jlongArray | jlong |
GetFloatArrayElements() |
jfloatArray | jfloat |
GetDoubleArrayElements() |
jdoubleArray | jdouble |
リンケージ:
JNIEnvインタフェース関数表のインデックス。
Get<PrimitiveType>ArrayElementsルーチン | 索引 |
---|---|
GetBooleanArrayElements() |
183 |
GetByteArrayElements() |
184 |
GetCharArrayElements() |
185 |
GetShortArrayElements() |
186 |
GetIntArrayElements() |
187 |
GetLongArrayElements() |
188 |
GetFloatArrayElements() |
189 |
GetDoubleArrayElements() |
190 |
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
array
: Java配列オブジェクトは、NULL
であってはなりません。
isCopy
: ブール値へのポインタは、NULL
の値になります。
戻り値:
配列要素を参照するポインタを返すか、処理が失敗した場合はNULL
を返します。
例外:
OutOfMemoryError
: システムがメモリー不足の場合。
Release<PrimitiveType>ArrayElementsルーチン
void
「リリース <PrimitiveType> ArrayElements」 (JNIEnv *env,
ArrayType array,
NativeType *elems, jint mode);
ネイティブ・コードがelems
にアクセスする必要がなくなったことをVMに通知する関数ファミリ。 elems
引数は、対応するGet<PrimitiveType>ArrayElements()関数を使用してarray
から派生したポインタです。 必要に応じて、この関数は、elems
に施された変更をすべて元の配列にコピーし直します。
mode
引数は、配列バッファの解放方法に関する情報を提供します。elems
がarray
の要素のコピーでない場合、mode
は影響しません。 それ以外の場合、mode
は次の表に示されているような影響を及ぼします。
mode | actions |
---|---|
0 |
内容を元の配列にコピーし直し、elems バッファを解放する |
JNI_COMMIT |
内容を元の配列にコピーし直すが、elems バッファを解放しない |
JNI_ABORT |
変更の可能性があってもその内容を元に戻さず、バッファを解放する |
ほとんどの場合、プログラマは"0"をmode
引数として渡して、固定配列とコピーした配列の両方の一貫した動作を実現します。 0以外を渡す場合は、プログラマはメモリーを十分に注意して管理する必要があります。 elems
がarray
の要素のコピーである場合に、JNI_COMMIT
がmode
引数として渡される場合は、"0"またはJNI_ABORT
のmode
引数を渡す「リリース<PrimitiveType> ArrayElements」への最後のコールを行って、elems
バッファを解放する必要があります。
次の表には、プリミティブ配列処置機能のファミリを構成する特定のルーチンが示されています。 次の置換を行う必要があります。
- Release<PrimitiveType>ArrayElementsを、次の表に示されている実際のプリミティブ配列処置機能ルーチン名のいずれかと置き換える。
- ArrayTypeを対応する配列型と置き換える。
- NativeTypeを、そのルーチンに対応するネイティブ型と置き換える。
Release<PrimitiveType>ArrayElementsルーチン | 配列型 | ネイティブ型 |
---|---|---|
ReleaseBooleanArrayElements() |
jbooleanArray | jboolean |
ReleaseByteArrayElements() |
jbyteArray | jbyte |
ReleaseCharArrayElements() |
jcharArray | jchar |
ReleaseShortArrayElements() |
jshortArray | jshort |
ReleaseIntArrayElements() |
jintArray | jint |
ReleaseLongArrayElements() |
jlongArray | jlong |
ReleaseFloatArrayElements() |
jfloatArray | jfloat |
ReleaseDoubleArrayElements() |
jdoubleArray | jdouble |
リンケージ:
JNIEnvインタフェース関数表のインデックス。
Release<PrimitiveType>ArrayElementsルーチン | 索引 |
---|---|
ReleaseBooleanArrayElements() |
191 |
ReleaseByteArrayElements() |
192 |
ReleaseCharArrayElements() |
193 |
ReleaseShortArrayElements() |
194 |
ReleaseIntArrayElements() |
195 |
ReleaseLongArrayElements() |
196 |
ReleaseFloatArrayElements() |
197 |
ReleaseDoubleArrayElements() |
198 |
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
array
: Java配列オブジェクトは、NULL
であってはなりません。
elems
: 以前のGet<PrimitiveType>ArrayElements呼び出しによって返された配列要素へのポインタ。
mode
: リリース・モード: 0
、JNI_COMMIT
またはJNI_ABORT
。
Get<PrimitiveType>ArrayRegionルーチン
void
Get<PrimitiveType>ArrayRegion(JNIEnv *env,
ArrayType array, jsize start, jsize len,
NativeType *buf);
プリミティブ配列の領域をバッファにコピーする関数のファミリです。
次の表には、特定のプリミティブ配列要素アクセス機能が示されています。 次の置換を行う必要があります。
- Get<PrimitiveType>ArrayRegionを、次の表に示されている実際のプリミティブ要素アクセス用ルーチン名のいずれかと置き換える。
- ArrayTypeを対応する配列型と置き換える。
- NativeTypeを、そのルーチンに対応するネイティブ型と置き換える。
Get<PrimitiveType>ArrayRegionルーチン | 配列型 | ネイティブ型 |
---|---|---|
GetBooleanArrayRegion() |
jbooleanArray | jboolean |
GetByteArrayRegion() |
jbyteArray | jbyte |
GetCharArrayRegion() |
jcharArray | jchar |
GetShortArrayRegion() |
jshortArray | jhort |
GetIntArrayRegion() |
jintArray | jint |
GetLongArrayRegion() |
jlongArray | jlong |
GetFloatArrayRegion() |
jfloatArray | jloat |
GetDoubleArrayRegion() |
jdoubleArray | jdouble |
リンケージ:
JNIEnvインタフェース関数表のインデックス。
Get<PrimitiveType>ArrayRegionルーチン | 索引 |
---|---|
GetBooleanArrayRegion() |
199 |
GetByteArrayRegion() |
200 |
GetCharArrayRegion() |
201 |
GetShortArrayRegion() |
202 |
GetIntArrayRegion() |
203 |
GetLongArrayRegion() |
204 |
GetFloatArrayRegion() |
205 |
GetDoubleArrayRegion() |
206 |
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
array
: Java配列は、NULL
であってはなりません。
start
: 開始インデックスは0以上で、配列の長さ(GetArrayLength()
)より小さくなければなりません。
len
: コピーする要素の数はゼロ以上でなければならず、"start + len
"は配列の長さ("GetArrayLength()
")より小さくなければなりません。
buf
: 宛先バッファは、NULL
であってはなりません。
例外:
ArrayIndexOutOfBoundsException
: リージョン内の索引のいずれかが有効でない場合。
Set<PrimitiveType>ArrayRegionルーチン
void
Set<PrimitiveType>ArrayRegion (JNIEnv *env,
ArrayType array, jsize start, jsize len, const
NativeType *buf);
バッファからのプリミティブ配列の領域を元の値に戻す関数のファミリです。
次の表には、特定のプリミティブ配列要素アクセス機能が示されています。 次の置換を行う必要があります。
- Set<PrimitiveType>ArrayRegionを、次の表の実際のプリミティブ要素アクセス用ルーチン名の1つと置き換える。
- ArrayTypeを対応する配列型と置き換える。
- NativeTypeを、そのルーチンに対応するネイティブ型と置き換える。
Set<PrimitiveType>ArrayRegionルーチン | 配列型 | ネイティブ型 |
---|---|---|
SetBooleanArrayRegion() |
jbooleanArray | jboolean |
SetByteArrayRegion() |
jbyteArray | jbyte |
SetCharArrayRegion() |
jcharArray | jchar |
SetShortArrayRegion() |
jshortArray | jshort |
SetIntArrayRegion() |
jintArray | jint |
SetLongArrayRegion() |
jlongArray | jlong |
SetFloatArrayRegion() |
jfloatArray | jfloat |
SetDoubleArrayRegion() |
jdoubleArray | jdouble |
リンケージ:
JNIEnvインタフェース関数表のインデックス。
Set<PrimitiveType>ArrayRegionルーチン | 索引 |
---|---|
SetBooleanArrayRegion() |
207 |
SetByteArrayRegion() |
208 |
SetCharArrayRegion() |
209 |
SetShortArrayRegion() |
210 |
SetIntArrayRegion() |
211 |
SetLongArrayRegion() |
212 |
SetFloatArrayRegion() |
213 |
SetDoubleArrayRegion() |
214 |
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
array
: Java配列は、NULL
であってはなりません。
start
: 開始インデックスは0以上で、配列の長さ(GetArrayLength()
)より小さくなければなりません。
len
: コピーする要素の数はゼロ以上でなければならず、"start + len
"は配列の長さ("GetArrayLength()
")より小さくなければなりません。
buf
: ソース・バッファは、NULL
であってはなりません。
例外:
ArrayIndexOutOfBoundsException
: リージョン内の索引のいずれかが有効でない場合。
ノート: プログラマは、<primitivetype> ArrayElementsの取得/リリースファンクションを使用してプリミティブ配列要素へのポインタを取得できます。 VMがピニングをサポートしている場合、元のデータへのポインタが返されました。そうでない場合には、コピーが作成されました。 「<primitivetype> ArrayCriticalの取得/リリース」関数を使用すると、ネイティブ・コードで配列要素への直接ポインタを取得できます。これは、VMで固定がサポートされていない場合でも同様です。
GetPrimitiveArrayCritical、ReleasePrimitiveArrayCritical
void * GetPrimitiveArrayCritical(JNIEnv *env, jarray array, jboolean *isCopy);
void ReleasePrimitiveArrayCritical(JNIEnv *env, jarray array, void *carray, jint mode);
これらの2つの関数のセマンティクスは、既存の「<primitivetype> ArrayElementsの取得/リリース」関数と非常によく似ています。 可能な場合は、VMはプリミティブ配列へのポインタを返します。そうでない場合は、コピーが作成されます。 ただし、これらの関数の使用方法に関して重要な制限があります。
GetPrimitiveArrayCritical
を呼び出したあと、ReleasePrimitiveArrayCritical
を呼び出す前に、ネイティブ・コードを特定の期間実行しないようにします。 この1組の関数内部のコードは「クリティカル・リージョン」で実行されているものとして扱う必要があります。 クリティカル・リージョン内部においてネイティブ・コードは、ほかのJNI関数を呼び出してはならず、現在のスレッドにほかのJavaスレッドをブロックして待機させることを可能にするどのシステム・コールも呼び出してはいけません。 (たとえば、現在のスレッドは、ほかのJavaスレッドが書き込んでいるストリームに対してread
を呼び出してはいけません。)
これらの制限は、VMがピニングをサポートしない場合でも、ネイティブ・コードが配列のコピーされていないバージョンを取得する可能性を高めます。 たとえば、ネイティブ・コードがGetPrimitiveArrayCritical
によって取得された配列へのポインタを保持している場合、VMは一時的にガベージ・コレクションを無効にすることがあります。
GetPrimtiveArrayCritical
とReleasePrimitiveArrayCritical
の複数のペアを入れ子にすることができます。 たとえば:
jint len = (*env)->GetArrayLength(env, arr1);
jbyte *a1 = (*env)->GetPrimitiveArrayCritical(env, arr1, 0);
jbyte *a2 = (*env)->GetPrimitiveArrayCritical(env, arr2, 0);
/* We need to check in case the VM tried to make a copy. */
if (a1 == NULL || a2 == NULL) {
... /* out of memory exception thrown */
}
memcpy(a1, a2, len);
(*env)->ReleasePrimitiveArrayCritical(env, arr2, a2, 0);
(*env)->ReleasePrimitiveArrayCritical(env, arr1, a1, 0);
VMが内部的に異なる形式で配列を表す場合、GetPrimitiveArrayCritical
はまだ配列のコピーを作成する可能性があります。 そのため、起こり得るメモリー不足の状況に対応するために、戻り値がNULL
かどうかをチェックする必要があります。
GetPrimitiveArrayCritical
リンケージ:
JNIEnvインタフェース関数表のリンケージ・インデックス222。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
array
: Java配列は、NULL
であってはなりません。
isCopy
: ブール値へのポインタは、NULL
の値になります。
戻り値:
配列要素へのポインタを返します。操作が失敗した場合はNULLを返します。
例外:
OutOfMemoryError
: システムがメモリー不足の場合。
導入されたバージョン:
JDK/JRE 1.2
ReleasePrimitiveArrayCritical
リンケージ:
JNIEnvインタフェース関数表のリンケージ・インデックス223。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
array
: Java配列は、NULL
であってはなりません。
carray
: GetPrimitiveArrayCritical
によって返されるクリティカルな配列ポインタ。
mode
: リリース・モード(プリミティブ配列のリリース・モードを参照してください): 0
、JNI_COMMIT
またはJNI_ABORT
。 carray
がコピーでない場合は無視されます。
導入されたバージョン:
JDK/JRE 1.2
ネイティブ・メソッドの登録
RegisterNatives
jint RegisterNatives(JNIEnv *env, jclass clazz, const JNINativeMethod *methods, jint nMethods);
clazz
引数によって指定されたクラスにネイティブ・メソッドを登録します。 methods
パラメータは、ネイティブ・メソッドの名前、シグネチャおよび関数ポインタを含むJNINativeMethod
構造の配列を指定します。 JNINativeMethod構造のname
およびsignature
フィールドは、変更されたUTF-8文字列へのポインタです。 nMethods
パラメータは、配列内のネイティブ・メソッドの数を指定します。 JNINativeMethod
構造は次のように定義されます:
typedef struct {
char *name;
char *signature;
void *fnPtr;
} JNINativeMethod;
関数ポインタは、形式上、次のシグニチャを備えている必要があります。
ReturnType (*fnPtr)(JNIEnv *env, jobject objectOrClass, ...);
RegisterNatives
は、特定のネイティブJavaメソッドに対して実行されるネイティブ・コードを変更することで、JVM (暗号化アルゴリズム、正確性、セキュリティ、型の安全性を含む)のドキュメント化された動作を変更できることに注意してください。 したがって、RegisterNatives
関数を使用するネイティブ・ライブラリを持つアプリケーションは慎重に使用してください。
リンケージ:
JNIEnvインタフェース関数表のインデックス215。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
clazz
: Javaクラス・オブジェクトは、NULL
であってはなりません。
methods
: クラスのネイティブ・メソッドは、NULL
であってはなりません。
nMethods
: クラス内のネイティブ・メソッドの数はゼロより大きくなければなりません。
戻り値:
成功すると"0"を返します。失敗すると負の値を返します。
例外:
NoSuchMethodError
: 指定されたメソッドが見つからない場合、または、そのメソッドがネイティブではない場合。
UnregisterNatives
jint UnregisterNatives(JNIEnv *env, jclass clazz);
あるクラスのネイティブ・メソッドの登録を解除します。 そのクラスは、そのネイティブ・メソッド機能にリンクされる前または再登録される前の状態に戻ります。
この関数は、通常のネイティブ・コードでは使用するべきではありません。 その代わりに、特別なプログラムにネイティブ・ライブラリを再ロードしたり再リンクしたりする方法を提供します。
リンケージ:
JNIEnvインタフェース関数表のインデックス216。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
clazz
: Javaクラス・オブジェクトは、NULL
であってはなりません。
戻り値:
成功すると"0"を返します。失敗すると負の値を返します。
モニター・オペレーション
MonitorEnter
jint MonitorEnter(JNIEnv *env, jobject obj);
obj
によって参照されるベースとなるJavaオブジェクトに関連するモニターに入ります。
objによって参照されるオブジェクトに関連するモニターに入ります。 obj
参照はNULL
にはできません。
Javaオブジェクトはそれぞれ、関連するモニターを持っています。 現在のスレッドがすでにobj
に関連するモニターを所有している場合は、このスレッドがモニターに入った回数を表すモニター内のカウンタが増分されます。 obj
に関連付けられたモニターがスレッドによって所有されていない場合、現在のスレッドはモニターの所有者となり、このモニターのエントリ数を1に設定します。 別のスレッドがすでにobj
に関連するモニターを所有している場合、現在のスレッドはモニターが解放されるのを待ち、再度、所有権を獲得しようとします。
MonitorEnter
JNI関数呼出しで入ったモニターから、monitorexit
Java仮想マシンの命令またはsynchronizedメソッドの戻り値を使用して出ることはできません。 MonitorEnter
JNI関数呼び出しとmonitorenter
Java仮想マシンの命令が、同じオブジェクトに関連付けられたモニターと競合することがあります。
デッドロックを回避するには、DetachCurrentThread
呼出しを使用してJNIモニターを暗黙的に解放しないかぎり、MonitorEnter
JNI関数呼出しで入ったモニターから出る場合はMonitorExit
JNI呼出しを使用する必要があります。
リンケージ:
JNIEnvインタフェース関数表のインデックス217。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
obj
: 通常のJavaオブジェクトまたはクラス・オブジェクトは、NULL
であってはなりません。
戻り値:
成功すると"0"を返します。失敗すると負の値を返します。
MonitorExit
jint MonitorExit(JNIEnv *env, jobject obj);
現在のスレッドは、obj
によって参照されたベースとなるJavaオブジェクトに関連するモニターの所有者でなければなりません。 このスレッドは、このモニターに入った回数を表すカウンタを減少させます。 カウンタの値がゼロになると、現在のスレッドはモニターを解放します。
ネイティブ・コードは、synchronizedメソッドまたはmonitorenter
Java仮想マシンの命令で入ったモニターから出るためにMonitorExit
を使用してはいけません。
リンケージ:
JNIEnvインタフェース関数表のインデックス218。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
obj
: 通常のJavaオブジェクトまたはクラス・オブジェクトは、NULL
であってはなりません。
戻り値:
成功すると"0"を返します。失敗すると負の値を返します。
例外:
IllegalMonitorStateException
: 現在のスレッドがモニターを所有していない場合。
NIOのサポート
NIO関連のエントリ・ポイントにより、ネイティブ・コードがjava.nio
直接バッファにアクセスできます。 直接バッファのコンテンツは、通常のガベージ・コレクトされたヒープの外側の、ネイティブ・メモリー内に格納できます。 ダイレクト・バッファの詳細は、「NIOパッケージ内のバッファ」およびjava.nio.ByteBuffer
クラスの仕様を参照してください。
次の3つの関数によって、JNIコードで直接バッファを作成、調査および操作できます:
Java仮想マシンの各実装ではこれらの関数をサポートする必要がありますが、すべての実装が直接バッファへのJNIのアクセスをサポートする必要はありません。 JVMがそのようなアクセスをサポートしていない場合、NewDirectByteBuffer
およびGetDirectBufferAddress
関数は常にNULL
を返し、GetDirectBufferCapacity
関数は常に-1
を返す必要があります。 JVMがこのようなアクセスをサポートする場合、これら3つの関数は適切な値を返すように実装される必要があります。
NewDirectByteBuffer
jobject NewDirectByteBuffer(JNIEnv* env, void* address, jlong capacity);
メモリー・アドレスaddress
から始まるメモリーのブロックおよびcapacity
バイトを拡張する直接java.nio.ByteBuffer
を割り当てて返します。 返されるバッファのバイト順序は常にビッグ・エンディアン(1バイト大きい、つまりjava.nio.ByteOrder.BIG_ENDIAN
)です。
この関数を呼び出して、Javaレベルのコードに最終的なバイト・バッファのオブジェクトを返すネイティブ・コードは、そのバッファが、読み込みと、適切な場合には書出しのアクセスが可能な、有効なメモリー領域を参照する必要があります。 Javaコードから無効なメモリー位置にアクセスしようとすると、視覚効果のない任意の値を返すか、指定されていない例外が発生します。
リンケージ:
JNIEnvインタフェース関数表のインデックス229。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
address
: メモリー領域の開始アドレスは、NULL
であってはなりません。
capacity
: メモリー領域のバイト単位のサイズは正でなければなりません。
戻り値:
新しくインスタンス化されたjava.nio.ByteBuffer
オブジェクトへのローカル参照を返します。 例外が発生した場合、またはダイレクト・バッファへのJNIアクセスがこの仮想マシンでサポートされていない場合、NULL
を返します。
例外:
OutOfMemoryError
: ByteBuffer
オブジェクトの割当てが失敗した場合
導入されたバージョン:
JDK/JRE 1.4
GetDirectBufferAddress
void* GetDirectBufferAddress(JNIEnv* env, jobject buf);
指定された直接java.nio.Buffer
によって参照されるメモリー・リージョンの開始アドレスをフェッチして返します。
この関数によって、ネイティブ・コードは、Javaコードがバッファ・オブジェクトを介してアクセスできるメモリー領域と同じメモリー領域にアクセスできるようになります。
リンケージ:
JNIEnvインタフェース関数表のインデックス230。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
buf
: 直接java.nio.Buffer
オブジェクトは、NULL
であってはなりません。
戻り値:
バッファに参照されるメモリー領域の開始アドレスを返します。 メモリー・リージョンが未定義の場合、指定されたオブジェクトが直接のjava.nio.Buffer
でない場合、または直接バッファへのJNIアクセスがこの仮想マシンでサポートされていない場合、NULL
を返します。
導入されたバージョン:
JDK/JRE 1.4
GetDirectBufferCapacity
jlong GetDirectBufferCapacity(JNIEnv* env, jobject buf);
指定された直接java.nio.Buffer
によって参照されるメモリー・リージョンの容量をフェッチして返します。 この容量は、そのメモリー領域に含まれている要素の数です。
リンケージ:
JNIEnvインタフェース関数表のインデックス231。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
buf
: 直接java.nio.Buffer
オブジェクトは、NULL
であってはなりません。
戻り値:
バッファに関連付けられたメモリー領域の容量を返します。 指定されたオブジェクトが直接java.nio.Buffer
ではない場合、オブジェクトが未整列ビューバッファであり、プロセッサアーキテクチャが未整列アクセスをサポートしていない場合、または直接バッファへのJNIアクセスがこの仮想マシンでサポートされていない場合に、-1
を返します。
導入されたバージョン:
JDK/JRE 1.4
リフレクションのサポート
プログラマは、メソッドまたはフィールドの名前および型を把握している場合、JNIを使用してJavaメソッドの呼び出しまたはJavaフィールドへのアクセスを行うことができます。 Java Core Reflection APIを使用すると、プログラマは実行時にJavaクラスの内部を調査できます。 JNIは、JNIで使用されるフィールドとメソッドIDおよびJava Core Reflection APIで使用されるメソッド・オブジェクトの間の変換関数のセットを提供します。
FromReflectedMethod
jmethodID FromReflectedMethod(JNIEnv *env, jobject method);
java.lang.reflect.Method
またはjava.lang.reflect.Constructor
オブジェクトをメソッドIDに変換します。
リンケージ:
JNIEnvインタフェース関数表のインデックス7。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
method
: java.lang.reflect.Method
またはjava.lang.reflect.Constructor
オブジェクトは、NULL
であってはなりません。
戻り値:
指定されたJavaリフレクション・メソッドに対応するJNIメソッドID。操作が失敗した場合はNULL。
導入されたバージョン:
JDK/JRE 1.2
FromReflectedField
jfieldID FromReflectedField(JNIEnv *env, jobject field);
java.lang.reflect.Field
をフィールドIDに変換します。
リンケージ:
JNIEnvインタフェース関数表のインデックス8。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
field
: java.lang.reflect.Field
オブジェクトは、NULL
であってはなりません。
戻り値:
指定されたJavaリフレクションfield
に対応するJNIフィールドID、または操作が失敗した場合はNULL
。
導入されたバージョン:
JDK/JRE 1.2
ToReflectedMethod
jobject ToReflectedMethod(JNIEnv *env, jclass cls, jmethodID methodID, jboolean isStatic);
cls
から導出されたメソッドIDをjava.lang.reflect.Method
またはjava.lang.reflect.Constructor
オブジェクトに変換します。isStatic
は、メソッドIDが静的フィールドを参照する場合はJNI_TRUE
、それ以外の場合はJNI_FALSE
に設定する必要があります。
失敗した場合はOutOfMemoryError
をスローし、0を返します。
リンケージ:
JNIEnvインタフェース関数表のインデックス9。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
cls
: Javaクラス・オブジェクトは、NULL
であってはなりません。
methodID
: メソッドIDは、NULL
であってはなりません。
isStatic
: 指定されたmethodID
が静的メソッドであるかどうかを示します。
戻り値:
指定されたmethodID
に対応するjava.lang.reflect.Method
またはjava.lang.reflect.Constructor
のインスタンス、または操作が失敗した場合はNULL
のインスタンスを返します。
導入されたバージョン:
JDK/JRE 1.2
ToReflectedField
jobject ToReflectedField(JNIEnv *env, jclass cls, jfieldID fieldID, jboolean isStatic);
cls
から導出されたフィールドIDをjava.lang.reflect.Field
オブジェクトに変換します。fieldID
が静的フィールドを参照する場合はisStatic
をJNI_TRUE
に設定し、それ以外の場合はJNI_FALSE
に設定する必要があります。
失敗した場合はOutOfMemoryError
をスローし、0を返します。
リンケージ:
JNIEnvインタフェース関数表のインデックス12。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
cls
: Javaクラス・オブジェクトは、NULL
であってはなりません。
fieldID
: フィールドIDは、NULL
であってはなりません。
isStatic
: 指定されたfieldID
が静的フィールドであるかどうかを示します。
戻り値:
与えられたfieldID
に対応するjava.lang.reflect.Field
のインスタンス、または操作が失敗した場合はNULL
を返します。
導入されたバージョン:
JDK/JRE 1.2
Java VMインタフェース
GetJavaVM
jint GetJavaVM(JNIEnv *env, JavaVM **vm);
現在のスレッドに関連するJava VMインタフェース(呼び出しAPIで使用)を返します。 その結果は、2番目の引数vm
で示された位置に置かれます。
リンケージ:
JNIEnvインタフェース関数表のインデックス219。
パラメータ:
env
: JNIインタフェース・ポインタは、NULL
であってはなりません。
vm
: 結果を配置する場所へのポインタは、NULL
であってはなりません。
戻り値:
成功すると"0"を返します。失敗すると負の値を返します。