GCHandle.Alloc Method

Definition

Namespace:

System.Runtime.InteropServices

Assembly:

System.Runtime.dll

Allocates a handle for the specified object.

Overloads

Alloc(Object)	Allocates a Normal handle for the specified object.
Alloc(Object, GCHandleType)	Allocates a handle of the specified type for the specified object.

Alloc(Object)

Source:

GCHandle.cs

Allocates a Normal handle for the specified object.

public:
 static System::Runtime::InteropServices::GCHandle Alloc(System::Object ^ value);

public static System.Runtime.InteropServices.GCHandle Alloc (object? value);

static member Alloc : obj -> System.Runtime.InteropServices.GCHandle

Public Shared Function Alloc (value As Object) As GCHandle

Parameters

value

Object

The object that uses the GCHandle.

Returns

GCHandle

A new GCHandle that protects the object from garbage collection. This GCHandle must be released with Free() when it is no longer needed.

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.

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

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

internal static class NativeMethods
{
    // passing managed object as LPARAM
    // BOOL EnumWindows(WNDENUMPROC lpEnumFunc, LPARAM lParam);

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

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

    public static void Run()
    {
        TextWriter tw = Console.Out;
        GCHandle gch = GCHandle.Alloc(tw);

        CallBack cewp = new CallBack(CaptureEnumWindowsProc);

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

        NativeMethods.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;
    }
}

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


Friend Module NativeMethods

    ' passing managed object as LPARAM
    ' BOOL EnumWindows(WNDENUMPROC lpEnumFunc, LPARAM lParam);
    <DllImport("user32.dll")>
    Friend Function EnumWindows(ByVal cb As CallBack, ByVal param As IntPtr) As Boolean
    End Function
End Module


Module App

    Sub Main()

        Run()

    End Sub

    <SecurityPermission(SecurityAction.Demand, UnmanagedCode:=True)>
    Sub Run()

        Dim tw As TextWriter = 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
        NativeMethods.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

Remarks

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

See also

• GCHandleType

Alloc(Object, GCHandleType)

Source:

GCHandle.cs

Allocates a handle of the specified type for the specified object.

public:
 static System::Runtime::InteropServices::GCHandle Alloc(System::Object ^ value, System::Runtime::InteropServices::GCHandleType type);

public static System.Runtime.InteropServices.GCHandle Alloc (object? value, System.Runtime.InteropServices.GCHandleType type);

static member Alloc : obj * System.Runtime.InteropServices.GCHandleType -> System.Runtime.InteropServices.GCHandle

Public Shared Function Alloc (value As Object, type As GCHandleType) As GCHandle

Parameters

value

Object

The object that uses the GCHandle.

type

GCHandleType

One of the GCHandleType values, indicating the type of GCHandle to create.

Returns

GCHandle

A new GCHandle of the specified type. This GCHandle must be released with Free() when it is no longer needed.

Exceptions

ArgumentException

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

See also

• GCHandleType