Storage Streams API Reference

This section provides detailed information about the Windows Runtime (WinRT) Streams API for Windows Universal Platform (UWP) applications. These APIs enable efficient reading from and writing to various data sources, such as files, network sockets, and memory buffers.

Core Concepts

The Streams API is built around several key interfaces:

  • IRandomAccessStream: Represents a stream that supports random access, allowing you to read from or write to any position within the stream.
  • IInputStream: Represents a stream that can only be read from.
  • IOutputStream: Represents a stream that can only be written to.
  • DataReader and DataWriter: Helper classes for reading and writing primitive data types in a portable format.

These interfaces abstract away the complexities of underlying storage mechanisms, providing a consistent way to handle data transfer.

Key Interfaces and Classes

Windows.Storage.Streams.IRandomAccessStream

This is the primary interface for streams that allow both reading and writing, and where you can seek to specific positions.

interface IRandomAccessStream with IInputStream, IOutputStream {
    ulong Size { get; set; }
    ulong Position { get; }
    bool CanRead { get; }
    bool CanWrite { get; }
    bool CanSeek { get; }
    IRandomAccessStream CloneStream();
    void Seek(ulong position);
    void SetData(IInputStream stream);
    IInputStream GetInputStreamAt(ulong position);
    IOutputStream GetOutputStreamAt(ulong position);
}

Windows.Storage.Streams.DataReader

A helper class to read binary data from an input stream.

class DataReader with IDisposable public static DataReader FromBuffer(IBuffer buffer);
public byte ReadByte();
public string ReadString(uint length);
public int ReadInt32();
public uint UnconsumedBufferLength { get; }
// ... other Read methods for different data types

Windows.Storage.Streams.DataWriter

A helper class to write binary data to an output stream.

class DataWriter with IDisposable public IBuffer DetachBuffer();
public uint StoreAsync() returns IAsyncOperation<uint>;
public void WriteByte(byte value);
public void WriteString(string value);
public void WriteInt32(int value);
// ... other Write methods for different data types

Common Scenarios

Reading from a File

Using FileRandomAccessStream and DataReader to read text from a file.

C# Example

async void ReadFileContent(StorageFile file) {
    using (var stream = await file.OpenAsync(FileAccessMode.Read))
    {
        var reader = new DataReader(stream);
        var bytes = await reader.LoadAsync(stream.Size);
        string content = reader.ReadString(bytes);
        // Process the content string
    }
}

Writing to a File

Using FileRandomAccessStream and DataWriter to write text to a file.

C# Example

async void WriteToFile(StorageFile file, string dataToWrite) {
    using (var stream = await file.OpenAsync(FileAccessMode.Create))
    {
        var writer = new DataWriter(stream);
        writer.WriteString(dataToWrite);
        await writer.StoreAsync();
    }
}

Performance Considerations

  • Always use using statements or ensure streams are properly disposed to release resources.
  • For large amounts of data, consider reading or writing in chunks to avoid excessive memory consumption.
  • Utilize DataReader.LoadAsync and DataWriter.StoreAsync for efficient data transfer.
  • Understand the capabilities of the underlying stream (e.g., random access vs. sequential).