===========
nonvolatile
===========

.. This document is automatically generated. Don't edit it!

`Index <index>`_

----------

======================================= ======================================= ======================================= ======================================= 
`DeleteNV()`_                           `FreeNVData()`_                         `GetCopyNV()`_                          `GetNVInfo()`_                          
`GetNVList()`_                          `SetNVProtection()`_                    `StoreNV()`_                            
======================================= ======================================= ======================================= ======================================= 

-----------

DeleteNV()
==========

Synopsis
~~~~~~~~
::

 BOOL DeleteNV(
          STRPTR appName,
          STRPTR itemName,
          BOOL killRequesters );

Function
~~~~~~~~
::


 Delete a piece of data in the nonvolatile storage.


Inputs
~~~~~~
::


 appName         --  the application owning the data to be deleted; maximum
                     length 31
 itemName        --  name of the data to be deleted; maximum length 31
 killRequesters  --  if set to TRUE no system requesters will be displayed
                     during the deletion operation; if set to FALSE, system
                     requesters will be allowed to be displayed


Result
~~~~~~
::

 
 Success / failure indicator.


Notes
~~~~~
::


 The 'appName' and 'itemName' strings may NOT include the characters
 '/' or ':'.



----------

FreeNVData()
============

Synopsis
~~~~~~~~
::

 VOID FreeNVData(
          APTR data );

Function
~~~~~~~~
::


 Free data allocated by nonvolatile.library (GetCopyNV(), GetNVInfo(),
 GetNVList()).


Inputs
~~~~~~
::


 data  --  data got from a nonvolatile.library function; may be NULL in
           which case this function does nothing



See also
~~~~~~~~

`GetCopyNV()`_ `GetNVInfo()`_ `GetNVList()`_ 

----------

GetCopyNV()
===========

Synopsis
~~~~~~~~
::

 APTR GetCopyNV(
          STRPTR appName,
          STRPTR itemName,
          BOOL killRequesters );

Function
~~~~~~~~
::


 Search the nonvolatile storage for the object 'itemName' allocated by
 'appName' and return a copy of the data.


Inputs
~~~~~~
::


 appName         --  name of the application that allocated the item
 itemName        --  the object to look for
 killRequesters  --  if TRUE no system requesters will be allowed to be
                     displayed during the operation of this function


Result
~~~~~~
::


 Pointer to the data assocated with 'itemName' as allocated by 'appName'.
 


See also
~~~~~~~~

`FreeNVData()`_ `libraries/nonvolatile.h </documentation/headerfiles/libraries/nonvolatile.h>`_ 

----------

GetNVInfo()
===========

Synopsis
~~~~~~~~
::

 struct NVInfo * GetNVInfo(
          BOOL killRequesters );

Function
~~~~~~~~
::


 Report information on the user's preferred nonvolatile storage device.


Inputs
~~~~~~
::


 killRequesters  --  if TRUE no system requesters will be displayed during
                     the operation of this function


Result
~~~~~~
::


 Pointer to an NVInfo structure containing the information on the nonvolatile
 storage device currently in use. Returns NULL in case of a failure.
 


See also
~~~~~~~~

`FreeNVData()`_ `StoreNV()`_ `libraries/nonvolatile.h </documentation/headerfiles/libraries/nonvolatile.h>`_ 

----------

GetNVList()
===========

Synopsis
~~~~~~~~
::

 struct MinList * GetNVList(
          STRPTR appName,
          BOOL killRequesters );

Function
~~~~~~~~
::


 Returns a list of items allocated by application 'appName'.


Inputs
~~~~~~
::


 appName         --  the application the nonvolatile items of which to query
                     about
 killRequesters  --  if TRUE you make sure that no system requesters will be
                     displayed during the operation of this function


Result
~~~~~~
::


 Pointer to a MinList of NVEntries which describes the items. Failure due to
 lack of memory will be indicated by returning NULL.
 

Notes
~~~~~
::


 The protection field should be examined using the field masks NVIF_DELETE
 or by the bit definition NVIB_DELETE as the other bits are reserved for
 system use.



See also
~~~~~~~~

`FreeNVData()`_ `SetNVProtection()`_ `libraries/nonvolatile.h </documentation/headerfiles/libraries/nonvolatile.h>`_ 

----------

SetNVProtection()
=================

Synopsis
~~~~~~~~
::

 BOOL SetNVProtection(
          STRPTR appName,
          STRPTR itemName,
          LONG mask,
          BOOL killRequesters );

Function
~~~~~~~~
::


 Set the protection attributes for a nonvolatile item.


Inputs
~~~~~~
::


 appName         --  the application owning the item stored in nonvolatile
                     memory
 itemName        --  the name of the item to change the protection of
 mask            --  the new protection status
 
 killRequesters  --  if TRUE no system requesters will be displayed during
                     the operation of this function


Result
~~~~~~
::


 Success / failure indicator.
 

Notes
~~~~~
::


 The only bit that should currently be used in the 'mask' is the DELETE bit.



See also
~~~~~~~~

`GetNVList()`_ `libraries/nonvolatile.h </documentation/headerfiles/libraries/nonvolatile.h>`_ 

----------

StoreNV()
=========

Synopsis
~~~~~~~~
::

 LONG StoreNV(
          STRPTR appName,
          STRPTR itemName,
          APTR data,
          ULONG length,
          BOOL killRequesters );

Function
~~~~~~~~
::


 Save data in the nonvolatile storage.


Inputs
~~~~~~
::


 appName         --  the application to save an item in the nonvolatile
                     storage
 itemName        --  the name of the item to save
 data            --  the data to save
 length          --  number of tens of bytes of the data to save rounded
                     upwards (for instance to save 24 bytes specify 3).
 killRequesters  --  if TRUE no system requesters will be displayed during
                     the operation of this function


Result
~~~~~~
::


 Indication of the success of the operation
 
     0                --  no error
     NVERR_BADNAME    --  'appName' or 'itemName' were not correctly
                          specified names
     NVERR_WRITEPROT  --  the nonvolatile storage is read only
     NVERR_FAIL       --  failure in data saving (storage is full or write
                          protected)
     NVERR_FATAL      --  fatal error (possible loss of previously saved
                          data)
 

Notes
~~~~~
::


 The strings 'appName' and 'itemName' should be descripive but short as the
 size of the nonvolatile storage may be very limited. The strings may not
 contatin the characters ':' or '/'. The maximum length for each of these
 strings is 31.



See also
~~~~~~~~

`GetCopyNV()`_ `GetNVInfo()`_ 

