/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
 *
 * 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>
 */

#include "nsISupports.idl"
#include "nsIFileSpec.idl"
#include "nsIPrefListener.idl"

%{C++

typedef int (*PrefChangedFunc)(const char *, void *);
typedef void (*PrefEnumerationFunc)(const char *, void *);
 
%}
      

native PrefEnumerationFunc(PrefEnumerationFunc);
native PrefChangedFunc(PrefChangedFunc);

[scriptable, uuid(56c35506-f14b-11d3-99d3-ddbfac2ccf65)]
interface nsIPrefBranch : 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);
    
    /**
     * the root of this branch, such as "browser."
     */
    readonly attribute string root;
    
    /*
     * standard methods for accessing prefs
     */
    PRInt32 getPrefType(in string prefName);
    
    boolean getBoolPref(in string prefName);
    void    setBoolPref(in string prefName, in long value);
    
    long    getIntPref(in string prefName);
    void    setIntPref(in string prefName, in long value);
    
    string  getCharPref(in string prefName);
    void    setCharPref(in string prefName, in string value);

    wstring getUnicharPref(in string prefName);
    void    setUnicharPref(in string prefName, in wstring value);

    /* going away in favor of nsIFile! */
    nsIFileSpec getFileSpecPref(in string prefName);
    void setFileSpecPref(in string prefName, in nsIFileSpec value);

    boolean prefIsLocked(in string pref);
    
    void clearPref(in string prefName);
    
    /* do we need other prefs like color, rect, etc?
       or maybe we should just have a prefTranslation service
       that translates a string pref into any other type */
    
    /*
     * same as above but for getting default prefs
     */
    boolean getDefaultBoolPref(in string prefName);
    void    setDefaultBoolPref(in string prefName, in boolean value);
    
    long    getDefaultIntPref(in string prefName);
    void    setDefaultIntPref(in string prefName, in long value);
    
    string  getDefaultCharPref(in string prefName);
    void    setDefaultCharPref(in string prefName, in string value);

    wstring getDefaultUnicharPref(in string prefName);
    void    setDefaultUnicharPref(in string prefName, in wstring value);

    /* going away in favor of nsIFile! */
    nsIFileSpec getDefaultFileSpecPref(in string prefName);
    void setDefaultFileSpecPref(in string prefName, in nsIFileSpec value);

    /*
     * branch-level operations
     */

    /**
     * clearBranch
     * 
     * clears all prefs starting at the given pref prefix
     * pass in null or "" to clear this branch
     */
    void clearBranch(in string startingAt);
    
    /**
     * 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 voidStar data);
    /*
     * Listeners/Callbacks
     */

    /**
     * addListener
     * removeListener - for adding/removing interfaces that listen on
     *                  preference changes
     */
    void addListener(in string prefName, in nsIPrefListener listener);
    void removeListener(in string prefName, in nsIPrefListener listener);


    /**
     * registerCallback
     * unregisterCallback - old C-style registration system
     */
    [noscript] void registerCallback(in string domain,
                                     in PrefChangedFunc callback,
                                     in voidStar closure);
    [noscript] void unregisterCallback(in string domain,
                                       in PrefChangedFunc callback,
                                       in voidStar closure);
    
                           
};

