Compartilhar via

Método Marshal.StructureToPtr (Object, IntPtr, Boolean)

  • Artigo

 

Observação

The .NET API Reference documentation has a new home. Visit the .NET API Browser on docs.microsoft.com to see the new experience.

Realizar o marshaling de dados de um objeto gerenciado para um bloco não gerenciado de memória.

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

Sintaxe

[SecurityCriticalAttribute]
[ComVisibleAttribute(true)]
public static void StructureToPtr(
    object structure,
    IntPtr ptr,
    bool fDeleteOld
)

public:
[SecurityCriticalAttribute]
[ComVisibleAttribute(true)]
static void StructureToPtr(
    Object^ structure,
    IntPtr ptr,
    bool fDeleteOld
)

[<SecurityCriticalAttribute>]
[<ComVisibleAttribute(true)>]
static member StructureToPtr : 
        structure:Object *
        ptr:nativeint *
        fDeleteOld:bool -> unit

<SecurityCriticalAttribute>
<ComVisibleAttribute(True)>
Public Shared Sub StructureToPtr (
    structure As Object,
    ptr As IntPtr,
    fDeleteOld As Boolean
)

Parâmetros

  • structure
    Type: System.Object

    Um objeto gerenciado que mantém os dados que terão o marshaling realizado. Este objeto deve ser uma estrutura ou uma instância de uma classe formatada.

  • ptr
    Type: System.IntPtr

    Um ponteiro para um bloco não gerenciado de memória, que deve ser alocado antes que este método seja chamado.

  • fDeleteOld
    Type: System.Boolean

    true para chamar o método Marshal.DestroyStructure no parâmetro ptr antes de esse método copiar os dados. O bloco deve conter dados válidos. Observe que passar false quando o bloco de memória já contém dados pode levar a um vazamento de memória.

Exceções

Exception Condition
ArgumentException

structure é um tipo de referência que não é uma classe formatada.

-ou-

structure é um tipo genérico.

Comentários

Se structure é um tipo de valor pode ser demarcado ou desencaixotado. Se ele é convertido, é não demarcado antes de copiar.

Uma classe formatada é um tipo de referência cujo layout é especificado pelo StructLayoutAttribute atributo, como LayoutKind.Explicit ou LayoutKind.Sequential.

StructureToPtrCopia o conteúdo de structure para o bloco pré-alocados de memória que o ptr parâmetro aponta para. Se structure contém tipos de referência que realizar marshaling de ponteiros de interface COM (interfaces, classes sem layout, e System.Object), os objetos gerenciados são mantidos ativas com contagens de referência. Todos os outros tipos de referência (por exemplo, cadeias de caracteres e matrizes) são empacotados para cópias. Para liberar esses objetos gerenciados ou não gerenciados, você deve chamar o Marshal.DestroyStructuremétodo antes de liberar o bloco de memória.

Se você usar o StructureToPtr método para copiar uma instância diferente para o bloco de memória em um momento posterior, especifique true para fDeleteOld remover a referência de conta para tipos de referência na instância anterior. Caso contrário, as cópias de typesand não gerenciado de referência gerenciada efetivamente seja perdidas.

O padrão geral para usar StructureToPtr é o seguinte:

  1. Na primeira chamada para o StructureToPtrmétodo depois que um bloco de memória foi alocado, fDeleteOlddevem serfalse, pois não há nenhum conteúdo para limpar.

    Importante

    Especifique true para fDeleteOld somente se o bloco contém dados válidos.

  2. Se você copiar uma instância diferente para o bloco de memória e o objeto contém os tipos de referência, fDeleteOld devem ser true para liberar os tipos de referência no conteúdo antigo.

  3. Se o objeto contiver tipos de referência, você deve chamar o DestroyStructure método antes de liberar o bloco de memória.

Observação

Para fixar uma estrutura existente em vez de copiá-lo, use o System.Runtime.InteropServices.GCHandle tipo para criar um identificador fixo para a estrutura. Para obter detalhes sobre como fixar, consulte Copiando e fixando.

Exemplos

O exemplo a seguir cria uma estrutura gerenciada, transfere-a memória não gerenciada usando o StructureToPtr método e, em seguida, transfere-o novamente para memória gerenciada usando o PtrToStructure método.

using System;
using System.Runtime.InteropServices;

public struct Point
{
    public int x;
    public int y;
}

class Example
{

    static void Main()
    {

        // Create a point struct.
        Point p;
        p.x = 1;
        p.y = 1;

        Console.WriteLine("The value of first point is " + p.x + " and " + p.y + ".");

        // Initialize unmanged memory to hold the struct.
        IntPtr pnt = Marshal.AllocHGlobal(Marshal.SizeOf(p));

        try
        {

            // Copy the struct to unmanaged memory.
            Marshal.StructureToPtr(p, pnt, false);

            // Create another point.
            Point anotherP;

            // Set this Point to the value of the 
            // Point in unmanaged memory. 
            anotherP = (Point)Marshal.PtrToStructure(pnt, typeof(Point));

            Console.WriteLine("The value of new point is " + anotherP.x + " and " + anotherP.y + ".");

        }
        finally
        {
            // Free the unmanaged memory.
            Marshal.FreeHGlobal(pnt);
        }



    }

}

Imports System
Imports System.Runtime.InteropServices



Public Structure Point
    Public x As Integer
    Public y As Integer
End Structure


Module Example


    Sub Main()

        ' Create a point struct.
        Dim p As Point
        p.x = 1
        p.y = 1

        Console.WriteLine("The value of first point is " + p.x.ToString + " and " + p.y.ToString + ".")

        ' Initialize unmanged memory to hold the struct.
        Dim pnt As IntPtr = Marshal.AllocHGlobal(Marshal.SizeOf(p))

        Try

            ' Copy the struct to unmanaged memory.
            Marshal.StructureToPtr(p, pnt, False)

            ' Create another point.
            Dim anotherP As Point

            ' Set this Point to the value of the 
            ' Point in unmanaged memory. 
            anotherP = CType(Marshal.PtrToStructure(pnt, GetType(Point)), Point)

            Console.WriteLine("The value of new point is " + anotherP.x.ToString + " and " + anotherP.y.ToString + ".")

        Finally
            ' Free the unmanaged memory.
            Marshal.FreeHGlobal(pnt)
        End Try

    End Sub
End Module

Segurança

SecurityCriticalAttribute

requires full trust for the immediate caller. This member cannot be used by partially trusted or transparent code.

Informações de Versão

Plataforma Universal do Windows
Disponível desde 8
.NET Framework
Disponível desde 1.1
Biblioteca de Classes Portátil
Com suporte no: plataformas portáteis do .NET
Silverlight
Disponível desde 2.0
Windows Phone Silverlight
Disponível desde 7.0
Windows Phone
Disponível desde 8.1

Confira Também

DestroyStructure
GCHandle
StructureToPtr Sobrecarga
Classe Marshal
Namespace System.Runtime.InteropServices

Retornar ao início