HandleRef 示例
该示例说明如何在非托管函数完成前防止对托管对象进行垃圾回收。 它还说明如何使用函数重载来传递 null 引用（在 Visual Basic 中为 Nothing），而不是对值类型的引用。
HandleRef 示例使用以下非托管函数（这里同时显示其原始函数声明）：
从 Kernel32.dll 导出的 ReadFile。
BOOL ReadFile( HANDLE hFile, LPVOID lpBuffer, DWORD nNumberOfBytesToRead, LPDWORD lpNumberOfBytesRead, LPOVERLAPPED lpOverlapped);
传递到该函数的初始结构包含以下元素：
typedef struct _OVERLAPPED {
ULONG_PTR Internal;
ULONG_PTR InternalHigh;
DWORD Offset;
DWORD OffsetHigh;
HANDLE hEvent;
} OVERLAPPED;
在该示例中，Overlapped 结构和 Overlapped2 类包含 IntPtr 类型而不是指针类型和 HANDLE 类型。 StructLayoutAttribute 特性经过设置，可确保成员在内存中按它们的出现顺序依次排列。
LibWrap 类包含 ReadFile 和 ReadFile2 方法的托管原型。 ReadFile 将 Overlapped 结构作为参数之一进行传递。 通过重载 ReadFile 方法，该示例可以在必要时传递一个 null 引用（在 Visual Basic 中为 Nothing），而不是对该结构的引用。 C# 和 Visual Basic 2005 都不允许直接传递 null 引用 (Nothing)。
ReadFile2 传递 Overlapped2 类。 默认情况下，作为引用类型的类将作为 In 参数进行传递。 将 InAttribute 和 OutAttribute 特性应用于声明会使 Overlapped2 作为 In/Out 参数进行封送处理。 该示例可以在必要时直接传递 null 引用 (Nothing)，而不是类，因为类是引用类型并且您可以在它们的位置传递 null 引用 (Nothing)。 App 类为 FileStream 创建一个 HandleRef 包装以防止在对 ReadFile 或 ReadFile2 的调用完成之前发生垃圾回收。
声明原型
' Declares a managed structure for the unmanaged structure.
<StructLayout(LayoutKind.Sequential)> _
Public Structure Overlapped
' ...
End Structure
' Declares a managed class for the unmanaged structure.
<StructLayout(LayoutKind.Sequential)> _
Public Class Overlapped2
' ...
End Class
Public Class LibWrap
' Declares a managed prototypes for unmanaged functions.
' Because Overlapped is a structure, you cannot pass Nothing as a
' parameter. Instead, declares an overloaded method.
Overloads Declare Ansi Function ReadFile Lib "Kernel32.dll" ( _
ByVal hndRef As HandleRef, _
ByVal buffer As StringBuilder, _
ByVal numberOfBytesToRead As Integer, _
ByRef numberOfBytesRead As Integer, _
ByRef flag As Overlapped) As Boolean
' Declares an int instead of a structure reference for 'flag'
Overloads Declare Ansi Function ReadFile Lib "Kernel32.dll" ( _
ByVal hndRef As HandleRef, _
ByVal buffer As StringBuilder, _
ByVal numberOfBytesToRead As Integer, _
ByRef numberOfBytesRead As Integer, _
ByVal flag As IntPtr) As Boolean
' Because Overlapped2 is a class, you can pass Nothing as a parameter.
' No overloading is needed.
Declare Ansi Function ReadFile2 Lib "Kernel32.dll" Alias "ReadFile" ( _
ByVal hndRef As HandleRef, _
ByVal buffer As StringBuilder, _
ByVal numberOfBytesToRead As Integer, _
ByRef numberOfBytesRead As Integer, _
<[In], Out> ByVal flag As Overlapped2) As Boolean
End Class
// Declares a managed structure for the unmanaged structure.
[StructLayout(LayoutKind.Sequential)]
public struct Overlapped
{
// ...
}
// Declares a managed class for the unmanaged structure.
[StructLayout(LayoutKind.Sequential)]
public class Overlapped2
{
// ...
}
public class LibWrap
{
// Declares managed prototypes for unmanaged functions.
// Because Overlapped is a structure, you cannot pass null as a
// parameter. Instead, declares an overloaded method.
[DllImport("Kernel32.dll")]
public static extern bool ReadFile(
HandleRef hndRef,
StringBuilder buffer,
int numberOfBytesToRead,
out int numberOfBytesRead,
ref Overlapped flag );
[DllImport("Kernel32.dll")]
public static extern bool ReadFile(
HandleRef hndRef,
StringBuilder buffer,
int numberOfBytesToRead,
out int numberOfBytesRead,
IntPtr flag ); // Declares an int instead of a structure reference.
// Because Overlapped2 is a class, you can pass null as parameter.
// No overloading is needed.
[DllImport("Kernel32.dll", EntryPoint="ReadFile")]
public static extern bool ReadFile2(
HandleRef hndRef,
StringBuilder buffer,
int numberOfBytesToRead,
out int numberOfBytesRead,
Overlapped2 flag);
}
// Declares a managed structure for the unmanaged structure.
[StructLayout(LayoutKind::Sequential)]
public value struct Overlapped
{
// ...
};
// Declares a managed class for the unmanaged structure.
[StructLayout(LayoutKind::Sequential)]
public ref class Overlapped2
{
// ...
};
public ref class LibWrap
{
public:
// Declares managed prototypes for unmanaged functions.
// Because Overlapped is a structure, you cannot pass null as a
// parameter. Instead, declares an overloaded method.
[DllImport("Kernel32.dll")]
static bool ReadFile(
HandleRef hndRef,
StringBuilder^ buffer,
int numberOfBytesToRead,
int numberOfBytesRead,
Overlapped% flag );
[DllImport("Kernel32.dll")]
static bool ReadFile(
HandleRef hndRef,
StringBuilder^ buffer,
int numberOfBytesToRead,
int% numberOfBytesRead,
IntPtr flag ); // Declares an int instead of a structure reference.
// Because Overlapped2 is a class, you can pass null as parameter.
// No overloading is needed.
[DllImport("Kernel32.dll", EntryPoint="ReadFile")]
static bool ReadFile2(
HandleRef hndRef,
StringBuilder^ buffer,
int numberOfBytesToRead,
int% numberOfBytesRead,
Overlapped2^ flag);
};
调用函数
Public Class App
Public Shared Sub Main()
Dim fs As New FileStream("HandleRef.txt", FileMode.Open)
' Wraps the FileStream handle in HandleRef to prevent it
' from being garbage collected before the call ends.
Dim hr As New HandleRef(fs, fs.SafeFileHandle.DangerousGetHandle())
Dim buffer As New StringBuilder(5)
Dim read As Integer = 0
' Platform invoke holds the reference to HandleRef until the
' call ends.
LibWrap.ReadFile(hr, buffer, 5, read, IntPtr.Zero)
Console.WriteLine("Read {0} bytes with struct parameter: {1}", read, buffer)
LibWrap.ReadFile2(hr, buffer, 5, read, Nothing)
Console.WriteLine("Read {0} bytes with class parameter: {1}", read, buffer)
End Sub
End Class
public class App
{
public static void Main()
{
FileStream fs = new FileStream("HandleRef.txt", FileMode.Open);
// Wraps the FileStream handle in HandleRef to prevent it
// from being garbage collected before the call ends.
HandleRef hr = new HandleRef(fs, fs.SafeFileHandle.DangerousGetHandle());
StringBuilder buffer = new StringBuilder(5);
int read = 0;
// Platform invoke holds a reference to HandleRef until the call
// ends.
LibWrap.ReadFile(hr, buffer, 5, out read, IntPtr.Zero);
Console.WriteLine("Read {0} bytes with struct parameter: {1}", read, buffer);
LibWrap.ReadFile2(hr, buffer, 5, out read, null);
Console.WriteLine("Read {0} bytes with class parameter: {1}", read, buffer);
}
}
public ref class App
{
public:
static void Main()
{
FileStream^ fs = gcnew FileStream("HandleRef.txt", FileMode::Open);
// Wraps the FileStream handle in HandleRef to prevent it
// from being garbage collected before the call ends.
HandleRef hr = HandleRef(fs, fs->SafeFileHandle->DangerousGetHandle());
StringBuilder^ buffer = gcnew StringBuilder(5);
int read = 0;
// Platform invoke holds a reference to HandleRef until the call
// ends.
LibWrap::ReadFile(hr, buffer, 5, read, IntPtr::Zero);
Console::WriteLine("Read {0} bytes with struct parameter: {1}", read, buffer);
LibWrap::ReadFile2(hr, buffer, 5, read, nullptr);
Console::WriteLine("Read {0} bytes with class parameter: {1}", read, buffer);
}
};