/* -*- Mode: C++; tab-width: 8; 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.org 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): 
 */

#include "nsISupports.idl"
#include "nsILocalFile.idl"
#include "nsIObserver.idl"

/**
 * @status UNDER_REVIEW
 */

%{C++


typedef int (*PR_CALLBACK PrefChangedFunc)(const char *, void *);
typedef void (*PrefEnumerationFunc)(const char *, void *);
 
#define NS_PREF_CID                                    \
  { /* {dc26e0e0-ca94-11d1-a9a4-00805f8a7ac4} */       \
    0xdc26e0e0,                                        \
    0xca94,                                            \
    0x11d1,                                            \
    { 0xa9, 0xa4, 0x00, 0x80, 0x5f, 0x8a, 0x7a, 0xc4 } \
  }

#define NS_PREF_CONTRACTID \
  "@mozilla.org/preferences;1" 

#define NS_PREF_CLASSNAME "Preferences Service"
 
#define NS_PREF_VALUE_CHANGED 1 
%}
native PrefChangedFunc(PrefChangedFunc);
native PrefEnumerationFunc(PrefEnumerationFunc);

interface nsIFileSpec;

[scriptable, uuid(a22ad7b0-ca86-11d1-a9a4-00805f8a7ac4)]
interface nsIPref : nsISupports {
    const long ePrefInvalid = 0;
    const long ePrefLocked = 1;
    const long ePrefUserset = 2;
    const long ePrefConfig = 4;
    const long ePrefRemote = 8;
    const long ePrefLilocal = 16;
    const long ePrefString = 32;
    const long ePrefInt = 64;
    const long ePrefBool = 128;
    const long ePrefValuetypeMask = (ePrefString | ePrefInt | ePrefBool);
        
  // Initialize/shutdown
  void StartUp();
  void ReadUserPrefs();
  void ReadUserPrefsFrom(in nsIFileSpec spec);
  void ResetUserPrefs();
  void ResetPrefs();
  void ShutDown();

  // Config file input
  void SavePrefFileAs(in nsIFileSpec filename);

  /* Getters */
  long GetPrefType(in string pref);
  long GetIntPref(in string pref);
  boolean GetBoolPref(in string pref);
  [noscript] void GetBinaryPref(in string pref, in voidPtr buf,
                                inout long buf_length);

  unsigned long GetColorPrefDWord(in string pref);
  /* set preferences */
  void SetCharPref(in string pref, in string value);
  void SetUnicharPref(in string pref, in wstring value);
  void SetIntPref(in string pref, in long value);
  void SetBoolPref(in string pref, in boolean value);
  [noscript] void SetBinaryPref(in string pref, in voidPtr value,
                                in unsigned long size);

    
  void ClearUserPref(in string pref_name);
  
  /* get defaults */
  long GetDefaultIntPref(in string pref);
  boolean GetDefaultBoolPref(in string pref);
  [noscript] void GetDefaultBinaryPref(in string pref, in voidPtr value,
                            out long length);

  /* set defaults */
  void SetDefaultCharPref(in string pref, in string value);
  void SetDefaultUnicharPref(in string pref, in wstring value);
  void SetDefaultIntPref(in string pref, in long value);
  void SetDefaultBoolPref(in string pref, in boolean value);
  [noscript] void SetDefaultBinaryPref(in string pref, in voidPtr value,
                                       in unsigned long size);
  
  // these are eventually changing from Copy->get
  string CopyCharPref(in string pref);
  wstring CopyUnicharPref(in string pref);
  [noscript] voidPtr CopyBinaryPref(in string pref, out long size);
    
  // "localized" prefs - stored in the properties files
  wstring getLocalizedUnicharPref(in string pref);
  wstring getDefaultLocalizedUnicharPref(in string pref);
  
  string CopyDefaultCharPref(in string pref);
  wstring CopyDefaultUnicharPref(in string pref);
  [noscript] voidPtr CopyDefaultBinaryPref(in string pref, out long size);

  nsIFileSpec GetFilePref(in string pref);
  void SetFilePref(in string pref, in nsIFileSpec value, in boolean setDefault);
  nsILocalFile getFileXPref(in string pref);
  void setFileXPref(in string pref, in nsILocalFile value);

  /* pref attributes */
  boolean PrefIsLocked(in string pref);

  /* save pref values */
  void SavePrefFile();

  /* callbacks */
  [noscript] void RegisterCallback(in string domain,
                        in PrefChangedFunc callback,
                        in voidPtr closure);
  [noscript] void UnregisterCallback(in string domain,
                          in PrefChangedFunc callback,
                          in voidPtr closure);
  /*
   * The observers have their |Observe| methods called with
   * ([the observer], "nsPref:changed", [pref name]).
   */
  void addObserver(in string domain, in nsIObserver observer);
  void removeObserver(in string domain, in nsIObserver observer);


  
  /* void CopyPrefsTree(in string srcRoot, in string destRoot); */
  void DeleteBranch(in string branchName);
  
  void CreateChildList(in string parent_node,out string childList);
  [noscript] string NextChild(in string child_list, inout short index);

  /**
   * EnumerateChildren
   *
   * Call back function "callback" with every preference string
   * having prefix "parent". Pass "data" to "callback" when calling.
   * 
   * @param parent A string representation of a prefix of preferences
   * @param callback A function to call back for each matching preference
   * @param data A piece of data to pass on to the callback
   */
  [noscript] void EnumerateChildren(in string parent, 
                                    in PrefEnumerationFunc callback, 
                                    in voidPtr data);
};
