GCHandle GCHandle GCHandle GCHandle Struct

定義

提供從 Unmanaged 記憶體存取 Managed 物件的方法。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
繼承
屬性

範例

下列範例顯示App的類別,會GCHandle.Alloc使用方法建立 managed 物件的控制碼,以防止收集 managed 物件。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. EnumWindows方法的呼叫會傳遞委派和 managed 物件(兩者都宣告為 managed 類型,但不會顯示),並將控制碼轉換IntPtr成。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. 非受控函式會將型別傳遞回呼叫端做為回呼函式的參數。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

備註

結構會搭配GCHandleType列舉使用,以建立對應至任何 managed 物件的控制碼。 GCHandleThe GCHandle structure is used with the GCHandleType enumeration to create a handle corresponding to any managed object. 這個控制碼可以是四種類型的Weak其中WeakTrackResurrection一種: Pinned、、 Normal或。This handle can be one of four types: Weak, WeakTrackResurrection, Normal, or Pinned. 配置控制碼之後,您可以使用它來防止垃圾收集行程在未受管理的用戶端保有唯一的參考時,回收 managed 物件。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.

您也可以使用GCHandle來建立已釘選的物件,以傳回記憶體位址,以防止垃圾收集行程將物件移動到記憶體中。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.

當控制碼超出範圍時,您必須藉由呼叫Free方法明確地釋放它,否則可能會發生記憶體流失。When the handle goes out of scope you must explicitly release it by calling the 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.

屬性

IsAllocated IsAllocated IsAllocated IsAllocated

取得值,指出控制代碼是否已配置。Gets a value indicating whether the handle is allocated.

Target Target Target Target

取得或設定這個控制代碼表示的物件。Gets or sets the object this handle represents.

方法

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

擷取 Pinned 控制代碼中物件資料的位址。Retrieves the address of object data in a Pinned handle.

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

配置 Normal 控制代碼給指定的物件。Allocates a Normal handle for the specified object.

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

配置指定類型的控制代碼給指定的物件。Allocates a handle of the specified type for the specified object.

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

判斷指定的 GCHandle 物件是否等於目前的 GCHandle 物件。Determines whether the specified GCHandle object is equal to the current GCHandle object.

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

釋放 GCHandleReleases a GCHandle.

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

傳回新的 GCHandle 物件,而此物件是從 Managed 物件的控制代碼所建立。Returns a new GCHandle object created from a handle to a managed object.

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

傳回目前 GCHandle 物件的識別項。Returns an identifier for the current GCHandle object.

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

傳回 GCHandle 物件的內部整數表示。Returns the internal integer representation of a GCHandle object.

運算子

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

傳回值,這個值表示兩個 GCHandle 物件是否相等。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)

GCHandle 是使用內部整數表示來儲存。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)

GCHandle 是使用內部整數表示來儲存。A GCHandle is stored using an internal integer representation.

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

傳回值,指出兩個 GCHandle 物件是否不相等。Returns a value indicating whether two GCHandle objects are not equal.

適用於

另請參閱