nsIPrefService

IID:decb9cc7-c08f-4ea5-be91-a8fc637ce2d2
Inherits From:nsISupports
Status:FROZEN

The nsIPrefService interface is the main entry point into the back end preferences management library. The preference service is directly responsible for the management of the preferences files and also facilitates access to the preference branch object which allows the direct manipulation of the preferences themselves.

This interface is intended to be used as a service.

This interface is implemented by the following components:


Methods

nsIPrefBranch getBranch ( char* prefRoot ) nsIPrefBranch getDefaultBranch ( char* prefRoot ) void readUserPrefs ( nsIFile file ) void resetPrefs ( ) void resetUserPrefs ( ) void savePrefFile ( nsIFile file )

nsIPrefBranch getBranch ( char* prefRoot )

Call to get a Preferences "Branch" which accesses user preference data. Using a Set method on this object will always create or set a user preference value. When using a Get method a user set value will be returned if one exists, otherwise a default value will be returned.

Arguments:
prefRoot: The preference "root" on which to base this "branch". For example, if the root "browser.startup." is used, the branch will be able to easily access the preferences "browser.startup.page", "browser.startup.homepage", or "browser.startup.homepage_override" by simply requesting "page", "homepage", or "homepage_override". nsnull or "" may be used to access to the entire preference "tree".
Returns:
nsIPrefBranch The object representing the requested branch.

nsIPrefBranch getDefaultBranch ( char* prefRoot )

Call to get a Preferences "Branch" which accesses only the default preference data. Using a Set method on this object will always create or set a default preference value. When using a Get method a default value will always be returned.

Arguments:
prefRoot: The preference "root" on which to base this "branch". For example, if the root "browser.startup." is used, the branch will be able to easily access the preferences "browser.startup.page", "browser.startup.homepage", or "browser.startup.homepage_override" by simply requesting "page", "homepage", or "homepage_override". nsnull or "" may be used to access to the entire preference "tree".
Returns:
nsIPrefBranch The object representing the requested default branch.

void readUserPrefs ( nsIFile file )

Called to read in the preferences specified in a user preference file.

Arguments:
file: The file to be read.
Returns:
Other File failed to read or contained invalid data.

void resetPrefs ( )

Called to completely flush and re-initialize the preferences system.

Returns:
Other The preference service failed to restart correctly.

void resetUserPrefs ( )

Called to reset all preferences with user set values back to the application default values.

Returns:
NS_OK Always.

void savePrefFile ( nsIFile file )

Called to write current preferences state to a file.

Arguments:
file: The file to be written.
Returns:
Other File failed to write.

Reference documentation is generated from Mozilla's source.

Add a note User Contributed Notes
February 15, 2005, 2:12 pm asqueella at gmail dot com
Note that readUserPrefs(file) method does more than just reading prefs from a given file - it also makes file the "current prefs file" (nsPrefService::mCurrentFile).

The effect you should be aware of is that later calls to savePrefFile(null) overwrite the file. I believe that prefs.js is written out by a call to savePrefFile(null).

A related forum thread
December 28, 2004, 7:58 pm kristoffer dot lunden at gmail dot com
Note that in the example with getBranch, the prefRoot "browser.startup." ends with a period, since they will not be automatically added between the root and the rest of the path.

Copyright © 1999 - 2005 XULPlanet.com