Marshal.PtrToStructure Method

Definition

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

Overloads

PtrToStructure(IntPtr, Object)
Obsolete.

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

PtrToStructure(IntPtr, Type)
Obsolete.

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

PtrToStructure<T>(IntPtr)

Marshals data from an unmanaged block of memory to a newly allocated managed object of the type specified by a generic type parameter.

PtrToStructure<T>(IntPtr, T)

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

PtrToStructure(IntPtr, Object)

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

Caution

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

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

[System.Obsolete("PtrToStructure(IntPtr, Object) may be unavailable in future releases. Instead, use PtrToStructure<T>(IntPtr). For more info, go to http://go.microsoft.com/fwlink/?LinkID=296512")]
[System.Security.SecurityCritical]
public static void PtrToStructure (IntPtr ptr, object structure);
public static void PtrToStructure (IntPtr ptr, object structure);
[System.Security.SecurityCritical]
public static void PtrToStructure (IntPtr ptr, object structure);
[System.Runtime.InteropServices.ComVisible(true)]
public static void PtrToStructure (IntPtr ptr, object structure);
[System.Security.SecurityCritical]
[System.Runtime.InteropServices.ComVisible(true)]
public static void PtrToStructure (IntPtr ptr, object structure);

Parameters

ptr
IntPtr

A pointer to an unmanaged block of memory.

structure
Object

The object to which the data is to be copied. This must be an instance of a formatted class.

Attributes

Exceptions

Structure layout is not sequential or explicit.

-or-

Structure is a boxed value type.

Remarks

PtrToStructure is often necessary in COM interop and platform invoke when structure parameters are represented as an System.IntPtr value. You cannot use this overload method with value types. If the ptr parameter equals IntPtr.Zero, null will be returned.

Applies to

.NET 9 and other versions
Product Versions (Obsolete)
.NET Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9 (Core 1.0)
.NET Framework 1.1, 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.1, 2.0, 2.1 (1.2, 1.3, 1.4, 1.5, 1.6)
UWP (10.0)

PtrToStructure(IntPtr, Type)

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

Caution

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

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

[System.Obsolete("PtrToStructure(IntPtr, Type) may be unavailable in future releases. Instead, use PtrToStructure<T>(IntPtr). For more info, go to http://go.microsoft.com/fwlink/?LinkID=296513")]
[System.Security.SecurityCritical]
public static object PtrToStructure (IntPtr ptr, Type structureType);
public static object? PtrToStructure (IntPtr ptr, Type structureType);
[System.Security.SecurityCritical]
public static object PtrToStructure (IntPtr ptr, Type structureType);
public static object PtrToStructure (IntPtr ptr, Type structureType);
[System.Runtime.InteropServices.ComVisible(true)]
public static object PtrToStructure (IntPtr ptr, Type structureType);
[System.Security.SecurityCritical]
[System.Runtime.InteropServices.ComVisible(true)]
public static object PtrToStructure (IntPtr ptr, Type structureType);

Parameters

ptr
IntPtr

A pointer to an unmanaged block of memory.

structureType
Type

The type of object to be created. This object must represent a formatted class or a structure.

Returns

A managed object containing the data pointed to by the ptr parameter.

Attributes

Exceptions

The structureType parameter layout is not sequential or explicit.

-or-

The structureType parameter is a generic type definition.

structureType is null.

The class specified by structureType does not have an accessible parameterless constructor.

Examples

The following example creates a managed structure, transfers it to unmanaged memory, 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);
        }
    }
}

The following example demonstrates how to marshal an unmanaged block of memory to a managed structure using the PtrToStructure method.

Important

This code assumes 32-bit compilation. Before using a 64-bit compiler, replace IntPtr.ToInt32 with IntPtr.ToInt64.


        [StructLayout(LayoutKind.Sequential)]

        public class  INNER

        {

            [MarshalAs(UnmanagedType.ByValTStr, SizeConst =  10)]

            public string field1 = "Test";
        }	

        [StructLayout(LayoutKind.Sequential)]

        public struct OUTER

        {

            [MarshalAs(UnmanagedType.ByValTStr, SizeConst =  10)]

            public string field1;

            [MarshalAs(UnmanagedType.ByValArray, SizeConst =  100)]

            public byte[] inner;
        }
        [DllImport(@"SomeTestDLL.dll")]

        public static extern void CallTest( ref OUTER po);
        static void Main(string[] args)

        {

            OUTER ed = new OUTER();

            INNER[] inn=new INNER[10];

            INNER test = new INNER();

            int iStructSize = Marshal.SizeOf(test);
            int sz =inn.Length * iStructSize;

            ed.inner = new byte[sz];
            try

            {

                CallTest( ref ed);
            }

            catch(Exception e)

            {

                Console.WriteLine(e.Message);
            }

            IntPtr buffer = Marshal.AllocCoTaskMem(iStructSize*10);

            Marshal.Copy(ed.inner,0,buffer,iStructSize*10);
            int iCurOffset = 0;

            for(int i=0;i<10;i++)

            {
                inn[i] = (INNER)Marshal.PtrToStructure(new
IntPtr(buffer.ToInt32()+iCurOffset),typeof(INNER) );

                iCurOffset += iStructSize;
            }

            Console.WriteLine(ed.field1);

            Marshal.FreeCoTaskMem(buffer);
        }

Remarks

PtrToStructure is often necessary in COM interop and platform invoke when structure parameters are represented as an System.IntPtr value. You can pass a value type to this overload method. In this case, the returned object is a boxed instance. If the ptr parameter equals IntPtr.Zero, null will be returned.

See also

Applies to

.NET 9 and other versions
Product Versions (Obsolete)
.NET Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9 (Core 1.0)
.NET Framework 1.1, 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.1, 2.0, 2.1 (1.2, 1.3, 1.4, 1.5, 1.6)
UWP (10.0)

PtrToStructure<T>(IntPtr)

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

Marshals data from an unmanaged block of memory to a newly allocated managed object of the type specified by a generic type parameter.

[System.Security.SecurityCritical]
public static T PtrToStructure<T> (IntPtr ptr);
public static T? PtrToStructure<T> (IntPtr ptr);
public static T PtrToStructure<T> (IntPtr ptr);

Type Parameters

T

The type of the object to which the data is to be copied. This must be a formatted class or a structure.

Parameters

ptr
IntPtr

A pointer to an unmanaged block of memory.

Returns

T

A managed object that contains the data that the ptr parameter points to.

Attributes

Exceptions

The layout of T is not sequential or explicit.

The class specified by T does not have an accessible parameterless constructor.

Remarks

PtrToStructure<T>(IntPtr) is often necessary in COM interop and platform invoke when structure parameters are represented as System.IntPtr values. You can pass a value type to this method overload. If the ptr parameter equals IntPtr.Zero and T is a reference type, null is returned. If ptr equals IntPtr.Zero and T is a value type, a NullReferenceException is thrown.

Applies to

.NET 9 and other versions
Product Versions
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.2, 1.3, 1.4, 1.5, 1.6, 2.0, 2.1
UWP 10.0

PtrToStructure<T>(IntPtr, T)

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

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

[System.Security.SecurityCritical]
public static void PtrToStructure<T> (IntPtr ptr, T structure);
public static void PtrToStructure<T> (IntPtr ptr, T structure);

Type Parameters

T

The type of structure. This must be a formatted class.

Parameters

ptr
IntPtr

A pointer to an unmanaged block of memory.

structure
T

The object to which the data is to be copied.

Attributes

Exceptions

Structure layout is not sequential or explicit.

Remarks

PtrToStructure<T>(IntPtr, T) is often necessary in COM interop and platform invoke when structure parameters are represented as IntPtr values. You cannot use this method overload with value types. If the ptr parameter equals IntPtr.Zero and T is a reference type, null is returned. If ptr equals IntPtr.Zero and T is a value type, a NullReferenceException is thrown.

Applies to

.NET 9 and other versions
Product Versions
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.2, 1.3, 1.4, 1.5, 1.6, 2.0, 2.1
UWP 10.0