Marshal.StructureToPtr Método

Definição

Sobrecargas

StructureToPtr(Object, IntPtr, Boolean)

Realizar o marshaling de dados de um objeto gerenciado para um bloco não gerenciado de memória.Marshals data from a managed object to an unmanaged block of memory.

StructureToPtr<T>(T, IntPtr, Boolean)

[Suporte somente no .NET Framework 4.5.1 e versões posteriores][Supported in the .NET Framework 4.5.1 and later versions]

Realiza marshaling de dados de um objeto gerenciado de um tipo especificado para um bloco de memória não gerenciado.Marshals data from a managed object of a specified type to an unmanaged block of memory.

StructureToPtr(Object, IntPtr, Boolean)

Aviso

Esta API agora é obsoleta.

Realizar o marshaling de dados de um objeto gerenciado para um bloco não gerenciado de memória.Marshals data from a managed object to an unmanaged block of memory.

public:
 static void StructureToPtr(System::Object ^ structure, IntPtr ptr, bool fDeleteOld);
[System.Runtime.InteropServices.ComVisible(true)]
[System.Obsolete("StructureToPtr(Object, IntPtr, Boolean) may be unavailable in future releases. Instead, use StructureToPtr<T>(T, IntPtr, Boolean). For more info, go to https://go.microsoft.com/fwlink/?LinkID=296516")]
[System.Security.SecurityCritical]
public static void StructureToPtr (object structure, IntPtr ptr, bool fDeleteOld);
static member StructureToPtr : obj * nativeint * bool -> unit
Public Shared Sub StructureToPtr (structure As Object, ptr As IntPtr, fDeleteOld As Boolean)

Parâmetros

structure
Object

Um objeto gerenciado que mantém os dados que terão o marshaling realizado.A managed object that holds the data to be marshaled. Este objeto deve ser uma estrutura ou uma instância de uma classe formatada.This object must be a structure or an instance of a formatted class.

ptr
IntPtr

Um ponteiro para um bloco não gerenciado de memória, que deve ser alocado antes que este método seja chamado.A pointer to an unmanaged block of memory, which must be allocated before this method is called.

fDeleteOld
Boolean

true para chamar o método DestroyStructure(IntPtr, Type) no parâmetro ptr antes de esse método copiar os dados.true to call the DestroyStructure(IntPtr, Type) method on the ptr parameter before this method copies the data. O bloco deve conter dados válidos.The block must contain valid data. Observe que passar false quando o bloco de memória já contém dados pode levar a um vazamento de memória.Note that passing false when the memory block already contains data can lead to a memory leak.

Atributos

Exceções

structure é um tipo de referência que não é uma classe formatada.structure is a reference type that is not a formatted class.

- ou --or- structure é uma instância de um tipo genérico (somente no .NET Framework 4.5 e versões anteriores).structure is an instance of a generic type (in the .NET Framework 4.5 and earlier versions only).

Exemplos

O exemplo a seguir cria uma estrutura gerenciada, transfere-a para a memória não gerenciada usando o método StructureToPtr e, em seguida, a transfere de volta para a memória gerenciada usando o método PtrToStructure.The following example creates a managed structure, transfers it to unmanaged memory using the StructureToPtr method, and then transfers it back to managed memory using the PtrToStructure method.

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.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


Comentários

Se structure for um tipo de valor, ele poderá ser Boxed ou unboxed.If structure is a value type, it can be boxed or unboxed. Se ele estiver em caixa, ele será desemoldurado antes da cópia.If it is boxed, it is unboxed before copying.

Uma classe formatada é um tipo de referência cujo layout é especificado pelo atributo StructLayoutAttribute, como LayoutKind.Explicit ou LayoutKind.Sequential.A formatted class is a reference type whose layout is specified by the StructLayoutAttribute attribute, as either LayoutKind.Explicit or LayoutKind.Sequential.

StructureToPtr copia o conteúdo de structure para o bloco pré-alocado de memória ao qual o parâmetro ptr aponta.StructureToPtr copies the contents of structure to the pre-allocated block of memory that the ptr parameter points to. Se structure contiver tipos de referência que realizam marshaling em ponteiros de interface COM (interfaces, classes sem layout e System.Object), os objetos gerenciados são mantidos ativos com contagens de referência.If structure contains reference types that marshal to COM interface pointers (interfaces, classes without layout, and System.Object), the managed objects are kept alive with reference counts. Todos os outros tipos de referência (por exemplo, cadeias de caracteres e matrizes) são empacotados para cópias.All other reference types (for example, strings and arrays) are marshaled to copies. Para liberar esses objetos gerenciados ou não gerenciados, você deve chamar o método Marshal.DestroyStructure antes de liberar o bloco de memória.To release these managed or unmanaged objects, you must call the Marshal.DestroyStructure method before you free the memory block.

Se você usar o método StructureToPtr para copiar uma instância diferente para o bloco de memória posteriormente, especifique true para fDeleteOld remover contagens de referência para tipos de referência na instância anterior.If you use the StructureToPtr method to copy a different instance to the memory block at a later time, specify true for fDeleteOld to remove reference counts for reference types in the previous instance. Caso contrário, os tipos de referência gerenciada e as cópias não gerenciadas serão efetivamente vazadas.Otherwise, the managed reference types and unmanaged copies are effectively leaked.

O padrão geral para usar StructureToPtr é o seguinte:The overall pattern for using StructureToPtr is as follows:

  1. Na primeira chamada para o método StructureToPtr após a alocação de um bloco de memória, fDeleteOld deve ser false, porque não há nenhum conteúdo para limpar.On the first call to the StructureToPtr method after a memory block has been allocated, fDeleteOld must be false, because there are no contents to clear.

    Importante

    Especifique true para fDeleteOld somente se o bloco contiver dados válidos.Specify true for fDeleteOld only if the block contains valid data.

  2. Se você copiar uma instância diferente para o bloco de memória e o objeto contiver tipos de referência, fDeleteOld deverá ser true para liberar tipos de referência no conteúdo antigo.If you copy a different instance to the memory block, and the object contains reference types, fDeleteOld must be true to free reference types in the old contents.

  3. Se o objeto contiver tipos de referência, você deverá chamar o método DestroyStructure antes de liberar o bloco de memória.If the object contains reference types, you must call the DestroyStructure method before you free the memory block.

Observação

Para fixar uma estrutura existente em vez de copiá-la, use o tipo de System.Runtime.InteropServices.GCHandle para criar um identificador fixado para a estrutura.To pin an existing structure instead of copying it, use the System.Runtime.InteropServices.GCHandle type to create a pinned handle for the structure. Para obter detalhes sobre como fixar, consulte copiando e fixando.For details on how to pin, see Copying and Pinning.

Segurança

SecurityCriticalAttribute
requer confiança total para o chamador imediato.requires full trust for the immediate caller. Este membro não pode ser usado pelo código transparente ou parcialmente confiável.This member cannot be used by partially trusted or transparent code.

Veja também

StructureToPtr<T>(T, IntPtr, Boolean)

[Suporte somente no .NET Framework 4.5.1 e versões posteriores][Supported in the .NET Framework 4.5.1 and later versions]

Realiza marshaling de dados de um objeto gerenciado de um tipo especificado para um bloco de memória não gerenciado.Marshals data from a managed object of a specified type to an unmanaged block of memory.

public:
generic <typename T>
 static void StructureToPtr(T structure, IntPtr ptr, bool fDeleteOld);
[System.Security.SecurityCritical]
public static void StructureToPtr<T> (T structure, IntPtr ptr, bool fDeleteOld);
static member StructureToPtr : 'T * nativeint * bool -> unit
Public Shared Sub StructureToPtr(Of T) (structure As T, ptr As IntPtr, fDeleteOld As Boolean)

Parâmetros de tipo

T

O tipo do objeto gerenciado.The type of the managed object.

Parâmetros

structure
T

Um objeto gerenciado que mantém os dados que terão o marshaling realizado.A managed object that holds the data to be marshaled. O objeto deve ser uma estrutura ou uma instância de uma classe formatada.The object must be a structure or an instance of a formatted class.

ptr
IntPtr

Um ponteiro para um bloco não gerenciado de memória, que deve ser alocado antes que este método seja chamado.A pointer to an unmanaged block of memory, which must be allocated before this method is called.

fDeleteOld
Boolean

true para chamar o método DestroyStructure<T>(IntPtr) no parâmetro ptr antes de esse método copiar os dados.true to call the DestroyStructure<T>(IntPtr) method on the ptr parameter before this method copies the data. O bloco deve conter dados válidos.The block must contain valid data. Observe que passar false quando o bloco de memória já contém dados pode levar a um vazamento de memória.Note that passing false when the memory block already contains data can lead to a memory leak.

Atributos

Exceções

structure é um tipo de referência que não é uma classe formatada.structure is a reference type that is not a formatted class.

Comentários

Uma classe formatada é um tipo de referência cujo layout é especificado pelo atributo StructLayoutAttribute, como LayoutKind.Explicit ou LayoutKind.Sequential.A formatted class is a reference type whose layout is specified by the StructLayoutAttribute attribute, as either LayoutKind.Explicit or LayoutKind.Sequential.

StructureToPtr<T>(T, IntPtr, Boolean) copia o conteúdo de structure para o bloco pré-alocado de memória ao qual o parâmetro ptr aponta.StructureToPtr<T>(T, IntPtr, Boolean) copies the contents of structure to the pre-allocated block of memory that the ptr parameter points to. Se structure contiver tipos de referência que realizam marshaling em ponteiros de interface COM (interfaces, classes sem layout e System.Object), os objetos gerenciados são mantidos ativos com contagens de referência.If structure contains reference types that marshal to COM interface pointers (interfaces, classes without layout, and System.Object), the managed objects are kept alive with reference counts. Todos os outros tipos de referência (por exemplo, cadeias de caracteres e matrizes) são empacotados para cópias.All other reference types (for example, strings and arrays) are marshaled to copies. Para liberar esses objetos gerenciados ou não gerenciados, você deve chamar o método DestroyStructure<T>(IntPtr) antes de liberar o bloco de memória.To release these managed or unmanaged objects, you must call the DestroyStructure<T>(IntPtr) method before you free the memory block.

Se você usar o método StructureToPtr<T>(T, IntPtr, Boolean) para copiar uma instância diferente para o bloco de memória posteriormente, especifique true para fDeleteOld remover contagens de referência para tipos de referência na instância anterior.If you use the StructureToPtr<T>(T, IntPtr, Boolean) method to copy a different instance to the memory block at a later time, specify true for fDeleteOld to remove reference counts for reference types in the previous instance. Caso contrário, os tipos de referência gerenciada e as cópias não gerenciadas serão efetivamente vazadas.Otherwise, the managed reference types and unmanaged copies are effectively leaked.

O padrão geral para usar StructureToPtr<T>(T, IntPtr, Boolean) é o seguinte:The overall pattern for using StructureToPtr<T>(T, IntPtr, Boolean) is as follows:

  1. Na primeira chamada para o método StructureToPtr após a alocação de um bloco de memória, fDeleteOld deve ser false, porque não há nenhum conteúdo para limpar.On the first call to the StructureToPtr method after a memory block has been allocated, fDeleteOld must be false, because there are no contents to clear.

    Importante

    Especifique true para fDeleteOld somente se o bloco contiver dados válidos.Specify true for fDeleteOld only if the block contains valid data.

  2. Se você copiar uma instância diferente para o bloco de memória e o objeto contiver tipos de referência, fDeleteOld deverá ser true para liberar tipos de referência no conteúdo antigo.If you copy a different instance to the memory block, and the object contains reference types, fDeleteOld must be true to free reference types in the old contents.

  3. Se o objeto contiver tipos de referência, você deverá chamar o método DestroyStructure antes de liberar o bloco de memória.If the object contains reference types, you must call the DestroyStructure method before you free the memory block.

Observação

Para fixar uma estrutura existente em vez de copiá-la, use o tipo de System.Runtime.InteropServices.GCHandle para criar um identificador fixado para a estrutura.To pin an existing structure instead of copying it, use the System.Runtime.InteropServices.GCHandle type to create a pinned handle for the structure. Para obter detalhes sobre como fixar, consulte copiando e fixando.For details on how to pin, see Copying and Pinning.

Segurança

SecurityCriticalAttribute
requer confiança total para o chamador imediato.requires full trust for the immediate caller. Este membro não pode ser usado pelo código transparente ou parcialmente confiável.This member cannot be used by partially trusted or transparent code.

Veja também

Aplica-se a