Compartir a través de

Estructura GCHandle

  • Artículo

 

Publicado: octubre de 2016

Proporciona una forma de obtener acceso a un objeto administrado desde la memoria no administrada.

Espacio de nombres:   System.Runtime.InteropServices
Ensamblado:  mscorlib (en mscorlib.dll)

Sintaxis

[ComVisibleAttribute(true)]
public struct GCHandle

[ComVisibleAttribute(true)]
public value struct GCHandle

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

<ComVisibleAttribute(True)>
Public Structure GCHandle

Propiedades

Nombre Descripción
System_CAPS_pubproperty IsAllocated

Obtiene un valor que indica si el identificador está asignado.
System_CAPS_pubproperty Target

Obtiene o establece el objeto al que representa este identificador.

Métodos

Nombre Descripción
System_CAPS_pubmethod AddrOfPinnedObject()

Recupera la dirección de un objeto en un identificador GCHandleType.Pinned.
System_CAPS_pubmethodSystem_CAPS_static Alloc(Object)

Asigna un identificador Normal para el objeto especificado.
System_CAPS_pubmethodSystem_CAPS_static Alloc(Object, GCHandleType)

Asigna un identificador del tipo especificado para el objeto especificado.
System_CAPS_pubmethod Equals(Object)

Determina si el objeto GCHandle especificado es igual al objeto GCHandle actual.(Invalida ValueType.Equals(Object)).
System_CAPS_pubmethod Free()

Libera un GCHandle.
System_CAPS_pubmethodSystem_CAPS_static FromIntPtr(IntPtr)

Devuelve un nuevo objeto GCHandle creado a partir de un identificador a un objeto administrado.
System_CAPS_pubmethod GetHashCode()

Devuelve un identificador para el objeto GCHandle actual.(Invalida ValueType.GetHashCode()).
System_CAPS_pubmethod GetType()

Obtiene el Type de la instancia actual.(Heredado de Object).
System_CAPS_pubmethodSystem_CAPS_static ToIntPtr(GCHandle)

Devuelve la representación entera interna de un objeto GCHandle.
System_CAPS_pubmethod ToString()

Devuelve el nombre de tipo completo de esta instancia.(Heredado de ValueType).

Operadores

Nombre Descripción
System_CAPS_puboperatorSystem_CAPS_static Equality(GCHandle, GCHandle)

Devuelve un valor que indica si dos objetos GCHandle son iguales.
System_CAPS_puboperatorSystem_CAPS_static Explicit(GCHandle to IntPtr)

Un GCHandle se almacena mediante una representación de entero interna.
System_CAPS_puboperatorSystem_CAPS_static Explicit(IntPtr to GCHandle)

Un GCHandle se almacena mediante una representación de entero interna.
System_CAPS_puboperatorSystem_CAPS_static Inequality(GCHandle, GCHandle)

Devuelve un valor que indica si dos objetos GCHandle no son iguales.

Comentarios

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.

Ejemplos

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

Información de versión

Plataforma universal de Windows
Disponible desde 8
.NET Framework
Disponible desde 1.1
Biblioteca de clases portable
Se admite en: plataformas portátiles de .NET
Silverlight
Disponible desde 2.0
Windows Phone Silverlight
Disponible desde 7.0
Windows Phone
Disponible desde 8.1

Seguridad para subprocesos

Cualquier miembro ( Compartido en Visual Basic) estático público de este tipo es seguro para subprocesos. No se garantiza que los miembros de instancia sean seguros para subprocesos.

Ver también

GCHandleType
Espacio de nombres System.Runtime.InteropServices
The Truth About GCHandles

Volver al principio