40 Preferences

This chapter provides reference material for the preferences API. The preferences API is declared in the header file Preferences.h.

Preferences Functions

PrefGetAppPreferences

Purpose

Return a copy of an application's preferences. Sometimes, for variable length resources, this routine is called twice:

• Once with a NULL pointer and size of zero to find out how many bytes need to be read.
  
  
• A second time with an allocated buffer allocated of the correct size. Note that the application should always check that the return value is greater than or equal to prefsSize.
  

Prototype

Int16 PrefGetAppPreferences (UInt32 creator, UInt16 id, void* prefs, UInt16* prefsSize, Boolean saved)

Parameters

creator

Application creator.

id

ID number (lets an application have multiple preferences).

prefs

Pointer to a buffer to hold preferences.

prefsSize

Pointer to size the buffer passed.

saved

If true, retrieve the saved preferences. If false, retrieve the current preferences.

Result

Returns the constant noPreferenceFound if the preference resource wasn't found.

If the preference resource was found, the application should check that the value in prefsSize is equal or less than the return value. If it's greater than the size passed, then some bytes were not retrieved.

Compatibility

Implemented only if 2.0 New Feature Set is present.

See Also

PrefSetPreferences, PrefGetAppPreferencesV10

PrefGetAppPreferencesV10

Purpose

Return a copy of an application's preferences.

Prototype

Boolean PrefGetAppPreferencesV10 (UInt32 type, Int16 version, void* prefs, UInt16 prefsSize)

Parameters

type

Application creator type.

version

Version number of the application.

prefs

Pointer to a buffer to hold preferences.

prefsSize

Size of the buffer passed.

Result

Returns false if the preference resource was not found or the preference resource contains the wrong version number.

Comments

The content and format of an application preference is application-dependent.

Compatibility

This function corresponds to the 1.0 version of PrefGetAppPreferences.

See Also

PrefSetPreferences, PrefGetAppPreferences

PrefGetPreference

Purpose

Return a system preference. Use this instead of PrefGetPreferences.

Prototype

UInt32 PrefGetPreference (SystemPreferencesChoice choice)

Parameters

choice

System preference choice; see Preferences.h for available options.

Result

Returns the system preference.

Comments

This function replaces the 1.0 function PrefGetPreferences. While PrefGetPreferences only let you retrieve the whole system preferences structure, this function lets you specify which preferences to retrieve. You can also choose among different preferences using an ID, or choose to access the saved or unsaved preferences.

Compatibility

Implemented only if 2.0 New Feature Set is present.

See Also

PrefSetPreferences, PrefGetAppPreferences, PrefGetAppPreferencesV10

PrefGetPreferences

Purpose

Return a copy of the system preferences.

Prototype

void PrefGetPreferences (SystemPreferencesPtr p)

Parameters

p

Pointer to system preferences.

Result

Returns nothing. Stores the system preferences in p.

Comments

The p parameter points to a memory block allocated by the caller that is filled in by this function.

This function is often called in StartApplication to get localized settings.

See Also

PrefSetPreferences

PrefOpenPreferenceDBV10

Purpose

Return a handle to the system preference database.

Prototype

DmOpenRef PrefOpenPreferenceDBV10 (void)

Parameters

Nothing.

Result

Returns the handle, or 0 if an error results.

Comments

This function is for system use only in Palm OS^® 2.0 and later.

Compatibility

This function corresponds to the 1.0 version of PrefOpenPreferenceDB.

See Also

PrefGetPreferences, PrefSetPreferences

PrefSetAppPreferences

Purpose

Set an application's preferences in the preferences database.

Prototype

void PrefSetAppPreferences (UInt32 creator, UInt16 id, Int16 version, void* prefs, UInt16 prefsSize, Boolean saved)

Parameters

creator

Application creator type.

id

Resource ID (usually 0).

version

Version number of the application.

prefs

Pointer to a buffer that holds preferences.

prefsSize

Size of the buffer passed.

saved

If true, set the saved preferences. If not, set the current preferences.

Result

Returns nothing.

Compatibility

Implemented only if 2.0 New Feature Set is present.

See Also

PrefSetAppPreferencesV10

PrefSetAppPreferencesV10

Purpose

Save an application's preferences in the preferences database.

Prototype

void PrefSetAppPreferencesV10 (UInt32 creator, Int16 version, void* prefs, UInt16 prefsSize)

Parameters

creator

Application creator type.

version

Version number of the application.

prefs

Pointer to a buffer holding preferences.

prefsSize

Size of the buffer passed.

Result

Returns nothing.

Comments

The content and format of an application preference is application-dependent.

Compatibility

This function corresponds to the 1.0 version of PrefSetAppPreferences.

See Also

PrefSetAppPreferences, PrefGetPreferences

PrefSetPreference

Purpose

Set a system preference. Using this function instead of PrefSetPreferences allows you to set selected preferences without having to access the whole structure.

Prototype

void PrefSetPreference (SystemPreferencesChoice choice, UInt32 value)

Parameters

choice

A SystemPreferencesChoice (see Preferences.h)

value

Value to assign to the item in SystemPreferencesChoice.

Result

Returns the system preference.

Compatibility

Implemented only if 2.0 New Feature Set is present.

PrefSetPreferences

Purpose

Set the system preferences.

Prototype

void PrefSetPreferences (SystemPreferencesPtr p)

Parameters

p Pointer to system preferences.

Result

Returns nothing.

Comments

Unless there's a reason for you to access the whole preferences structure, call PrefSetPreference instead.

See Also

PrefGetPreferences