Skip to main content
.NET Framework Class Library
GCHandle Structure

Provides a way to access a managed object from unmanaged memory.

Namespace: System.Runtime.InteropServices
Assembly: mscorlib (in mscorlib.dll)
Syntax
<ComVisibleAttribute(True)> _
Public Structure GCHandle
[ComVisibleAttribute(true)]
public struct GCHandle
[ComVisibleAttribute(true)]
public value class GCHandle
[<Sealed>]
[<ComVisibleAttribute(true)>]
type GCHandle =  struct end

The GCHandle type exposes the following members.

Properties
 NameDescription
Public propertySupported by the XNA FrameworkIsAllocatedGets a value indicating whether the handle is allocated.
Public propertySupported by the XNA FrameworkTargetGets or sets the object this handle represents.
Top
Methods
 NameDescription
Public methodSupported by the XNA FrameworkAddrOfPinnedObjectRetrieves the address of an object in a Pinned handle.
Public methodStatic memberSupported by the XNA FrameworkAlloc(Object)Allocates a Normal handle for the specified object.
Public methodStatic memberSupported by the XNA FrameworkAlloc(Object, GCHandleType)Allocates a handle of the specified type for the specified object.
Public methodSupported by the XNA FrameworkEqualsDetermines whether the specified GCHandle object is equal to the current GCHandle object. (Overrides ValueType..::.Equals(Object).)

In XNA Framework, this member is overridden by Equals(Object).
Protected methodSupported by the XNA FrameworkFinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public methodSupported by the XNA FrameworkFreeReleases a GCHandle.
Public methodStatic memberFromIntPtrReturns a new GCHandle object created from a handle to a managed object.
Public methodSupported by the XNA FrameworkGetHashCodeReturns an identifier for the current GCHandle object. (Overrides ValueType..::.GetHashCode()()().)

In XNA Framework, this member is overridden by GetHashCode()()().
Public methodSupported by the XNA FrameworkGetTypeGets the Type of the current instance. (Inherited from Object.)
Protected methodSupported by the XNA FrameworkMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Public methodStatic memberToIntPtrReturns the internal integer representation of a GCHandle object.
Public methodSupported by the XNA FrameworkToStringReturns the fully qualified type name of this instance. (Inherited from ValueType.)

In XNA Framework 3.0, this member is inherited from Object..::.ToString()()().
Top
Operators
 NameDescription
Public operatorStatic memberEqualityReturns a value indicating whether two GCHandle objects are equal.
Public operatorStatic memberSupported by the XNA FrameworkExplicitNarrowingExplicitExplicit(GCHandle to IntPtr)A GCHandle is stored using an internal integer representation.
Public operatorStatic memberSupported by the XNA FrameworkExplicitNarrowingExplicitExplicit(IntPtr to GCHandle)A GCHandle is stored using an internal integer representation.
Public operatorStatic memberInequalityReturns a value indicating whether two GCHandle objects are not equal.
Top
Remarks

The GCHandle structure is used 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. When the handle has been allocated, you can use it 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 GCHandle to create a pinned object that returns a memory address to prevent the garbage collector from moving the object in memory.

When the handle goes out of scope you must explicitly release it by calling the Free method; otherwise, memory leaks may occur. When you free a pinned handle, the associated object will be unpinned and will become eligible for garbage collection, if there are no other references to it.

Examples

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


using System;
using System.IO;
using System.Threading;
using System.Windows.Forms;
using System.Runtime.InteropServices;
using System.Security.Permissions;

public delegate bool CallBack(int handle, IntPtr param);

public class LibWrap
{
	// passing managed object as LPARAM
	// BOOL EnumWindows(WNDENUMPROC lpEnumFunc, LPARAM lParam);

	[DllImport("user32.dll")]
	public static extern bool EnumWindows(CallBack cb, IntPtr param);
}

public class App
{
	public static void Main()
	{
		Run();
	}

        [SecurityPermission(SecurityAction.Demand, UnmanagedCode=true)]
	public static void Run()
        {
		TextWriter tw = System.Console.Out;
		GCHandle gch = GCHandle.Alloc(tw);

		CallBack cewp = new CallBack(CaptureEnumWindowsProc);

		// platform invoke will prevent delegate to be garbage collected
		// before call ends

		LibWrap.EnumWindows(cewp, GCHandle.ToIntPtr(gch));
		gch.Free();
        }

	private static bool CaptureEnumWindowsProc(int handle, IntPtr param)
	{
		GCHandle gch = GCHandle.FromIntPtr(param);
		TextWriter tw = (TextWriter)gch.Target;
		tw.WriteLine(handle);
		return true;
	}
}

Version Information

.NET Framework

Supported in: 4, 3.5, 3.0, 2.0, 1.1, 1.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1
Platforms

Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows XP SP2 x64 Edition, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.
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.