Skip to content

Layer 2 Registration and Identity

Jump to bottom
abduznik edited this page Jul 15, 2026 · 7 revisions

Layer 2 — Registration and Identity

Registration is how the library learns about a save file. Identity resolution determines what game a save belongs to.

Registration

sv_register() creates a new registration from a live_save_path (required) plus optional metadata:

  • rom_path — path to the ROM/disc image
  • platform — target platform identifier
  • emulator — emulator name/version
  • product_version — emulator/core/backend version
  • mode — SV_MODE_DEFAULT or SV_MODE_STRATEGY

Produces an opaque sv_registration_t* handle and a persistent 8-character unique ID.

Updating

sv_update_register() mutates an existing registration using an explicit set_mask bitfield. The bitfield distinguishes "leave unchanged" from "explicitly reset to default/empty," since update semantics can't rely on zero-default alone.

Includes a "poke check" against the destination path: reports SV_CONFLICT_EXISTING_DATA by default rather than guessing. Caller can pass SV_ON_CONFLICT_OVERRIDE or SV_ON_CONFLICT_ABORT_SILENT explicitly.

Relocation supports:

  • SV_RELOCATE_COPY (default, non-destructive)
  • SV_RELOCATE_MOVE (copy-verify-then-delete-source, never delete-then-copy)

Unregistering

sv_unregister() drops the metadata record only — it never touches the magazine or live files. Entries under a removed registration become orphans (parent_id zeroed), not deleted.

Identity Resolution (STRATEGY mode)

In SV_MODE_STRATEGY, identity resolution uses a tiered approach:

  1. Embedded serial extraction (zero external data needed): PSP/PS1/PS2 SYSTEM.CNF/PARAM.SFO, Saturn IP.BIN, GameCube/Wii boot headers
  2. Header checksums: SNES/Genesis internal checksum + file size
  3. Pluggable hash-database module (optional, database-free core): for remaining edge cases

In SV_MODE_DEFAULT, none of this runs — it's a bare, generic file/folder tracker.

Mode Selection

Mode Identity Manifest Use Case
SV_MODE_DEFAULT None None Generic testing, simple sync
SV_MODE_STRATEGY Tiered resolution Per-platform/emulator Real emulator save management

See also: Architecture-Overview | Layer-3-Metadata-Store | API-Reference

libsavesync Wiki

Clone this wiki locally