GCHandle Struktura

Definice

Poskytuje způsob přístupu ke spravovanému objektu z nespravované paměti.Provides a way to access a managed object from unmanaged memory.

public value class GCHandle
[System.Runtime.InteropServices.ComVisible(true)]
public struct GCHandle
type GCHandle = struct
Public Structure GCHandle
Dědičnost
GCHandle
Atributy

Příklady

Následující příklad ukazuje App třídu, která vytvoří popisovač spravovaného objektu GCHandle.Alloc pomocí metody, která zabraňuje shromáždění spravovaného objektu.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. Volání EnumWindows metody předává delegáta a spravovaný objekt (oba deklarované jako spravované typy, ale nejsou zobrazeny) a přetypování popisovač IntPtrna.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. Nespravovaná funkce předá typ zpět volajícímu jako parametr funkce zpětného volání.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);

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();
    }

    [SecurityPermission(SecurityAction.Demand, UnmanagedCode = true)]
    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

Poznámky

Struktura se používá GCHandleType s výčtem k vytvoření popisovače odpovídajícího spravovanému objektu. GCHandleThe GCHandle structure is used with the GCHandleType enumeration to create a handle corresponding to any managed object. Tento popisovač může být jeden ze čtyř typů: Weak, WeakTrackResurrection, Normalnebo Pinned.This handle can be one of four types: Weak, WeakTrackResurrection, Normal, or Pinned. Když je popisovač přidělen, můžete jej použít k zabránění shromažďování spravovaného objektu systémem uvolňování paměti, pokud je v něm uložen pouze nespravovaný klient s jediným odkazem.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. Bez takového popisovače může být objekt shromážděn systémem uvolňování paměti před dokončením své práce jménem nespravovaného klienta.Without such a handle, the object can be collected by the garbage collector before completing its work on behalf of the unmanaged client.

Můžete také použít GCHandle k vytvoření připnutého objektu, který vrací adresu paměti, aby systém uvolňování paměti zabránil v přesunutí objektu do paměti.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.

Pokud se popisovač dostane mimo rozsah, je nutné jej explicitně uvolnit voláním Free metody. v opačném případě může dojít k nevrácení paměti.When the handle goes out of scope you must explicitly release it by calling the Free method; otherwise, memory leaks may occur. Když uvolníte připnutý popisovač, přidružený objekt nebude odpojen a bude mít nárok na uvolňování paměti, pokud na něj neexistují žádné další odkazy.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.

Vlastnosti

IsAllocated

Načte hodnotu, která označuje, jestli je popisovač přidělený.Gets a value indicating whether the handle is allocated.

Target

Získá nebo nastaví objekt, který tento popisovač představuje.Gets or sets the object this handle represents.

Metody

AddrOfPinnedObject()

Načte adresu dat objektu v Pinned popisovači.Retrieves the address of object data in a Pinned handle.

Alloc(Object)

Přidělí Normal popisovač pro zadaný objekt.Allocates a Normal handle for the specified object.

Alloc(Object, GCHandleType)

Přidělí popisovač zadaného typu pro zadaný objekt.Allocates a handle of the specified type for the specified object.

Equals(Object)

Určuje, zda je GCHandle zadaný objekt stejný jako aktuální GCHandle objekt.Determines whether the specified GCHandle object is equal to the current GCHandle object.

Free()

GCHandleUvolní.Releases a GCHandle.

FromIntPtr(IntPtr)

Vrátí nový GCHandle objekt vytvořený z popisovače na spravovaný objekt.Returns a new GCHandle object created from a handle to a managed object.

GetHashCode()

Vrátí identifikátor aktuálního GCHandle objektu.Returns an identifier for the current GCHandle object.

ToIntPtr(GCHandle)

Vrátí vnitřní celočíselnou reprezentaci GCHandle objektu.Returns the internal integer representation of a GCHandle object.

Operátory

Equality(GCHandle, GCHandle)

Vrací hodnotu určující, zda jsou GCHandle dva objekty stejné.Returns a value indicating whether two GCHandle objects are equal.

Explicit(GCHandle to IntPtr)

A GCHandle je uložen pomocí interní celočíselné reprezentace.A GCHandle is stored using an internal integer representation.

Explicit(IntPtr to GCHandle)

A GCHandle je uložen pomocí interní celočíselné reprezentace.A GCHandle is stored using an internal integer representation.

Inequality(GCHandle, GCHandle)

Vrátí hodnotu, která znamená, GCHandle zda dva objekty nejsou stejné.Returns a value indicating whether two GCHandle objects are not equal.

Platí pro

Viz také