HandleRef-Struktur

Erstellt einen Wrapper für ein verwaltetes Objekt, das ein Handle auf eine Ressource enthält, die mithilfe eines Plattformaufrufs an nicht verwalteten Code übergeben wird.

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

Syntax

'Declaration
<ComVisibleAttribute(True)> _
Public Structure HandleRef
'Usage
Dim instance As HandleRef

[ComVisibleAttribute(true)] 
public struct HandleRef

[ComVisibleAttribute(true)] 
public value class HandleRef

/** @attribute ComVisibleAttribute(true) */ 
public final class HandleRef extends ValueType

JScript unterstützt die Verwendung von Strukturen, aber nicht die Deklaration von neuen Strukturen.

Hinweise

Wenn ein verwaltetes Objekt mit einem Plattformaufruf aufgerufen wird und nach dem Plattformaufruf kein Verweis auf das Objekt an anderer Stelle vorhanden ist, kann der Garbage Collector das verwaltete Objekt finalisieren. Mit diesen Vorgang wird die Ressource freigegeben und das Handle für ungültig erklärt, wodurch der Plattformaufruf fehlschlägt. Wenn Sie HandleRef als Wrapper für ein Handle verwenden, ist sichergestellt, dass das verwaltete Objekt nicht an den Garbage Collector übergeben wird, bevor der Plattformaufruf beendet ist. Eine Beschreibung von Diensten für Plattformaufrufe finden Sie unter Verwenden nicht verwalteter DLL-Funktionen.

Der HandleRef-Werttyp, beispielsweise GCHandle, ist ein spezieller Typ, der vom Interop-Marshaller erkannt wird. Auch ein normales, nicht fixiertes GCHandle verhindert die vorzeitige Erfassung durch die Garbage Collection, HandleRef bietet jedoch eine bessere Leistung. Obwohl die Verwendung von HandleRef zur Beibehaltung eines Objekts über die gesamte Dauer eines Plattformaufrufs zu bevorzugen ist, können Sie für denselben Zweck auch die GC.KeepAlive-Methode einsetzen.

Der HandleRef-Konstruktor akzeptiert zwei Parameter: ein Object, das den Wrapper darstellt, und ein IntPtr, das das nicht verwaltete Handle darstellt. Der Interop-Marshaller übergibt nur das Handle an nicht verwalteten Code und stellt sicher, dass der Wrapper (als erster Parameter an den Konstruktor von HandleRef übergeben) über die Dauer des Aufrufs aktiv bleibt.

Beispiel

Im folgenden Beispiel wird veranschaulicht, wie ein als erster Parameter übergebenes Objekt mit HandleRef als aktiv beibehalten wird. Der Interop-Marshaller übergibt lediglich das Handle an nicht verwalteten Code.

Dim fs As New FileStream("HandleRef.txt", FileMode.Open)
Dim hr As New HandleRef(fs, fs.SafeFileHandle.DangerousGetHandle())
Dim buffer As New StringBuilder(5)
Dim read As Integer = 0

' platform invoke will hold reference to HandleRef until call ends

LibWrap.ReadFile(hr, buffer, 5, read, 0)
Console.WriteLine("Read with struct parameter: {0}", buffer)

FileStream fs = new FileStream("HandleRef.txt", FileMode.Open);
HandleRef hr = new HandleRef(fs, fs.SafeFileHandle.DangerousGetHandle());
StringBuilder buffer = new StringBuilder(5);
int read = 0;

// platform invoke will hold reference to HandleRef until call ends

LibWrap.ReadFile(hr, buffer, 5, out read, 0);
Console.WriteLine("Read with struct parameter: {0}", buffer);

FileStream^ fs = gcnew FileStream( "HandleRef.txt", FileMode::Open );
HandleRef hr = HandleRef(fs,fs->Handle);
StringBuilder^ buffer = gcnew StringBuilder( 5 );
int read = 0;

// platform invoke will hold reference to HandleRef until call ends
LibWrap::ReadFile( hr, buffer, 5,  &read, 0 );
Console::WriteLine( "Read with struct parameter: {0}", buffer );

Threadsicherheit

Alle öffentlichen statischen (Shared in Visual Basic) Member dieses Typs sind threadsicher. Bei Instanzmembern ist die Threadsicherheit nicht gewährleistet.

Plattformen

Windows 98, Windows 2000 SP4, Windows Millennium Edition, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

.NET Framework unterstützt nicht alle Versionen sämtlicher Plattformen. Eine Liste der unterstützten Versionen finden Sie unter Systemanforderungen.

Versionsinformationen

.NET Framework

Unterstützt in: 2.0, 1.1, 1.0

Siehe auch

Referenz

HandleRef-Member
System.Runtime.InteropServices-Namespace
GCHandle-Struktur