GCHandle 結構

定義

命名空間:

System.Runtime.InteropServices

組件:

System.Runtime.dll

來源:

GCHandle.cs

提供從 Unmanaged 記憶體存取 Managed 物件的方法。

public value class GCHandle : IEquatable<System::Runtime::InteropServices::GCHandle>

public struct GCHandle : IEquatable<System.Runtime.InteropServices.GCHandle>

type GCHandle = struct

Public Structure GCHandle
Implements IEquatable(Of GCHandle)

繼承

Object

ValueType

GCHandle

實作

IEquatable<GCHandle>

範例

下列範例示範使用 App 方法建立Managed物件的 GCHandle.Alloc 句柄的類別，以防止收集Managed物件。 呼叫 方法會 EnumWindows 傳遞委派和 Managed 物件， (宣告為 Managed 型別，但未顯示) ，並將句柄 IntPtr轉換成 。 Unmanaged 函式會將型別傳回給呼叫端做為回呼函式的參數。

using System;
using System.IO;
using System.Threading;
using System.Windows.Forms;
using System.Runtime.InteropServices;

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();
    }

    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

備註

結構 GCHandle 會與 列舉搭配 GCHandleType 使用，以建立對應至任何 Managed 物件的句柄。 這個句柄可以是四種類型之一： Weak、 WeakTrackResurrection、 Normal或 Pinned。 配置句柄時，您可以使用它來防止垃圾收集行程收集 Managed 物件，而 Unmanaged 用戶端保留唯一的參考。 如果沒有這類句柄，垃圾收集行程可以先收集物件，再代表 Unmanaged 用戶端完成其工作。

您也可以使用 GCHandle 建立固定的物件，以傳回記憶體位址，以防止垃圾收集行程將物件移到記憶體中。

當句柄超出範圍時，您必須藉由呼叫 Free 方法來明確釋放它，否則可能會發生記憶體流失。 當您釋放釘選的句柄時，相關聯的物件將會取消釘選，而且如果沒有任何其他參考，就會成為垃圾收集的資格。

屬性

IsAllocated	取得值，指出控制代碼是否已配置。
Target	取得或設定這個控制代碼表示的物件。

方法

AddrOfPinnedObject()	擷取 Pinned 控制代碼中物件資料的位址。
Alloc(Object)	配置 Normal 控制代碼給指定的物件。
Alloc(Object, GCHandleType)	配置指定類型的控制代碼給指定的物件。
Equals(GCHandle)	指出目前的實例是否等於相同類型的另一個實例。
Equals(Object)	判斷指定的 GCHandle 物件是否等於目前的 GCHandle 物件。
Free()	釋放 GCHandle。
FromIntPtr(IntPtr)	傳回新的 GCHandle 物件，而此物件是從 Managed 物件的控制代碼所建立。
GetHashCode()	傳回目前 GCHandle 物件的識別項。
ToIntPtr(GCHandle)	傳回 GCHandle 物件的內部整數表示。

運算子

Equality(GCHandle, GCHandle)	傳回值，這個值表示兩個 GCHandle 物件是否相等。
Explicit(GCHandle to IntPtr)	GCHandle 是使用內部整數表示來儲存。
Explicit(IntPtr to GCHandle)	GCHandle 是使用內部整數表示來儲存。
Inequality(GCHandle, GCHandle)	傳回值，指出兩個 GCHandle 物件是否不相等。

另請參閱

• GCHandleType