HandleRef 構造体

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

この型のすべてのメンバの一覧については、HandleRef メンバ を参照してください。

System.Object
   System.ValueType
      System.Runtime.InteropServices.HandleRef

Public Structure HandleRef
[C#]
public struct HandleRef
[C++]
public __value struct HandleRef

[JScript] JScript では、.NET Framework の構造体を利用することができます。ただし、独自に定義することはできません。

スレッドセーフ

この型の public static (Visual Basicでは Shared) のすべてのメンバは、マルチスレッド操作で安全に使用できます。インスタンスのメンバの場合は、スレッドセーフであるとは限りません。

解説

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

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

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

使用例

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

 
Dim fs As New FileStream( "HandleRef.txt", FileMode.Open )
Dim hr As New HandleRef( fs, fs.Handle )
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 )

[C#] 
FileStream fs = new FileStream( "HandleRef.txt", FileMode.Open );
HandleRef hr = new HandleRef( fs, fs.Handle );
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 = new FileStream( S"HandleRef.txt", FileMode::Open );
HandleRef hr = HandleRef( fs, fs->Handle );
StringBuilder* buffer = new StringBuilder( 5 );
int read = 0;

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

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

[JScript] JScript のサンプルはありません。Visual Basic、C#、および C++ のサンプルを表示するには、このページの左上隅にある言語のフィルタ ボタン をクリックします。

必要条件

名前空間: System.Runtime.InteropServices

プラットフォーム: Windows 98, Windows NT 4.0, Windows Millennium Edition, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 ファミリ

アセンブリ: Mscorlib (Mscorlib.dll 内)

参照

HandleRef メンバ | System.Runtime.InteropServices 名前空間 | GCHandle