Marshal.StructureToPtr Method
Marshals data from a managed object to an unmanaged block of memory.
Assembly: mscorlib (in mscorlib.dll)
[ComVisibleAttribute(true)] public static void StructureToPtr( Object structure, IntPtr ptr, bool fDeleteOld )
Parameters
- structure
- Type: System.Object
A managed object holding the data to be marshaled. This object must be an instance of a formatted class.
- ptr
- Type: System.IntPtr
A pointer to an unmanaged block of memory, which must be allocated before this method is called.
- fDeleteOld
- Type: System.Boolean
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 | Condition |
|---|---|
| ArgumentException |
The structure parameter is a generic type. |
StructureToPtr copies the contents of structure to the pre-allocated block of memory that the ptr parameter points to. If the fDeleteOld parameter is true, the pre-allocated buffer is deleted with the appropriate deletion method 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 that ptr points to an unmanaged block of memory. The layout of this block is described by a corresponding managed class, which is specified by structure. StructureToPtr marshals field values from a structure to a pointer. Suppose the ptr block includes a reference field pointing to a string buffer that currently holds "abc", and the corresponding field on the managed side is a string that holds "vwxyz". If you do not specify 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 (its memory is not released back to the unmanaged heap). The result is an orphan buffer that represents a memory leak in your code. If you set the fDeleteOld parameter to true, StructureToPtr frees the buffer that holds "abc" before allocating a new buffer for "vwxyz".
Note
|
|---|
|
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. |
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); } } }
-
SecurityCriticalAttribute
requires full trust for the immediate caller. This member cannot be used by partially trusted or transparent code.
Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows XP SP2 x64 Edition, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2
The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.
