GCHandle GCHandle GCHandle GCHandle Struct

Definição

Fornece uma maneira de acessar um objeto gerenciado de memória não gerenciada.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
Herança
Atributos

Exemplos

O exemplo a seguir mostra App uma classe que cria um identificador para um objeto gerenciado usando GCHandle.Alloc o método, que impede que o objeto gerenciado seja coletado.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. Uma chamada para o EnumWindows método passa um delegado e um objeto gerenciado (ambos declarados como tipos gerenciados, mas não mostrados) e converte o identificador IntPtrem um.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. A função não gerenciada passa o tipo de volta para o chamador como um parâmetro da função de retorno de chamada.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

Comentários

A GCHandle estrutura é usada com a GCHandleType enumeração para criar um identificador correspondente a qualquer objeto gerenciado.The GCHandle structure is used with the GCHandleType enumeration to create a handle corresponding to any managed object. Esse identificador pode ser de um dos quatro tipos Weak: WeakTrackResurrection Normal,, ou Pinned.This handle can be one of four types: Weak, WeakTrackResurrection, Normal, or Pinned. Quando o identificador tiver sido alocado, você poderá usá-lo para impedir que o objeto gerenciado seja coletado pelo coletor de lixo quando um cliente não gerenciado mantiver a única referência.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. Sem esse tipo de identificador, o objeto pode ser coletado pelo coletor de lixo antes de concluir seu trabalho em nome do cliente não gerenciado.Without such a handle, the object can be collected by the garbage collector before completing its work on behalf of the unmanaged client.

Você também pode usar GCHandle o para criar um objeto fixado que retorna um endereço de memória para impedir que o coletor de lixo mova o objeto na memória.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.

Quando o identificador sai do escopo, você deve liberá-lo explicitamente chamando o Free método; caso contrário, podem ocorrer vazamentos de memória.When the handle goes out of scope you must explicitly release it by calling the Free method; otherwise, memory leaks may occur. Quando você liberar um identificador fixado, o objeto associado será desafixado e se tornará qualificado para coleta de lixo, se não houver nenhuma outra referência a ele.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.

Propriedades

IsAllocated IsAllocated IsAllocated IsAllocated

Obtém um valor que indica se o identificador está alocado.Gets a value indicating whether the handle is allocated.

Target Target Target Target

Obtém ou define o objeto que esse identificador representa.Gets or sets the object this handle represents.

Métodos

AddrOfPinnedObject() AddrOfPinnedObject() AddrOfPinnedObject() AddrOfPinnedObject()

Recupera o endereço dos dados do objeto em um identificador Pinned.Retrieves the address of object data in a Pinned handle.

Alloc(Object) Alloc(Object) Alloc(Object) Alloc(Object)

Aloca um identificador Normal para o objeto especificado.Allocates a Normal handle for the specified object.

Alloc(Object, GCHandleType) Alloc(Object, GCHandleType) Alloc(Object, GCHandleType) Alloc(Object, GCHandleType)

Aloca um identificador do tipo especificado para o objeto especificado.Allocates a handle of the specified type for the specified object.

Equals(Object) Equals(Object) Equals(Object) Equals(Object)

Determina se o objeto GCHandle especificado é igual ao objeto GCHandle atual.Determines whether the specified GCHandle object is equal to the current GCHandle object.

Free() Free() Free() Free()

Libera um GCHandle.Releases a GCHandle.

FromIntPtr(IntPtr) FromIntPtr(IntPtr) FromIntPtr(IntPtr) FromIntPtr(IntPtr)

Retorna um novo objeto GCHandle criado de um identificador para um objeto gerenciado.Returns a new GCHandle object created from a handle to a managed object.

GetHashCode() GetHashCode() GetHashCode() GetHashCode()

Retorna um identificador do objeto GCHandle atual.Returns an identifier for the current GCHandle object.

ToIntPtr(GCHandle) ToIntPtr(GCHandle) ToIntPtr(GCHandle) ToIntPtr(GCHandle)

Retorna a representação de número inteiro interna de um GCHandle objeto.Returns the internal integer representation of a GCHandle object.

Operadores

Equality(GCHandle, GCHandle) Equality(GCHandle, GCHandle) Equality(GCHandle, GCHandle) Equality(GCHandle, GCHandle)

Retorna um valor que indica se dois objetos GCHandle são iguais.Returns a value indicating whether two GCHandle objects are equal.

Explicit(IntPtr to GCHandle) Explicit(IntPtr to GCHandle) Explicit(IntPtr to GCHandle) Explicit(IntPtr to GCHandle)

Um GCHandle é armazenado usando uma representação de inteiro interna.A GCHandle is stored using an internal integer representation.

Explicit(GCHandle to IntPtr) Explicit(GCHandle to IntPtr) Explicit(GCHandle to IntPtr) Explicit(GCHandle to IntPtr)

Um GCHandle é armazenado usando uma representação de inteiro interna.A GCHandle is stored using an internal integer representation.

Inequality(GCHandle, GCHandle) Inequality(GCHandle, GCHandle) Inequality(GCHandle, GCHandle) Inequality(GCHandle, GCHandle)

Retorna um valor que indica se dois objetos GCHandle não são iguais.Returns a value indicating whether two GCHandle objects are not equal.

Aplica-se a

Veja também