nonvolatile.library Reference¶
Comprehensive function reference for nonvolatile.library, synthesised from the AmigaOS NDK 3.2 Release 4 (Autodocs/AG/nonvolatile).
This page documents 7 functions of nonvolatile.library. Each function entry follows the canonical autodoc format. struct Name, union Name, enum Name are clickable links to the type definition in the types reference.
Function index¶
DeleteNV()¶
DeleteNV -- remove an entry from nonvoltatile storage. (V40)
Synopsis
success = DeleteNV(appName, itemName, killRequesters);
D0 A0 A1 D1
BOOL DeleteNV(STRPTR, STRPTR, BOOL);
Function
Searches the nonvolatile storage for the indicated entry and removes it.
The strings appName and itemName may not contain the '/' or ':'
characters. It is recommended that these characters be blocked
from user input when requesting AppName and ItemName strings.
Inputs
appName - NULL terminated string identifing the application that created the data. Maximum length is 31. ItemName - NULL terminated string uniquely identifing the data within the application. Maximum length is 31. killRequesters - suppress system requesters flag. TRUE if all system requesters are to be suppressed during this function. FALSE if system requesters are allowed.
Results
success - TRUE will be returned if the entry is found and deleted. If the entry is not found, FALSE will be returned.
FreeNVData()¶
FreeNVData -- release the memory allocated by a function of this library. (V40)
Synopsis
FreeNVData(data);
A0
VOID FreeNVData(APTR);
Function
Frees a block of memory that was allocated by any of the following: GetCopyNV(), GetNVInfo(), GetNVList().
Inputs
data - pointer to the memory block to be freed. If passed NULL, this function does nothing.
See also
GetCopyNV(), GetNVInfo(), GetNVList()
GetCopyNV()¶
GetCopyNV -- return a copy of an item stored in nonvolatile storage. (V40)
Synopsis
data = GetCopyNV(appName, itemName, killRequesters);
D0 A0 A1 D1
APTR GetCopyNV(STRPTR, STRPTR, BOOL);
Function
Searches the nonvolatile storage for the indicated appName and itemName. A pointer to a copy of this data will be returned.
The strings appName and itemName may not contain the '/' or ':'
characters. It is recommended that these characters be blocked
from user input when requesting appName and itemName strings.
Inputs
appName - NULL terminated string indicating the application name to be found. Maximum length is 31. itemName - NULL terminated string indicated the item within the application to be found. Maximum length is 31. killRequesters - Suppress system requesters flag. TRUE if all system requesters are to be suppressed during this function. FALSE if system requesters are allowed.
Results
data - pointer to a copy of the data found in the nonvolatile storage assocated with appName and itemName. NULL will be returned if there is insufficient memory or the appName/itemName does not exist.
See also
GetNVInfo()¶
GetNVInfo -- report information on the current nonvolatile storage. (V40)
Synopsis
information = GetNVInfo(killRequesters);
D0 D1
struct NVInfo*GetNVInfo(BOOL);
Function
Finds the user's preferred nonvolatile device and reports information about it.
Inputs
killRequesters - suppress system requesters flag. TRUE if all system requesters are to be suppressed during this function. FALSE if system requesters are allowed.
Results
information - pointer to an NVInfo structure. This structure contains information on the NV storage media with the largest storage. The structure contains 2 longword fields: nvi_MaxStorage and nvi_FreeStorage. Both values are rounded down to the nearest ten. The nvi_MaxStorage field is defined as the total amount of nonvolatile storage available on this device. The nvi_FreeStorage is defined as the amount of available space for NVDISK or the amount of non-locked storage for NVRAM. For NVDISK, the nvi_FreeStorage takes into account the amount of overhead room required to store a new App/Item. This amount is 3 blocks to allow room for storing a new Item file and possibly a new App directory. For NVRAM, the amount of overhead is 5 bytes. However, the amount of room required to store a new NVRAM item depends on the length of the App and Item names. Refer to StoreNV() function for storage details.
This function may return NULL in the case of failure.
See also
GetNVList()¶
GetNVList -- return a list of the items stored in nonvolatile storage. (V40)
Synopsis
list = GetNVList(appName, killRequesters);
D0 A0 D1
MinList*GetNVList(STRPTR, BOOL);
Function
Returns a pointer to an Exec list of nonvolatile Items associated with the appName requested.
The string appName may not contain the '/' or ':' characters.
It is recommended that these characters be blocked from user input
when requesting an appName string.
Inputs
appName - NULL terminated string indicating the application name to be matched. Maximum length is 31. killRequesters - Suppress system requesters flag. TRUE if all system requesters are to be suppressed during this function. FALSE if system requesters are allowed.
Results
list - a pointer to an Exec MinList of NVEntries. A NULL will be returned if there is insufficient memory. If there are no entries in the nonvolatile storage for the AppName, an empty list will be returned.
Note
The protection field contains more bits than are required for storing the delete protection status. These bits are reserved for other system usage and may not be zero. When checking for the delete status use either the field mask NVIF_DELETE, or the bit definition NVIB_DELETE.
See also
FreeNVData(), SetNVProtection()
SetNVProtection()¶
SetNVProtection -- set the protection flags. (V40)
Synopsis
success = SetNVProtection(appName, itemName, mask, killRequesters);
D0 A0 A1 D2 D1
BOOL SetNVProtection(STRPTR, STRPTR, LONG, BOOL);
Function
Sets the protection attributes for an item currently in the nonvolatile storage.
Although 'mask' is LONG only the delete bit, NVEF_DELETE/NVEB_DELETE,
may be set. If any other bits are set this function will return
FALSE.
The strings appName and itemName may not contain the '/' or ':'
characters. It is recommended that these characters be blocked
from user input when requesting AppName and ItemName strings.
Inputs
appName - NULL terminated string indicating the application name to be matched. Maximum length is 31. itemName - NULL terminated string indicated the item within the application to be found. Maximum length is 31. mask - the new protection mask. Only set the delete bit otherwise this function WILL CRASH. killRequesters - suppress system requesters flag. TRUE if all system requesters are to be suppressed during this function. FALSE if system requesters are allowed.
Results
success - FALSE if the protection could not be change (ie the data does not exist).
See also
StoreNV()¶
StoreNV -- store data in nonvolatile storage. (V40)
Synopsis
error = StoreNV(appName, itemName, data, length, killRequesters);
D0 A0 A1 A2 D0 D1
UWORD StoreNV(STRPTR, STRPTR, APTR, ULONG, BOOL);
Function
Saves some data in nonvolatile storage. The data is tagged with AppName and ItemName so it can be retrieved later. No single item should be larger than one fourth of the maximum storage as returned by GetNVInfo().
There is no data compression associated with this function.
The strings, AppName and ItemName, should be short, but descriptive.
They need to be short since the string is stored with the data and
the nonvolatile storage for a stand alone game system is limited.
The game system allows the user to selectively remove entries from
storage, so the string should be desriptive.
The strings AppName and ItemName may not contain the '/' or ':'
characters. It is recommended that these characters be blocked
from user input when requesting AppName and ItemName strings.
Inputs
appName - NULL terminated string identifying the application creating the data. Maximum length is 31. itemName - NULL terminated string uniquely identifying the data within the application. Maximum length is 31. data - pointer to the memory block to be stored. length - number of bytes to be stored in the units of tens of bytes. For example, if you have 23 bytes to store length = 3; 147 byte then length = 15. killRequesters - suppress system requesters flag. TRUE if all system requesters are to be suppressed during this function. FALSE if system requesters are allowed.
Results
error - 0 means no error, NVERR_BADNAME error in AppName, or ItemName. NVERR_WRITEPROT Nonvolatile storage is read only. NVERR_FAIL Failure in writing data (nonvolatile storage full, or write protected). NVERR_FATAL Fatal error when accessing nonvolatile storage, possible loss of previously saved nonvolatile data.
See also