This documentation is archived and is not being maintained.

GCHandle.Alloc Method (Object)

Allocates a Normal handle for the specified object.

Namespace:  System.Runtime.InteropServices
Assembly:  mscorlib (in mscorlib.dll)

'Declaration
<SecurityPermissionAttribute(SecurityAction.LinkDemand, Flags := SecurityPermissionFlag.UnmanagedCode)> _
Public Shared Function Alloc ( _
	value As Object _
) As GCHandle
'Usage
Dim value As Object 
Dim returnValue As GCHandle 

returnValue = GCHandle.Alloc(value)

Parameters

value
Type: System.Object

The object that uses the GCHandle.

Return Value

Type: System.Runtime.InteropServices.GCHandle
A new GCHandle that protects the object from garbage collection. This GCHandle must be released with Free when it is no longer needed.

ExceptionCondition
ArgumentException

An instance with nonprimitive (non-blittable) members cannot be pinned.

Normal handles are opaque, which means that you cannot resolve the address of the object it contains through the handle.

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 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98, Windows CE, Windows Mobile for Smartphone, Windows Mobile for Pocket PC, Xbox 360, Zune

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

.NET Framework

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

.NET Compact Framework

Supported in: 3.5, 2.0, 1.0

XNA Framework

Supported in: 3.0, 2.0, 1.0
Show: