Estrutura GCHandle

Artigo
04/19/2018

Dica

The .NET API Reference documentation has a new home. Visit the .NET API Browser on docs.microsoft.com to see the new experience.

Fornece uma maneira de acessar um objeto gerenciado de memória não gerenciada.

Namespace: System.Runtime.InteropServices
Assembly: mscorlib (em mscorlib.dll)

Sintaxe

[ComVisibleAttribute(true)]
public struct GCHandle

[ComVisibleAttribute(true)]
public value struct GCHandle

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

<ComVisibleAttribute(True)>
Public Structure GCHandle

Propriedades

	Nome	Descrição
	IsAllocated	Obtém um valor que indica se o identificador está alocado.
	Target	Obtém ou define o objeto que esse identificador representa.

Métodos

	Nome	Descrição
	AddrOfPinnedObject()	Recupera o endereço de um objeto em um identificador GCHandleType.Pinned.
	Alloc(Object)	Aloca um identificador Normal para o objeto especificado.
	Alloc(Object, GCHandleType)	Aloca um identificador do tipo especificado para o objeto especificado.
	Equals(Object)	Determina se o objeto GCHandle especificado é igual ao objeto GCHandle atual.(Substitui o ValueType.Equals(Object).)
	Free()	Libera um GCHandle.
	FromIntPtr(IntPtr)	Retorna um novo objeto GCHandle criado de um identificador para um objeto gerenciado.
	GetHashCode()	Retorna um identificador do objeto GCHandle atual.(Substitui o ValueType.GetHashCode().)
	GetType()	Obtém o Type da instância atual.(Herdado de Object.)
	ToIntPtr(GCHandle)	Retorna a representação de número inteiro interna de um GCHandle objeto.
	ToString()	Retorna o nome do tipo totalmente qualificado dessa instância.(Herdado de ValueType.)

Operadores

	Nome	Descrição
	Equality(GCHandle, GCHandle)	Retorna um valor que indica se dois objetos GCHandle são iguais.
	Explicit(GCHandle to IntPtr)	Um GCHandle é armazenado usando uma representação de inteiro interna.
	Explicit(IntPtr to GCHandle)	Um GCHandle é armazenado usando uma representação de inteiro interna.
	Inequality(GCHandle, GCHandle)	Retorna um valor que indica se dois objetos GCHandle não são iguais.

Comentários

O GCHandle estrutura é usada com o GCHandleType enumeração para criar um identificador correspondente a qualquer objeto gerenciado. Esse identificador pode ser um dos quatro tipos: Weak, WeakTrackResurrection, Normal, ou Pinned. Quando o identificador foi alocado, você pode usá-lo para impedir que o objeto gerenciado que está sendo coletado pelo coletor de lixo quando um cliente não gerenciado contém somente a referência. Sem identificador, o objeto pode ser coletado pelo coletor de lixo antes de concluir seu trabalho em nome do cliente não gerenciado.

Você também pode usar GCHandle para criar um objeto afixado que retorna um endereço de memória para impedir que o coletor de lixo mover o objeto na memória.

Quando o identificador sai do escopo você deve liberá-lo explicitamente chamando o Free método; caso contrário, memória vazamentos podem ocorrer. Quando você liberar um identificador fixo, o objeto associado será desafixado e se torna qualificado para a coleta de lixo, se existem outras referências a ele.

Exemplos

A exemplo a seguir mostra um App classe que cria um identificador para um objeto gerenciado usando o GCHandle.Alloc método, o que impede que o objeto gerenciado que estão sendo coletados. Uma chamada para o EnumWindows método passa um representante e um objeto gerenciado (os declarado como tipos gerenciados, mas não mostrado) e converte o identificador para um 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.

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

Informações de Versão

Plataforma Universal do Windows
Disponível desde 8
.NET Framework
Disponível desde 1.1
Biblioteca de Classes Portátil
Com suporte no: plataformas portáteis do .NET
Silverlight
Disponível desde 2.0
Windows Phone Silverlight
Disponível desde 7.0
Windows Phone
Disponível desde 8.1

Acesso thread-safe

Quaisquer membros estáticos públicos ( Compartilhado no Visual Basic) desse tipo são thread-safe. Não há garantia de que qualquer membro de instância seja thread-safe.

Confira Também

GCHandleType
Namespace System.Runtime.InteropServices
The Truth About GCHandles

Retornar ao início

Compartilhar via