Compartilhar via


Exemplo de HandleRef

Este exemplo demonstra como impedir a coleta de lixo em um objeto gerenciado antes da conclusão da função não gerenciada. Ele também demonstra como usar a função de sobrecarga para passar uma referência nula (nada em Visual Basic) em vez de uma referência a um tipo de valor.

O exemplo de HandleRef usa a seguinte função não gerenciada, mostrada com sua declaração de função original:

  • ReadFile exportados do Kernel32. dll.

    BOOL ReadFile(
       HANDLE hFile, 
       LPVOID lpBuffer, 
       DWORD nNumberOfBytesToRead, 
       LPDWORD lpNumberOfBytesRead, 
       LPOVERLAPPED lpOverlapped);
    

A estrutura original passada para a função contém os seguintes elementos:

typedef struct _OVERLAPPED { 
    ULONG_PTR  Internal; 
    ULONG_PTR  InternalHigh; 
    DWORD  Offset; 
    DWORD  OffsetHigh; 
    HANDLE hEvent; 
} OVERLAPPED; 

Neste exemplo, o Overlapped estrutura e o Overlapped2 contém a classe IntPtr tipos em vez de ponteiro e o tratar tipo. O StructLayoutAttribute atributo está definido para garantir que os membros são organizados na memória seqüencialmente, na ordem em que aparecem.

O LibWrap classe contém protótipos de gerenciado para o ReadFile e ReadFile2 métodos. ReadFilepassa a Overlapped estrutura como um dos parâmetros. Pela sobrecarga o ReadFile método, a amostra pode passar uma referência nula (nada em Visual Basic) em vez de uma referência para a estrutura, quando necessário. Nem C# nem Visual Basic 2005 Permitir passar uma referência nula (nada) diretamente.

ReadFile2passa a Overlapped2 classe. Classes, que são tipos de referência, são passadas como nos parâmetros por padrão. Aplicando o InAttribute e OutAttribute faz de atributos para a declaração Overlapped2 para ser empacotado como um parâmetro In/Out. A amostra pode passar uma referência nula (nada) diretamente, quando necessário, em vez de uma classe, porque as classes são tipos de referência e você pode passar uma referência nula (nada) em seu lugar. O App classe cria uma HandleRef wrapper para o FileStream para evitar a coleta de lixo ocorra antes chamada de ReadFile ou ReadFile2 forem concluídas.

A declaração de protótipos

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

Chamando funções

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

Consulte também

Conceitos

Diversos exemplos de empacotamento

Tipos de dados de invocação de plataforma

A criação de protótipos em código gerenciado