You are currently viewing a snapshot of www.mozilla.org taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to www.mozilla.org, please file a bug.


TOC PREV NEXT INDEX

Embedding Gecko API


nsIPrefService


The 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 scriptable.

See also: nsIPrefBranch

Methods
readUserPrefs

Reads in the preferences specified in a user preference file.

Syntax:

void nsIPrefService::readUserPrefs(in nsIFile aFile) 

Parameters:

aFile: The file to be read.

Note: If nsnull is passed in for the aFile parameter the default preferences file(s) [prefs.js, user.js] will be read and processed.

nsresult:

NS_OK if file was read and processed.
Other if file failed to read or contained invalid data.

See also: nsIFile.

resetPrefs

Completely flushes the preferences system and then re-initializes it.

Syntax:

void nsIPrefService::resetPrefs() 

Parameters:

None.

nsresult:

NS_OK if the preference service was re-initialized correctly.
Other if the preference service failed to restart correctly.
resetUserPrefs

Resets all preferences with user-set values back to the application default values.

Syntax:

void nsIPrefService::resetUserPrefs()  

Parameters:

None.

nsresult:

NS_OK always.
savePrefFile

Writes current preferences state to a file.

Syntax:

void nsIPrefService::savePrefFile(in nsIFile aFile)  

Parameters:

aFile: The file to be written.

Note: If nsnull is passed in for the aFile parameter the preference data is written out to the current preferences file (usually prefs.js.)

nsresult:

NS_OK if file was written
Other if file failed to write.

See also: nsIFilee.

getBranch

Gets a Preferences "Branch" object 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.

Syntax:

nsIPrefBranch nsIPrefService::getBranch(
	in string aPrefRoot) 

Parameters:

aPrefRoot: 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::

The nsIPrefBranch object representing the requested branch

See also: nsIPrefBranch.

getDefaultBranch

Gets a Preferences "Branch" object 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.

Syntax:

nsIPrefBranch nsIPrefService::getDefaultBranch(
	in string aPrefRoot) 

Parameters:

aPrefRoot: 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".

Note: Few consumers will want to create default branch objects. Many of the branch methods do nothing on a default branch because the operations only make sense when applied to user set preferences.

Returns:

The nsIPrefBranch object representing the requested default branch.

See also: nsIPrefBranch.


Written by:Ellen Evans | Comments, questions, complaints? Bug 143387
TOC PREV NEXT INDEX