Provides a way to access a managed object from unmanaged memory.
Assembly: mscorlib (in mscorlib.dll)
Thetype exposes the following members.
|AddrOfPinnedObject||Retrieves the address of an object in a Pinned handle.|
|Alloc(Object)||Allocates a Normal handle for the specified object.|
|Alloc(Object, GCHandleType)||Allocates a handle of the specified type for the specified object.|
|Equals||Determines whether the specified object is equal to the current object. (Overrides ValueType.Equals(Object).)|
In XNA Framework, this member is overridden by Equals(Object).
|Free||Releases a .|
|FromIntPtr||Returns a new object created from a handle to a managed object.|
|GetHashCode||Returns an identifier for the current object. (Overrides ValueType.GetHashCode.)|
In XNA Framework, this member is overridden by GetHashCode.
|GetType||Gets the Type of the current instance. (Inherited from Object.)|
|ToIntPtr||Returns the internal integer representation of a object.|
|ToString||Returns the fully qualified type name of this instance. (Inherited from ValueType.)|
In XNA Framework 3.0, this member is inherited from Object.ToString.
|Equality||Returns a value indicating whether two objects are equal.|
|Narrowing(GCHandle to IntPtr)||A is stored using an internal integer representation.|
|Narrowing(IntPtr to GCHandle)||A is stored using an internal integer representation.|
|Inequality||Returns a value indicating whether two objects are not equal.|
The 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 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.
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
.NET FrameworkSupported in: 4.5.2, 4.5.1, 4.5, 4, 3.5, 3.0, 2.0, 1.1, 1.0
.NET Framework Client ProfileSupported in: 4, 3.5 SP1
Portable Class LibrarySupported in: Portable Class Library
.NET for Windows Store appsSupported in: Windows 8
.NET for Windows Phone appsSupported in: Windows Phone 8.1, Windows Phone 8, Silverlight 8.1
Windows Phone 8.1, Windows Phone 8, Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)
The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.