LocaleService.h

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode:nil; c-basic-offset: 2 -*- */
/* 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/. */

#ifndef mozilla_intl_LocaleService_h__
#define mozilla_intl_LocaleService_h__

#include "nsIObserver.h"
#include "nsString.h"
#include "nsTArray.h"
#include "nsWeakReference.h"
#include "MozLocaleBindings.h"
#include "mozilla/intl/ICU4CGlue.h"
#include "mozILocaleService.h"

namespace mozilla {
namespace intl {

/**
 * LocaleService is a manager of language negotiation in Gecko.
 *
 * It's intended to be the core place for collecting available and
 * requested languages and negotiating them to produce a fallback
 * chain of locales for the application.
 *
 * Client / Server
 *
 * LocaleService may operate in one of two modes:
 *
 *   server
 *     in the server mode, LocaleService is collecting and negotiating
 *     languages. It also subscribes to relevant observers.
 *     There should be at most one server per application instance.
 *
 *   client
 *     in the client mode, LocaleService is not responsible for collecting
 *     or reacting to any system changes. It still distributes information
 *     about locales, but internally, it gets information from the server
 * instance instead of collecting it on its own. This prevents any data
 * desynchronization and minimizes the cost of running the service.
 *
 *   In both modes, all get* methods should work the same way and all
 *   static methods are available.
 *
 *   In the server mode, other components may inform LocaleService about their
 *   status either via calls to set* methods or via observer events.
 *   In the client mode, only the process communication should provide data
 *   to the LocaleService.
 *
 *   At the moment desktop apps use the parent process in the server mode, and
 *   content processes in the client mode.
 *
 * Locale / Language
 *
 * The terms `Locale ID` and `Language ID` are used slightly differently
 * by different organizations. Mozilla uses the term `Language ID` to describe
 * a string that contains information about the language itself, script,
 * region and variant. For example "en-Latn-US-mac" is a correct Language ID.
 *
 * Locale ID contains a Language ID plus a number of extension tags that
 * contain information that go beyond language inforamation such as
 * preferred currency, date/time formatting etc.
 *
 * An example of a Locale ID is `en-Latn-US-x-hc-h12-ca-gregory`
 *
 * At the moment we do not support full extension tag system, but we
 * try to be specific when naming APIs, so the service is for locales,
 * but we negotiate between languages etc.
 */
class LocaleService final : public mozILocaleService,
                            public nsIObserver,
                            public nsSupportsWeakReference {
 public:
  NS_DECL_ISUPPORTS
  NS_DECL_NSIOBSERVER
  NS_DECL_MOZILOCALESERVICE

  /**
   * List of available language negotiation strategies.
   *
   * See the mozILocaleService.idl for detailed description of the
   * strategies.
   */
  static const int32_t kLangNegStrategyFiltering = 0;
  static const int32_t kLangNegStrategyMatching = 1;
  static const int32_t kLangNegStrategyLookup = 2;

  explicit LocaleService(bool aIsServer);

  /**
   * Create (if necessary) and return a raw pointer to the singleton instance.
   * Use this accessor in C++ code that just wants to call a method on the
   * instance, but does not need to hold a reference, as in
   *    nsAutoCString str;
   *    LocaleService::GetInstance()->GetAppLocaleAsLangTag(str);
   */
  static LocaleService* GetInstance();

  /**
   * Return an addRef'd pointer to the singleton instance. This is used by the
   * XPCOM constructor that exists to support usage from JS.
   */
  static already_AddRefed<LocaleService> GetInstanceAddRefed() {
    return RefPtr<LocaleService>(GetInstance()).forget();
  }

  /**
   * Canonicalize a Unicode Language Identifier string.
   *
   * The operation is:
   *   * Normalizing casing (`eN-Us-Windows` -> `en-US-windows`)
   *   * Switching `_` to `-` (`en_US` -> `en-US`)
   *   * Rejecting invalid identifiers (`e21-X` sets aLocale to `und` and
   * returns false)
   *   * Normalizing Mozilla's `ja-JP-mac` to `ja-JP-macos`
   *   * Cutting off POSIX dot postfix (`en-US.utf8` -> `en-US`)
   *
   * This operation should be used on any external input before
   * it gets used in internal operations.
   */
  static bool CanonicalizeLanguageId(nsACString& aLocale) {
    return ffi::unic_langid_canonicalize(&aLocale);
  }
  /**
   * This method should only be called in the client mode.
   *
   * It replaces all the language negotiation and is supposed to be called
   * in order to bring the client LocaleService in sync with the server
   * LocaleService.
   *
   * Currently, it's called by the IPC code.
   */
  void AssignAppLocales(const nsTArray<nsCString>& aAppLocales);
  void AssignRequestedLocales(const nsTArray<nsCString>& aRequestedLocales);

  /**
   * Those two functions allow to trigger cache invalidation on one of the
   * three cached values.
   *
   * In most cases, the functions will be called by the observer in
   * LocaleService itself, but in a couple special cases, we have the
   * other component call this manually instead of sending a global event.
   *
   * If the result differs from the previous list, it will additionally
   * trigger a corresponding event
   *
   * This code should be called only in the server mode..
   */
  void RequestedLocalesChanged();
  void LocalesChanged();

  /**
   * This function keeps the pref setting updated.
   */
  void WebExposedLocalesChanged();

  /**
   * Returns whether the locale is RTL.
   */
  static bool IsLocaleRTL(const nsACString& aLocale);

  /**
   * Returns whether the current app locale is RTL.
   *
   * This method respects this override:
   *  - `intl.l10n.pseudo`
   */
  bool IsAppLocaleRTL();

  static bool LanguagesMatch(const nsACString& aRequested,
                             const nsACString& aAvailable);

  bool IsServer();

  /**
   * Create a component from intl/components with the current app's locale. This
   * is a convenience method for efficient string management with the app
   * locale.
   */
  template <typename T, typename... Args>
  static Result<UniquePtr<T>, ICUError> TryCreateComponent(Args... args) {
    // 32 is somewhat arbitrary for the length, but it should fit common
    // locales, but locales such as the following will be heap allocated:
    //
    //  "de-u-ca-gregory-fw-mon-hc-h23-co-phonebk-ka-noignore-kb-false-kc-
    //    false-kf-false-kh-false-kk-false-kn-false-kr-space-ks-level1-kv-space-cf-
    //    standard-cu-eur-ms-metric-nu-latn-lb-strict-lw-normal-ss-none-tz-atvie-em-
    //    default-rg-atzzzz-sd-atat1-va-posix"
    nsAutoCStringN<32> appLocale;
    mozilla::intl::LocaleService::GetInstance()->GetAppLocaleAsBCP47(appLocale);

    return T::TryCreate(appLocale.get(), args...);
  }

  /**
   * Create a component from intl/components with a given locale, but fallback
   * to the app locale if it doesn't work.
   */
  template <typename T, typename... Args>
  static Result<UniquePtr<T>, ICUError> TryCreateComponentWithLocale(
      const char* aLocale, Args... args) {
    auto result = T::TryCreate(aLocale, args...);
    if (result.isOk()) {
      return result;
    }
    return TryCreateComponent<T>(args...);
  }

 private:
  void NegotiateAppLocales(nsTArray<nsCString>& aRetVal);

  void InitPackagedLocales();

  void RemoveObservers();

  virtual ~LocaleService() = default;

  nsAutoCStringN<16> mDefaultLocale;
  nsTArray<nsCString> mAppLocales;
  nsTArray<nsCString> mRequestedLocales;
  nsTArray<nsCString> mAvailableLocales;
  nsTArray<nsCString> mPackagedLocales;
  nsTArray<nsCString> mWebExposedLocales;
  const bool mIsServer;

  static StaticRefPtr<LocaleService> sInstance;
};
}  // namespace intl
}  // namespace mozilla

#endif /* mozilla_intl_LocaleService_h__ */