HandleRef 構造体とは何？わかりやすく解説 Weblio辞書

.NET Framework クラスライブラリリファレンス

索引トップ用語の索引ランキング

HandleRef 構造体

プラットフォームの呼び出しを使用して、アンマネージコードに渡されるリソースへのハンドルを保持しているマネージオブジェクトをラップします。

名前空間: System.Runtime.InteropServices
アセンブリ: mscorlib (mscorlib.dll 内)
構文

Visual Basic (宣言)

<ComVisibleAttribute(True)> _
Public Structure HandleRef

Visual Basic (使用法)

Dim instance As HandleRef

[ComVisibleAttribute(true)] 
public struct HandleRef

C++

[ComVisibleAttribute(true)] 
public value class HandleRef

/** @attribute ComVisibleAttribute(true) */ 
public final class HandleRef extends ValueType

JScript

JScript では、構造体を使用できますが、新規に宣言することはできません。

解説

プラットフォーム呼び出しを使用してマネージオブジェクトを呼び出し、このプラットフォーム呼び出しの後でオブジェクトが他で一切参照されていない場合、ガベージコレクタがマネージオブジェクトを終了する可能性があります。これによって、リソースが解放され、ハンドルが無効になり、プラットフォーム呼び出しは失敗します。HandleRef でハンドルをラップすると、プラットフォーム呼び出しが終了するまで、マネージオブジェクトはガベージコレクションの対象になることはありません。プラットフォーム呼び出しサービスの説明については、「アンマネージ DLL 関数の処理」を参照してください。

GCHandle と同様、HandleRef 値型は、相互運用マーシャラが認識できる特別な型です。通常の固定されていない GCHandle を使用しても、予期しないガベージコレクションを防ぐことができますが、HandleRef の動作の方が優れています。プラットフォーム呼び出しの有効期間の間オブジェクトを有効にしておくには HandleRef の使用を推奨しますが、同じ目的で GC.KeepAlive メソッドを使用することもできます。

HandleRef コンストラクタは、ラッパーを表す Object、およびアンマネージハンドルを表す IntPtr の 2 つのパラメータを受け取ります。相互運用マーシャラは、ハンドルだけをアンマネージコードに渡し、呼び出しの有効期間の間ラッパー (HandleRef のコンストラクタの 1 番目のパラメータとして渡される) が有効となるよう保証します。

使用例

HandleRef を使用して、1 番目のパラメータに渡されたオブジェクトを有効に保つ方法を次の例に示します。相互運用マーシャラは、ハンドルだけをアンマネージコードに渡します。

Visual Basic

Dim fs As New FileStream("HandleRef.txt",
 FileMode.Open)
Dim hr As New HandleRef(fs,
 fs.SafeFileHandle.DangerousGetHandle())
Dim buffer As New StringBuilder(5)
Dim read As Integer = 0

' platform invoke will hold reference to HandleRef until call ends

LibWrap.ReadFile(hr, buffer, 5, read, 0)
Console.WriteLine("Read with struct parameter: {0}",
 buffer)

FileStream fs = new FileStream("HandleRef.txt", FileMode.Open);
HandleRef hr = new HandleRef(fs, fs.SafeFileHandle.DangerousGetHandle());
StringBuilder buffer = new StringBuilder(5);
int read = 0;

// platform invoke will hold reference to HandleRef until call ends

LibWrap.ReadFile(hr, buffer, 5, out read, 0);
Console.WriteLine("Read with struct parameter: {0}", buffer);

C++

FileStream^ fs = gcnew FileStream( "HandleRef.txt", FileMode::Open );
HandleRef hr = HandleRef(fs,fs->Handle);
StringBuilder^ buffer = gcnew StringBuilder( 5 );
int read = 0;

// platform invoke will hold reference to HandleRef until call ends
LibWrap::ReadFile( hr, buffer, 5,  &read, 0 );
Console::WriteLine( "Read with struct parameter: {0}", buffer );