AnkiIO.AnkiMediaCollection Class Reference

Owns media registrations for a deck and prevents unsafe or colliding names. More...

Public Member Functions
	AnkiMediaCollection ()
	Initializes an empty media collection.
async Task< AnkiMediaFile >	AddFileAsync (string path, CancellationToken cancellationToken=default)
	Hashes and registers a local file without loading it into memory.
AnkiMediaFile	AddBytes (string fileName, ReadOnlySpan< byte > content)
	Copies and registers reusable in-memory content.
bool	Remove (string fileName)
	Removes a media registration without deleting or invalidating its source content.

Properties
IReadOnlyCollection< AnkiMediaFile >	Files [get]
	Gets a snapshot of registered files in deterministic filename order.

Detailed Description

Owns media registrations for a deck and prevents unsafe or colliding names.

Choose AddBytes when the collection should own a stable, reusable payload. It eagerly copies the entire input into managed memory. Choose AddFileAsync for large assets: hashing is streamed, but the source path remains caller-owned and must stay readable and unchanged through serialization. Package reading also registers extracted media as byte-backed payloads and therefore has memory use proportional to extracted media size.

A filename and SHA-256 digest form the registration identity. Repeating the same name and content is idempotent and returns the descriptor already stored in the collection. Reusing the name for different content throws, preventing a template reference from becoming ambiguous. Content may be shared by different filenames.

Names are validated against a portable subset usable on Windows, macOS, Linux, and in a ZIP package. Directory components, control and reserved characters, Windows device names, and trailing spaces or periods are rejected even when the current operating system would accept them. Comparison remains ordinal and case-sensitive; avoid names that differ only by case when packages may be extracted on a case-insensitive filesystem.

The collection is mutable and is not safe for concurrent mutation. Files returns a detached, read-only, deterministically ordered snapshot. A package reader exposes extracted media through AnkiPackage.Media; it does not attach those registrations to the AnkiDeck.Media collection of each imported deck.

Definition at line 30 of file AnkiMediaCollection.cs.

Constructor & Destructor Documentation

AnkiMediaCollection()

AnkiIO.AnkiMediaCollection.AnkiMediaCollection ( )

inline

Initializes an empty media collection.

The new collection owns no external resource and requires no disposal.

Definition at line 36 of file AnkiMediaCollection.cs.

Member Function Documentation

AddBytes()

AnkiMediaFile AnkiIO.AnkiMediaCollection.AddBytes ( string fileName, ReadOnlySpan< byte > content )

inline

Copies and registers reusable in-memory content.

Parameters

fileName	A portable simple filename without directory components.
content	Content copied on registration so caller mutation cannot affect it.

Returns

The stored descriptor for the copied content. If identical content is already registered under the same filename, the collection remains unchanged and its existing descriptor is returned.

Copying and SHA-256 hashing are synchronous and eager, including for large inputs. Empty payloads are valid. Each stream later opened from the descriptor reads the owned copy and is unaffected by mutation of the caller's buffer.

Exceptions

ArgumentNullException	fileName is null.
ArgumentException	fileName is blank, rooted, a dot segment, a Windows reserved device name, ends in a space or period, or contains a path separator, control character, or portable-invalid filename character.
InvalidOperationException	The filename is already registered with different content.

Definition at line 106 of file AnkiMediaCollection.cs.

AddFileAsync()

async Task< AnkiMediaFile > AnkiIO.AnkiMediaCollection.AddFileAsync ( string path, CancellationToken cancellationToken = default )

inline

Hashes and registers a local file without loading it into memory.

Parameters

path	The source path. Only its final filename is used as the Anki media name; ownership of the file remains with the caller.
cancellationToken	Cancels asynchronous hashing before the registration is added.

Returns

The stored descriptor for the supplied filename and content. If identical content is already registered under the same filename, the collection remains unchanged and its existing descriptor is returned.

Content is streamed once to compute SHA-256, but the source path is retained rather than copied. Keep the file readable and unchanged until every package write consuming this registration completes. A pre-canceled or mid-hash cancellation leaves the collection unchanged.

Exceptions

ArgumentNullException	path is null.
ArgumentException	path is blank, resolves without a filename, or its filename is unsafe for portable Anki media.
FileNotFoundException	The source file does not exist.
DirectoryNotFoundException	A source directory does not exist.
PathTooLongException	path exceeds a platform path-length limit.
UnauthorizedAccessException	The caller cannot read the source file.
IOException	The source cannot be opened or read.
OperationCanceledException	cancellationToken is canceled while hashing.
InvalidOperationException	The filename is already registered with different content.

Definition at line 72 of file AnkiMediaCollection.cs.

Remove()

bool AnkiIO.AnkiMediaCollection.Remove ( string fileName )

inline

Removes a media registration without deleting or invalidating its source content.

Parameters

fileName

The case-sensitive registered filename to remove.

Returns

true when a registration was removed; otherwise, false.

Existing descriptors and streams remain usable. Path-backed files are never deleted, and byte-backed content remains owned by any descriptor that still references it.

Exceptions

ArgumentNullException

fileName is null.

Definition at line 127 of file AnkiMediaCollection.cs.

Property Documentation

Files

IReadOnlyCollection<AnkiMediaFile> AnkiIO.AnkiMediaCollection.Files

get

Gets a snapshot of registered files in deterministic filename order.

A newly allocated, read-only view ordered by AnkiMediaFile.FileName using ordinal comparison. Later registrations and removals do not alter a previously retrieved snapshot.

Definition at line 45 of file AnkiMediaCollection.cs.

---

The documentation for this class was generated from the following file:

• src/AnkiIO/Media/AnkiMediaCollection.cs