Export (0) Print
Expand All
Expand Minimize

Marshal.StructureToPtr Method

Marshals data from a managed object to an unmanaged block of memory.

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

[ComVisibleAttribute(true)] 
public static void StructureToPtr (
	Object structure,
	IntPtr ptr,
	bool fDeleteOld
)
/** @attribute ComVisibleAttribute(true) */ 
public static void StructureToPtr (
	Object structure, 
	IntPtr ptr, 
	boolean fDeleteOld
)
ComVisibleAttribute(true) 
public static function StructureToPtr (
	structure : Object, 
	ptr : IntPtr, 
	fDeleteOld : boolean
)

Parameters

structure

A managed object holding the data to be marshaled. This object must be an instance of a formatted class.

ptr

A pointer to an unmanaged block of memory, which must be allocated before this method is called.

fDeleteOld

true to have the Marshal.DestroyStructure method called on the ptr parameter before this method executes. Note that passing false can lead to a memory leak.

Exception typeCondition

ArgumentException

The structure parameter is a generic type.

StructureToPtr copies the contents of structure to the pre-allocated block of memory pointed to by the ptr parameter. If the fDeleteOld parameter is true, the buffer originally pointed to by ptr is deleted with the appropriate delete API on the embedded pointer, but the buffer must contain valid data. This method cleans up every reference field specified in the mirrored managed class.

Suppose your unmanaged block of memory is pointed to by ptr. The layout of this block is described by a corresponding managed class, structure. StructureToPtr marshals field values from a structure to a pointer. Suppose the ptr block includes a reference field, pointing to a string buffer currently holding "abc". Suppose the corresponding field on the managed side is a string holding "vwxyz". If you do not tell it otherwise, StructureToPtr allocates a new unmanaged buffer to hold "vwxyz", and hooks it up to the ptr block. This action casts the old buffer "abc" adrift without freeing it back to the unmanaged heap. You end up with an orphan buffer that represents a memory leak in your code. If you set the fDeleteOld parameter true, StructureToPtr frees the buffer holding "abc" before going on to allocate a new buffer for "vwxyz".

NoteNote

To pin an existing structure, instead of copying it, use the System.Runtime.InteropServices.GCHandle type to create a pinned handle for the structure. For details on how to pin, see Copying and Pinning.

NoteNote

This method uses SecurityAction.LinkDemand to prevent it from being called from untrusted code; only the immediate caller is required to have SecurityPermissionAttribute.UnmanagedCode permission. If your code can be called from partially trusted code, do not pass user input to Marshal class methods without validation. For important limitations on using the LinkDemand member, see Demand vs. LinkDemand.

The following code 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);
        }
        


    }

}

Windows 98, Windows 2000 SP4, Windows CE, Windows Millennium Edition, Windows Mobile for Pocket PC, Windows Mobile for Smartphone, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see System Requirements.

.NET Framework

Supported in: 2.0, 1.1, 1.0

.NET Compact Framework

Supported in: 2.0, 1.0

Community Additions

ADD
Show:
© 2014 Microsoft