This documentation is archived and is not being maintained.

Marshal.StructureToPtr Method

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

[Visual Basic]
Public Shared Sub StructureToPtr( _
   ByVal structure As Object, _
   ByVal ptr As IntPtr, _
   ByVal fDeleteOld As Boolean _
)
[C#]
public static void StructureToPtr(
 object structure,
 IntPtr ptr,
 bool fDeleteOld
);
[C++]
public: static void StructureToPtr(
 Object* structure,
 IntPtr ptr,
 bool fDeleteOld
);
[JScript]
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.

Remarks

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

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

Example

[Visual Basic, C#] As the following example demonstrates, StructureToPtr is useful for swapping one structure with another in the same memory location.

[Visual Basic] 
Dim IntPtr addressOfStructure1 As IntPtr = ...
Dim structure2 As TYPEATTR = ...
Marshal.StructureToPtr(structure2, addressOfStructure1, True)
[C#] 
IntPtr addressOfStructure1 = ...;
TYPEATTR structure2 = ...;
Marshal.StructureToPtr(structure2, addressOfStructure1, true);

[C++, JScript] No example is available for C++ or JScript. To view a Visual Basic or C# example, click the Language Filter button Language Filter in the upper-left corner of the page.

Requirements

Platforms: Windows 98, Windows NT 4.0, Windows Millennium Edition, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 family, .NET Compact Framework

.NET Framework Security: 

See Also

Marshal Class | Marshal Members | System.Runtime.InteropServices Namespace | DestroyStructure | GCHandle

Show: