UnmanagedMemoryStream Constructors

Definition

Namespace:

System.IO

Assembly:

System.Runtime.dll

Initializes a new instance of the UnmanagedMemoryStream class.

Overloads

UnmanagedMemoryStream()	Initializes a new instance of the UnmanagedMemoryStream class.
UnmanagedMemoryStream(Byte*, Int64)	Initializes a new instance of the UnmanagedMemoryStream class using the specified location and memory length.
UnmanagedMemoryStream(SafeBuffer, Int64, Int64)	Initializes a new instance of the UnmanagedMemoryStream class in a safe buffer with a specified offset and length.
UnmanagedMemoryStream(Byte*, Int64, Int64, FileAccess)	Initializes a new instance of the UnmanagedMemoryStream class using the specified location, memory length, total amount of memory, and file access values.
UnmanagedMemoryStream(SafeBuffer, Int64, Int64, FileAccess)	Initializes a new instance of the UnmanagedMemoryStream class in a safe buffer with a specified offset, length, and file access.

UnmanagedMemoryStream()

Source:

UnmanagedMemoryStream.cs

Initializes a new instance of the UnmanagedMemoryStream class.

protected:
 UnmanagedMemoryStream();

protected UnmanagedMemoryStream ();

Protected Sub New ()

Exceptions

SecurityException

The user does not have the required permission.

UnmanagedMemoryStream(Byte*, Int64)

Source:

UnmanagedMemoryStream.cs

Important

This API is not CLS-compliant.

Initializes a new instance of the UnmanagedMemoryStream class using the specified location and memory length.

public:
 UnmanagedMemoryStream(System::Byte* pointer, long length);

[System.CLSCompliant(false)]
public UnmanagedMemoryStream (byte* pointer, long length);

[<System.CLSCompliant(false)>]
new System.IO.UnmanagedMemoryStream : nativeptr<byte> * int64 -> System.IO.UnmanagedMemoryStream

Parameters

pointer

Byte*

A pointer to an unmanaged memory location.

length

Int64

The length of the memory to use.

Attributes

CLSCompliantAttribute

Exceptions

SecurityException

The user does not have the required permission.

ArgumentNullException

The pointer value is null.

ArgumentOutOfRangeException

The length value is less than zero.

-or-

The length is large enough to cause an overflow.

Examples

The following code example demonstrates how to read from and write to unmanaged memory using the UnmanagedMemoryStream class. A block of unmanaged memory is allocated and de-allocated using the Marshal class.

// Note: You must compile this sample using the unsafe flag.
// From the command line, type the following: csc sample.cs /unsafe
using System;
using System.IO;
using System.Runtime.InteropServices;
using System.Text;

unsafe class Program
{
    static void Main()
    {
        // Create some data to write.
        byte[] text = UnicodeEncoding.Unicode.GetBytes("Data to write.");

        // Allocate a block of unmanaged memory.
        IntPtr memIntPtr = Marshal.AllocHGlobal(text.Length);

        // Get a byte pointer from the unmanaged memory block.
        byte* memBytePtr = (byte*)memIntPtr.ToPointer();

        UnmanagedMemoryStream writeStream =
            new UnmanagedMemoryStream(
            memBytePtr, text.Length, text.Length, FileAccess.Write);

        // Write the data.
        WriteToStream(writeStream, text);

        // Close the stream.
        writeStream.Close();

        // Create another UnmanagedMemoryStream for reading.
        UnmanagedMemoryStream readStream =
            new UnmanagedMemoryStream(memBytePtr, text.Length);

        // Display the contents of the stream to the console.
        PrintStream(readStream);

        // Close the reading stream.
        readStream.Close();

        // Free up the unmanaged memory.
        Marshal.FreeHGlobal(memIntPtr);
    }

    public static void WriteToStream(UnmanagedMemoryStream writeStream, byte[] text)
    {
        // Verify that the stream is writable:
        // By default, UnmanagedMemoryStream objects do not have write access,
        // write access must be set explicitly.
        if (writeStream.CanWrite)
        {
            // Write the data, byte by byte
            for (int i = 0; i < writeStream.Length; i++)
            {
                writeStream.WriteByte(text[i]);
            }
        }
    }

    public static void PrintStream(UnmanagedMemoryStream readStream)
    {
        byte[] text = new byte[readStream.Length];
        // Verify that the stream is writable:
        // By default, UnmanagedMemoryStream objects do not have write access,
        // write access must be set explicitly.
        if (readStream.CanRead)
        {
            // Write the data, byte by byte
            for (int i = 0; i < readStream.Length; i++)
            {
                text[i] = (byte)readStream.ReadByte();
            }
        }

        Console.WriteLine(UnicodeEncoding.Unicode.GetString(text));
    }
}

Remarks

This constructor creates a new instance of the UnmanagedMemoryStream class, and by default sets the CanWrite property to false and the CanRead property to true. The Length property is set to the value of the length parameter and cannot be changed.

UnmanagedMemoryStream(SafeBuffer, Int64, Int64)

Source:

UnmanagedMemoryStream.cs

Initializes a new instance of the UnmanagedMemoryStream class in a safe buffer with a specified offset and length.

public:
 UnmanagedMemoryStream(System::Runtime::InteropServices::SafeBuffer ^ buffer, long offset, long length);

public UnmanagedMemoryStream (System.Runtime.InteropServices.SafeBuffer buffer, long offset, long length);

new System.IO.UnmanagedMemoryStream : System.Runtime.InteropServices.SafeBuffer * int64 * int64 -> System.IO.UnmanagedMemoryStream

Public Sub New (buffer As SafeBuffer, offset As Long, length As Long)

Parameters

buffer

SafeBuffer

The buffer to contain the unmanaged memory stream.

offset

Int64

The byte position in the buffer at which to start the unmanaged memory stream.

length

Int64

The length of the unmanaged memory stream.

UnmanagedMemoryStream(Byte*, Int64, Int64, FileAccess)

Source:

UnmanagedMemoryStream.cs

Important

This API is not CLS-compliant.

Initializes a new instance of the UnmanagedMemoryStream class using the specified location, memory length, total amount of memory, and file access values.

public:
 UnmanagedMemoryStream(System::Byte* pointer, long length, long capacity, System::IO::FileAccess access);

[System.CLSCompliant(false)]
public UnmanagedMemoryStream (byte* pointer, long length, long capacity, System.IO.FileAccess access);

[<System.CLSCompliant(false)>]
new System.IO.UnmanagedMemoryStream : nativeptr<byte> * int64 * int64 * System.IO.FileAccess -> System.IO.UnmanagedMemoryStream

Parameters

pointer

Byte*

A pointer to an unmanaged memory location.

length

Int64

The length of the memory to use.

capacity

Int64

The total amount of memory assigned to the stream.

access

FileAccess

One of the FileAccess values.

Attributes

CLSCompliantAttribute

Exceptions

SecurityException

The user does not have the required permission.

ArgumentNullException

The pointer value is null.

ArgumentOutOfRangeException

The length value is less than zero.

-or-

The capacity value is less than zero.

-or-

The length value is greater than the capacity value.

Examples

The following code example demonstrates how to read from and write to unmanaged memory using the UnmanagedMemoryStream class. A block of unmanaged memory is allocated and de-allocated using the Marshal class.

// Note: you must compile this sample using the unsafe flag.
// From the command line, type the following: csc sample.cs /unsafe

using System;
using System.IO;
using System.Text;
using System.Runtime.InteropServices;

unsafe class TestWriter
{
    static void Main()
    {
        // Create some data to read and write.
        byte[] message = UnicodeEncoding.Unicode.GetBytes("Here is some data.");

        // Allocate a block of unmanaged memory and return an IntPtr object.	
        IntPtr memIntPtr = Marshal.AllocHGlobal(message.Length);

        // Get a byte pointer from the IntPtr object.
        byte* memBytePtr = (byte*)memIntPtr.ToPointer();

        // Create an UnmanagedMemoryStream object using a pointer to unmanaged memory.
        UnmanagedMemoryStream writeStream = new UnmanagedMemoryStream(memBytePtr, message.Length, message.Length, FileAccess.Write);

        // Write the data.
        writeStream.Write(message, 0, message.Length);

        // Close the stream.
        writeStream.Close();

        // Create another UnmanagedMemoryStream object using a pointer to unmanaged memory.
        UnmanagedMemoryStream readStream = new UnmanagedMemoryStream(memBytePtr, message.Length, message.Length, FileAccess.Read);

        // Create a byte array to hold data from unmanaged memory.
        byte[] outMessage = new byte[message.Length];

        // Read from unmanaged memory to the byte array.
        readStream.Read(outMessage, 0, message.Length);

        // Close the stream.
        readStream.Close();

        // Display the data to the console.
        Console.WriteLine(UnicodeEncoding.Unicode.GetString(outMessage));

        // Free the block of unmanaged memory.
        Marshal.FreeHGlobal(memIntPtr);

        Console.ReadLine();
    }
}

Remarks

The length parameter defines the current amount of memory in use. If reading or appending data to the stream, the length value should be equal to the amount of valid data in the stream to be read from or preserved. If writing to the stream, this value should be zero.

The capacity parameter indicates the amount of total memory available. This value can describe a region that is longer than the length specified, or indicate a region that can be appended to. Any attempt to write beyond this value will fail.

The access parameter sets the CanRead, and CanWrite properties. Note that specifying Write does not guarantee that the stream will be writable. The access parameters allow the implementer to create an object whose implementation can match the actual stream that is exposed.

UnmanagedMemoryStream(SafeBuffer, Int64, Int64, FileAccess)

Source:

UnmanagedMemoryStream.cs

Initializes a new instance of the UnmanagedMemoryStream class in a safe buffer with a specified offset, length, and file access.

public:
 UnmanagedMemoryStream(System::Runtime::InteropServices::SafeBuffer ^ buffer, long offset, long length, System::IO::FileAccess access);

public UnmanagedMemoryStream (System.Runtime.InteropServices.SafeBuffer buffer, long offset, long length, System.IO.FileAccess access);

new System.IO.UnmanagedMemoryStream : System.Runtime.InteropServices.SafeBuffer * int64 * int64 * System.IO.FileAccess -> System.IO.UnmanagedMemoryStream

Public Sub New (buffer As SafeBuffer, offset As Long, length As Long, access As FileAccess)

Parameters

buffer

SafeBuffer

The buffer to contain the unmanaged memory stream.

offset

Int64

The byte position in the buffer at which to start the unmanaged memory stream.

length

Int64

The length of the unmanaged memory stream.

access

FileAccess

The mode of file access to the unmanaged memory stream.