These APIs are:

• PrefGetAppPreferences
• PrefGetPreferences
• PrefOpenPreferencesDB
• PrefSetAppPreferences
• PrefSetPreferences

The names changed when the PalmPilots came out with Palm OS version 2.

PrefGetPreferences and PrefSetPreferences read and write the system preferences structure all at one time. This structure contains things like the date and time display format, the auto-shut-off time, whether or not private records should be displayed and so forth. The structure is defined in preferences.h. If you're using the Palm OS 2 or 3 SDK, the OS 1 structure is a typedef named SystemPreferencesTypeV10. This structure is shown at http://www.component-net.com/pp-extras/prefs1.html.

PrefGetAppPreferences and PrefSetAppPreferences allow you to read and write an arbitrary structure (you define whatever you want) to the preferences database. Essentially, as your program exits you copy any data you want to save to a structure, then tell Palm OS to save it as the preferences for this program. When you start up the next time, you read the preferences and use that as the starting configuration.

The Palm OS 1 APIs always use the saved preferences database.

Palm OS version 2
One of the big improvements when the PalmPilot Professional and PalmPilot Personal came out was the upgrade to Palm OS version 2.

Several of the OS 1 APIs were renamed by appending "V10" to them, and replaced by several new APIs with additional functionality. This structure is shown at http://www.component-net.com/pp-extras/prefs2.html.

The OS 2 preferences APIS are:

• PrefGetAppPreferences
• PrefGetAppPreferencesV10
• PrefGetPreference
• PrefGetPreferences
• PrefOpenPreferenceDB
• PrefOpenPreferenceDBV10
• PrefSetAppPreferences
• PrefSetAppPreferencesV10
• PrefSetPreference
• PrefSetPreferences

PrefOpenPreferenceDB isn't listed in the OS 2 or OS 3 documentation, but it is in the preferences.h file.

The system preferences structure also changed, and in a rather ugly way. New data was inserted in the middle of the structure, in addition to new preferences appended to the end of the structure. This is unfortunate since it breaks older code. If an older program gets the system preferences structure to find the "hide secret records" boolean, it will look at the wrong place in the OS 2 structure because gameSoundLevel was inserted before it -- moving the later data down.

Fortunately, when the PalmPilots came out, developers were quick to update their Pilot 1000 and Pilot 5000 applications. At this point virtually all apps work with OS 1 and OS 2, and almost all work with OS 3.

The xxxV10 APIs are the original APIs from Palm OS version 1. Only the name has changed. Old programs calling the old APIs call these V10 APIs automatically. Their internal system-trap numbers haven't changed.

The newer functions PrefGetPreference and PrefSetPreference get and set the system preferences a single preference at a time. There's no need to know the overall structure, just an identification number. These numbers are enumerated in preferences.h. For example, you can get the show-hidden-records setting by calling PrefGetPreference(prefHidePrivateRecords).