Storage

Microsoft::Xna::Framework::Storage — StorageDevice, StorageContainer, StorageDeviceNotConnectedException

Overview

The Microsoft::Xna::Framework::Storage namespace provides a platform-independent abstraction for save-game and user-data persistence. On the original Xbox 360, StorageDevice represented a physical memory unit or hard drive, and device selection was presented to the player as a system UI. On PC, the selector returned immediately with the local user profile directory.

CNA preserves the full XNA 4.0 API shape, including the Begin/End asynchronous pattern, and backs it with genuine std::filesystem operations. StorageContainer maps to a real directory on the local filesystem and StorageDevice represents that location.

The async wrappers complete synchronously. This is a deliberate choice rather than a shortcut: the pattern exists in XNA because Xbox 360 storage selection could block on player interaction with a system UI, which has no desktop analogue. Local filesystem operations return fast enough that dispatching them to a thread would add latency and failure modes without adding responsiveness. Source-level XNA compatibility is preserved either way — your callback still fires and End* still returns the result.

Namespace members at a glance

StorageDevice

StorageDevice is the entry point into the storage system. On PC (and in CNA on all platforms) it represents the local filesystem. To obtain a device, use the static Begin/End async selector pattern. On a PC target the selector returns immediately with a device backed by the current user's profile directory.

Device selection (Begin/End pattern)

Opening a container

On-disk layout

Saves are namespaced on disk as <root>/<displayName>/Player{N}, matching XNA's own scheme:

• <root> — the storage root the StorageDevice represents.
• <displayName> — the container name you pass to BeginOpenContainer.
• Player{N} — the per-player subdirectory, derived from the PlayerIndex the device was selected for.

The consequence is the one XNA intended: two players on the same machine writing to the same container name do not collide, and a container opened without a player index is shared across the title.

StorageContainer

StorageContainer provides file and directory access scoped to a named save context within a device. It implements the XNA 4.0 API almost entirely. All paths passed to its methods are relative to the container root directory.

File operations

Directory operations

Pattern matching

The pattern-taking overloads are backed by a hand-written glob matcher rather than a delegation to the platform shell or a regex engine. That keeps wildcard semantics identical across every platform CNA builds for, instead of inheriting whatever the host's directory-enumeration API happens to do.

StorageDeviceNotConnectedException

StorageDeviceNotConnectedException is thrown when a StorageDevice that was previously valid is no longer accessible — for example, if a memory unit was ejected on Xbox 360. In CNA, because storage always maps to the local filesystem, this exception is raised only in exceptional circumstances such as the backing directory being removed by an external process after the device was opened.

It derives from ExternalException and carries a human-readable message. Catch it wherever you call BeginOpenContainer or perform file operations if your application needs to handle a missing device gracefully.

try {
    auto result = device.BeginOpenContainer("SaveData", nullptr, nullptr);
    auto container = device.EndOpenContainer(result);
    // ... use container ...
    container->Dispose();
} catch (const StorageDeviceNotConnectedException& ex) {
    // Storage unavailable — prompt the user to reconnect or select another device
    ShowErrorDialog(ex.what());
}

IAsyncResult pattern

XNA 4.0 used the standard .NET IAsyncResult Begin/End async pattern so that storage operations could show system UI (device selector, container namer) without blocking the game loop. The pattern works as follows:

1. Call the Begin* method, supplying an optional AsyncCallback and state object. It returns an IAsyncResult.
2. In the callback (or by polling IAsyncResult::IsCompleted), call the matching End* method to retrieve the result.

In CNA, all storage operations complete synchronously: the Begin* call performs the operation immediately and the returned IAsyncResult has IsCompleted == true before the callback is even invoked. The pattern is preserved verbatim so that XNA save-game code ports without changes, and synchronous completion is the correct semantics for a desktop filesystem — there is no system UI to wait on and no removable media to negotiate.

Code examples

Saving a file

// Obtain a StorageDevice
StorageDevice* device = nullptr;
StorageDevice::BeginShowSelector(
    [](IAsyncResult* result) {
        device = StorageDevice::EndShowSelector(result);
    }, nullptr);

// Open a container named after your save slot
auto openResult = device->BeginOpenContainer("Slot1", nullptr, nullptr);
auto container  = device->EndOpenContainer(openResult);

// Write a save file
if (!container->DirectoryExists("profile"))
    container->CreateDirectory("profile");

auto stream = container->OpenFile("profile/save.dat", FileMode::Create);
stream->Write(saveData.data(), 0, static_cast<int>(saveData.size()));
stream->Close();

container->Dispose();

Loading a file

auto openResult = device->BeginOpenContainer("Slot1", nullptr, nullptr);
auto container  = device->EndOpenContainer(openResult);

auto stream = container->OpenFile("profile/save.dat", FileMode::Open);

std::vector<uint8_t> buffer(stream->Length());
stream->Read(buffer.data(), 0, static_cast<int>(buffer.size()));
stream->Close();

container->Dispose();

// Deserialise from buffer ...
LoadGameState(buffer);

Checking file existence before loading

auto openResult = device->BeginOpenContainer("Slot1", nullptr, nullptr);
auto container  = device->EndOpenContainer(openResult);

if (container->FileExists("profile/save.dat")) {
    auto stream = container->OpenFile("profile/save.dat", FileMode::Open);
    // ... read and deserialise ...
    stream->Close();
} else {
    // No save file found — start a new game
    StartNewGame();
}

container->Dispose();