Inhaltsverzeichnis

nonvolatile.library/--Hintergrund--
nonvolatile.library/DeleteNV
nonvolatile.library/FreeNVData
nonvolatile.library/GetCopyNV
nonvolatile.library/GetNVInfo
nonvolatile.library/GetNVList
nonvolatile.library/SetNVProtection
nonvolatile.library/StoreNV


nonvolatile.library/--Hintergrund--         nonvolatile.library/--Hintergrund--

   ZWECK
        Die nonvolatile.library bietet dem Entwickler von Anwendungen
        einfache Mittel, um nichtflüchtige (nonvolatile) Speicherung zu
        handhaben.

   ÜBERBLICK
        Die nonvolatile.library kann transparent über alle Konfigurationen
        hinweg benutzt werden. Derzeit kann nichtflüchtige Speicherung
        in NVRAM und/oder auf Disk-Geräten erfolgen. Die nonvolatile.library
        greift automatisch auf die beste Speichermöglichkeit zu, die das
        System bietet. Zunächst wird auf Disk-Medien basierende Speicherung
        ausgewählt und wenn diese nicht zur Verfügung steht, wird auf NVRAM-
        Speicherung zurückgegriffen. 

    * NVRAM

        Auf Amiga-Einstiegsgeräten ohne Diskettensystem kann NVRAM zur
        Verfügung stehen. Dieses RAM behält seinen Dateninhalt bei, auch
        wenn das System abgeschaltet wird. Das geschieht unabhängig davon,
        ob Batterien oder Batterie-gestützte Uhren vorhanden sind. Die im
        NVRAM gespeicherten Daten sind nur über die im ROM untergebrachten
        Funktionsaufrufe der nonvolatile.library zugänglich. Die Größe des
        NVRAM-Speichers hängt von der System-Plattform ab und kann durch die
        Funktion GetNVInfo() ermittelt werden.

    * Disk

        Um die allgemeinen Möglichkeiten zur Konfiguration des Amiga
        beibehalten zu können, kann die aktuell Disk-Position, die von der
        nonvolatile.library zum Speichern benützt wird, durch den Anwender
        verändert werden.

        Auf dem Amiga wird das Verzeichnis "prefs" zur Speicherung vieler
        vom Benutzer einstellbarer Möglichkeiten verwendet. Der Platz auf dem
        Plattenspeicher für die nichtflüchtige Speicherung ist in der Datei
        "prefs/env-archive/sys/nv_location" angegeben. Diese Datei sollte
        eine Zeichenkette enthalten, die einen festlegbaren (lockable) Ort
        (Dateipfad) angibt. Wenn die Zeichenkette keinen ansprechbaren Ort
        angibt, wird die Datei ignoriert.

        Wenn die nonvolatile.library geöffnet wird, sucht sie alle Laufwerke
        des Systems ab, bis sie diese Datei findet und und erfolgreich eine
        Verbindung mit dem Ort, der darin angegeben ist, herstellt. Um eine
        erneute Suche in allen Laufwerken zu erzwingen, kann die Library
        geschlossen und wieder geöffnet werden oder es muss die Funktion
        GetNVInfo() ausgeführt werden.

        Eine einfache Methode zur Erstellung einer Diskette zur Speicherung
        nichtflüchtiger Daten ist folgende:
        
        Formatieren einer Diskette mit dem Namen "NV".
        Erzeugen eines Pfades "prefs/env-archive/sys/nv_location", wobei die
        Datei "nv_location" folgendes enthält: "NV:nonvolatile".
        Erzeugen eines Verzeichnisses mit dem Namen "nonvolatile".

        Das folgende Script kann zur Herstellung einer Diskette zur Verwendung
        mit der nonvolatile.library benutzt werden:

    .KEY DRIVE/A,DISK
    .BRA {
    .KET }
    format Drive {DRIVE} Name {DISK$NV} noicons ffs
    makedir {DRIVE}prefs
    makedir {DRIVE}nonvolatile
    makedir {DRIVE}prefs/env-archive
    makedir {DRIVE}prefs/env-archive/sys
    echo {DISK$NV}:nonvolatile >{DRIVE}prefs/env-archive/sys/nv_location

    !!!Anmerkung!!!

        Da NVRAM einen Disk-Zugriff ausführt, muss seine Funktionalität
        von einem DOS-Prozess aus geöffnet und angewendet werden, nicht
        von einem EXEC-Auftrag (task). Normalerweise wird eine CDGS-Anwendung
        als DOS-Prozess aufgerufen, deshalb sollte diese Forderung kein
        Problem darstellen. Man muss nur diese Forderung beachten, wenn ein
        EXEC-Vorgang erzeugt wird und daraus die nonvolatile.library
        aufgerufen werden soll.


nonvolatile.library/DeleteNV                     nonvolatile.library/DeleteNV

   NAME
    DeleteNV -- Entfernen eines Eintrags aus dem nichtflüchtigen
                    (nonvoltatile) Speicher. (V40)

   SYNOPSIS
    success = DeleteNV(appName, itemName, killRequesters);
    D0           A0        A1          D1

    BOOL DeleteNV(STRPTR, STRPTR, BOOL);

   FUNKTION
        Sucht im nichtflüchtigen Speicher nach dem angegebenen Eintrag und
        entfernt ihn.

        Die Zeichenketten appName und itemName dürfen die Zeichen '/' oder ':'
        nicht enthalten. Es wird empfohlen diese Zeichen abzublocken, wenn
        vom Anwender Eingaben in die Zeichenketten AppName and ItemName
        angefordert werden.

   EINGABEN
        appName - Mit NULL terminierte Zeichenkette, die die Anwendung
                  identifiziert, welche die Daten erzeugt hat. Maximale
                  Länge ist 31.
        ItemName - Mit NULL terminierter Zeichensatz, der eindeutig die
                   Daten in der Anwendung kennzeichnet. Maximale Länge
                   ist 31.
        killRequesters - Flag zum Unterdrücken der System-Requester.
                         TRUE bedeutet, dass alle System-Requester
                         während dieser Funktion zu unterdrücken sind,
                         FALSE bedeutet, dass System-Requester zugelassen
                         sind.

   RÜCKGABE
    success - TRUE wird zurückgegeben, wenn der Eintrag gefunden und
                  gelöscht wurde. Wurde der Eintrag nicht gefunden, wird
                  FALSE zurückgegeben.


nonvolatile.library/FreeNVData                 nonvolatile.library/FreeNVData

   NAME
    FreeNVData -- Gibt den Speicher frei, der von einer Funktion dieser
                      Library belegt wurde. (V40)

   SYNOPSIS
    FreeNVData(data);
           A0

    VOID FreeNVData(APTR);

   FUNKTION
        Gibt einen Speicherblock frei, der durch einer der folgenden
        Funktionen belegt wurde:
    GetCopyNV(), GetNVInfo(), GetNVList().

   EINGABEN
    data - Zeiger auf den Speicherblock, der frei gegeben werden soll.
               Wenn NULL übergeben wird, passiert garnichts.

   SIEHE AUCH
    GetCopyNV(), GetNVInfo(), GetNVList()


nonvolatile.library/GetCopyNV                   nonvolatile.library/GetCopyNV

   NAME
    GetCopyNV -- Gibt eine Kopie eines Elementes zurück, das im
                     nichtflüchtigen Speicher abgelegt ist. (V40)

   SYNOPSIS
    data = GetCopyNV(appName, itemName, killRequesters);
    D0         A0      A1        D1

    APTR GetCopyNV(STRPTR, STRPTR, BOOL);

   FUNKTION
        Durchsucht den nichtflüchtigen Speicher nach dem angegebenen
        appName und itemName. Ein Zeiger auf eine Kopie dieser Daten
        wird zurück gegeben.

        Die Zeichenketten appName und itemName dürfen die Zeichen '/' oder
        ':' nicht enthalten. Es wird empfohlen diese Zeichen abzublocken,
        wenn vom Anwender Eingaben in die Zeichenketten appName and itemName
        angefordert werden.

   EINGABEN
        appName - Mit NULL terminierte Zeichenkette, die den Namen der
                  Anwendung enthält, die gesucht wird. Maximale Länge ist 31.
        itemName - Mit NULL terminierter Zeichensatz, der eindeutig den
                   Eintrag in der gesuchten Anwendung kennzeichnet.
                   Maximale Länge ist 31.
        killRequesters - Flag zum Unterdrücken der System-Requester. TRUE
                         bedeutet, dass alle System-Requester während dieser
                         Funktion zu unterdrücken sind, FALSE bedeutet, dass
                         System-Requester zugelassen sind.
 
   RÜCKGABE
    data - Zeiger auf eine Kopie der Daten, die im nichtflüchtigen
               Speicher in Verbindung mit appName and itemName gefunden
               wurden. NULL wird zurück gegeben, wenn zu wenig Speicher
               vorhanden ist oder appName/itemName nicht existieren.

   SIEHE AUCH
    FreeNVData(), 


nonvolatile.library/GetNVInfo                   nonvolatile.library/GetNVInfo

   NAME
    GetNVInfo -- Informationen über den aktuellen nichtflüchtigen
                     Speicher. (V40)

   SYNOPSIS
    information = GetNVInfo(killRequesters);
    D0            D1

    struct NVInfo *GetNVInfo(BOOL);

   FUNKTION
        Findet das vom Anwender bevorzugte nichtflüchtige Gerät (nonvolatile
        device) und gibt Informationen darüber aus.

   EINGABEN
    killRequesters - Flag zum Unterdrücken der System-Requester. TRUE
                         bedeutet, dass alle System-Requester während dieser
                         Funktion zu unterdrücken sind, FALSE bedeutet, dass
                         System-Requester zugelassen sind.

   RÜCKGABE
    information - Zeiger auf eine NVInfo-Struktur. Diese Struktur enthält
                      Informationen über das NV-Speicher-Medium mit dem
                      größten Speicher. Die Struktur enhält zwei Langwort-
                      Felder: nvi_MaxStorage und nvi_FreeStorage. Beide Werte
                      sind auf die nächst niedrige Zehnerzahl abgerundet. Das
                      Feld nvi_MaxStorage ist definiert als die Gesamtmenge
                      an nichtflüchtigem Speicher auf diesem Gerät.
                      nvi_FreeStorage ist definiert als der zur Verfügung
                      stehende Bereich für NVDISK oder die Menge an nicht
                      gebundenem (non-locked) Speicher für NVRAM. Für NVDISK
                      berücksichtigt nvi_FreeStorage die Menge an zusätzlichem
                      Platz, der zum Speichern von neuen App/Items benötigt
                      wird. Diese Menge beträgt 3 Blöcke, um Platz zu bieten
                      zum Speichern einer neuen Datei mit Einträgen (items)
                      und möglicherweise eines neuen App-Verzeichnisses. Für
                      NVRAM ist die Zusatzmenge 5 Bytes. Jedoch hängt der
                      benötigte Platz zur Speicherung eines neuen NVRAM-
                      Eintrags von der Länge der App- und Eintrags-Namen ab.
                      Wegen Einzelheiten der Speicherung ist die Funktion
                      StoreNV() zu beachten.

                      Diese Funktion gibt im Fehlerfall NULL zurück.
 
   SIEHE AUCH
    FreeNVData(), StoreNV(), 


nonvolatile.library/GetNVList                   nonvolatile.library/GetNVList

   NAME
    GetNVList -- Gibt eine Liste der im nichtflüchtigen Speicher
                     abgelegten Einträge zurück. (V40)

   SYNOPSIS
    list = GetNVList(appName, killRequesters);
    D0         A0      D1

    struct MinList *GetNVList(STRPTR, BOOL);

   FUNKTION
        Gibt einen Zeiger auf eine EXEC-Liste mit nichtflüchtigen
        Einträgen zurück, die mit dem angegebenen appName zusammenhängen.

        Die Zeichenkette appName darf die Zeichen '/' oder ':' nicht
        enthalten. Es wird empfohlen diese Zeichen abzublocken, wenn
        vom Anwender Eingaben in die Zeichenkette appName angefordert
        werden.

   EINGABEN
    appName - NULL-terminierte Zeichenkette, die den Namen der Anwendung
                  enthält, der gesucht wird. Maximale Länge ist 31.
    killRequesters - Flag zum Unterdrücken der System-Requester. TRUE
                         bedeutet, dass alle System-Requester während dieser
                         Funktion zu unterdrücken sind, FALSE bedeutet, dass
                         System-Requester zugelassen sind.

   RÜCKGABE
    list - Ein Zeiger auf eine Exec-MinList mit NV-Einträgen. Eine
               NULL wird zurückgegeben, wenn zu wenig Speicher vorhanden
               ist. Wenn für den appName keine Einträge im nichtflüchtigen
               Speicher vorhanden sind, wird eine leere Liste zurück gegeben.

   ANMERKUNG
        Das Feld für Markierungsbits (protection field) enthält mehr Bits,
        als für die Speicherung des Löschschutz-Status erforderlich sind.
        Diese Bits sind reserviert für ander Systemanwendungen und sind
        möglicher Weise nicht Null. Wenn auf den Lösch-Status geprüft
        werden soll, ist entweder die Feld-Maske NVIF_DELETE oder die
        Bit-Definition NVIB_DELETE zu verwenden.

   SIEHE AUCH
    FreeNVData(), SetNVProtection()


nonvolatile.library/SetNVProtection       nonvolatile.library/SetNVProtection

   NAME
    SetNVProtection -- Setzen der Schutz-(protection)-Flags. (V40)

   SYNOPSIS
    success = SetNVProtection(appName, itemName, mask, killRequesters);
    D0              A0       A1         D2    D1

    BOOL SetNVProtection(STRPTR, STRPTR, LONG, BOOL);

   FUNKTION
        Setzt die Schutz-(protection)-Attribute für einen Eintrag im
        nichtflüchtigen Speicher.

        Obwohl 'mask' LONG ist, kann nur das Löschschutz-Bit
        NVEF_DELETE/NVEB_DELETE gesetzt werden. Wenn irgend ein anderes
        Bit gesetzt wird, gibt die Funktion FALSE zurück.

        Die Zeichenketten appName und itemName dürfen die Zeichen '/' oder
        ':' nicht enthalten. Es wird empfohlen diese Zeichen abzublocken,
        wenn vom Anwender Eingaben in die Zeichenketten appName und
        itemName angefordert werden.

   EINGABEN
        appName - Mit NULL terminierte Zeichenkette, die den Namen der
                  Anwendung enthält, die gesucht wird. Maximale Länge
                  ist 31.
        itemName - Mit NULL terminierter Zeichensatz, der eindeutig den
                   Eintrag in der gesuchten Anwendung kennzeichnet.
                   Maximale Länge ist 31.
        mask - Die neue Schutzbit-Maske. Nur das Lösch-Bit darf gesetzt
               werden, sonst ERZEUGT diese Funktion einen CRASH.
        killRequesters - Flag zum Unterdrücken der System-Requester.
                         TRUE bedeutet, dass alle System-Requester während
                         dieser Funktion zu unterdrücken sind, FALSE
                         bedeutet, dass System-Requester zugelassen sind.

   RÜCKGABE
    success - FALSE, wenn das Schutzbit nicht verändert werden konnte
                  (d.h. die Daten existieren nicht).

   SIEHE AUCH
    GetNVList(), 


nonvolatile.library/StoreNV                       nonvolatile.library/StoreNV

   NAME
    StoreNV --  Daten im nichtflüchtigen Speicher ablegen. (V40)

   SYNOPSIS
    error = StoreNV(appName, itemName, data, length, killRequesters);
    D0        A0     A1       A2    D0     D1

    UWORD StoreNV(STRPTR, STRPTR, APTR, ULONG, BOOL);

   FUNKTION
        Damit werden Daten im nichtflüchtigen Speicher gesichert. Die
        Daten sind durch appName und itemName markiert und können später
        zurück geholt werden. Ein einzelner Eintrag sollte in keinem
        Falle größer sein als ein Viertel des maximal zur Verfügung
        stehenden Platzes, der durch GetNVInfo() angezeigt wird.
        
        Mit dieser Funktion ist keine Daten-Kompression verbunden.
        
        Die Zeichenketten appName und itemName sollten kurz, aber klar
        bezeichnend sein. Die Kürze ist notwendig, weil die Zeichenkette
        mit den Daten gespeichert wird und der Bereich für nichtflüchtige
        Speicherung bei reinen Spielsystemen beschränkt ist. Das Spielsystem
        erlaubt dem Anwender, selektiv Einträge zu entfernen, deshalb muss
        die Zeichenkette deutlich beschreibend sein.

        Die Zeichenketten appName und itemName dürfen die Zeichen '/' oder
        ':' nicht enthalten. Es wird empfohlen diese Zeichen abzublocken,
        wenn vom Anwender Eingaben in die Zeichenketten appName und
        itemName angefordert werden.

   EINGABEN
        appName - Mit NULL terminierte Zeichenkette, die den Namen der
                  Anwendung enthält, die gesucht wird. Maximale Länge
                  ist 31.
        itemName - Mit NULL terminierter Zeichensatz, der eindeutig den
                   Eintrag in der gesuchten Anwendung kennzeichnet.
                   Maximale Länge ist 31.
        data - Zeiger auf den Speicherblock, der gesichert werden soll.
        length - Zahl der zu sichernden Bytes in Einheiten von je zehn Bytes.
                 Wenn z.B. 23 Bytes zu speichern sind, ist length = 3; bei
                 147 Bytes ist length = 15.
        killRequesters - Flag zum Unterdrücken der System-Requester. TRUE
                         bedeutet, dass alle System-Requester während dieser
                         Funktion zu unterdrücken sind, FALSE bedeutet, dass
                         System-Requester zugelassen sind.

   RÜCKGABE
    error - 0                Bedeutet kein Fehler,
            NVERR_BADNAME    Fehler in appName oder in itemName.
            NVERR_WRITEPROT  Nicht-flüchtiger Speicher "read only".
            NVERR_FAIL       Fehler beim Schreiben der Daten
                                 (nichtflüchtiger Speicher voll oder
                                 schreibgeschützt.
            NVERR_FATAL      Fataler Fehler beim Zugriff auf nicht-
                                 flüchtigen Speicher, Verlust vorher
                                 gespeicherter nichtflüchtiger Daten ist
                                 möglich.

   SIEHE AUCH
    GetCopyNV(), GetNVInfo()

Nähste Seite
Vorige Seite