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

Other StorageDevice members

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 (next section).
• <displayName> — the container name you pass to BeginOpenContainer.
• Player{N} — the per-player subdirectory, derived from the PlayerIndex the device was selected for and numbered from one: PlayerIndex::One is Player1.
• AllPlayers — used instead when the device was selected without a player (the (callback, state) overload).

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.

Where the root is: the persistence-path chain

The root is not SDL_GetPrefPath, and it does not depend on the selected windowing platform: the same policy applies under SDL3, HEADLESS and TERMINAL. It is resolved once, on first use, from the first of these that applies:

<app> is the literal string game unless the program calls StorageDevice::SetAppNameEXT("MyGame"). Nothing derives it from the window title or the executable name, so two CNA games that never call SetAppNameEXT share one folder. SetAppNameEXT discards the cached root (so call it before the first container is opened, or an earlier save stays under the old name) and also re-points Sharp Runtime’s isolated-storage root at <root>/.cna_isolated_storage. UTF-8 roots and names are handled on Windows by the root resolution and the container paths, but getIsConnectedProperty(), getFreeSpaceProperty() and getTotalSpaceProperty() still build narrow paths from the UTF-8 root, so with a non-ASCII root they may not resolve it correctly there. If the root cannot be created, the first access throws StorageDeviceNotConnectedException; that failure is not repeated, because the root is then latched empty and later calls silently resolve against the working directory (both points read from the source, not executed).

Path containment

A StorageContainer is an authority boundary. A container name, and every file or directory path passed to a container, must be relative and must stay inside the container. An empty name or path, an absolute path, a .. that climbs past the container root, or a path that resolves through a symlink to somewhere outside it throws std::invalid_argument. (DeleteContainer had its own containment check in alpha.1; the file, directory and container-name checks are new.) Code that passed "../other" or an absolute path to a container must be changed.

StorageContainer

StorageContainer provides file and directory access scoped to a named save context within a device. It implements the XNA 4.0 API. All paths passed to its methods are relative to the container root directory and are contained in it. The container also exposes getDisplayNameProperty(), getIsDisposedProperty(), getStorageDeviceProperty(), the Disposing event, and an idempotent Dispose().

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 — on Xbox 360, for example, if a memory unit was ejected. In CNA, because storage always maps to the local filesystem, it is raised only when the storage root cannot be created on first use (“Unable to create the storage directory.”) or when getFreeSpaceProperty() / getTotalSpaceProperty() cannot query the root, with the underlying filesystem error attached as the inner exception.

It derives from ExternalException, carries a human-readable message, and has a protected serialization constructor and a GetObjectData round trip (covered by four of the module’s tests). Catch it wherever you first touch the device if your application needs to handle an unusable save location gracefully; note that ordinary I/O errors and bad paths surface as other exceptions (std::invalid_argument for a contained-path violation, stream or filesystem errors for I/O).

try {
    auto opening   = device->BeginOpenContainer("SaveData", nullptr, nullptr);
    auto container = device->EndOpenContainer(opening.get());
    // ... use container ...
    container->Dispose();
} catch (const StorageDeviceNotConnectedException& ex) {
    // Storage unavailable — the root could not be created or queried
    ShowErrorDialog(ex.what());
} catch (const std::invalid_argument& ex) {
    // The container name was empty, absolute, or escaped the storage root
    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 callback and state object. It returns a std::unique_ptr<System::IAsyncResult>.
2. In the callback (or right after the call), pass result.get() to the matching End* method to retrieve the result.

In CNA, all storage operations complete synchronously: the Begin* call finishes its work, invokes your callback, and only then returns the IAsyncResult. The pattern is preserved so that XNA save-game code ports with little change, 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. End* throws std::invalid_argument if handed a result that another Begin* produced.

Code examples

These use the real signatures at this snapshot: results are owned by std::unique_ptr, End* takes result.get(), and stream lengths and reads use Sharp Runtime’s getLengthProperty() and Read/Write(buffer, offset, count) with SharpRuntime::bytecs buffers. For a complete, runnable save-slot program see Tutorial 141: Save Data Portably.

Saving a file

using namespace Microsoft::Xna::Framework::Storage;
using System::IO::FileMode;

// Obtain a StorageDevice (the Begin/End pair completes synchronously)
auto selection = StorageDevice::BeginShowSelector(nullptr, nullptr);
std::unique_ptr<StorageDevice> device = StorageDevice::EndShowSelector(selection.get());

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

// 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<SharpRuntime::intcs>(saveData.size()));
stream->Close();

container->Dispose();

Loading a file

auto opening   = device->BeginOpenContainer("Slot1", nullptr, nullptr);
auto container = device->EndOpenContainer(opening.get());

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

std::vector<SharpRuntime::bytecs> buffer(static_cast<std::size_t>(stream->getLengthProperty()));
stream->Read(buffer.data(), 0, static_cast<SharpRuntime::intcs>(buffer.size()));
stream->Close();

container->Dispose();

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

Checking file existence before loading

auto opening   = device->BeginOpenContainer("Slot1", nullptr, nullptr);
auto container = device->EndOpenContainer(opening.get());

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

StorageContainer details that affect save code

Three behaviours are easy to miss when XNA save code is ported; each was checked by reading StorageContainer.cpp at this snapshot (not executed). The internals are on the storage internals page.

Reading a save back completely

Stream::Read returns how many bytes it actually copied, which may be fewer than requested. Loop until the expected length is reached or a read returns 0, and treat a short result as a truncated save rather than parsing it:

std::unique_ptr<System::IO::Stream> in =
    container->OpenFile("savegame.dat", System::IO::FileMode::Open);
std::vector<SharpRuntime::bytecs> bytes(static_cast<std::size_t>(in->getLengthProperty()));

SharpRuntime::intcs offset = 0;
const auto total = static_cast<SharpRuntime::intcs>(bytes.size());
while (offset < total) {
    const SharpRuntime::intcs n = in->Read(bytes.data(), offset, total - offset);
    if (n == 0) break;          // end of file before the expected length
    offset += n;
}
if (offset != total) { /* reject a truncated save */ }

Syntax-checked with g++ -fsyntax-only against the snapshot's headers and a sibling sharp-runtime checkout; not run.

Wildcard patterns, exactly

GetFileNames(pattern) and GetDirectoryNames(pattern) match each entry name at the container's top level (not recursively) against the whole pattern with CNA's own matcher: * matches any run of bytes, including none; ? matches exactly one byte, so a non-ASCII character, which is several UTF-8 bytes, needs several; every other byte, . included, matches only itself, case-sensitively on every host. There are no character classes and no escapes, and an empty pattern throws std::invalid_argument. "slot?.sav" therefore finds slot1.sav but not Slot1.SAV or slot10.sav. The storage tests exercise path containment, not the matcher's edge cases, so test the patterns your game depends on.

Disposal and concurrent writers

Dispose() sets IsDisposed and raises Disposing once, but no file or directory method checks the flag: calls after disposal still reach the filesystem. Treat a disposed container as unusable anyway: no code should depend on calls after disposal working. The FileShare argument of the four-argument OpenFile is accepted and not applied: the stream is opened with path, mode and access only, and there is no cross-process lock, so FileShare::None, Read and ReadWrite behave the same. Do not rely on it to keep two writers apart; serialise saves in the game.