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