/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"
#include "nsILocale.idl"

/**
 * The Locale service interface. This is a singleton object, and should be
 * obtained from the <tt>nsServiceManager</tt>.
 */
[scriptable, uuid(c2edc848-4219-4440-abbf-98119882c83f)]
interface nsILocaleService : nsISupports
{
    /**
     * Create a new nsILocale from a locale string.
     *
     * @param aLocale
     *        A locale code as described in nsILocale.
     * @return A nsILocale representing the given locale.
     */
    nsILocale newLocale(in AString aLocale);

    /**
     * Get the user preference for locale from the operating system.
     *
     * @return User's OS setting for preferred locale.
     */
    nsILocale getSystemLocale();

    /**
     * Get the user preference for locale from the operating system.
     * 
     * NOTE: This has nothing to do with the locale used for localization of
     * the application (UI text strings etc.). This method returns something
     * similar to getSystemLocale.
     *
     * @return User's OS setting for preferred locale.
     */
    nsILocale getApplicationLocale();

    /**
     * Get the most preferred locale from a list of locale preferences.
     *
     * @param acceptLanguage
     *        Locale preference in the same format as the Accept-Language HTTP
     *        header.
     * @return The most preferred locale according to the acceptLanguage
     *         parameter.
     */
    nsILocale getLocaleFromAcceptLanguage(in string acceptLanguage);

    /**
     * Get the user preference for locale from the operating system.
     *
     * NOTE: This has nothing to do with any HTTP User-Agent. This method
     * returns the same as getSystemLocale, but as a string.
     *
     * @return User's OS setting for preferred locale in the format described
     *         in nsILocale.
     */
    AString getLocaleComponentForUserAgent();
};

%{C++

// {C8E518C1-47AE-11d3-91CD-00105AA3F7DC}
#define NS_LOCALESERVICE_CID {0xc8e518c1,0x47ae,0x11d3,{0x91,0xcd,0x0,0x10,0x5a,0xa3,0xf7,0xdc}}
#define NS_LOCALESERVICE_CONTRACTID "@mozilla.org/intl/nslocaleservice;1"

extern nsresult
NS_NewLocaleService(nsILocaleService** result);

%}