This documentation is archived and is not being maintained.

HandleRef Structure

Wraps a managed object holding a handle to a resource that is passed to unmanaged code using platform invoke.

For a list of all members of this type, see HandleRef Members.

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

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

[JScript] In JScript, you can use the structures in the .NET Framework, but you cannot define your own.

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Remarks

If you use platform invoke to call a managed object, and the object is not referenced elsewhere after the platform invoke call, it is possible for the garbage collector to finalize the managed object. This action releases the resource and invalidates the handle, causing the platform invoke call to fail. Wrapping a handle with HandleRef guarantees that the managed object is not garbage collected until the platform invoke call completes. For a description of platform invoke services, see Consuming Unmanaged DLL Functions.

The HandleRef value type, like GCHandle, is a special type recognized by the interop marshaler. A normal, nonpinned GCHandle also prevents untimely garbage collection, yet HandleRef provides better performance. Although using HandleRef to keep an object alive for the duration of a platform invoke call is preferred, you can also use the GC.KeepAlive method for the same purpose.

The HandleRef constructor takes two parameters: an Object representing the wrapper, and an IntPtr representing the unmanaged handle. The interop marshaler passes only the handle to unmanaged code, and guarantees that the wrapper (passed as the first parameter to the constructor of the HandleRef) remains alive for the duration of the call.

Example

[Visual Basic, C#, C++] The following example shows how to use HandleRef to keep alive an object passed as the first parameter. The interop marshaler passes only the handle to unmanaged code.

[Visual Basic] 
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] No example is available for JScript. To view a Visual Basic, C#, or C++ example, click the Language Filter button Language Filter in the upper-left corner of the page.

Requirements

Namespace: System.Runtime.InteropServices

Platforms: Windows 98, Windows NT 4.0, Windows Millennium Edition, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 family

Assembly: Mscorlib (in Mscorlib.dll)

See Also

HandleRef Members | System.Runtime.InteropServices Namespace | GCHandle

Show: