Export (0) Print
Expand All

GCHandle Structure

Provides a means for accessing a managed object from unmanaged memory.

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

System.Object
   System.ValueType
      System.Runtime.InteropServices.GCHandle

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

[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

The garbage collector handle, or GCHandle value type, is used in conjunction with the GCHandleType enumeration to create a handle corresponding to any managed object. This handle can be one of four types: Weak, WeakTrackResurrection, Normal, or Pinned. Once allocated, you can use a GCHandle to prevent the managed object from being collected by the garbage collector when an unmanaged client holds the only reference. Without such a handle, the object can be collected by the garbage collector before completing its work on behalf of the unmanaged client.

You can also use the GCHandle to create a pinned object that returns a memory address and prevents the garbage collector from moving the object in memory. From managed code, you can obtain a new object reference. For all but the IsAllocated property, you must apply unmanaged code permission by using SecurityPermission with the associated SecurityPermissionFlag.UnmanagedCode enumeration value.

Example

[Visual Basic, C#] The following example shows an App class that creates a handle to a managed object using the GCHandle.Alloc method, which prevents the managed object from being collected. A call to the EnumWindows method passes a delegate and a managed object (both declared as managed types, but not shown), and casts the handle to an IntPtr. The unmanaged function passes the type back to the caller as a parameter of the callback function.

[Visual Basic] 
Public Class App
   Public Shared Sub Main()
      Dim tw As TextWriter = System.Console.Out
      Dim gch As GCHandle = GCHandle.Alloc( tw )
      
      ' Platform invoke prevents the delegate from being garbage collected
      ' before the call ends.
      Dim cewp As CallBack
      cewp = AddressOf App.CaptureEnumWindowsProc
      LibWrap.EnumWindows( cewp, GCHandle.op_Explicit( gch ))
      gch.Free()
   End Sub 'Main
   
   Public Shared Function CaptureEnumWindowsProc( ByVal handle _
         As Integer, ByVal param As IntPtr ) As Boolean
      Dim gch As GCHandle = GCHandle.op_Explicit( param )
      Dim tw As TextWriter = CType( gch.Target, TextWriter )
      tw.WriteLine( handle )
      return True
   End Function 'CaptureEnumWindowsProc
End Class 'App
[C#] 
public class App
{
   public static void Main()
   {
      TextWriter tw = System.Console.Out;
      GCHandle gch = GCHandle.Alloc( tw );
      CallBack cewp = new CallBack( CaptureEnumWindowsProc );
      
      // Platform invoke prevents the delegate from being garbage 
      // collected before the call ends.
      LibWrap.EnumWindows( cewp, (IntPtr)gch );
      gch.Free();
   }
   
   private static bool CaptureEnumWindowsProc( int handle, IntPtr param )
   {
      GCHandle gch = (GCHandle)param;
      TextWriter tw = (TextWriter)gch.Target;
      tw.WriteLine( handle );
      return true;
   }   
}

[C++, JScript] No example is available for C++ or JScript. To view a Visual Basic 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, .NET Compact Framework

Assembly: Mscorlib (in Mscorlib.dll)

See Also

GCHandle Members | System.Runtime.InteropServices Namespace | GCHandleType

Show:
© 2014 Microsoft