GCHandle-Struktur

Artikel
04/20/2017

Veröffentlicht: Oktober 2016

Bietet die Möglichkeit, aus nicht verwaltetem Speicher auf ein verwaltetes Objekt zuzugreifen.

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

Syntax

[ComVisibleAttribute(true)]
public struct GCHandle

[ComVisibleAttribute(true)]
public value struct GCHandle

[<Sealed>]
[<ComVisibleAttribute(true)>]
type GCHandle = struct end

<ComVisibleAttribute(True)>
Public Structure GCHandle

Eigenschaften

	Name	Beschreibung
	IsAllocated	Ruft einen Wert ab, der angibt, ob das Handle reserviert ist.
	Target	Ruft das Objekt ab, das von diesem Handle dargestellt wird, oder legt dieses fest.

Methoden

	Name	Beschreibung
	AddrOfPinnedObject()	Ruft die Adresse eines Objekts in einer GCHandleType.Pinned behandeln.
	Alloc(Object)	Ordnet eine Normal für das angegebene Objekt behandeln.
	Alloc(Object, GCHandleType)	Reserviert ein Handle vom angegebenen Typ für das angegebene Objekt.
	Equals(Object)	Bestimmt, ob das angegebene GCHandle Objekt ist gleich dem aktuellen GCHandle Objekt.(Überschreibt ValueType.Equals(Object).)
	Free()	Versionen einer GCHandle.
	FromIntPtr(IntPtr)	Gibt eine neue GCHandle Objekt aus einem Handle für ein verwaltetes Objekt erstellt.
	GetHashCode()	Gibt einen Bezeichner für den aktuellen GCHandle Objekt.(Überschreibt ValueType.GetHashCode().)
	GetType()	Ruft den Type der aktuellen Instanz ab.(Geerbt von „Object“.)
	ToIntPtr(GCHandle)	Gibt die interne ganzzahlige Darstellung der ein GCHandle Objekt.
	ToString()	Gibt den voll qualifizierten Typnamen dieser Instanz zurück.(Geerbt von „ValueType“.)

Operatoren

	Name	Beschreibung
	Equality(GCHandle, GCHandle)	Gibt einen Wert, der angibt, ob zwei GCHandle -Objekte gleich sind.
	Explicit(GCHandle to IntPtr)	Ein GCHandle mithilfe einer internen ganzzahldarstellung gespeichert.
	Explicit(IntPtr to GCHandle)	Ein GCHandle mithilfe einer internen ganzzahldarstellung gespeichert.
	Inequality(GCHandle, GCHandle)	Gibt einen Wert, der angibt, ob zwei GCHandle -Objekte ungleich sind.

Hinweise

The T:System.Runtime.InteropServices.GCHandle structure is used with the T:System.Runtime.InteropServices.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 T:System.Runtime.InteropServices.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 M:System.Runtime.InteropServices.GCHandle.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.

Beispiele

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 T:System.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;
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;
    }
}

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

Versionsinformationen

Universelle Windows-Plattform
Verfügbar seit 8
.NET Framework
Verfügbar seit 1.1
Portierbare Klassenbibliothek
Unterstützt in: portierbare .NET-Plattformen
Silverlight
Verfügbar seit 2.0
Windows Phone Silverlight
Verfügbar seit 7.0
Windows Phone
Verfügbar seit 8.1

Threadsicherheit

Alle öffentlichen statischen Member ( Shared in Visual Basic) dieses Typs sind threadsicher. Die Threadsicherheit für Instanzmember ist nicht garantiert.

Siehe auch

GCHandleType
System.Runtime.InteropServices-Namespace
The Truth About GCHandles

Zurück zum Anfang

Freigeben über