NAME PURPOSE
The preferences.library provides a convenient way to store the
preferences for your program. All internal management and I/O of your
data is handled by the library, and is controlled via a simple interface
which makes use of identifiers and tags to access the data. Multiple
programs can access the data (held only once in memory) at the same time
as access is arbitrated through the use of semaphores.
OVERVIEW
Most of the data and structures mentioned here will be unavailable to
the programmer, but it is useful to know, so that the correct use of the
library can be adhered to.
* All accesses to a preferences structure must be made through a
"PrefsHandle". A PrefsHandle is accessed by name (maximum of 32
unique characters) using AllocPrefsHandle(). Within a PrefsHandle a
list of ID's within this handle is stored. The pointer remains valid
until you call FreePrefsHandle().
* The ID's are the first level of separation of preference data. Each
ID must be 4 ASCII characters, for example "MAIN", or "MENU". For
creating the ID you can use the MAKE_ID macro as defined in
libraries/iffparse.h. ID's are unique within each PrefsHandle. This
means that you can have an ID "MAIN" within two PrefsHandle's
and they will be completely different ID's.
* The second level of separating the data is to use tags. A tag can have
any value except 0. The data is stored along with the tag. Tags are
unique within an ID the same way an ID is unique within a PrefsHandle.
This gives the following structure to preferences items:
Main list of all preferences handles
/ | \
______________/ | \___________________
/ | \
PrefsHandle PrefsHandle ... PrefsHandle
_/ \_
/ \
ID ______ID
_/ |\ / __/ |\
/ | \ | / / \ etc.
Tag+ | Tag+ | Tag+ | Tag+
Data | Data | Data | Data
| | |
Tag+ Tag+ Tag+
Data Data Data
The data can be manipulated in these structures using SetPreferences()
to set the data and GetPreferences() to retrieve the data.
There is an alternative way to store the data. You can also have a list
of data items for each tag value. NB: you cannot mix normal single data
tags and their functions with the list type tags and their functions.
This is achieved using SetEntry(), GetEntry() and RemEntry() functions.
Each data item in the list is accessed using a logical entry number.
Since the data items are not explicitly accessed using this entry
number (such as with an array), their positions can change when you add
items in the middle of the list. For this reason you cannot guarantee
the order of data items in this sub-list. Applications of this method of
storing data could be a list of files which your program runs at
startup, without needing them to be in any specific order.
FindPreferences() will return a pointer to the tag specified and can be
used to find whether a certain tag exists or to access the data (if you
know the internal structure of tag items :). This works for either
type of tag (single data item or list of data items).
ReadPrefsHandle() and WritePrefsHandle() can be used to read or write an
entire PrefsHandle in the specified file.
NAME
AllocPrefsHandle -- Allocate preferences handle
SYNOPSIS
prefshandle = AllocPrefsHandle( name )
D0 A0
APTR AllocPrefsHandle( CONST_STRPTR );
FUNCTION
Allocate a handle so that the preferences inside can be accessed. All
successful calls to this function must be matched by a call to the
FreePrefsHandle() function.
INPUTS
name - a string that you can identify the preferences set by
RESULT
prefshandle - a pointer to the newly allocated preferences set or NULL
for failure.
EXAMPLE
NOTES
BUGS
SEE ALSO
NAME
FindPreferences -- get pointer to data stored for a preference tag
SYNOPSIS
prefsstruct = FindPreferences(prefshandle, ID, Tag);
D0 A0 D0 D1
struct PrefsStruct *FindPreferences(APTR, ULONG, ULONG);
FUNCTION
Searchs for the preferences entry specified by the preferences handle,
ID and Tag values and returns a pointer to whatever is stored there.
Similar to GetPreferences() and GetEntry(), but since it does not copy
any data can be used on both types of tag it can be used to find out
whether a tag is present in a PrefsHandle.
INPUTS
PrefsHandle - pointer to a previously successfully allocated
preferences handle
ID - id of the set within the preferences handle you wish to
use
Tag - the tag used to identify this preference data within the
the ID set
RESULT
prefsstruct - pointer to the preferences item if found, NULL otherwise
EXAMPLE
NOTES
The returned pointer will return a pointer to the tag item, which will
either be followed by the data (if set with SetPreferences()) or the
list of sub items (if set by SetEntry()).
BUGS
SEE ALSO
AllocPrefsHandle(), SetPreferences(), SetEntry(), GetPreferences(),
GetEntry()
NAME
FreePrefsHandle -- free a previously allocated preferences handle
SYNOPSIS
FreePrefsHandle(PrefsHandle);
A0
void FreePrefsHandle(APTR);
FUNCTION
Frees the preferences set associated with the handle passed into this
function. This handle can ONLY be created by calling AllocPrefsHandle
successfully. You MUST NOT use this preferences handle after you free
it.
INPUTS
PrefsHandle - pointer to the preferences handle successfully allocated
using AllocPrefsHandle()
RESULT
SEE ALSO
NAME
GetEntry -- fills in a user structure from a preferences item
SYNOPSIS
bytescopied = GetEntry(PrefsHandle, ID, Tag, Struct, Struct_Size, Entry)
D0 A0 D0 D1 A1 D2 D3
ULONG GetEntry(APTR, ULONG, ULONG, APTR, UWORD, ULONG);
FUNCTION
Copies the data stored in a preferences item to a struture or area of
memory supplied by the programmer. The preference item will come from
the list item at position "Entry" from the list in the Tag / ID /
preferences handle.
INPUTS
PrefsHandle - pointer to a previously successfully allocated
preferences handle
ID - id of the set within the preferences handle you wish to
use
Tag - the tag used to identify this preference data within the
the ID set
Struct - pointer to the structure/memory you wish to copy the
preferences data to
Struct_Size - size of the structure/memory
Entry - the position in the Tag's entry list to read this data
from
RESULT
bytescopied - the actual number of bytes copied from the preference data
to the structure/memory pointer.
EXAMPLE
NOTES
DO NOT MIX this command with Tag's which have had their preference data
set with SetPreferences. They are different internally. Only use this
with Tag's used with SetEntry.
BUGS
SEE ALSO
AllocPrefsHandle(), SetPreferences(), SetEntry()
NAME
GetPreferences -- returns data from a preference item to the programmer
SYNOPSIS
bytescopied = GetPreferences(PrefsHandle, ID, Tag, Struct, Struct_Size);
D0 A0 D0 D1 A1 D2
ULONG GetPreferences(APTR, ULONG, ULONG, const APTR, UWORD);
FUNCTION
Copies the data stored in a preferences item (as referenced the prefs
handle, ID and Tag values) into a structure/memory that the user passes.
The number of bytes actually copied will be returned.
INPUTS
PrefsHandle - pointer to a previously successfully allocated
preferences handle
ID - id of the set within the preferences handle you wish to
use
Tag - the tag used to identify this preference data within the
the ID set
Struct - pointer to the structure/memory you wish to store
Struct_Size - size of the structure/memory
RESULT
EXAMPLE
NOTES
This function does nothing if the ID and Tag values are 0, as they are
not considered valid as an ID or a Tag.
This function assumes a single preferences item per tag, DO NOT USE IT
with preferences items set up with the "Entry" functions.
BUGS
SEE ALSO
AllocPrefsHandle(), SetPreferences()
NAME
ReadPrefsHandle -- Load an entire prefs handle from disk
SYNOPSIS
ReadPrefsHandle(PrefsHandle, Filename);
A0 A1
void ReadPrefsHandle(APTR, CONST_STRPTR);
FUNCTION
Attempts to read data from a file on disk (previously saved with
WritePrefsHandle) into the specified preferences handle.
INPUTS
PrefsHandle - pointer to a previously allocated preferences handle
Filename - full path and name of file to load from
RESULT
EXAMPLE
NOTES
Data is stored in memory using SetPreferences() and SetEntry()
functions.
BUGS
Should probably return a value to indicate whether file was read
successfully or not.
SEE ALSO
AllocPrefsHandle(), WritePrefsHandle(), SetPreferences(), SetEntry()
NAME
RemEntry -- remove an preferences item entry from a Tag that has a list
SYNOPSIS
success = RemEntry(PrefsHandle, ID, Tag, Entry);
D0 A0 D0 D1 D2
ULONG RemEntry(APTR, ULONG, ULONG, ULONG);
FUNCTION
Removes a preferences item, that is in a list at position "Entry", at
the given preferences handle, ID and Tag locations.
INPUTS
PrefsHandle - pointer to a previously successfully allocated
preferences handle
ID - id of the set within the preferences handle you wish to
use
Tag - the tag used to identify this preference data within the
the ID set
Entry - the position in the Tag's entry list to read this data
from
RESULT
success - whether the entry was successfully removed or not.
EXAMPLE
NOTES
DO NOT MIX this function with Tag's which have been created with
SetPreferences.
BUGS
SEE ALSO
AllocPrefsHandle(), SetPreferences(), SetEntry()
NAME
SetEntry -- adds preference data to a list of entries related to the Tag
SYNOPSIS
SetEntry(PrefsHandle, ID, Tag, Struct, Struct_Size, Entry)
A0 D0 D1 A1 D2 D3
void SetEntry(APTR, ULONG, ULONG, const APTR, UWORD, ULONG);
FUNCTION
Stores some user data in the preferences item in the preferences handle,
under the specified ID and Tag values. It will be stored at position
"Entry" in a list of values being stored under the given Tag value.
INPUTS
PrefsHandle - pointer to a previously successfully allocated
preferences handle
ID - id of the set within the preferences handle you wish to
use
Tag - the tag used to identify this preference data within the
the ID set
Struct - pointer to the structure/memory you wish to store
Struct_Size - size of the structure/memory
Entry - the position in the Tag's entry list to store this data
RESULT
EXAMPLE
NOTES
DO NOT MIX this command with Tag values which have been created with
SetPreferences. They are different internally. If you have previously
stored data in this PrefsHandle/ID/Tag/Entry combination, it will be
overwritten if the data sizes are the same, otherwise this new data will
be inserted at the position specified.
BUGS
Since the entry can be added at the end of the list (if the position is
not found), this means that it can be added at a position not equal to
the given Entry value. This is not a bug as such, but the function
should probably return the actual position that it is inserted at. Also,
the function can fail (when allocating memory) so it should also return
a value to indicate that failure.
SEE ALSO
AllocPrefsHandle(), SetPreferences()
NAME
SetPreferences -- store data in a preference item
SYNOPSIS
SetPreferences(PrefsHandle, ID, Tag, Struct, Struct_Size);
A0, D0, D1, A1, D2
void SetPreferences(APTR, ULONG, ULONG, const APTR, UWORD);
FUNCTION
Stores a structure of data in the preferences handle, under the given
ID and tag values.
INPUTS
PrefsHandle - pointer to a previously successfully allocated
preferences handle
ID - id of the set within the preferences handle you wish to
use
Tag - the tag used to identify this preference data within the
the ID set
Struct - pointer to the structure/memory you wish to store
Struct_Size - size of the structure/memory
RESULT
EXAMPLE
NOTES
This function does nothing if the ID and Tag values are 0, as they are
not considered valid as an ID or a Tag. This will overwrite any data
that has previously been stored in this PrefsHandle/ID/Tag combination.
This sets up a single preferences item for the given tag. DO NOT MIX
preferences created with this function with the "Entry" commands!!!
BUGS
SEE ALSO
NAME
WritePrefsHandle -- saves an entire preferences handle to a file
SYNOPSIS
WritePrefsHandle(PrefsHandle, Filename);
A0 A1
void WritePrefsHandle(APTR, CONST_STRPTR);
FUNCTION
Stores all the data and structure of the preferences handle to a file
on disk.
INPUTS
PrefsHandle - pointer to a previously allocated preferences handle
Filename - full path and name of file to save to
RESULT
EXAMPLE
NOTES
This function can deal with single or list entries for a Tag value.
BUGS
Should probably return a value to show if the file was successfully
saved or not.
SEE ALSO
AllocPrefsHandle(), ReadPrefsHandle()