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, but all operations complete synchronously on current platforms. The StorageContainer maps directly to a directory on the local filesystem, and StorageDevice represents that location. The async wrappers exist purely for source-level XNA compatibility and return immediately.

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

Platform storage paths

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

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.

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();