DataWriter DataWriter DataWriter DataWriter Class

Definition

Writes data to an output stream.

public : sealed class DataWriter : IClosable, IDataWriter
public sealed class DataWriter : IDisposable, IDataWriter
Public NotInheritable Class DataWriter Implements IDisposable, IDataWriter
var dataWriter = new dataWriter();
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Examples

The following example shows how to write and read strings to an in-memory stream. For the full code sample, see Reading and writing data sample.

#include "pch.h"
#include "WriteReadStream.xaml.h"

using namespace Concurrency;
using namespace DataReaderWriter;
using namespace Platform;
using namespace Windows::Storage::Streams;
using namespace Windows::UI::Xaml;
using namespace Windows::UI::Xaml::Controls;
using namespace Windows::UI::Xaml::Navigation;

Array<String^>^ _inputElements = ref new Array<String^>
{
    "Hello", "World", "1 2 3 4 5", "Très bien!", "Goodbye"
};

WriteReadStream::WriteReadStream()
{
    InitializeComponent();

    // Populate the text block with the input elements.
    ElementsToWrite->Text = "";
    for (unsigned int i = 0; i < _inputElements->Length; i++)
    {
        ElementsToWrite->Text += _inputElements[i] + ";";
    }
}

// Invoked when this page is about to be displayed in a Frame.
void WriteReadStream::OnNavigatedTo(NavigationEventArgs^ e)
{
    // Get a pointer to our main page.
    rootPage = MainPage::Current;
}

// This is the click handler for the 'Copy Strings' button.  Here we will parse the
// strings contained in the ElementsToWrite text block, write them to a stream using
// DataWriter, retrieve them using DataReader, and output the results in the
// ElementsRead text block.
void DataReaderWriter::WriteReadStream::TransferData(
Platform::Object^ sender, Windows::UI::Xaml::RoutedEventArgs^ e)
{
    // Initialize the in-memory stream where data will be stored.
    InMemoryRandomAccessStream^ stream = ref new InMemoryRandomAccessStream();

    // Create the DataWriter object backed by the in-memory stream.  When
    // dataWriter is deleted, it will also close the underlying stream.
    DataWriter^ dataWriter = ref new DataWriter(stream);
    dataWriter->UnicodeEncoding = UnicodeEncoding::Utf8;
    dataWriter->ByteOrder = ByteOrder::LittleEndian;

    // Create the data reader by using the input stream set at position 0 so that 
    // the stream will be read from the beginning regardless of where the position
    // the original stream ends up in after the store.
    IInputStream^ inputStream = stream->GetInputStreamAt(0);
    DataReader^ dataReader = ref new DataReader(inputStream);
    // The encoding and byte order need to match the settings of the writer 
    / we previously used.
    dataReader->UnicodeEncoding = UnicodeEncoding::Utf8;
    dataReader->ByteOrder = ByteOrder::LittleEndian;

    // Write the input data to the output stream.  Serialize the elements by writing
    // each string separately, preceded by its length.
    for (unsigned int i = 0; i < _inputElements->Length; i++) 
    {
        unsigned int inputElementSize = dataWriter->MeasureString(_inputElements[i]);
        dataWriter->WriteUInt32(inputElementSize);
        dataWriter->WriteString(_inputElements[i]);
    }

    // Send the contents of the writer to the backing stream.
    create_task(dataWriter->StoreAsync()).then([this, dataWriter] (unsigned int bytesStored)
    {
        // For the in-memory stream implementation we are using, the FlushAsync() call 
        // is superfluous, but other types of streams may require it.
        return dataWriter->FlushAsync();
    }).then([this, dataReader, stream] (bool flushOp)
    {
        // Once we have written the contents successfully we load the stream.
        return dataReader->LoadAsync((unsigned int) stream->Size);
    }).then([this, dataReader] (task<unsigned int> bytesLoaded)
    {
        try
        {
            // Check for possible exceptions that could have been thrown 
            // in the async call chain.
            bytesLoaded.get();

            String^ readFromStream = "";

            // Keep reading until we consume the complete stream.
            while (dataReader->UnconsumedBufferLength > 0)
            {
                // Note that the call to ReadString requires a length of 
                // "code units" to read. This is the reason each string is 
                // preceded by its length when "on the wire".
                unsigned int bytesToRead = dataReader->ReadUInt32();
                readFromStream += dataReader->ReadString(bytesToRead) + "\n";
            }

            // Populate the ElementsRead text block with the items we read from the stream
            ElementsRead->Text = readFromStream;
        }
        catch (Exception^ e)
        {
            ElementsRead->Text = "Error: " + e->Message;
        }
    });
}

using System;
using System.Diagnostics;
using Windows.Foundation;
using Windows.UI.Xaml;
using Windows.UI.Xaml.Controls;
using Windows.UI.Xaml.Navigation;

// This is the click handler for the 'Copy Strings' button.  Here we will parse the
// strings contained in the ElementsToWrite text block, write them to a stream using
// DataWriter, retrieve them using DataReader, and output the results in the
// ElementsRead text block.
private async void TransferData(object sender, RoutedEventArgs e)
{
    // Initialize the in-memory stream where data will be stored.
    using (var stream = new Windows.Storage.Streams.InMemoryRandomAccessStream())
    {
        // Create the data writer object backed by the in-memory stream.
        using (var dataWriter = new Windows.Storage.Streams.DataWriter(stream))
        {
            dataWriter.UnicodeEncoding = Windows.Storage.Streams.UnicodeEncoding.Utf8;
            dataWriter.ByteOrder = Windows.Storage.Streams.ByteOrder.LittleEndian;

            // Parse the input stream and write each element separately.
            string[] inputElements = ElementsToWrite.Text.Split(';');
            foreach (string inputElement in inputElements)
            {
                uint inputElementSize = dataWriter.MeasureString(inputElement);
                dataWriter.WriteUInt32(inputElementSize);
                dataWriter.WriteString(inputElement);
            }

            // Send the contents of the writer to the backing stream.
            await dataWriter.StoreAsync();

            // For the in-memory stream implementation we are using, the flushAsync call 
            // is superfluous,but other types of streams may require it.
            await dataWriter.FlushAsync();

            // In order to prolong the lifetime of the stream, detach it from the 
            // DataWriter so that it will not be closed when Dispose() is called on 
            // dataWriter. Were we to fail to detach the stream, the call to 
            // dataWriter.Dispose() would close the underlying stream, preventing 
            // its subsequent use by the DataReader below.
            dataWriter.DetachStream();
        }

        // Create the input stream at position 0 so that the stream can be read 
        // from the beginning.
        using (var inputStream = stream.GetInputStreamAt(0))
        {
            using (var dataReader = new Windows.Storage.Streams.DataReader(inputStream))
            {
                // The encoding and byte order need to match the settings of the writer 
                // we previously used.
                dataReader.UnicodeEncoding = Windows.Storage.Streams.UnicodeEncoding.Utf8;
                dataReader.ByteOrder = Windows.Storage.Streams.ByteOrder.LittleEndian;

                // Once we have written the contents successfully we load the stream.
                await dataReader.LoadAsync((uint)stream.Size);

                var receivedStrings = "";

                // Keep reading until we consume the complete stream.
                while (dataReader.UnconsumedBufferLength > 0)
                {
                    // Note that the call to readString requires a length of "code units" 
                    // to read. This is the reason each string is preceded by its length 
                    // when "on the wire".
                    uint bytesToRead = dataReader.ReadUInt32();
                    receivedStrings += dataReader.ReadString(bytesToRead) + "\n";
                }

                // Populate the ElementsRead text block with the items we read 
                // from the stream.
                ElementsRead.Text = receivedStrings;
            }
        }
    }
}

(function () {
    "use strict";
    var page = WinJS.UI.Pages.define("/html/write-read-stream.html", {
        ready: function (element, options) {
            var sourceElement = document.getElementById("ElementsToSend");
            sourceElement.innerHTML = "Hello;World;1 2 3 4 5;Très bien!;Goodbye";
            var sendButton = document.getElementById("SendButton");
            sendButton.addEventListener("click", transferData);
        }
    });

function transferData() {
        var sourceElement = document.getElementById("ElementsToSend");
        var destinationElement = document.getElementById("scenario1Output");

        // First a DataWriter object is created, backed by an in-memory stream where 
        // the data will be stored.
        var writer = Windows.Storage.Streams.DataWriter(
            new Windows.Storage.Streams.InMemoryRandomAccessStream());
        writer.unicodeEncoding = Windows.Storage.Streams.UnicodeEncoding.utf8;
        writer.byteOrder = Windows.Storage.Streams.ByteOrder.littleEndian;

        // We separate the contents of the sourceElement div in multiple strings 
        // using ';' as the separator. Each string will be written separately.
        var elements = sourceElement.innerHTML.split(";");
        elements.forEach(function (element) {
            var codeUnits = writer.measureString(element);
            writer.writeInt32(codeUnits);
            writer.writeString(element);
        });

        var reader;
        var stream;

        // The call to store async sends the actual contents of the writer 
        // to the backing stream.
        writer.storeAsync().then(function () {
            // For the in-memory stream implementation we are using, the flushAsync call 
            // is superfluous, but other types of streams may require it.
            return writer.flushAsync();
        }).then(function () {
            // We detach the stream to prolong its useful lifetime. Were we to fail 
            // to detach the stream, the call to writer.close() would close the underlying 
            // stream, preventing its subsequent use by the DataReader below. Most clients 
            // of DataWriter will have no reason to use the underlying stream after 
            // writer.close() is called, and will therefore have no reason to call
            // writer.detachStream(). Note that once we detach the stream, we assume 
            // responsibility for closing the stream subsequently; after the stream 
            // has been detached, a call to writer.close() will have no effect on the stream.
            stream = writer.detachStream();
            // Make sure the stream is read from the beginning in the reader 
            // we are creating below.
            stream.seek(0);
            // Most DataWriter clients will not call writer.detachStream(), 
            // and furthermore will be working with a file-backed or network-backed stream, 
            // rather than an in-memory-stream. In such cases, it would be particularly 
            // important to call writer.close(). Doing so is always a best practice.
            writer.close();

            reader = new Windows.Storage.Streams.DataReader(stream);
            // The encoding and byte order need to match the settings of the writer 
            // we previously used.
            reader.unicodeEncoding = Windows.Storage.Streams.UnicodeEncoding.utf8;
            reader.byteOrder = Windows.Storage.Streams.ByteOrder.littleEndian;
            // Once we have written the contents successfully we load the stream, 
            // this is also an asynchronous operation
            return reader.loadAsync(stream.size);
        }).done(function () {
            var receivedStrings = "";
            // Keep reading until we consume the complete stream
            while (reader.unconsumedBufferLength > 0) {
                // Note that the call to readString requires a length of "code units" 
                // to read. This is the reason each string is preceeded by its length 
                // when "on the wire".
                var codeUnitsToRead = reader.readInt32();
                receivedStrings += reader.readString(codeUnitsToRead) + "<br/>";
            }
            // Calling reader.close() closes the underlying stream. It would be particularly important
            // to call reader.close() if the underlying stream were file-backed or 
            // network-backed. Note that this call to reader.close() satisfies 
            // our obligation to close the stream previously detached from DataReader.
            reader.close();
            destinationElement.innerHTML = receivedStrings;
        });
    };
})();

Constructors

DataWriter() DataWriter() DataWriter() DataWriter()

Creates and initializes a new instance of the data writer.

public : DataWriter()
public DataWriter()
Public Sub New()
var dataWriter = new dataWriter();
See Also

DataWriter(IOutputStream) DataWriter(IOutputStream) DataWriter(IOutputStream) DataWriter(IOutputStream)

Creates and initializes a new instance of the data writer to an output stream.

public : DataWriter(IOutputStream outputStream)
public DataWriter(IOutputStream outputStream)
Public Sub New(outputStream As IOutputStream)
var dataWriter = new dataWriter(outputStream);
Parameters
outputStream
IOutputStream IOutputStream IOutputStream IOutputStream

The new output stream instance.

See Also

Properties

ByteOrder ByteOrder ByteOrder ByteOrder

Gets or sets the byte order of the data in the output stream.

public : ByteOrder ByteOrder { get; set; }
public ByteOrder ByteOrder { get; set; }
Public ReadWrite Property ByteOrder As ByteOrder
var byteOrder = dataWriter.byteOrder;
dataWriter.byteOrder = byteOrder;
Value
ByteOrder ByteOrder ByteOrder ByteOrder

One of the enumeration values.

UnicodeEncoding UnicodeEncoding UnicodeEncoding UnicodeEncoding

Gets or sets the Unicode character encoding for the output stream.

public : UnicodeEncoding UnicodeEncoding { get; set; }
public UnicodeEncoding UnicodeEncoding { get; set; }
Public ReadWrite Property UnicodeEncoding As UnicodeEncoding
var unicodeEncoding = dataWriter.unicodeEncoding;
dataWriter.unicodeEncoding = unicodeEncoding;
Value
UnicodeEncoding UnicodeEncoding UnicodeEncoding UnicodeEncoding

One of the enumeration values.

UnstoredBufferLength UnstoredBufferLength UnstoredBufferLength UnstoredBufferLength

Gets the size of the buffer that has not been used.

public : unsigned int UnstoredBufferLength { get; }
public uint UnstoredBufferLength { get; }
Public ReadOnly Property UnstoredBufferLength As uint
var uint = dataWriter.unstoredBufferLength;
Value
unsigned int uint uint uint

The size of the buffer that has not been used, in bytes.

Methods

Close() Close() Close() Close()

Closes the current stream and releases system resources.

public : void Close()
This member is not implemented in C#
This member is not implemented in VB.Net
dataWriter.close();

Remarks

DataWriter takes ownership of the stream that is passed to its constructor. Calling this method also calls on the associated stream. After calling this method, calls to most other DataWriter methods will fail.

If you do not want the associated stream to be closed when the reader closes, call DataWriter.DetachStream before calling this method.

DetachBuffer() DetachBuffer() DetachBuffer() DetachBuffer()

Detaches the buffer that is associated with the data writer.

public : IBuffer DetachBuffer()
public IBuffer DetachBuffer()
Public Function DetachBuffer() As IBuffer
var iBuffer = dataWriter.detachBuffer();
Returns

The detached buffer.

DetachStream() DetachStream() DetachStream() DetachStream()

Detaches the stream that is associated with the data writer.

public : IOutputStream DetachStream()
public IOutputStream DetachStream()
Public Function DetachStream() As IOutputStream
var iOutputStream = dataWriter.detachStream();
Returns

Dispose() Dispose() Dispose() Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

This member is not implemented in C++
void Dispose()
Sub Dispose
void Dispose()

FlushAsync() FlushAsync() FlushAsync() FlushAsync()

Flushes data asynchronously.

public : IAsyncOperation<Platform::Boolean> FlushAsync()
public IAsyncOperation<bool> FlushAsync()
Public Function FlushAsync() As IAsyncOperation( Of bool )
var iAsyncOperation = dataWriter.flushAsync();
Returns

The stream flush operation.

Remarks

The FlushAsync method may produce latencies and does not always guarantee durable and coherent storage of data. It's generally recommended to avoid this method if possible.

MeasureString(String) MeasureString(String) MeasureString(String) MeasureString(String)

Gets the size of a string.

public : unsigned int MeasureString(Platform::String value)
public uint MeasureString(String value)
Public Function MeasureString(value As String) As uint
var uint = dataWriter.measureString(value);
Parameters
value
Platform::String String String String

The string.

Returns
unsigned int uint uint uint

The size of the string, in bytes.

StoreAsync() StoreAsync() StoreAsync() StoreAsync()

Commits data in the buffer to the output stream. This method should only be called when the DataWriter is writing into a stream; it will fail when the underlying store is a buffer.

public : DataWriterStoreOperation StoreAsync()
public DataWriterStoreOperation StoreAsync()
Public Function StoreAsync() As DataWriterStoreOperation
var dataWriterStoreOperation = dataWriter.storeAsync();
Returns

WriteBoolean(Boolean) WriteBoolean(Boolean) WriteBoolean(Boolean) WriteBoolean(Boolean)

Writes a Boolean value to the output stream.

public : void WriteBoolean(bool value)
public void WriteBoolean(Boolean value)
Public Function WriteBoolean(value As Boolean) As void
dataWriter.writeBoolean(value);
Parameters
value
bool Boolean Boolean Boolean

The value.

WriteBuffer(IBuffer) WriteBuffer(IBuffer) WriteBuffer(IBuffer) WriteBuffer(IBuffer)

Writes the contents of the specified buffer to the output stream.

public : void WriteBuffer(IBuffer buffer)
public void WriteBuffer(IBuffer buffer)
Public Function WriteBuffer(buffer As IBuffer) As void
dataWriter.writeBuffer(buffer);
Parameters
buffer
IBuffer IBuffer IBuffer IBuffer

The buffer.

See Also

WriteBuffer(IBuffer, UInt32, UInt32) WriteBuffer(IBuffer, UInt32, UInt32) WriteBuffer(IBuffer, UInt32, UInt32) WriteBuffer(IBuffer, UInt32, UInt32)

Writes the specified bytes from a buffer to the output stream.

public : void WriteBuffer(IBuffer buffer, unsigned int start, unsigned int count)
public void WriteBuffer(IBuffer buffer, UInt32 start, UInt32 count)
Public Function WriteBuffer(buffer As IBuffer, start As UInt32, count As UInt32) As void
dataWriter.writeBuffer(buffer, start, count);
Parameters
buffer
IBuffer IBuffer IBuffer IBuffer

The buffer.

start
unsigned int UInt32 UInt32 UInt32

The starting byte.

count
unsigned int UInt32 UInt32 UInt32

The number of bytes to write.

See Also

WriteByte(Byte) WriteByte(Byte) WriteByte(Byte) WriteByte(Byte)

Writes a byte value to the output stream.

public : void WriteByte(Byte value)
public void WriteByte(Byte value)
Public Function WriteByte(value As Byte) As void
dataWriter.writeByte(value);
Parameters
value
Byte Byte Byte Byte

The value.

WriteBytes(Byte[]) WriteBytes(Byte[]) WriteBytes(Byte[]) WriteBytes(Byte[])

Writes an array of byte values to the output stream.

public : void WriteBytes(Byte[] value)
public void WriteBytes(Byte[] value)
Public Function WriteBytes(value As Byte[]) As void
dataWriter.writeBytes(value);
Parameters
value
Byte[] Byte[] Byte[] Byte[]

The array of values.

WriteDateTime(DateTime) WriteDateTime(DateTime) WriteDateTime(DateTime) WriteDateTime(DateTime)

Writes a date and time value to the output stream.

public : void WriteDateTime(DateTime value)
public void WriteDateTime(DateTimeOffset value)
Public Function WriteDateTime(value As DateTimeOffset) As void
dataWriter.writeDateTime(value);
Parameters
value
DateTime DateTimeOffset DateTimeOffset DateTimeOffset

The value.

WriteDouble(Double) WriteDouble(Double) WriteDouble(Double) WriteDouble(Double)

Writes a floating-point value to the output stream.

public : void WriteDouble(double value)
public void WriteDouble(Double value)
Public Function WriteDouble(value As Double) As void
dataWriter.writeDouble(value);
Parameters
value
double Double Double Double

The value.

WriteGuid(Guid) WriteGuid(Guid) WriteGuid(Guid) WriteGuid(Guid)

Writes a GUID value to the output stream.

public : void WriteGuid(Platform::Guid value)
public void WriteGuid(Guid value)
Public Function WriteGuid(value As Guid) As void
dataWriter.writeGuid(value);
Parameters
value
Platform::Guid Guid Guid Guid

The value.

WriteInt16(Int16) WriteInt16(Int16) WriteInt16(Int16) WriteInt16(Int16)

Writes a 16-bit integer value to the output stream.

public : void WriteInt16(short value)
public void WriteInt16(Int16 value)
Public Function WriteInt16(value As Int16) As void
dataWriter.writeInt16(value);
Parameters
value
short Int16 Int16 Int16

The value.

WriteInt32(Int32) WriteInt32(Int32) WriteInt32(Int32) WriteInt32(Int32)

Writes a 32-bit integer value to the output stream.

public : void WriteInt32(int value)
public void WriteInt32(Int32 value)
Public Function WriteInt32(value As Int32) As void
dataWriter.writeInt32(value);
Parameters
value
int Int32 Int32 Int32

The value.

WriteInt64(Int64) WriteInt64(Int64) WriteInt64(Int64) WriteInt64(Int64)

Writes a 64-bit integer value to the output stream.

public : void WriteInt64(long value)
public void WriteInt64(Int64 value)
Public Function WriteInt64(value As Int64) As void
dataWriter.writeInt64(value);
Parameters
value
long Int64 Int64 Int64

The value.

WriteSingle(Single) WriteSingle(Single) WriteSingle(Single) WriteSingle(Single)

Writes a floating-point value to the output stream.

public : void WriteSingle(float value)
public void WriteSingle(Single value)
Public Function WriteSingle(value As Single) As void
dataWriter.writeSingle(value);
Parameters
value
float Single Single Single

The value.

WriteString(String) WriteString(String) WriteString(String) WriteString(String)

Writes a string value to the output stream.

public : unsigned int WriteString(Platform::String value)
public uint WriteString(String value)
Public Function WriteString(value As String) As uint
var uint = dataWriter.writeString(value);
Parameters
value
Platform::String String String String

The value.

Returns
unsigned int uint uint uint

The length of the string, in bytes.

WriteTimeSpan(TimeSpan) WriteTimeSpan(TimeSpan) WriteTimeSpan(TimeSpan) WriteTimeSpan(TimeSpan)

Writes a time-interval value to the output stream.

public : void WriteTimeSpan(TimeSpan value)
public void WriteTimeSpan(TimeSpan value)
Public Function WriteTimeSpan(value As TimeSpan) As void
dataWriter.writeTimeSpan(value);
Parameters
value
TimeSpan TimeSpan TimeSpan TimeSpan

The value.

WriteUInt16(UInt16) WriteUInt16(UInt16) WriteUInt16(UInt16) WriteUInt16(UInt16)

Writes a 16-bit unsigned integer value to the output stream.

public : void WriteUInt16(unsigned short value)
public void WriteUInt16(UInt16 value)
Public Function WriteUInt16(value As UInt16) As void
dataWriter.writeuInt16(value);
Parameters
value
unsigned short UInt16 UInt16 UInt16

The value.

WriteUInt32(UInt32) WriteUInt32(UInt32) WriteUInt32(UInt32) WriteUInt32(UInt32)

Writes a 32-bit unsigned integer value to the output stream.

public : void WriteUInt32(unsigned int value)
public void WriteUInt32(UInt32 value)
Public Function WriteUInt32(value As UInt32) As void
dataWriter.writeuInt32(value);
Parameters
value
unsigned int UInt32 UInt32 UInt32

The value.

WriteUInt64(UInt64) WriteUInt64(UInt64) WriteUInt64(UInt64) WriteUInt64(UInt64)

Writes a 64-bit unsigned integer value to the output stream.

public : void WriteUInt64(unsigned __int64 value)
public void WriteUInt64(UInt64 value)
Public Function WriteUInt64(value As UInt64) As void
dataWriter.writeuInt64(value);
Parameters
value
unsigned __int64 UInt64 UInt64 UInt64

The value.

See Also