GCHandle Structure

Définition

Fournit un moyen d'accéder à un objet managé à partir d'une mémoire non managée.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
Héritage
GCHandle
Attributs

Exemples

L’exemple suivant illustre une App classe qui crée un handle vers un objet managé à l' GCHandle.Alloc aide de la méthode, ce qui empêche la collecte de l’objet managé.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. Un appel à la EnumWindows méthode passe un délégué et un objet managé (tous deux déclarés comme types managés, mais non affichés) et effectue un cast du IntPtrhandle vers un.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. La fonction non managée passe le type à l’appelant en tant que paramètre de la fonction de rappel.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

Remarques

La GCHandle structure est utilisée avec l' GCHandleType énumération pour créer un handle correspondant à n’importe quel objet managé.The GCHandle structure is used with the GCHandleType enumeration to create a handle corresponding to any managed object. Ce handle peut être l’un des quatre types Weaksuivants WeakTrackResurrection: Normal,, Pinnedou.This handle can be one of four types: Weak, WeakTrackResurrection, Normal, or Pinned. Lorsque le handle a été alloué, vous pouvez l’utiliser pour empêcher l’objet managé d’être collecté par le garbage collector lorsqu’un client non managé contient la seule référence.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. Sans ce descripteur, l’objet peut être collecté par le garbage collector avant de terminer son travail pour le compte du client non géré.Without such a handle, the object can be collected by the garbage collector before completing its work on behalf of the unmanaged client.

Vous pouvez également utiliser GCHandle pour créer un objet épinglé qui retourne une adresse mémoire pour empêcher le garbage collector de déplacer l’objet en mémoire.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.

Lorsque le descripteur est hors de portée, vous devez le libérer explicitement Free en appelant la méthode ; sinon, des fuites de mémoire peuvent se produire.When the handle goes out of scope you must explicitly release it by calling the Free method; otherwise, memory leaks may occur. Lorsque vous libérez un handle épinglé, l’objet associé est désépinglé et devient éligible pour garbage collection, s’il n’y a aucune autre référence à celui-ci.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.

Propriétés

IsAllocated

Obtient une valeur indiquant si le handle est alloué.Gets a value indicating whether the handle is allocated.

Target

Obtient ou définit l'objet représenté par le handle.Gets or sets the object this handle represents.

Méthodes

AddrOfPinnedObject()

Récupère l’adresse des données de l’objet dans un handle Pinned.Retrieves the address of object data in a Pinned handle.

Alloc(Object)

Alloue un handle Normal pour l'objet spécifié.Allocates a Normal handle for the specified object.

Alloc(Object, GCHandleType)

Alloue un handle du type spécifié pour l'objet spécifié.Allocates a handle of the specified type for the specified object.

Equals(Object)

Détermine si l'objet GCHandle spécifié est égal à l'objet GCHandle en cours.Determines whether the specified GCHandle object is equal to the current GCHandle object.

Free()

Libère un GCHandle.Releases a GCHandle.

FromIntPtr(IntPtr)

Retourne un nouvel objet GCHandle créé à partir d'un handle d'objet managé.Returns a new GCHandle object created from a handle to a managed object.

GetHashCode()

Retourne un identificateur pour l'objet GCHandle actuel.Returns an identifier for the current GCHandle object.

ToIntPtr(GCHandle)

Retourne la représentation interne sous forme d'entier d'un objet GCHandle.Returns the internal integer representation of a GCHandle object.

Opérateurs

Equality(GCHandle, GCHandle)

Retourne une valeur indiquant si deux objets GCHandle sont égaux.Returns a value indicating whether two GCHandle objects are equal.

Explicit(GCHandle to IntPtr)

GCHandle est stocké en utilisant une représentation sous forme d'entier interne.A GCHandle is stored using an internal integer representation.

Explicit(IntPtr to GCHandle)

GCHandle est stocké en utilisant une représentation sous forme d'entier interne.A GCHandle is stored using an internal integer representation.

Inequality(GCHandle, GCHandle)

Retourne une valeur indiquant si deux objets GCHandle sont égaux.Returns a value indicating whether two GCHandle objects are not equal.

S’applique à

Voir aussi