michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: /**
michael@0:  * nsIURLFormatter
michael@0:  *
michael@0:  * nsIURLFormatter exposes methods to substitute variables in URL formats.
michael@0:  * Variable names can contain 'A-Z' letters and '_' characters.
michael@0:  *
michael@0:  * Mozilla Applications linking to Mozilla websites are strongly encouraged to use
michael@0:  * URLs of the following format:
michael@0:  *
michael@0:  *   http[s]://%SERVICE%.mozilla.[com|org]/%LOCALE%/
michael@0:  */
michael@0: 
michael@0: #include "nsISupports.idl"
michael@0: 
michael@0: [scriptable, uuid(4ab31d30-372d-11db-a98b-0800200c9a66)]
michael@0: interface nsIURLFormatter: nsISupports
michael@0: {
michael@0:   /** 
michael@0:    * formatURL - Formats a string URL
michael@0:    *
michael@0:    * The set of known variables is predefined.
michael@0:    * If a variable is unknown, it is left unchanged and a non-fatal error is reported.
michael@0:    *
michael@0:    * @param aFormat string Unformatted URL.
michael@0:    *
michael@0:    * @return The formatted URL.
michael@0:    */
michael@0:   AString formatURL(in AString aFormat);
michael@0: 
michael@0:   /** 
michael@0:    * formatURLPref - Formats a string URL stored in a preference
michael@0:    *
michael@0:    * If the preference value cannot be retrieved, a fatal error is reported
michael@0:    * and the "about:blank" URL is returned.
michael@0:    *
michael@0:    * @param aPref string Preference name.
michael@0:    *
michael@0:    * @return The formatted URL returned by formatURL(), or "about:blank".
michael@0:    */
michael@0:   AString formatURLPref(in AString aPref);
michael@0: };