Bug 99611, Freeze nsIPrefService, nsIPrefBranch, (and nsIPrefLocalizedString) interfaces. r=dveditz, sr=alecf.
git-svn-id: svn://10.0.0.236/trunk@104810 18797224-902f-48f8-a5cc-f745e15eee43
This commit is contained in:
@@ -39,113 +39,306 @@
|
||||
|
||||
#include "nsISupports.idl"
|
||||
|
||||
/**
|
||||
* The nsIPrefBranch interface is used to manipulate the preferences data. This
|
||||
* object may be obtained from the preferences service (nsIPrefService) and
|
||||
* used to get and set default and/or user preferences across the application.
|
||||
*
|
||||
* This object is created with a "root" value which describes the base point in
|
||||
* the preferences "tree" from which this "branch" stems. Preferences are
|
||||
* accessed off of this root by using just the final portion of the preference.
|
||||
* For example, if this object is created with the root "browser.startup.",
|
||||
* the preferences "browser.startup.page", "browser.startup.homepage",
|
||||
* and "browser.startup.homepage_override" can be accessed by simply passing
|
||||
* "page", "homepage", or "homepage_override" to the various Get/Set methods.
|
||||
*
|
||||
* @see nsIPrefService
|
||||
*
|
||||
* @status FROZEN
|
||||
*/
|
||||
|
||||
[scriptable, uuid(56c35506-f14b-11d3-99d3-ddbfac2ccf65)]
|
||||
interface nsIPrefBranch : nsISupports
|
||||
{
|
||||
|
||||
/**
|
||||
* Values describing the basic preference types.
|
||||
*
|
||||
* @see getPrefType
|
||||
*/
|
||||
const long PREF_INVALID = 0;
|
||||
const long PREF_LOCKED = 1;
|
||||
const long PREF_USER_SET = 2;
|
||||
const long PREF_CONFIG = 4;
|
||||
const long PREF_REMOTE = 8;
|
||||
const long PREF_LI_LOCAL = 16;
|
||||
const long PREF_STRING = 32;
|
||||
const long PREF_INT = 64;
|
||||
const long PREF_BOOL = 128;
|
||||
const long PREF_VALUE_TYPE_MASK = (PREF_STRING | PREF_INT | PREF_BOOL);
|
||||
|
||||
/*
|
||||
* the root of this branch, such as "browser.startup."
|
||||
/**
|
||||
* Called to get the root on which this branch is based, such as
|
||||
* "browser.startup."
|
||||
*/
|
||||
readonly attribute string root;
|
||||
|
||||
/*
|
||||
* standard methods for accessing preferences
|
||||
* pass in a string to be added to the root such as "homepage"
|
||||
/**
|
||||
* Called to determine the type of a specific preference.
|
||||
*
|
||||
* @param aPrefName The preference to get the type of.
|
||||
*
|
||||
* @return long A value representing the type of the preference. This
|
||||
* value will be PREF_STRING, PREF_INT, or PREF_BOOL.
|
||||
*/
|
||||
long getPrefType(in string aPrefName);
|
||||
long getPrefType(in string aPrefName);
|
||||
|
||||
/**
|
||||
* Called to get the state of an individual boolean preference.
|
||||
*
|
||||
* @param aPrefName The boolean preference to get the state of.
|
||||
*
|
||||
* @return boolean The value of the requested boolean preference.
|
||||
*
|
||||
* @see setBoolPref
|
||||
*/
|
||||
boolean getBoolPref(in string aPrefName);
|
||||
void setBoolPref(in string aPrefName, in long aValue);
|
||||
|
||||
string getCharPref(in string aPrefName);
|
||||
void setCharPref(in string aPrefName, in string aValue);
|
||||
|
||||
long getIntPref(in string aPrefName);
|
||||
void setIntPref(in string aPrefName, in long aValue);
|
||||
|
||||
/*
|
||||
* methods for accessing complex preferences (i.e. items beyond the simple
|
||||
* bool, char, and int)
|
||||
* Interfaces currently supported are:
|
||||
* - nsILocalFile
|
||||
* - nsISupportsWString (UniChar)
|
||||
* - nsIPrefLocalizedString (Localized UniChar)
|
||||
* - nsIFileSpec (depricated - support will be removed eventually)
|
||||
/**
|
||||
* Called to set the state of an individual boolean preference.
|
||||
*
|
||||
* @param aPrefName The boolean preference to set the state of.
|
||||
* @param aValue The boolean value to set the preference to.
|
||||
*
|
||||
* @return NS_OK The value was successfully set.
|
||||
* @return Other The value was not set or is the wrong type.
|
||||
*
|
||||
* @see getBoolPref
|
||||
*/
|
||||
void setBoolPref(in string aPrefName, in long aValue);
|
||||
|
||||
/**
|
||||
* Called to get the state of an individual string preference.
|
||||
*
|
||||
* @param aPrefName The string preference to retrieve.
|
||||
*
|
||||
* @return string The value of the requested string preference.
|
||||
*
|
||||
* @see setCharPref
|
||||
*/
|
||||
string getCharPref(in string aPrefName);
|
||||
|
||||
/**
|
||||
* Called to set the state of an individual string preference.
|
||||
*
|
||||
* @param aPrefName The string preference to set.
|
||||
* @param aValue The string value to set the preference to.
|
||||
*
|
||||
* @return NS_OK The value was successfully set.
|
||||
* @return Other The value was not set or is the wrong type.
|
||||
*
|
||||
* @see getCharPref
|
||||
*/
|
||||
void setCharPref(in string aPrefName, in string aValue);
|
||||
|
||||
/**
|
||||
* Called to get the state of an individual integer preference.
|
||||
*
|
||||
* @param aPrefName The integer preference to get the value of.
|
||||
*
|
||||
* @return long The value of the requested integer preference.
|
||||
*
|
||||
* @see setIntPref
|
||||
*/
|
||||
long getIntPref(in string aPrefName);
|
||||
|
||||
/**
|
||||
* Called to set the state of an individual integer preference.
|
||||
*
|
||||
* @param aPrefName The integer preference to set the value of.
|
||||
* @param aValue The integer value to set the preference to.
|
||||
*
|
||||
* @return NS_OK The value was successfully set.
|
||||
* @return Other The value was not set or is the wrong type.
|
||||
*
|
||||
* @see getIntPref
|
||||
*/
|
||||
void setIntPref(in string aPrefName, in long aValue);
|
||||
|
||||
/**
|
||||
* Called to get the state of an individual complex preference. A complex
|
||||
* preference is a preference which represents an XPCOM object that can not
|
||||
* be easily represented using a standard boolean, integer or string value.
|
||||
*
|
||||
* @param aPrefName The complex preference to get the value of.
|
||||
* @param aType The XPCOM interface that this complex preference
|
||||
* represents. Interfaces currently supported are:
|
||||
* - nsILocalFile
|
||||
* - nsISupportsWString (UniChar)
|
||||
* - nsIPrefLocalizedString (Localized UniChar)
|
||||
* - nsIFileSpec (depricated - to be removed eventually)
|
||||
* @param aValue The XPCOM object into which to the complex preference
|
||||
* value should be retrieved.
|
||||
*
|
||||
* @return NS_OK The value was successfully retrieved.
|
||||
* @return Other The value does not exist or is the wrong type.
|
||||
*
|
||||
* @see setComplexValue
|
||||
*/
|
||||
void getComplexValue(in string aPrefName, in nsIIDRef aType,
|
||||
[iid_is(aType), retval] out nsQIResult aValue);
|
||||
|
||||
/**
|
||||
* Called to set the state of an individual complex preference. A complex
|
||||
* preference is a preference which represents an XPCOM object that can not
|
||||
* be easily represented using a standard boolean, integer or string value.
|
||||
*
|
||||
* @param aPrefName The complex preference to set the value of.
|
||||
* @param aType The XPCOM interface that this complex preference
|
||||
* represents. Interfaces currently supported are:
|
||||
* - nsILocalFile
|
||||
* - nsISupportsWString (UniChar)
|
||||
* - nsIPrefLocalizedString (Localized UniChar)
|
||||
* - nsIFileSpec (depricated - to be removed eventually)
|
||||
* @param aValue The XPCOM object from which to set the complex preference
|
||||
* value.
|
||||
*
|
||||
* @return NS_OK The value was successfully set.
|
||||
* @return Other The value was not set or is the wrong type.
|
||||
*
|
||||
* @see getComplexValue
|
||||
*/
|
||||
void getComplexValue(in string aPrefName, in nsIIDRef aType, [iid_is(aType), retval] out nsQIResult aValue);
|
||||
void setComplexValue(in string aPrefName, in nsIIDRef aType, in nsISupports aValue);
|
||||
|
||||
/*
|
||||
* clearUserPref
|
||||
*
|
||||
* resets a preference to the default value.
|
||||
* pass in a string to be added to the root such as "homepage"
|
||||
/**
|
||||
* Called to clear a user set value from a specific preference. This will, in
|
||||
* effect, reset the value to the default value. If no default value exists
|
||||
* the preference will cease to exist.
|
||||
*
|
||||
* @param aPrefName The preference to be cleared.
|
||||
*
|
||||
* @note
|
||||
* This method does nothing if this object is a default branch.
|
||||
*
|
||||
* @return NS_OK The user preference was successfully cleared.
|
||||
* @return Other The preference does not exist or have a user set value.
|
||||
*/
|
||||
void clearUserPref(in string aPrefName);
|
||||
void clearUserPref(in string aPrefName);
|
||||
|
||||
|
||||
/*
|
||||
* methods for manipulating the ability to change the state of a preference.
|
||||
* pass in a string to be added to the root such as "homepage"
|
||||
/**
|
||||
* Called to lock a specific preference. Locking a preference will cause the
|
||||
* preference service to always return the default value regardless of
|
||||
* whether there is a user set value or not.
|
||||
*
|
||||
* @param aPrefName The preference to be locked.
|
||||
*
|
||||
* @note
|
||||
* This method can be called on either a default or user branch but, in
|
||||
* effect, always operates on the default branch.
|
||||
*
|
||||
* @return NS_OK The preference was successfully locked.
|
||||
* @return Other The preference does not exist or an error occurred.
|
||||
*
|
||||
* @see unlockPref
|
||||
*/
|
||||
void lockPref(in string aPrefName);
|
||||
|
||||
void lockPref(in string aPrefName);
|
||||
/**
|
||||
* Called to check if a specific preference has a user value associated to
|
||||
* it.
|
||||
*
|
||||
* @param aPrefName The preference to be tested.
|
||||
*
|
||||
* @note
|
||||
* This method can be called on either a default or user branch but, in
|
||||
* effect, always operates on the user branch.
|
||||
*
|
||||
* @return boolean true The preference has a user set value.
|
||||
* false The preference only has a default value.
|
||||
*/
|
||||
boolean prefHasUserValue(in string aPrefName);
|
||||
|
||||
/**
|
||||
* Called to check if a specific preference is locked. If a preference is
|
||||
* locked calling its Get method will always return the default value.
|
||||
*
|
||||
* @param aPrefName The preference to be tested.
|
||||
*
|
||||
* @note
|
||||
* This method can be called on either a default or user branch but, in
|
||||
* effect, always operates on the default branch.
|
||||
*
|
||||
* @return boolean true The preference is locked.
|
||||
* false The preference is not locked.
|
||||
*
|
||||
* @see lockPref
|
||||
* @see unlockPref
|
||||
*/
|
||||
boolean prefIsLocked(in string aPrefName);
|
||||
|
||||
/**
|
||||
* Called to unlock a specific preference. Unlocking a previously locked
|
||||
* preference allows the preference service to once again return the user set
|
||||
* value of the preference.
|
||||
*
|
||||
* @param aPrefName The preference to be unlocked.
|
||||
*
|
||||
* @note
|
||||
* This method can be called on either a default or user branch but, in
|
||||
* effect, always operates on the default branch.
|
||||
*
|
||||
* @return NS_OK The preference was successfully unlocked.
|
||||
* @return Other The preference does not exist or an error occurred.
|
||||
*
|
||||
* @see lockPref
|
||||
*/
|
||||
void unlockPref(in string aPrefName);
|
||||
|
||||
|
||||
/*
|
||||
* branch-level operations
|
||||
/**
|
||||
* Called to remove all of the preferences referenced by this branch.
|
||||
*
|
||||
* These operations can effect multiple preferences.
|
||||
* @param aStartingAt The point on the branch at which to start the deleting
|
||||
* preferences. Pass in "" to remove all preferences
|
||||
* referenced by this branch.
|
||||
*
|
||||
* If the root is set to "mail.identity." and "vcard" is passed in all of the
|
||||
* preferences related to "mail.identity.vcard" such as
|
||||
* "mail.identity.vcard.adr" and "mail.identity.vcard.email.internet" will be
|
||||
* manipulated but items such as "mail.identity.username" will be ignored. If
|
||||
* null or "" is passed in all preferences in the "mail.identity." hierarchy
|
||||
* will be manipulated.
|
||||
*/
|
||||
|
||||
/*
|
||||
* deleteBranch
|
||||
*
|
||||
* removes all preferences starting at the given preference prefix
|
||||
* pass in null or "" to remove this branch
|
||||
* @note
|
||||
* This method can be called on either a default or user branch but, in
|
||||
* effect, always operates on both.
|
||||
*
|
||||
* @return NS_OK The preference(s) were successfully removed.
|
||||
* @return Other The preference(s) do not exist or an error occurred.
|
||||
*/
|
||||
void deleteBranch(in string aStartingAt);
|
||||
|
||||
/*
|
||||
* getChildList
|
||||
*
|
||||
/**
|
||||
* Returns an array of strings representing the child preferences of the
|
||||
* branch root.
|
||||
* root of this branch.
|
||||
*
|
||||
* @param startingAt pass in null or "" to enumerate the entire branch
|
||||
* @param count Receives the number of elements in the array.
|
||||
* @param childArray Receives the array of child preferences.
|
||||
* @param aStartingAt The point on the branch at which to start enumerating
|
||||
* the child preferences. Pass in "" to enumerate all
|
||||
* preferences referenced by this branch.
|
||||
* @param aCount Receives the number of elements in the array.
|
||||
* @param aChildArray Receives the array of child preferences.
|
||||
*
|
||||
* @note
|
||||
* This method can be called on either a default or user branch but, in
|
||||
* effect, always operates on both.
|
||||
*
|
||||
* @return NS_OK The preference list was successfully retrieved.
|
||||
* @return Other The preference(s) do not exist or an error occurred.
|
||||
*/
|
||||
void getChildList(in string aStartingAt,
|
||||
out unsigned long aCount,
|
||||
void getChildList(in string aStartingAt, out unsigned long aCount,
|
||||
[array, size_is(aCount), retval] out string aChildArray);
|
||||
|
||||
/*
|
||||
* resetBranch
|
||||
*
|
||||
* clears all user preferences (i.e. resets them to their default values)
|
||||
* starting at the given preference prefix.
|
||||
* pass in null or "" to clear this branch
|
||||
/**
|
||||
* Called to reset all of the preferences referenced by this branch to their
|
||||
* default values.
|
||||
*
|
||||
* @param aStartingAt The point on the branch at which to start the resetting
|
||||
* preferences to their default values. Pass in "" to
|
||||
* reset all preferences referenced by this branch.
|
||||
*
|
||||
* @note
|
||||
* This method can be called on either a default or user branch but, in
|
||||
* effect, always operates on the user branch.
|
||||
*
|
||||
* @return NS_OK The preference(s) were successfully reset.
|
||||
* @return Other The preference(s) do not exist or an error occurred.
|
||||
*/
|
||||
void resetBranch(in string aStartingAt);
|
||||
|
||||
|
||||
@@ -38,21 +38,72 @@
|
||||
* ***** END LICENSE BLOCK ***** */
|
||||
|
||||
#include "nsISupports.idl"
|
||||
#include "nsIObserver.idl"
|
||||
|
||||
interface nsIObserver;
|
||||
|
||||
/**
|
||||
* The nsIPrefBranchInternal interface allows additional access to the
|
||||
* preference branch object. This interface allows functionality to be added to
|
||||
* the preference branch object which might be transitory in nature or
|
||||
* otherwise deemed unnecessary to, or unwanted in, the main (nsIPrefBranch)
|
||||
* interface.
|
||||
*
|
||||
* @see nsIPrefBranch
|
||||
*/
|
||||
|
||||
[scriptable, uuid(24ef9578-1dd2-11b2-b439-fcc3d2b4fa20)]
|
||||
interface nsIPrefBranchInternal : nsISupports
|
||||
{
|
||||
/*
|
||||
* Listeners
|
||||
*/
|
||||
|
||||
/*
|
||||
* The observers have their |Observe| methods called with
|
||||
* ([the observer], "nsPref:changed", [pref name]).
|
||||
/**
|
||||
* Called by a preferences consumer to add itself as a preference change
|
||||
* listener. This consumer must inherit from the nsIObserver interface and
|
||||
* will receive the notification via their |Observe| method. The following
|
||||
* arguments will be passed to the |Observe| method:
|
||||
* aSubject - The nsIPrefBranch object (this)
|
||||
* aTopic - The string defined by NS_PREFBRANCH_PREFCHANGE_OBSERVER_ID
|
||||
* aData - The preference which has changed
|
||||
*
|
||||
* @param aDomain The preference on which to listen for changes.
|
||||
* @param aObserver The object to be notified if the preference changes.
|
||||
*
|
||||
* @note
|
||||
* Registering as a preference observer can open an object to potential
|
||||
* cyclical references which will cause memory leaks. These cycles generally
|
||||
* occur because an object both registers itself as an observer (causing the
|
||||
* branch to hold a reference to the observer) and holds a reference to the
|
||||
* branch object for the purpose of getting/setting preference values. This
|
||||
* should be addressed in the near future.
|
||||
*
|
||||
* @return NS_OK The observer was successfully set.
|
||||
* @return Other The observer could not be created.
|
||||
*
|
||||
* @see nsIObserver
|
||||
* @see removeObserver
|
||||
*/
|
||||
void addObserver(in string aDomain, in nsIObserver aObserver);
|
||||
|
||||
/**
|
||||
* Called by a preferences consumer to remove itself from the preference
|
||||
* change observer list.
|
||||
*
|
||||
* @param aDomain The preference which is being observed for changes.
|
||||
* @param aObserver The object which is observing.
|
||||
*
|
||||
* @return NS_OK The observer was successfully removed.
|
||||
* @return Other The observer was not successfully removed.
|
||||
*
|
||||
* @see nsIObserver
|
||||
* @see addObserver
|
||||
*/
|
||||
void removeObserver(in string aDomain, in nsIObserver aObserver);
|
||||
|
||||
};
|
||||
|
||||
%{C++
|
||||
|
||||
/**
|
||||
* Notification sent when a preference changes.
|
||||
*/
|
||||
#define NS_PREFBRANCH_PREFCHANGE_OBSERVER_ID "nsPref:changed"
|
||||
|
||||
%}
|
||||
|
||||
@@ -39,21 +39,53 @@
|
||||
|
||||
#include "nsISupports.idl"
|
||||
|
||||
/*
|
||||
* nsIPrefLocalizedString is simply a wrapper for nsISupportsWString so we can have a unique
|
||||
* identifier to distinguish between requests for normal wstrings and localized wstrings
|
||||
/**
|
||||
* The nsIPrefLocalizedString interface is simply a wrapper interface for
|
||||
* nsISupportsWString so the preferences service can have a unique identifier
|
||||
* to distinguish between requests for normal wide strings (nsISupportsWString)
|
||||
* and "localized" wide strings, which get their default values from properites
|
||||
* files.
|
||||
*
|
||||
* @see nsIPrefBranch
|
||||
* @see nsISupportsWString
|
||||
*
|
||||
* @status FROZEN
|
||||
*/
|
||||
|
||||
[scriptable, uuid(ae419e24-1dd1-11b2-b39a-d3e5e7073802)]
|
||||
interface nsIPrefLocalizedString : nsISupports
|
||||
{
|
||||
attribute wstring data;
|
||||
wstring toString();
|
||||
/**
|
||||
* Provides access to string data stored in this property.
|
||||
*
|
||||
* @return NS_OK The operation succeeded.
|
||||
* @return Other An error occured.
|
||||
*/
|
||||
attribute wstring data;
|
||||
|
||||
// do not include space for null termination in |length|. It is handled
|
||||
// internally. |length| is in characters, not in bytes.
|
||||
void setDataWithLength(in unsigned long length,
|
||||
[size_is(length)] in wstring data);
|
||||
/**
|
||||
* Used to retrieve the contents of this object into a wide string.
|
||||
*
|
||||
* @return wstring The string containing the data stored within this object.
|
||||
*/
|
||||
wstring toString();
|
||||
|
||||
/**
|
||||
* Used to set the contents of this object.
|
||||
*
|
||||
* @param length The length of the string. This value should not include
|
||||
* space for the null terminator, nor should it account for the
|
||||
* size of a character. It should only be the number of
|
||||
* characters for which there is space in the string.
|
||||
* @param data The string data to be stored.
|
||||
*
|
||||
* @note
|
||||
* This makes a copy of the string argument passed in.
|
||||
*
|
||||
* @return NS_OK The data was successfully stored.
|
||||
*/
|
||||
void setDataWithLength(in unsigned long length,
|
||||
[size_is(length)] in wstring data);
|
||||
};
|
||||
|
||||
%{C++
|
||||
|
||||
@@ -42,70 +42,114 @@
|
||||
|
||||
interface nsIFile;
|
||||
|
||||
/**
|
||||
* 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.
|
||||
*
|
||||
* @see nsIPrefBranch
|
||||
*
|
||||
* @status FROZEN
|
||||
*/
|
||||
|
||||
[scriptable, uuid(decb9cc7-c08f-4ea5-be91-a8fc637ce2d2)]
|
||||
interface nsIPrefService : nsISupports
|
||||
{
|
||||
/*
|
||||
* readUserPrefs
|
||||
*
|
||||
* read a user preference file, pass in null for default file
|
||||
/**
|
||||
* Called to read in the preferences specified in a user preference file.
|
||||
*
|
||||
* @param 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.
|
||||
*
|
||||
* @return NS_OK File was read and processed.
|
||||
* @return Other File failed to read or contained invalid data.
|
||||
*
|
||||
* @see savePrefFile
|
||||
* @see nsIFile
|
||||
*/
|
||||
void readUserPrefs(in nsIFile aFile);
|
||||
|
||||
/*
|
||||
* resetPrefs
|
||||
*
|
||||
* completely flush and reload the preferences system
|
||||
/**
|
||||
* Called to completely flush and re-initialize the preferences system.
|
||||
*
|
||||
* @return NS_OK The preference service was re-initialized correctly.
|
||||
* @return Other The preference service failed to restart correctly.
|
||||
*/
|
||||
void resetPrefs();
|
||||
|
||||
/*
|
||||
* resetUserPrefs
|
||||
*
|
||||
* flush all current user prefrences (reset all preferences to the default
|
||||
* values)
|
||||
/**
|
||||
* Called to reset all preferences with user set values back to the
|
||||
* application default values.
|
||||
*
|
||||
* @return NS_OK Always.
|
||||
*/
|
||||
void resetUserPrefs();
|
||||
|
||||
/*
|
||||
* savePrefFile
|
||||
*
|
||||
* write current preferences state to a file, pass in null for default file
|
||||
/**
|
||||
* Called to write current preferences state to a file.
|
||||
*
|
||||
* @param 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.)
|
||||
*
|
||||
* @return NS_OK File was written.
|
||||
* @return Other File failed to write.
|
||||
*
|
||||
* @see readUserPrefs
|
||||
* @see nsIFile
|
||||
*/
|
||||
void savePrefFile(in nsIFile aFile);
|
||||
|
||||
|
||||
/*
|
||||
* branch operations
|
||||
*
|
||||
* These methods return a Preferences "Branch" from which preference data
|
||||
* may be accessed or manipulated. For example, if "browser.startup." is
|
||||
* passed in as the branch root, the branch will be able to access the
|
||||
* preferences "browser.startup.homepage",
|
||||
* "browser.startup.homepage_override", and "browser.startup.page".
|
||||
*
|
||||
* pass in null or "" to have access to all preferences.
|
||||
*/
|
||||
|
||||
/*
|
||||
* getBranch
|
||||
*
|
||||
* returns a Preferences "Branch" which accesses user preference data. If
|
||||
* no user preference has been set, the default value will be returned.
|
||||
*
|
||||
* When using a Set function, this will always create or set a user
|
||||
* preference.
|
||||
/**
|
||||
* 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.
|
||||
*
|
||||
* @param 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".
|
||||
*
|
||||
* @return nsIPrefBranch The object representing the requested branch.
|
||||
*
|
||||
* @see getDefaultBranch
|
||||
*/
|
||||
nsIPrefBranch getBranch(in string aPrefRoot);
|
||||
|
||||
/*
|
||||
* getDefaultBranch
|
||||
*
|
||||
* returns a Preferences "Branch" which accesses the default preference
|
||||
* data directly.
|
||||
*
|
||||
* When using a Set function, this will always create or set a default
|
||||
* preference.
|
||||
/**
|
||||
* 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.
|
||||
*
|
||||
* @param 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.
|
||||
*
|
||||
* @return nsIPrefBranch The object representing the requested default branch.
|
||||
*
|
||||
* @see getBranch
|
||||
*/
|
||||
nsIPrefBranch getDefaultBranch(in string aPrefRoot);
|
||||
|
||||
@@ -124,4 +168,15 @@ interface nsIPrefService : nsISupports
|
||||
#define NS_PREFSERVICE_CONTRACTID "@mozilla.org/preferences-service;1"
|
||||
#define NS_PREFSERVICE_CLASSNAME "Preferences Server"
|
||||
|
||||
/**
|
||||
* Notification sent before reading the default user preferences files.
|
||||
*/
|
||||
#define NS_PREFSERVICE_READ_OBSERVER_ID "prefservice:before-read-userprefs"
|
||||
|
||||
/**
|
||||
* Notification sent when resetPrefs has been called, but before the actual
|
||||
* reset process occurs.
|
||||
*/
|
||||
#define NS_PREFSERVICE_RESET_OBSERVER_ID "prefservice:before-reset"
|
||||
|
||||
%}
|
||||
|
||||
@@ -37,24 +37,106 @@
|
||||
|
||||
#include "nsISupports.idl"
|
||||
|
||||
/*
|
||||
* Interface for accessing preferences, bypassing the ususl security check
|
||||
* on prefs starting with "capability". This interface is used by
|
||||
/**
|
||||
* Interface for accessing preferences, bypassing the usual security check on
|
||||
* preferences starting with "capability". This interface is used by
|
||||
* nsScriptSecurityManager which needs unchecked access to security prefs.
|
||||
* *PLEASE* do not call this interface from any other file, as this
|
||||
* would be insecure.
|
||||
*
|
||||
* THIS INTERFACE SHOULD NEVER BE MADE SCRIPTABLE
|
||||
*
|
||||
* @see nsIPrefBranch
|
||||
*/
|
||||
|
||||
[uuid(94afd973-8045-4c6c-89e6-75bdced4209e)]
|
||||
interface nsISecurityPref : nsISupports {
|
||||
|
||||
/**
|
||||
* Called to get the state of a "capability" boolean preference.
|
||||
*
|
||||
* @param pref The boolean preference to get the state of.
|
||||
*
|
||||
* @return boolean The value of the requested boolean preference.
|
||||
*
|
||||
* @see securitySetBoolPref
|
||||
*/
|
||||
boolean securityGetBoolPref(in string pref);
|
||||
|
||||
/**
|
||||
* Called to set the state of a "capability" boolean preference.
|
||||
*
|
||||
* @param pref The boolean preference to set the state of.
|
||||
* @param value The boolean value to set the preference to.
|
||||
*
|
||||
* @return NS_OK The value was successfully set.
|
||||
* @return Other The value was not set or is the wrong type.
|
||||
*
|
||||
* @see securityGetBoolPref
|
||||
*/
|
||||
void securitySetBoolPref(in string pref, in boolean value);
|
||||
|
||||
/**
|
||||
* Called to get the state of a "capability" string preference.
|
||||
*
|
||||
* @param pref The string preference to retrieve.
|
||||
*
|
||||
* @return string The value of the requested string preference.
|
||||
*
|
||||
* @see securitySetCharPref
|
||||
*/
|
||||
string securityGetCharPref(in string pref);
|
||||
|
||||
/**
|
||||
* Called to set the state of a "capability" string preference.
|
||||
*
|
||||
* @param pref The string preference to set.
|
||||
* @param value The string value to set the preference to.
|
||||
*
|
||||
* @return NS_OK The value was successfully set.
|
||||
* @return Other The value was not set or is the wrong type.
|
||||
*
|
||||
* @see securityGetCharPref
|
||||
*/
|
||||
void securitySetCharPref(in string pref, in string value);
|
||||
|
||||
/**
|
||||
* Called to get the state of a "capability" integer preference.
|
||||
*
|
||||
* @param pref The integer preference to get the value of.
|
||||
*
|
||||
* @return long The value of the requested integer preference.
|
||||
*
|
||||
* @see securitySetIntPref
|
||||
*/
|
||||
long securityGetIntPref(in string pref);
|
||||
|
||||
/**
|
||||
* Called to set the state of a "capability" integer preference.
|
||||
*
|
||||
* @param pref The integer preference to set the value of.
|
||||
* @param value The integer value to set the preference to.
|
||||
*
|
||||
* @return NS_OK The value was successfully set.
|
||||
* @return Other The value was not set or is the wrong type.
|
||||
*
|
||||
* @see securityGetIntPref
|
||||
*/
|
||||
void securitySetIntPref(in string pref, in long value);
|
||||
|
||||
/**
|
||||
* Called to clear a user set value from a "capability" preference. This
|
||||
* will, in effect, reset the value to the default value. If no default value
|
||||
* exists the preference will cease to exist.
|
||||
*
|
||||
* @param pref_name The preference to be cleared.
|
||||
*
|
||||
* @note
|
||||
* This method does nothing if this object is a default branch.
|
||||
*
|
||||
* @return NS_OK The user preference was successfully cleared.
|
||||
* @return Other The preference does not exist or have a user set value.
|
||||
*/
|
||||
void securityClearUserPref(in string pref_name);
|
||||
|
||||
};
|
||||
|
||||
@@ -38,6 +38,7 @@
|
||||
#include "nsIPrefBranchInternal.h"
|
||||
#include "nsIFactory.h"
|
||||
#include "nsIComponentManager.h"
|
||||
#include "nsIObserver.h"
|
||||
#include "nsCOMPtr.h"
|
||||
#include "nsMemory.h"
|
||||
#include "prefapi.h"
|
||||
@@ -137,6 +138,7 @@ nsPref::nsPref()
|
||||
NS_INIT_REFCNT();
|
||||
|
||||
mPrefService = do_GetService(NS_PREFSERVICE_CONTRACTID);
|
||||
NS_ASSERTION(mPrefService, "Preference Service failed to start up!!");
|
||||
|
||||
if (mPrefService)
|
||||
mPrefService->GetDefaultBranch("", getter_AddRefs(mDefaultBranch));
|
||||
|
||||
@@ -65,7 +65,6 @@ struct PrefCallbackData {
|
||||
|
||||
|
||||
static NS_DEFINE_CID(kSecurityManagerCID, NS_SCRIPTSECURITYMANAGER_CID);
|
||||
static NS_DEFINE_CID(kStringBundleServiceCID, NS_STRINGBUNDLESERVICE_CID);
|
||||
|
||||
// Prototypes
|
||||
extern "C" PrefResult pref_UnlockPref(const char *key);
|
||||
@@ -93,7 +92,7 @@ static nsresult _convertRes(int res)
|
||||
return NS_ERROR_UNEXPECTED;
|
||||
|
||||
case PREF_VALUECHANGED:
|
||||
return 1;
|
||||
return NS_OK;
|
||||
}
|
||||
|
||||
NS_ASSERTION((res >= PREF_DEFAULT_VALUE_NOT_INITIALIZED) && (res <= PREF_PROFILE_UPGRADE), "you added a new error code to prefapi.h and didn't update _convertRes");
|
||||
@@ -580,6 +579,10 @@ NS_IMETHODIMP nsPrefBranch::GetChildList(const char *aStartingAt, PRUint32 *aCou
|
||||
}
|
||||
|
||||
|
||||
/*
|
||||
* nsIPrefBranchInternal methods
|
||||
*/
|
||||
|
||||
NS_IMETHODIMP nsPrefBranch::AddObserver(const char *aDomain, nsIObserver *aObserver)
|
||||
{
|
||||
PrefCallbackData *pCallback;
|
||||
@@ -656,7 +659,7 @@ static int PR_CALLBACK NotifyObserver(const char *newpref, void *data)
|
||||
|
||||
nsCOMPtr<nsIObserver> observer = NS_STATIC_CAST(nsIObserver *, pData->pObserver);
|
||||
observer->Observe(pData->pBranch,
|
||||
NS_LITERAL_STRING("nsPref:changed").get(),
|
||||
NS_LITERAL_STRING(NS_PREFBRANCH_PREFCHANGE_OBSERVER_ID).get(),
|
||||
NS_ConvertASCIItoUCS2(newpref).get());
|
||||
|
||||
return 0;
|
||||
@@ -675,7 +678,7 @@ nsresult nsPrefBranch::GetDefaultFromPropertiesFile(const char *aPrefName, PRUni
|
||||
return rv;
|
||||
|
||||
nsCOMPtr<nsIStringBundleService> bundleService =
|
||||
do_GetService(kStringBundleServiceCID, &rv);
|
||||
do_GetService(NS_STRINGBUNDLE_CONTRACTID, &rv);
|
||||
if (NS_FAILED(rv))
|
||||
return rv;
|
||||
|
||||
@@ -759,6 +762,8 @@ PR_STATIC_CALLBACK(PRIntn) pref_enumChild(PLHashEntry *he, int i, void *arg)
|
||||
|
||||
|
||||
/*
|
||||
* nsISecurityPref methods
|
||||
*
|
||||
* Pref access without security check - these are here
|
||||
* to support nsScriptSecurityManager.
|
||||
* These functions are part of nsISecurityPref, not nsIPref.
|
||||
|
||||
@@ -38,25 +38,22 @@
|
||||
|
||||
#include "nsPrefService.h"
|
||||
#include "jsapi.h"
|
||||
#include "nsAppDirectoryServiceDefs.h"
|
||||
#include "nsDirectoryServiceDefs.h"
|
||||
#include "nsIObserverService.h"
|
||||
#include "nsISignatureVerifier.h"
|
||||
#include "nsPrefBranch.h"
|
||||
#include "nsXPIDLString.h"
|
||||
#include "nsIAutoConfig.h"
|
||||
|
||||
#include "nsQuickSort.h"
|
||||
#include "prmem.h"
|
||||
|
||||
#include "prefapi.h"
|
||||
class nsIFileSpec; // needed for prefapi_private_data.h inclusion
|
||||
#include "prefapi_private_data.h"
|
||||
|
||||
// supporting lock files
|
||||
#include "nsDirectoryServiceDefs.h"
|
||||
#include "prmem.h"
|
||||
#include "prprf.h"
|
||||
|
||||
// supporting PREF_Init()
|
||||
#include "nsIJSRuntimeService.h"
|
||||
#include "nsAppDirectoryServiceDefs.h"
|
||||
|
||||
// lose these if possible (supporting nsIFileToFileSpec)
|
||||
#include "nsIFileSpec.h"
|
||||
@@ -67,6 +64,7 @@ class nsIFileSpec; // needed for prefapi_private_data.h inclusion
|
||||
#define PREFS_HEADER_LINE_2 "// This is a generated file!"
|
||||
#define INITIAL_MAX_DEFAULT_PREF_FILES 10
|
||||
|
||||
|
||||
// Prototypes
|
||||
static nsresult nsIFileToFileSpec(nsIFile* inFile, nsIFileSpec **aFileSpec);
|
||||
static nsresult openPrefFile(nsIFile* aFile, PRBool aIsErrorFatal, PRBool aVerifyHash,
|
||||
@@ -230,7 +228,7 @@ NS_IMETHODIMP nsPrefService::GetBranch(const char *aPrefRoot, nsIPrefBranch **_r
|
||||
{
|
||||
nsresult rv;
|
||||
|
||||
if ((nsnull != aPrefRoot) && (aPrefRoot != "")) {
|
||||
if ((nsnull != aPrefRoot) && (*aPrefRoot != '\0')) {
|
||||
// TODO: - cache this stuff and allow consumers to share branches (hold weak references I think)
|
||||
nsPrefBranch* prefBranch = new nsPrefBranch(aPrefRoot, PR_FALSE);
|
||||
|
||||
|
||||
Reference in New Issue
Block a user