Edit

Share via

Marshal.StructureToPtr Method

Definition

Namespace:
System.Runtime.InteropServices
Assemblies:
mscorlib.dll, System.Runtime.InteropServices.dll
Assemblies:
netstandard.dll, System.Runtime.InteropServices.dll
Assembly:
System.Runtime.InteropServices.dll
Assembly:
mscorlib.dll
Assembly:
netstandard.dll

Overloads

StructureToPtr(Object, IntPtr, Boolean)
Obsolete.

Marshals data from a managed object to an unmanaged block of memory.
StructureToPtr<T>(T, IntPtr, Boolean)

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

StructureToPtr(Object, IntPtr, Boolean)

Source:
Marshal.CoreCLR.cs
Source:
Marshal.cs
Source:
Marshal.cs
Source:
Marshal.CoreCLR.cs

Caution

StructureToPtr(Object, IntPtr, Boolean) may be unavailable in future releases. Instead, use StructureToPtr<T>(T, IntPtr, Boolean). For more info, go to http://go.microsoft.com/fwlink/?LinkID=296516

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

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

Parameters

structure
Object

A managed object that holds the data to be marshaled. This object must be a structure or an instance of a formatted class.

ptr
IntPtr

nativeint

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

fDeleteOld
Boolean

true to call the DestroyStructure(IntPtr, Type) method on the ptr parameter before this method copies the data. The block must contain valid data. Note that passing false when the memory block already contains data can lead to a memory leak.

Attributes
ObsoleteAttribute SecurityCriticalAttribute RequiresDynamicCodeAttribute ComVisibleAttribute

Exceptions

ArgumentException

structure is a reference type that is not a formatted class.

-or-

structure is an instance of a generic type (in the .NET Framework 4.5 and earlier versions only).

Remarks

If structure is a value type, it can be boxed or unboxed. If it is boxed, it is unboxed before copying.

A formatted class is a reference type whose layout is specified by the StructLayoutAttribute attribute, as either LayoutKind.Explicit or LayoutKind.Sequential.

StructureToPtr copies the contents of structure to the pre-allocated block of memory that the ptr parameter points to. 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. All other reference types (for example, strings and arrays) are marshaled to copies. To release these managed or unmanaged objects, you must call the Marshal.DestroyStructure method before you free the memory block.

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. Otherwise, the managed reference types and unmanaged copies are effectively leaked.

The overall pattern for using StructureToPtr is as follows:

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

    Important

    Specify true for fDeleteOld only if the block contains valid data.

  2. 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. If the object contains reference types, you must call the DestroyStructure method before you free the memory block.

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.

See also

Applies to

StructureToPtr<T>(T, IntPtr, Boolean)

Source:
Marshal.cs
Source:
Marshal.cs
Source:
Marshal.cs
Source:
Marshal.cs

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

Type Parameters

T

The type of the managed object.

Parameters

structure
T

A managed object that holds the data to be marshaled. The object must be a structure or an instance of a formatted class.

ptr
IntPtr

nativeint

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

fDeleteOld
Boolean

true to call the DestroyStructure<T>(IntPtr) method on the ptr parameter before this method copies the data. The block must contain valid data. Note that passing false when the memory block already contains data can lead to a memory leak.

Attributes
SecurityCriticalAttribute

Exceptions

ArgumentException

structure is a reference type that is not a formatted class.

Remarks

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) copies the contents of structure to the pre-allocated block of memory that the ptr parameter points to. 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. All other reference types (for example, strings and arrays) are marshaled to copies. To release these managed or unmanaged objects, you must call the DestroyStructure<T>(IntPtr) method before you free the memory block.

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. Otherwise, the managed reference types and unmanaged copies are effectively leaked.

The overall pattern for using StructureToPtr<T>(T, IntPtr, Boolean) is as follows:

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

    Important

    Specify true for fDeleteOld only if the block contains valid data.

  2. 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. If the object contains reference types, you must call the DestroyStructure method before you free the memory block.

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.

See also

Applies to