GCHandle Struktura

Definicja

Zapewnia sposób dostępu do obiektu zarządzanego z pamięci niezarządzanej.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
Dziedziczenie
GCHandle
Atrybuty

Przykłady

W poniższym przykładzie pokazano App klasę, która tworzy dojście do obiektu zarządzanego GCHandle.Alloc przy użyciu metody, która uniemożliwia zebranie obiektu zarządzanego.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. Wywołanie EnumWindows metody przekazuje delegata i zarządzany obiekt (zadeklarowane jako typy zarządzane, ale nie pokazano) i rzutuje uchwytu 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. Funkcja niezarządzana przekazuje typ z powrotem do obiektu wywołującego jako parametr funkcji wywołania zwrotnego.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

Uwagi

Struktura jest używana GCHandleType z wyliczeniem w celu utworzenia uchwytu odpowiadającego każdemu zarządzanemu obiektowi. GCHandleThe GCHandle structure is used with the GCHandleType enumeration to create a handle corresponding to any managed object. Ten uchwyt może być jednym z czterech typów: Weak, WeakTrackResurrection, Normal, lub Pinned.This handle can be one of four types: Weak, WeakTrackResurrection, Normal, or Pinned. Gdy dojście zostało przydzielone, można go użyć, aby zapobiec zbieraniu obiektu zarządzanego przez moduł wyrzucania elementów bezużytecznych, gdy niezarządzany klient utrzymuje tylko odwołanie.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 takiego dojścia obiekt może być zbierany przez moduł wyrzucania elementów bezużytecznych przed ukończeniem jego pracy w imieniu niezarządzanego klienta.Without such a handle, the object can be collected by the garbage collector before completing its work on behalf of the unmanaged client.

Można również użyć GCHandle do utworzenia przypiętego obiektu, który zwraca adres pamięci, aby zapobiec przeniesieniu obiektu przez moduł wyrzucania elementów bezużytecznych w pamięci.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.

Gdy dojście wykracza poza zakres, należy go jawnie zwolnić, wywołując Free metodę; w przeciwnym razie przecieki pamięci mogą wystąpić.When the handle goes out of scope you must explicitly release it by calling the Free method; otherwise, memory leaks may occur. Gdy zostanie zwolniony przypięty uchwyt, skojarzony obiekt zostanie odpięty i będzie kwalifikować się do wyrzucania elementów bezużytecznych, jeśli nie ma żadnych innych odwołań do niego.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.

Właściwości

IsAllocated

Pobiera wartość wskazującą, czy dojście jest przydzielono.Gets a value indicating whether the handle is allocated.

Target

Pobiera lub ustawia obiekt, który reprezentuje ten uchwyt.Gets or sets the object this handle represents.

Metody

AddrOfPinnedObject()

Pobiera adres danych obiektu z Pinned dojścia.Retrieves the address of object data in a Pinned handle.

Alloc(Object)

Normal Przydziela dojście dla określonego obiektu.Allocates a Normal handle for the specified object.

Alloc(Object, GCHandleType)

Przydziela dojście określonego typu dla określonego obiektu.Allocates a handle of the specified type for the specified object.

Equals(Object)

Określa, czy określony GCHandle obiekt jest równy bieżącemu GCHandle obiektowi.Determines whether the specified GCHandle object is equal to the current GCHandle object.

Free()

Zwalnia a GCHandle.Releases a GCHandle.

FromIntPtr(IntPtr)

Zwraca nowy GCHandle obiekt utworzony z dojścia do obiektu zarządzanego.Returns a new GCHandle object created from a handle to a managed object.

GetHashCode()

Zwraca identyfikator dla bieżącego GCHandle obiektu.Returns an identifier for the current GCHandle object.

ToIntPtr(GCHandle)

Zwraca wewnętrzną reprezentację GCHandle obiektu.Returns the internal integer representation of a GCHandle object.

Operatory

Equality(GCHandle, GCHandle)

Zwraca wartość wskazującą, czy dwa GCHandle obiekty są równe.Returns a value indicating whether two GCHandle objects are equal.

Explicit(GCHandle to IntPtr)

A GCHandle jest przechowywany przy użyciu wewnętrznej reprezentacji liczb całkowitych.A GCHandle is stored using an internal integer representation.

Explicit(IntPtr to GCHandle)

A GCHandle jest przechowywany przy użyciu wewnętrznej reprezentacji liczb całkowitych.A GCHandle is stored using an internal integer representation.

Inequality(GCHandle, GCHandle)

Zwraca wartość wskazującą, czy dwa GCHandle obiekty nie są równe.Returns a value indicating whether two GCHandle objects are not equal.

Dotyczy

Zobacz też