/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
 *
 * The contents of this file are subject to the Netscape Public
 * License Version 1.1 (the "License"); you may not use this file
 * except in compliance with the License. You may obtain a copy of
 * the License at http://www.mozilla.org/NPL/
 *
 * Software distributed under the License is distributed on an "AS
 * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
 * implied. See the License for the specific language governing
 * rights and limitations under the License.
 *
 * The Original Code is Mozilla Communicator client code.
 *
 * The Initial Developer of the Original Code is Netscape Communications
 * Corporation.  Portions created by Netscape are
 * Copyright (C) 1998 Netscape Communications Corporation. All
 * Rights Reserved.
 *
 * Contributor(s):
 * Alec Flett <alecf@netscape.com>
 * Brian Nesse <bnesse@netscape.com>
 */

#include "nsISupports.idl"
#include "nsIPrefBranch.idl"
#include "nsIFile.idl"

[scriptable, uuid(decb9cc7-c08f-4ea5-be91-a8fc637ce2d2)]
interface nsIPrefService : nsISupports
{
  /*
   * readConfigFile
   * 
   * identify and read the configuration (.cfg) file
   */
  void readConfigFile();

  /*
   * readUserPrefs
   * 
   * read a user preference file, pass in null for default file
   */
  void readUserPrefs(in nsIFile aFile);

  /*
   * resetPrefs
   * 
   * completely flush and reload the preferences system
   */
  void resetPrefs();

  /*
   * resetUserPrefs
   * 
   * flush all current user prefrences (reset all preferences to the default
   * values)
   */
  void resetUserPrefs();

  /*
   * savePrefFile
   * 
   * write current preferences state to a file, pass in null for default file
   */
  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.
   */
  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.
   */
  nsIPrefBranch getDefaultBranch(in string aPrefRoot);

};

%{C++

#define NS_PREFSERVICE_CID                             \
  { /* {1cd91b88-1dd2-11b2-92e1-ed22ed298000} */       \
    0x1cd91b88,                                        \
    0x1dd2,                                            \
    0x11b2,                                            \
    { 0x92, 0xe1, 0xed, 0x22, 0xed, 0x29, 0x80, 0x00 } \
  }

#define NS_PREFSERVICE_CONTRACTID "@mozilla.org/preferences-service;1"
#define NS_PREFSERVICE_CLASSNAME "Preferences Server"

%}
