目次|前|次

この章は、JNI関数のリファレンス・セクションです。 この章では、JNIの関数をすべて取り上げます。 また、JNI関数表の配置そのままに記載されています。

「必要がある」という言い方は、JNIプログラマに対する制限を示しています。 たとえば、あるJNI関数について、それがNULL以外のオブジェクトを受け取る必要があると説明されている場合、プログラマの責任において、そのJNI関数にNULLを渡さないようにしなければなりません。 それによって、JNI実装の際に、そのJNI関数におけるnullのポインタ・チェックを行う必要がなくなります。

この章の一部は、NetscapeのJRIドキュメントから転用されています。

参照資料では、関数を用途によってグループ化しています。 参照セクションは、次の機能分野から構成されています。

• インタフェース関数表
• バージョン情報
  • GetVersion
  • 定数
• クラス操作
  • DefineClass
  • FindClass
  • GetSuperclass
  • IsAssignableFrom
• 例外
  • Throw
  • ThrowNew
  • ExceptionOccurred
  • ExceptionDescribe
  • ExceptionClear
  • FatalError
  • ExceptionCheck
• グローバル参照およびローカル参照
  • Global References
  • NewGlobalRef
  • DeleteGlobalRef
  • Local References
  • DeleteLocalRef
  • EnsureLocalCapacity
  • PushLocalFrame
  • PopLocalFrame
  • NewLocalRef
• 弱グローバル参照
  • NewWeakGlobalRef
  • DeleteWeakGlobalRef
• オブジェクト・オペレーション
  • AllocObject
  • NewObject、NewObjectA、NewObjectV
  • GetObjectClass
  • GetObjectRefType
  • IsInstanceOf
  • IsSameObject
• オブジェクトのフィールドへのアクセス
  • GetFieldID
  • Get<type>Fieldルーチン
  • Set<type>Fieldルーチン
• インスタンス・メソッドの呼び出し
  • GetMethodID
  • Call<type>Methodルーチン、Call<type>MethodAルーチン、Call<type>MethodVルーチン
  • CallNonvirtual<type>Methodルーチン、CallNonvirtual<type>MethodAルーチン、CallNonvirtual<type>MethodVルーチン
• staticフィールドへのアクセス
  • GetStaticFieldID
  • GetStatic<type>Fieldルーチン
  • SetStatic<type>Fieldルーチン
• staticメソッドの呼び出し
  • GetStaticMethodID
  • CallStatic<type>Methodルーチン、CallStatic<type>MethodAルーチン、CallStatic<type>MethodVルーチン
• 文字列操作
  • NewString
  • GetStringLength
  • GetStringChars
  • ReleaseStringChars
  • NewStringUTF
  • GetStringUTFLength
  • GetStringUTFChars
  • ReleaseStringUTFChars
  • GetStringRegion
  • GetStringUTFRegion
  • GetStringCritical、ReleaseStringCritical
• 配列操作
  • GetArrayLength
  • NewObjectArray
  • GetObjectArrayElement
  • SetObjectArrayElement
  • New<PrimitiveType>Arrayルーチン
  • Get<PrimitiveType>ArrayElementsルーチン
  • Release<PrimitiveType>ArrayElementsルーチン
  • Get<PrimitiveType>ArrayRegionルーチン
  • Set<PrimitiveType>ArrayRegionルーチン
  • GetPrimitiveArrayCritical、ReleasePrimitiveArrayCritical
• ネイティブ・メソッドの登録
  • RegisterNatives
  • UnregisterNatives
• モニター・オペレーション
  • MonitorEnter
  • MonitorExit
• NIOのサポート
  • NewDirectByteBuffer
  • GetDirectBufferAddress
  • GetDirectBufferCapacity
• リフレクションのサポート
  • FromReflectedMethod
  • FromReflectedField
  • ToReflectedMethod
  • ToReflectedField
• Java VMインタフェース
  • GetJavaVM

インタフェース関数表

各関数は、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
  };

バージョン情報

GetVersion

jint GetVersion(JNIEnv *env);

ネイティブ・メソッド・インタフェースのバージョンを返します。

リンケージ:

JNIEnvインタフェース関数表のインデックス4。

パラメータ:

env: JNIインタフェース・ポインタ。

戻り値:

メジャー・バージョン番号を高位の16ビットで、マイナー・バージョン番号を下位の16ビットで返します。

JDK/JRE 1.1では、GetVersion()は0x00010001を返します。

JDK/JRE 1.2では、GetVersion()は0x00010002を返します。

JDK/JRE 1.4では、GetVersion()は0x00010004を返します。

JDK/JRE 1.6では、GetVersion()は0x00010006を返します。

定数

JDK/JRE 1.2以降:

#define JNI_VERSION_1_1 0x00010001
#define JNI_VERSION_1_2 0x00010002

/* Error codes */
#define JNI_EDETACHED    (-2)              /* thread detached from the VM */
#define JNI_EVERSION     (-3)              /* JNI version error 

JDK/JRE 1.4以降:

    #define JNI_VERSION_1_4 0x00010004

JDK/JRE 1.6以降:

    #define JNI_VERSION_1_6 0x00010006

クラス操作

DefineClass

jclass DefineClass(JNIEnv *env, const char *name, jobject loader,
const jbyte *buf, jsize bufLen);

rawクラス・データのバッファからクラスをロードします。 rawクラス・データを含むバッファは、DefineClass呼出しが戻った後はVMによって参照されません。必要に応じて破棄しても構いません。

リンケージ:

JNIEnvインタフェース関数表のインデックス5。

パラメータ:

env: JNIインタフェース・ポインタ。

name: 定義されるクラス名またはインタフェース名。 文字列は変更後のUTF-8でエンコードされます。

loader: 定義されたクラスに割り当てられるクラス・ローダー。

buf: .classファイル・データを含むバッファ。

bufLen: バッファ長。

戻り値:

Javaクラス・オブジェクトを返すか、エラーが発生した場合はNULLを返します。

例外:

ClassFormatError: クラス・データが有効なクラスを指定していない場合。

ClassCircularityError: クラスまたはインタフェースが、それ自体のスーパー・クラスまたはスーパー・インタフェースになる場合。

OutOfMemoryError: システムがメモリー不足の場合。

SecurityException: 呼出し側が「java」パッケージ・ツリー内にクラスを定義しようとした場合。

FindClass

jclass FindClass(JNIEnv *env, const char *name);

JDKリリース1.1では、この関数はローカルに定義されたクラスをロードします。 CLASSPATH環境変数が指定するディレクトリおよびZIPファイルで、指定された名前を持つクラスを検索します。

Java 2 SDKリリース1.2以降、Javaセキュリティ・モデルにより、システム・クラス以外のクラスでもネイティブ・メソッドのロードと呼出しが可能になりました。 FindClassは、現在のネイティブ・メソッドに関連付けられたクラス・ローダー、つまりネイティブ・メソッドを宣言したクラスのクラス・ローダーを検出します。 ネイティブ・メソッドがシステム・クラスに属する場合、クラス・ローダーは検出されません。 それ以外の場合には、適切なクラス・ローダーが呼び出され、名前が付けられたクラスのロードおよびリンクを行います。

Java 2 SDKリリース1.2以降、FindClassが呼出しインタフェースによって呼び出された場合、現在のネイティブ・メソッドまたはそれに関連付けられたクラス・ローダーは存在しません。 この場合、ClassLoader.getSystemClassLoaderの結果が使用されます。 これは、仮想マシンがアプリケーション用に作成するクラス・ローダーであり、java.class.pathプロパティにリストされたクラスを検索できます。

name引数は、完全修飾クラス名または配列型シグニチャです。 たとえば、java.lang.Stringクラスの完全修飾クラス名は次のとおりです。

                   "java/lang/String"

配列クラスjava.lang.Object[]の配列型シグニチャは次のとおりです。

                   "[Ljava/lang/Object;"

リンケージ:

JNIEnvインタフェース関数表のインデックス6。

パラメータ:

env: JNIインタフェース・ポインタ。

name: 完全修飾クラス名(「/」で区切ったあとにクラス名を付けたパッケージ名)。 その名前が「[」(配列シグニチャ文字)で始まっている場合は、配列クラスを返します。 文字列は変更後のUTF-8でエンコードされます。

戻り値:

完全修飾名からクラス・オブジェクトを返すか、クラスが見つからない場合はNULLを返します。

例外:

ClassFormatError: クラス・データが有効なクラスを指定していない場合。

ClassCircularityError: クラスまたはインタフェースが、それ自体のスーパー・クラスまたはスーパー・インタフェースになる場合。

NoClassDefFoundError: 要求されたクラスまたはインタフェースに対する定義が見つからない場合。

OutOfMemoryError: システムがメモリー不足の場合。

GetSuperclass

jclass GetSuperclass(JNIEnv *env, jclass clazz);

clazzがObjectクラス以外のクラスを表す場合、この関数は、clazzによって指定されたクラスのスーパー・クラスを表すオブジェクトを返します。

clazzがObjectクラスを指定する場合、またはclazzがインタフェースを表す場合は、この関数はNULLを返します。

リンケージ:

JNIEnvインタフェース関数表のインデックス10。

パラメータ:

env: JNIインタフェース・ポインタ。

clazz: Javaクラス・オブジェクト。

戻り値:

clazzによって表されるクラスのスーパー・クラス、またはNULLを返します。

IsAssignableFrom

jboolean IsAssignableFrom(JNIEnv *env, jclass clazz1,
jclass clazz2);

clazz1のオブジェクトが安全にclazz2へキャストされるかどうかを判定します。

リンケージ:

JNIEnvインタフェース関数表のインデックス11。

パラメータ:

env: JNIインタフェース・ポインタ。

clazz1: 最初のクラス引数。

clazz2: 2番目のクラス引数。

戻り値:

次のいずれかが真の場合にJNI_TRUEを返します。

• 最初と2番目のクラス引数が同じJavaクラスを表している。
• 最初のクラスが2番目のクラスのサブクラスである。
• 最初のクラスがそのインタフェースとして2番目のクラスを持っている。

例外

Throw

jint Throw(JNIEnv *env, jthrowable obj);

java.lang.Throwableオブジェクトのスローを発生させます。

リンケージ:

JNIEnvインタフェース関数表のインデックス13。

パラメータ:

env: JNIインタフェース・ポインタ。

obj: java.lang.Throwableオブジェクト。

戻り値:

成功すると「0」を返し、失敗すると負の値を返します。

例外:

java.lang.Throwable object obj.

ThrowNew

jint ThrowNew(JNIEnv *env, jclass clazz,
const char *message);

messageによって指定されたメッセージを使用して、指定されたクラスから例外オブジェクトを構築し、その例外がスローされるようにします。

リンケージ:

JNIEnvインタフェース関数表のインデックス14。

パラメータ:

env: JNIインタフェース・ポインタ。

clazz: java.lang.Throwableのサブクラス。

message: java.lang.Throwableオブジェクトの構築に使用するメッセージ。 文字列は変更後のUTF-8でエンコードされます。

戻り値:

成功すると「0」を返し、失敗すると負の値を返します。

例外:

新たに構築されたjava.lang.Throwableオブジェクト。

ExceptionOccurred

jthrowable ExceptionOccurred(JNIEnv *env);

例外がスローされるかどうかを決定します。 例外は、ネイティブ・コードがExceptionClear()を呼び出すか、またはJavaコードがその例外を処理するまで、スローされた状態を続けます。

リンケージ:

JNIEnvインタフェース関数表のインデックス15。

パラメータ:

env: JNIインタフェース・ポインタ。

戻り値:

現在スローされている例外オブジェクトを返すか、現在スローされている例外がない場合はNULLを返します。

ExceptionDescribe

void ExceptionDescribe(JNIEnv *env);

stderrなどのシステム・エラー報告チャネルに、例外およびスタックのバックトレースを出力します。 これは、デバッグのために提供されている便利なルーチンです。

リンケージ:

JNIEnvインタフェース関数表のインデックス16。

パラメータ:

env: JNIインタフェース・ポインタ。

ExceptionClear

void ExceptionClear(JNIEnv *env);

現在スローされている例外があればそれをクリアします。 現在スローされている例外がない場合は、このルーチンは影響を及ぼしません。

リンケージ:

JNIEnvインタフェース関数表のインデックス17。

パラメータ:

env: JNIインタフェース・ポインタ。

FatalError

void FatalError(JNIEnv *env, const char *msg);

致命的エラーを発生させます。VMの回復は期待できません。 この関数は値を返しません。

リンケージ:

JNIEnvインタフェース関数表のインデックス18。

パラメータ:

env: JNIインタフェース・ポインタ。

msg: エラー・メッセージ。 文字列は変更後のUTF-8でエンコードされます。

ExceptionCheck

例外オブジェクトへのローカル参照を作成せずに、未処理の例外を確認するための便利な関数を次に示します。

jboolean ExceptionCheck(JNIEnv *env);

未処理の例外がある場合はJNI_TRUE、ない場合はJNI_FALSEを返します。

リンケージ:

JNIEnvインタフェース関数表のインデックス228。

導入されたバージョン:

JDK/JRE 1.2

グローバル参照およびローカル参照

グローバル参照

NewGlobalRef

jobject NewGlobalRef(JNIEnv *env, jobject obj);

obj引数によって参照されたオブジェクトの新しいグローバル参照を作成します。 obj引数は、グローバル参照またはローカル参照のどちらでも構いません。 グローバル参照は、DeleteGlobalRef()を呼び出すことによって明示的に破棄する必要があります。

リンケージ:

JNIEnvインタフェース関数表のインデックス21。

パラメータ:

env: JNIインタフェース・ポインタ。

obj: グローバル参照またはローカル参照。

戻り値:

指定されたobjに対するグローバル参照を返します。

次の場合はNULLを返すことがあります:

• objはnullを参照
• システムのメモリーが不足しています
• objは弱いグローバル参照であり、既にガベージ・コレクションされています

DeleteGlobalRef

void DeleteGlobalRef(JNIEnv *env, jobject globalRef);

globalRefによって示されたグローバル参照を削除します。

リンケージ:

JNIEnvインタフェース関数表のインデックス22。

パラメータ:

env: JNIインタフェース・ポインタ。

globalRef: グローバル参照。

ローカル参照

ローカル参照は、ネイティブ・メソッドの呼出し期間中有効です。 ローカル参照は、ネイティブ・メソッドが復帰すると自動的に解放されます。 各ローカル参照は、Java仮想マシンのリソースをいくらか消費します。 プログラマは、ネイティブ・メソッドがローカル参照を過剰に割り当てないように確認する必要があります。 ローカル参照は、ネイティブ・メソッドがJavaに復帰すると自動的に解放されますが、ローカル参照を過剰に割り当てると、ネイティブ・メソッドの実行中にVMがメモリーを使い果たしてしまう可能性があります。

DeleteLocalRef

void DeleteLocalRef(JNIEnv *env, jobject localRef);

localRefによって示されたローカル参照を削除します。

リンケージ:

JNIEnvインタフェース関数表のインデックス23。

パラメータ:

env: JNIインタフェース・ポインタ。

localRef: ローカル参照。

ノート: 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を呼び出します。

リンケージ:

JNIEnvインタフェース関数表のインデックス26。

導入されたバージョン:

JDK/JRE 1.2

PushLocalFrame

jint PushLocalFrame(JNIEnv *env, jint capacity);

新しいローカル参照フレームを作成します。このフレームに最低限指定された数のローカル参照を作成できます。 成功した場合は0、失敗した場合は負の数と未処理のOutOfMemoryErrorを返します。

前回のローカル・フレームで作成済みのローカル参照は、現在のローカル・フレームでも引き続き有効です。

リンケージ:

JNIEnvインタフェース関数表のインデックス19。

導入されたバージョン:

JDK/JRE 1.2

PopLocalFrame

jobject PopLocalFrame(JNIEnv *env, jobject result);

現在のローカル参照フレームをポップし、すべてのローカル参照を解放し、指定されたresultオブジェクトに対する前回のローカル参照フレームのローカル参照を返します。

前回のフレームへの参照を返す必要がない場合は、resultとしてNULLを渡してください。

リンケージ:

JNIEnvインタフェース関数表のインデックス20。

導入されたバージョン:

JDK/JRE 1.2

NewLocalRef

jobject NewLocalRef(JNIEnv *env, jobject ref);

refと同じオブジェクトを参照する新しいローカル参照を作成します。 渡されたrefは、グローバル参照またはローカル参照である可能性があります。 refがnullを参照している場合は、NULLを返します。

リンケージ:

JNIEnvインタフェース関数表のインデックス25。

導入されたバージョン:

JDK/JRE 1.2

弱グローバル参照

弱グローバル参照は、特別な種類のグローバル参照です。 通常のグローバル参照と異なり、弱グローバル参照を使用すると、配下のJavaオブジェクトをガベージ・コレクトすることができます。 弱グローバル参照は、グローバルまたはローカル参照が使用されている状況ならどこででも使用できます。

弱いグローバル参照は、Javaファントム参照(java.lang.ref.PhantomReference)に関連しています。 特定のオブジェクトに対する弱いグローバル参照は、オブジェクトが「到達可能なファントム」 (java.lang.refを参照してください)かどうかを判断する際に、そのオブジェクトを参照するファントム参照として処理されます。 このような弱いグローバル参照は、同じオブジェクトを参照するPhantomReferenceがガベージ・コレクタによってクリアされるのと同時に、機能的にNULLと同等になります。

ガベージ・コレクションはネイティブ・メソッドの実行中に発生することもあるため、弱グローバル参照で参照されているオブジェクトはいつでも解放される可能性があります。 弱いグローバル参照は、グローバル参照が使用されている場合に使用できますが、通常、予告なくNULLと機能的に同等になる可能性があるため、使用することは不適切です。

IsSameObjectを使用すると、弱いグローバル参照をNULL以外のローカル参照またはグローバル参照と比較できます。 オブジェクトが同じ場合、他の参照が削除されていないかぎり、弱いグローバル参照は機能的にNULLと同等になりません。

IsSameObjectを使用して、弱いグローバル参照をNULLと比較し、基礎となるオブジェクトが解放されたかどうかを判断することもできます。 ただし、中間ガベージ・コレクションによって弱いグローバル参照が変更される可能性があるため、プログラマは、今後のJNI関数コールで弱いグローバル参照を(NULL以外の参照として)として使用できるかどうかを判断するためにこのチェックに依存しないでください。

かわりに、JNI関数NewLocalRefまたはNewGlobalRefのいずれかを使用して、基礎となるオブジェクトへの(強い)ローカル参照またはグローバル参照を取得することをお薦めします。 これらの関数は、オブジェクトが解放された場合にNULLを返します。 そうしないと、新しい参照によって、基礎となるオブジェクトが解放されなくなります。 新しい参照(NULL以外の場合)は、基礎となるオブジェクトへのアクセスに使用でき、そのようなアクセスが不要になったときに削除できます。

NewWeakGlobalRef

jweak NewWeakGlobalRef(JNIEnv *env, jobject obj);

弱グローバル参照を新規作成します。 objがnullを参照している場合、またはVMがメモリーを使い果たしてしまった場合は、NULLを返します。 VMがメモリーを使い果たしてしまった場合は、OutOfMemoryErrorがスローされます。

リンケージ:

JNIEnvインタフェース関数表のインデックス226。

導入されたバージョン:

JDK/JRE 1.2

DeleteWeakGlobalRef

void DeleteWeakGlobalRef(JNIEnv *env, jweak obj);

渡された弱グローバル参照に必要なVMリソースを削除します。

リンケージ:

JNIEnvインタフェース関数表のインデックス227。

導入されたバージョン:

JDK/JRE 1.2

オブジェクト・オペレーション

AllocObject

jobject AllocObject(JNIEnv *env, jclass clazz);

オブジェクト用としてコンストラクタを呼び出さずに、新しいJavaオブジェクトを割り当てます。 オブジェクトに対する参照を返します。

clazz引数は配列クラスを参照できません。

リンケージ:

JNIEnvインタフェース関数表のインデックス27。

パラメータ:

env: JNIインタフェース・ポインタ。

clazz: Javaクラス・オブジェクト。

戻り値:

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インタフェース・ポインタ。

clazz: Javaクラス・オブジェクト。

methodID: コンストラクタのメソッドID。

NewObjectに必要な追加パラメータ:

コンストラクタの引数。

NewObjectAに必要な追加パラメータ:

args: コンストラクタの引数の配列。

NewObjectVに必要な追加パラメータ:

args: コンストラクタの引数のva_list。

戻り値:

Javaオブジェクトを返すか、オブジェクトを構築できない場合はNULLを返します。

例外:

InstantiationException: クラスがインタフェースまたは抽象クラスの場合。

OutOfMemoryError: システムがメモリー不足の場合。

コンストラクタによってスローされるすべての例外。

GetObjectClass

jclass GetObjectClass(JNIEnv *env, jobject obj);

オブジェクトのクラスを返します。

リンケージ:

JNIEnvインタフェース関数表のインデックス31。

パラメータ:

env: JNIインタフェース・ポインタ。

obj: Javaオブジェクト(NULLは不可)。

戻り値:

Javaクラス・オブジェクトを返します。

GetObjectRefType

jobjectRefType GetObjectRefType(JNIEnv* env, jobject obj);

obj引数によって参照されるオブジェクトの型を返します。 引数objは、ローカル参照、グローバル参照、弱グローバル参照のいずれかです。

リンケージ:

JNIEnvインタフェース関数表のインデックス232。

パラメータ:

env: JNIインタフェース・ポインタ。

obj: ローカル参照、グローバル参照、または弱グローバル参照。

vm: インタフェース取得元の仮想マシン・インスタンス。

env: 現在のスレッドのJNIインタフェース・ポインタが配置される位置へのポインタ。

version: 要求されたJNIバージョン。

戻り値:

関数GetObjectRefTypeは、jobjectRefTypeとして定義された次の列挙値の1つを返します。

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インタフェース・ポインタ。

obj: Javaオブジェクト。

clazz: Javaクラス・オブジェクト。

戻り値:

objをclazzにキャストできる場合は、JNI_TRUEを返します。そうでない場合は、JNI_FALSEを返します。 NULLオブジェクトは、どのクラスにもキャストできます。

IsSameObject

jboolean IsSameObject(JNIEnv *env, jobject ref1,
jobject ref2);

2つの参照が同じJavaオブジェクトを参照するかどうかをテストします。

リンケージ:

JNIEnvインタフェース関数表のインデックス24。

パラメータ:

env: JNIインタフェース・ポインタ。

ref1: Javaオブジェクト。

ref2: Javaオブジェクト。

戻り値:

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インタフェース・ポインタ。

clazz: Javaクラス・オブジェクト。

name: 0で終了する変更後のUTF-8文字列内のフィールド名。

sig: 0で終了する修正UTF-8文字列内のフィールド・シグニチャ。

戻り値:

フィールド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ファミリ

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ファミリ

Get<type>Fieldルーチン名	索引
GetObjectField()	95
GetBooleanField()	96
GetByteField()	97
GetCharField()	98
GetShortField()	99
GetIntField()	100
GetLongField()	101
GetFloatField()	102
GetDoubleField()	103

パラメータ:

env: JNIインタフェース・ポインタ。

obj: Javaオブジェクト(NULLは不可)。

fieldID: 有効なフィールドID。

戻り値:

フィールドの内容を返します。

Set<type>Fieldルーチン

void Set<type>Field(JNIEnv *env, jobject obj, jfieldID fieldID,
NativeType value);

このアクセス用ルーチンのファミリは、オブジェクトのインスタンス(非static)フィールドの値を設定します。 アクセスすべきフィールドは、GetFieldID()を呼び出すことによって取得されるフィールドIDで指定されます。

次の表には、Set<type>Fieldルーチン名と値の型が示されています。 Set<type>Field内のtypeをフィールドのJava型と置き換えるか、または表の実際のルーチン名の1つを使用し、かつNativeTypeをそのルーチンに対応するネイティブ型と置き換える必要があります。

アクセス用ルーチンのSet<type>Fieldファミリ

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ファミリ

Set<type>Fieldルーチン	索引
SetObjectField()	104
SetBooleanField()	105
SetByteField()	106
SetCharField()	107
SetShortField()	108
SetIntField()	109
SetLongField()	110
SetFloatField()	111
SetDoubleField()	112

パラメータ:

env: JNIインタフェース・ポインタ。

obj: Javaオブジェクト(NULLは不可)。

fieldID: 有効なフィールドID。

value: フィールドの新しい値。

インスタンス・メソッドの呼び出し

GetMethodID

jmethodID GetMethodID(JNIEnv *env, jclass clazz,
const char *name, const char *sig);

クラスまたはインタフェースのインスタンス(非static)メソッドを表すメソッドIDを返します。 このメソッドは、clazzのスーパー・クラスのいずれかで定義し、clazzによって継承できます。 このメソッドは、その名前およびシグニチャによって決定されます。

GetMethodID()によって、まだ初期化されていないクラスが初期化されます。

コンストラクタのメソッドIDを取得するには、メソッド名として<init>を指定し、戻り値の型としてvoid (V)を指定します。

リンケージ:

JNIEnvインタフェース関数表のインデックス33。

パラメータ:

env: JNIインタフェース・ポインタ。

clazz: Javaクラス・オブジェクト。

name: 0で終了する変更後のUTF-8文字列内のメソッド名。

sig: 0で終了する変更後のUTF-8文字列内のメソッド・シグニチャ。

戻り値:

メソッド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 Routineルーチン名	ネイティブ型
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 Routineルーチン名	索引
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インタフェース・ポインタ。

obj: Javaオブジェクト。

methodID: メソッドID。

Call<type>Methodルーチンに必要な追加パラメータ:

Javaメソッドに対する引数。

Call<type>MethodAルーチンに必要な追加パラメータ:

args: 引数の配列。

Call<type>MethodVルーチンに必要な追加パラメータ:

args: 引数のva_list。

戻り値:

Javaメソッドを呼び出した結果を返します。

例外:

Exceptions raised during the execution of the Java method.

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ルーチン

プログラマは、メソッドに渡す引数をすべて、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ルーチン

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ルーチン

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インタフェース・ポインタ。

clazz: Javaクラス。

obj: Javaオブジェクト。

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インタフェース・ポインタ。

clazz: Javaクラス・オブジェクト。

name: 0で終了する変更後のUTF-8文字列内のstaticフィールド名。

sig: 0で終了する修正UTF-8文字列内のフィールド・シグニチャ。

戻り値:

フィールドIDを返します。指定されたstaticフィールドが見つからない場合は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ファミリ

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ファミリ

GetStatic<type>Fieldルーチン名	索引
GetStaticObjectField()	145
GetStaticBooleanField()	146
GetStaticByteField()	147
GetStaticCharField()	148
GetStaticShortField()	149
GetStaticIntField()	150
GetStaticLongField()	151
GetStaticFloatField()	152
GetStaticDoubleField()	153

パラメータ:

env: JNIインタフェース・ポインタ。

clazz: Javaクラス・オブジェクト。

fieldID: staticフィールド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ファミリ

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ファミリ

SetStatic<type>Fieldルーチン名	索引
SetStaticObjectField()	154
SetStaticBooleanField()	155
SetStaticByteField()	156
SetStaticCharField()	157
SetStaticShortField()	158
SetStaticIntField()	159
SetStaticLongField()	160
SetStaticFloatField()	161
SetStaticDoubleField()	162

パラメータ:

env: JNIインタフェース・ポインタ。

clazz: Javaクラス・オブジェクト。

fieldID: staticフィールドID。

value: フィールドの新しい値。

staticメソッドの呼び出し

GetStaticMethodID

jmethodID GetStaticMethodID(JNIEnv *env, jclass clazz,
const char *name, const char *sig);

クラスのstaticメソッドを表すメソッドIDを返します。 このメソッドは、その名前とシグニチャで指定します。

GetStaticMethodID()によって、まだ初期化されていないクラスが初期化されます。

リンケージ:

JNIEnvインタフェース関数表のインデックス113。

パラメータ:

env: JNIインタフェース・ポインタ。

clazz: Javaクラス・オブジェクト。

name: 0で終了する変更後のUTF-8文字列内のstaticメソッド名。

sig: 0で終了する変更後のUTF-8文字列内のメソッド・シグニチャ。

戻り値:

メソッド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は、clazzのスーパー・クラスの1つからではなく、それ自体から取得する必要があります。

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呼出し元のルーチン

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呼出し元のルーチン

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インタフェース・ポインタ。

clazz: Javaクラス・オブジェクト。

methodID: staticメソッドID。

CallStatic<type>Methodルーチンに必要な追加パラメータ:

staticメソッドの引数。

CallStatic<type>MethodAルーチンに必要な追加パラメータ:

args: 引数の配列。

CallStatic<type>MethodVルーチンに必要な追加パラメータ:

args: 引数のva_list。

戻り値:

static Javaメソッドを呼び出した結果を返します。

例外:

Exceptions raised during the execution of the Java method.

文字列操作

NewString

jstring NewString(JNIEnv *env, const jchar *unicodeChars,
jsize len);

Unicode文字の配列から新しいjava.lang.Stringオブジェクトを構築します。

リンケージ:

JNIEnvインタフェース関数表のインデックス163。

パラメータ:

env: JNIインタフェース・ポインタ。

unicodeChars: Unicode文字列を参照するポインタ。

len: Unicode文字列の長さ。

戻り値:

Java文字列オブジェクトを返すか、文字列を構築できない場合はNULLを返します。

例外:

OutOfMemoryError: システムがメモリー不足の場合。

GetStringLength

jsize GetStringLength(JNIEnv *env, jstring string);

Java文字列の長さ(Unicode文字のカウント)を返します。

リンケージ:

JNIEnvインタフェース関数表のインデックス164。

パラメータ:

env: JNIインタフェース・ポインタ。

string: Java文字列オブジェクト。

戻り値:

Java文字列の長さを返します。

GetStringChars

const jchar * GetStringChars(JNIEnv *env, jstring string,
jboolean *isCopy);

文字列のUnicode文字の配列を参照するポインタを返します。 このポインタは、ReleaseStringChars()が呼び出されるまで有効です。

isCopyがNULLでない場合にコピーが作成されると、*isCopyはJNI_TRUEに設定されます。コピーが作成されない場合は、JNI_FALSEに設定されます。

リンケージ:

JNIEnvインタフェース関数表のインデックス165。

パラメータ:

env: JNIインタフェース・ポインタ。

string: Java文字列オブジェクト。

isCopy: ブール値を指すポインタ。

戻り値:

Unicode文字列を参照するポインタを返すか、処理が失敗した場合はNULLを返します。

ReleaseStringChars

void ReleaseStringChars(JNIEnv *env, jstring string,
const jchar *chars);

ネイティブ・コードがcharsにアクセスする必要がなくなったことをVMに知らせます。 chars引数は、GetStringChars()を使用してstringから取得されるポインタです。

リンケージ:

JNIEnvインタフェース関数表のインデックス166。

パラメータ:

env: JNIインタフェース・ポインタ。

string: Java文字列オブジェクト。

chars: Unicode文字列を参照するポインタ。

NewStringUTF

jstring NewStringUTF(JNIEnv *env, const char *bytes);

変更後のUTF-8エンコーディングによる文字配列から新しいjava.lang.Stringオブジェクトを構築します。

リンケージ:

JNIEnvインタフェース関数表のインデックス167。

パラメータ:

env: JNIインタフェース・ポインタ。

bytes: 変更後のUTF-8文字列を参照するポインタ。

戻り値:

Java文字列オブジェクトを返すか、文字列を構築できない場合はNULLを返します。

例外:

OutOfMemoryError: システムがメモリー不足の場合。

GetStringUTFLength

jsize GetStringUTFLength(JNIEnv *env, jstring string);

文字列の長さを変更後のUTF-8によるバイト数で返します。

リンケージ:

JNIEnvインタフェース関数表のインデックス168。

パラメータ:

env: JNIインタフェース・ポインタ。

string: Java文字列オブジェクト。

戻り値:

文字列の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インタフェース・ポインタ。

string: Java文字列オブジェクト。

isCopy: ブール値を指すポインタ。

戻り値:

変更後のUTF-8文字列を参照するポインタを返します。演算に失敗した場合は、NULLを返します。

ReleaseStringUTFChars

void ReleaseStringUTFChars(JNIEnv *env, jstring string,
const char *utf);

ネイティブ・コードがutfにアクセスする必要がなくなったことをVMに知らせます。 utf引数は、GetStringUTFChars()を使用してstringから取得されるポインタです。

リンケージ:

JNIEnvインタフェース関数表のインデックス170。

パラメータ:

env: JNIインタフェース・ポインタ。

string: Java文字列オブジェクト。

utf: 変更後の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にコピーします。

StringIndexOutOfBoundsExceptionをインデックス・オーバーフロー時にスローします。

リンケージ:

JNIEnvインタフェース関数表のインデックス220。

導入されたバージョン:

JDK/JRE 1.2

GetStringUTFRegion

< void GetStringUTFRegion(JNIEnv *env, jstring str, jsize start, jsize len, char *buf);

オフセットstartで始まるlen個のUnicode文字を変更後のUTF-8エンコーディングに変換し、その結果を、指定されたバッファbufに置きます。

StringIndexOutOfBoundsExceptionをインデックス・オーバーフロー時にスローします。

リンケージ:

JNIEnvインタフェース関数表のインデックス221。

導入されたバージョン:

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インタフェース・ポインタ。

array: Java配列オブジェクト。

戻り値:

配列の長さを返します。

NewObjectArray

jobjectArray NewObjectArray(JNIEnv *env, jsize length,
jclass elementClass, jobject initialElement);

クラスelementClassにオブジェクトを持つ新しい配列を構築します。 要素はすべて、最初はinitialElementに設定されます。

リンケージ:

JNIEnvインタフェース関数表のインデックス172。

パラメータ:

env: JNIインタフェース・ポインタ。

length: 配列サイズ。

elementClass: 配列要素のクラス。

initialElement: 初期化値。

戻り値:

Java配列オブジェクトを返すか、配列を構築できない場合はNULLを返します。

例外:

OutOfMemoryError: システムがメモリー不足の場合。

GetObjectArrayElement

jobject GetObjectArrayElement(JNIEnv *env,
jobjectArray array, jsize index);

Object配列の要素を返します。

リンケージ:

JNIEnvインタフェース関数表のインデックス173。

パラメータ:

env: JNIインタフェース・ポインタ。

array: Java配列。

index: 配列のインデックス。

戻り値:

Javaオブジェクトを返します。

例外:

ArrayIndexOutOfBoundsException: indexが配列内の有効なインデックスを指定していない場合。

SetObjectArrayElement

void SetObjectArrayElement(JNIEnv *env, jobjectArray array,
jsize index, jobject value);

Object配列の要素を設定します。

リンケージ:

JNIEnvインタフェース関数表のインデックス174。

パラメータ:

env: JNIインタフェース・ポインタ。

array: Java配列。

index: 配列のインデックス。

value: 新しい値。

例外:

ArrayIndexOutOfBoundsException: indexが配列内の有効なインデックスを指定していない場合。

ArrayStoreException: valueのクラスが、配列の要素クラスのサブクラスではない場合。

New<PrimitiveType>Arrayルーチン

ArrayType New<PrimitiveType>Array(JNIEnv *env, jsize length);

新しいプリミティブ配列オブジェクトを構築するために使用される演算のファミリ。 次の表には、特定のプリミティブ配列コンストラクタが示されています。 New<PrimitiveType>Arrayを、この表の実際のプリミティブ配列コンストラクタ・ルーチン名の1つと置き換え、ArrayTypeをそのルーチンに対応する配列型と置き換える必要があります。

配列コンストラクタのNew<PrimitiveType>Arrayファミリ

New<PrimitiveType>Arrayルーチン	配列型
NewBooleanArray()	jbooleanArray
NewByteArray()	jbyteArray
NewCharArray()	jcharArray
NewShortArray()	jshortArray
NewIntArray()	jintArray
NewLongArray()	jlongArray
NewFloatArray()	jfloatArray
NewDoubleArray()	jdoubleArray

リンケージ:

JNIEnvインタフェース関数表のインデックス。

配列コンストラクタのNew<PrimitiveType>Arrayファミリ

New<PrimitiveType>Arrayルーチン	索引
NewBooleanArray()	175
NewByteArray()	176
NewCharArray()	177
NewShortArray()	178
NewIntArray()	179
NewLongArray()	180
NewFloatArray()	181
NewDoubleArray()	182

パラメータ:

env: JNIインタフェース・ポインタ。

length: 配列長。

戻り値:

Java配列を返すか、配列を構築できない場合はNULLを返します。

Get<PrimitiveType>ArrayElementsルーチン

NativeType *Get<PrimitiveType>ArrayElements(JNIEnv *env,
ArrayType array, jboolean *isCopy);

プリミティブ配列の本体を返す関数のファミリです。 その結果は、対応するRelease<PrimitiveType>ArrayElements()関数が呼び出されるまで有効です。 返された配列はJava配列のコピーである場合もあるため、その返された配列に加えられている変更は、Release<PrimitiveType>ArrayElements() が呼び出されるまでは、必ずしも元の array に反映されているとはかぎりません。

isCopyがNULLでない場合にコピーが作成されると、*isCopyはJNI_TRUEに設定されます。コピーが作成されない場合は、JNI_FALSEに設定されます。

次の表には、特定のプリミティブ配列要素アクセス機能が示されています。 次の置換を行う必要があります。

• Get<PrimitiveType>ArrayElementsを、次の表の実際のプリミティブ要素アクセス用ルーチン名の1つと置き換える。
• ArrayTypeを対応する配列型と置き換える。
• NativeTypeを、そのルーチンに対応するネイティブ型と置き換える。

Java VM内でブール配列がどのように表されているかにかかわらず、GetBooleanArrayElements()は常にjbooleansを参照するポインタを返します。各バイトが1つの要素を表しています(アンパック表示)。 その他の型の配列はすべて、メモリー内で必ず隣接するようになっています。

アクセス用ルーチンのGet<PrimitiveType>ArrayElementsファミリ

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ファミリ

Get<PrimitiveType>ArrayElementsルーチン	索引
GetBooleanArrayElements()	183
GetByteArrayElements()	184
GetCharArrayElements()	185
GetShortArrayElements()	186
GetIntArrayElements()	187
GetLongArrayElements()	188
GetFloatArrayElements()	189
GetDoubleArrayElements()	190

パラメータ:

env: JNIインタフェース・ポインタ。

array: Java文字列オブジェクト。

isCopy: ブール値を指すポインタ。

戻り値:

配列要素を参照するポインタを返すか、処理が失敗した場合はNULLを返します。

Release<PrimitiveType>ArrayElementsルーチン

void Release<PrimitiveType>ArrayElements(JNIEnv *env,
ArrayType array, NativeType *elems, jint mode);

ネイティブ・コードがelemsにアクセスする必要がなくなったことをVMに知らせる関数のファミリです。 elems引数は、対応するGet<PrimitiveType>ArrayElements()関数を使用してarrayから取得されるポインタです。 必要に応じて、この関数は、elemsに施された変更をすべて元の配列にコピーし直します。

mode引数は、配列バッファの解放方法に関する情報を提供します。elemsがarray内の要素のコピーでない場合、modeは影響を及ぼしません。 それ以外の場合、modeは次の表に示されているような影響を及ぼします。

プリミティブ配列解放モード

モード	アクション
0	内容を元の配列にコピーし直し、elemsバッファを解放する
JNI_COMMIT	内容を元の配列にコピーし直すが、elemsバッファを解放しない
JNI_ABORT	変更の可能性があってもその内容を元に戻さず、バッファを解放する

ほとんどの場合、プログラマは、ピン配列とコピー配列の両方に対して一貫した動作を保証するために、「0」をmode引数に渡します。 0以外を渡す場合は、プログラマはメモリーを十分に注意して管理する必要があります。

次の表には、プリミティブ配列処置機能のファミリを構成する特定のルーチンが示されています。 次の置換を行う必要があります。

• Release<PrimitiveType>ArrayElementsを、次の表に示されている実際のプリミティブ配列処置機能ルーチン名のいずれかと置き換える。
• ArrayTypeを対応する配列型と置き換える。
• NativeTypeを、そのルーチンに対応するネイティブ型と置き換える。

配列ルーチンのRelease<PrimitiveType>ArrayElementsファミリ

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ファミリ

Release<PrimitiveType>ArrayElementsルーチン	索引
ReleaseBooleanArrayElements()	191
ReleaseByteArrayElements()	192
ReleaseCharArrayElements()	193
ReleaseShortArrayElements()	194
ReleaseIntArrayElements()	195
ReleaseLongArrayElements()	196
ReleaseFloatArrayElements()	197
ReleaseDoubleArrayElements()	198

パラメータ:

env: JNIインタフェース・ポインタ。

array: Java配列オブジェクト。

elems: 配列要素を参照するポインタ。

mode: 解放モード。

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ファミリ

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インタフェース関数表のインデックス。

<table border="1" summary="Get<PrimitiveType>ArrayRegion Family of Array Accessor Routines" 配列アクセス機能ルーチンのGet<PrimitiveType>ArrayRegionファミリ Get<PrimitiveType>ArrayRegionルーチン 索引 GetBooleanArrayRegion() 199 GetByteArrayRegion() 200 GetCharArrayRegion() 201 GetShortArrayRegion() 202 GetIntArrayRegion() 203 GetLongArrayRegion() 204 GetFloatArrayRegion() 205 GetDoubleArrayRegion() 206

パラメータ:

env: JNIインタフェース・ポインタ。

array: Java配列。

start: 開始インデックス。

len: コピー対象の要素の数。

buf: 転送先バッファ。

例外:

ArrayIndexOutOfBoundsException: 領域内のインデックスの1つでも有効ではない場合。

Set<PrimitiveType>ArrayRegionルーチン

void Set<PrimitiveType>ArrayRegion(JNIEnv *env, ArrayType array,
jsize start, jsize len, const NativeType *buf);

バッファからのプリミティブ配列の領域を元の値に戻す関数のファミリです。

次の表には、特定のプリミティブ配列要素アクセス機能が示されています。 次の置換を行う必要があります。

• Set<PrimitiveType>ArrayRegionを、次の表の実際のプリミティブ要素アクセス用ルーチン名の1つと置き換える。
• ArrayTypeを対応する配列型と置き換える。
• NativeTypeを、そのルーチンに対応するネイティブ型と置き換える。

<table border="1" summary="Set<PrimitiveType>ArrayRegion Family of Array Accessor Routines" 配列アクセス機能ルーチンのSet<PrimitiveType>ArrayRegionファミリ 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インタフェース関数表のインデックス。

<table border="1" summary="Set<PrimitiveType>ArrayRegion Family of Array Accessor Routines" 配列アクセス機能ルーチンのSet<PrimitiveType>ArrayRegionファミリ Set<PrimitiveType>ArrayRegionルーチン 索引 SetBooleanArrayRegion() 207 SetByteArrayRegion() 208 SetCharArrayRegion() 209 SetShortArrayRegion() 210 SetIntArrayRegion() 211 SetLongArrayRegion() 212 SetFloatArrayRegion() 213 SetDoubleArrayRegion() 214

パラメータ:

env: JNIインタフェース・ポインタ。

array: Java配列。

start: 開始インデックス。

len: コピー対象の要素の数。

buf: 転送元バッファ。

例外:

ArrayIndexOutOfBoundsException: 領域内のインデックスの1つでも有効ではない場合。

ノート: JDK/JRE 1.1では、プログラマはGet/Release<primitivetype>ArrayElements関数を使用して、プリミティブ配列要素へのポインタを取得できます。 VMがピニングをサポートしている場合、元のデータへのポインタが返されました。そうでない場合には、コピーが作成されました。 JDK/JRE 1.3の時点で導入された新しい関数を使用すると、VMがピニングをサポートしていない場合でも、ネイティブ・コードは配列要素への直接ポインタを取得できます。

GetPrimitiveArrayCritical、ReleasePrimitiveArrayCritical

void * GetPrimitiveArrayCritical(JNIEnv *env, jarray array, jboolean *isCopy);
void ReleasePrimitiveArrayCritical(JNIEnv *env, jarray array, void *carray, jint mode);

これら2つの関数のセマンティックスは、既存のGet/Release<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。

リンケージ(ReleasePrimitiveArrayCritical):

JNIEnvインタフェース関数表のリンケージ・インデックス223。

導入されたバージョン:

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, ...);

リンケージ:

JNIEnvインタフェース関数表のインデックス215。

パラメータ:

env: JNIインタフェース・ポインタ。

clazz: Javaクラス・オブジェクト。

methods: クラス内のネイティブ・メソッド。

nMethods: クラス内のネイティブ・メソッドの数。

戻り値:

成功した場合は「0」を返し、失敗した場合は負の値を返します。

例外:

NoSuchMethodError: 指定されたメソッドが見つからない場合、または、そのメソッドがネイティブではない場合。

UnregisterNatives

jint UnregisterNatives(JNIEnv *env, jclass clazz);

あるクラスのネイティブ・メソッドの登録を解除します。 そのクラスは、そのネイティブ・メソッド機能にリンクされる前または再登録される前の状態に戻ります。

この関数は、通常のネイティブ・コードでは使用するべきではありません。 その代わりに、特別なプログラムにネイティブ・ライブラリを再ロードしたり再リンクしたりする方法を提供します。

リンケージ:

JNIEnvインタフェース関数表のインデックス216。

パラメータ:

env: JNIインタフェース・ポインタ。

clazz: Javaクラス・オブジェクト。

戻り値:

成功した場合は「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インタフェース・ポインタ。

obj: 通常のJavaオブジェクトまたはクラス・オブジェクト。

戻り値:

成功した場合は「0」を返し、失敗した場合は負の値を返します。

MonitorExit

jint MonitorExit(JNIEnv *env, jobject obj);

現在のスレッドは、objによって参照されたベースとなるJavaオブジェクトに関連するモニターの所有者でなければなりません。 このスレッドは、このモニターに入った回数を表すカウンタを減少させます。 カウンタの値がゼロになると、現在のスレッドはモニターを解放します。

ネイティブ・コードは、synchronizedメソッドまたはmonitorenter Java仮想マシンの命令で入ったモニターから出るためにMonitorExitを使用してはいけません。

リンケージ:

JNIEnvインタフェース関数表のインデックス218。

パラメータ:

env: JNIインタフェース・ポインタ。

obj: 通常のJavaオブジェクトまたはクラス・オブジェクト。

戻り値:

成功した場合は「0」を返し、失敗した場合は負の値を返します。

例外:

IllegalMonitorStateException: 現在のスレッドがモニターを所有していない場合。

NIOのサポート

NIO関連のエントリ・ポイントにより、ネイティブ・コードがjava.nio 直接バッファにアクセスできます。 直接バッファのコンテンツは、通常のガベージ・コレクトされたヒープの外側の、ネイティブ・メモリー内に格納できます。 直接バッファについては、New I/O APIおよびjava.nio.ByteBufferクラスの仕様を参照してください。

JDK/JRE 1.4で導入された3つの新しい関数を使用すると、JNIコードでバッファを直接作成、検査、および操作できます。

• NewDirectByteBuffer
• GetDirectBufferAddress
• GetDirectBufferCapacity

Java仮想マシンの各実装ではこれらの関数をサポートする必要がありますが、すべての実装が直接バッファへのJNIのアクセスをサポートする必要はありません。 JVMがこのようなアクセスをサポートしない場合は、NewDirectByteBufferおよびGetDirectBufferAddress関数は常にNULLを返し、GetDirectBufferCapacity関数は常に-1を返します。 JVMがこのようなアクセスをサポートする場合、これら3つの関数は適切な値を返すように実装される必要があります。

NewDirectByteBuffer

jobject NewDirectByteBuffer(JNIEnv* env, void* address, jlong capacity);

メモリー・アドレスaddressから始まるcapacityバイトまでのメモリー・ブロックを参照する直接バッファjava.nio.ByteBufferを割り当てて返します。

この関数を呼び出して、Javaレベルのコードに最終的なバイト・バッファのオブジェクトを返すネイティブ・コードは、そのバッファが、読み込みと、適切な場合には書出しのアクセスが可能な、有効なメモリー領域を参照する必要があります。 Javaコードから無効なメモリー位置にアクセスしようとすると、視覚効果のない任意の値を返すか、指定されていない例外が発生します。

リンケージ:

JNIEnvインタフェース関数表のインデックス229。

パラメータ:

env: JNIEnvインタフェース・ポインタ

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: JNIEnvインタフェース・ポインタ

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: JNIEnvインタフェース・ポインタ

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。

導入されたバージョン:

JDK/JRE 1.2

FromReflectedField

jfieldID FromReflectedField(JNIEnv *env, jobject field);

java.lang.reflect.FieldをフィールドIDに変換します。

リンケージ:

JNIEnvインタフェース関数表のインデックス8。

導入されたバージョン:

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オブジェクトに変換します。そのメソッドIDがstaticフィールドを参照している場合はisStaticをJNI_TRUEに、それ以外の場合はJNI_FALSEに設定する必要があります。

失敗した場合はOutOfMemoryErrorをスローし、0を返します。

リンケージ:

JNIEnvインタフェース関数表のインデックス9。

導入されたバージョン:

JDK/JRE 1.2

ToReflectedField

jobject ToReflectedField(JNIEnv *env, jclass cls,
   jfieldID fieldID, jboolean isStatic);

clsから取得したフィールドIDをjava.lang.reflect.Fieldオブジェクトに変換します。fieldIDがstaticフィールドを参照している場合はisStaticをJNI_TRUEに、それ以外の場合はJNI_FALSEに設定する必要があります。

失敗した場合はOutOfMemoryErrorをスローし、0を返します。

リンケージ:

JNIEnvインタフェース関数表のインデックス12。

導入されたバージョン:

JDK/JRE 1.2

Java VMインタフェース

GetJavaVM

jint GetJavaVM(JNIEnv *env, JavaVM **vm);

現在のスレッドに関連するJava VMインタフェース(呼び出しAPIで使用)を返します。 その結果は、2番目の引数vmで示された位置に置かれます。

リンケージ:

JNIEnvインタフェース関数表のインデックス219。

パラメータ:

env: JNIインタフェース・ポインタ。

vm: 結果が配置される位置へのポインタ。

戻り値:

成功した場合は「0」を返し、失敗した場合は負の値を返します。

目次|前|次