GCHandle Structure
Assembly: mscorlib (in mscorlib.dll)
The GCHandle class 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.
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.
Imports System Imports System.IO Imports System.Threading Imports System.Windows.Forms Imports System.Runtime.InteropServices Imports System.Security.Permissions Public Delegate Function CallBack(ByVal handle As Integer, ByVal param As IntPtr) As Boolean Module LibWrap ' passing managed object as LPARAM ' BOOL EnumWindows(WNDENUMPROC lpEnumFunc, LPARAM lParam); <DllImport("user32.dll")> _ Function EnumWindows(ByVal cb As CallBack, ByVal param As IntPtr) As Boolean End Function End Module 'LibWrap Module App Sub Main() Run() End Sub <SecurityPermission(SecurityAction.Demand, UnmanagedCode:=true)> _ Sub Run() Dim tw As TextWriter = System.Console.Out Dim gch As GCHandle = GCHandle.Alloc(tw) Dim cewp As CallBack cewp = AddressOf CaptureEnumWindowsProc ' platform invoke will prevent delegate to be garbage collected ' before call ends LibWrap.EnumWindows(cewp, GCHandle.ToIntPtr(gch)) gch.Free() End Sub Function CaptureEnumWindowsProc(ByVal handle As Integer, ByVal param As IntPtr) As Boolean Dim gch As GCHandle = GCHandle.FromIntPtr(param) Dim tw As TextWriter = CType(gch.Target, TextWriter) tw.WriteLine(handle) Return True End Function End Module
Windows 98, Windows Server 2000 SP4, Windows CE, Windows Millennium Edition, Windows Mobile for Pocket PC, Windows Mobile for Smartphone, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition
The Microsoft .NET Framework 3.0 is supported on Windows Vista, Microsoft Windows XP SP2, and Windows Server 2003 SP1.