tor-browser

The Tor Browser
git clone https://git.dasho.dev/tor-browser.git
Log | Files | Refs | README | LICENSE

Hal.h (8394B)

      1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
      2 /* vim: set sw=2 ts=8 et ft=cpp : */
      3 /* This Source Code Form is subject to the terms of the Mozilla Public
      4 * License, v. 2.0. If a copy of the MPL was not distributed with this file,
      5 * You can obtain one at http://mozilla.org/MPL/2.0/. */
      6 
      7 #ifndef mozilla_Hal_h
      8 #define mozilla_Hal_h
      9 
     10 #include "base/platform_thread.h"
     11 #include "nsTArray.h"
     12 #include "mozilla/hal_sandbox/PHal.h"
     13 #include "mozilla/HalScreenConfiguration.h"
     14 #include "mozilla/HalBatteryInformation.h"
     15 #include "mozilla/HalNetworkInformation.h"
     16 #include "mozilla/HalWakeLockInformation.h"
     17 #include "mozilla/HalTypes.h"
     18 #include "mozilla/MozPromise.h"
     19 
     20 #include <cstdint>
     21 
     22 /*
     23 * Hal.h contains the public Hal API.
     24 *
     25 * By default, this file defines its functions in the hal namespace, but if
     26 * MOZ_HAL_NAMESPACE is defined, we'll define our functions in that namespace.
     27 *
     28 * This is used by HalImpl.h and HalSandbox.h, which define copies of all the
     29 * functions here in the hal_impl and hal_sandbox namespaces.
     30 */
     31 
     32 class nsPIDOMWindowInner;
     33 
     34 #ifndef MOZ_HAL_NAMESPACE
     35 #  define MOZ_HAL_NAMESPACE hal
     36 #  define MOZ_DEFINED_HAL_NAMESPACE 1
     37 #endif
     38 
     39 namespace mozilla {
     40 
     41 namespace hal {
     42 
     43 class WindowIdentifier;
     44 
     45 }  // namespace hal
     46 
     47 namespace MOZ_HAL_NAMESPACE {
     48 
     49 /**
     50 * Initializes the HAL. This must be called before any other HAL function.
     51 */
     52 void Init();
     53 
     54 /**
     55 * Shuts down the HAL. Besides freeing all the used resources this will check
     56 * that all observers have been properly deregistered and assert if not.
     57 */
     58 void Shutdown();
     59 
     60 /**
     61 * Turn the default vibrator device on/off per the pattern specified
     62 * by |pattern|.  Each element in the pattern is the number of
     63 * milliseconds to turn the vibrator on or off.  The first element in
     64 * |pattern| is an "on" element, the next is "off", and so on.
     65 *
     66 * If |pattern| is empty, any in-progress vibration is canceled.
     67 *
     68 * Only an active window within an active tab may call Vibrate; calls
     69 * from inactive windows and windows on inactive tabs do nothing.
     70 *
     71 * If you're calling hal::Vibrate from the outside world, pass an
     72 * nsIDOMWindow* in place of the WindowIdentifier parameter.
     73 * The method with WindowIdentifier will be called automatically.
     74 */
     75 void Vibrate(const nsTArray<uint32_t>& pattern, nsPIDOMWindowInner* aWindow);
     76 void Vibrate(const nsTArray<uint32_t>& pattern, hal::WindowIdentifier&& id);
     77 
     78 /**
     79 * Cancel a vibration started by the content window identified by
     80 * WindowIdentifier.
     81 *
     82 * If the window was the last window to start a vibration, the
     83 * cancellation request will go through even if the window is not
     84 * active.
     85 *
     86 * As with hal::Vibrate(), if you're calling hal::CancelVibrate from the outside
     87 * world, pass an nsIDOMWindow*. The method with WindowIdentifier will be called
     88 * automatically.
     89 */
     90 void CancelVibrate(nsPIDOMWindowInner* aWindow);
     91 void CancelVibrate(hal::WindowIdentifier&& id);
     92 
     93 #define MOZ_DEFINE_HAL_OBSERVER(name_)                             \
     94  /**                                                              \
     95   * Inform the backend there is a new |name_| observer.           \
     96   * @param aObserver The observer that should be added.           \
     97   */                                                              \
     98  void Register##name_##Observer(hal::name_##Observer* aObserver); \
     99  /**                                                              \
    100   * Inform the backend a |name_| observer unregistered.           \
    101   * @param aObserver The observer that should be removed.         \
    102   */                                                              \
    103  void Unregister##name_##Observer(hal::name_##Observer* aObserver);
    104 
    105 MOZ_DEFINE_HAL_OBSERVER(Battery);
    106 
    107 /**
    108 * Returns the current battery information.
    109 */
    110 void GetCurrentBatteryInformation(hal::BatteryInformation* aBatteryInfo);
    111 
    112 /**
    113 * Notify of a change in the battery state.
    114 * @param aBatteryInfo The new battery information.
    115 */
    116 void NotifyBatteryChange(const hal::BatteryInformation& aBatteryInfo);
    117 
    118 /**
    119 * Register an observer for the sensor of given type.
    120 *
    121 * The observer will receive data whenever the data generated by the
    122 * sensor is avaiable.
    123 */
    124 void RegisterSensorObserver(hal::SensorType aSensor,
    125                            hal::ISensorObserver* aObserver);
    126 
    127 /**
    128 * Unregister an observer for the sensor of given type.
    129 */
    130 void UnregisterSensorObserver(hal::SensorType aSensor,
    131                              hal::ISensorObserver* aObserver);
    132 
    133 /**
    134 * Post a value generated by a sensor.
    135 *
    136 * This API is internal to hal; clients shouldn't call it directly.
    137 */
    138 void NotifySensorChange(const hal::SensorData& aSensorData);
    139 
    140 /**
    141 * Enable sensor notifications from the backend
    142 *
    143 * This method is only visible from implementation of sensor manager.
    144 * Rest of the system should not try this.
    145 */
    146 void EnableSensorNotifications(hal::SensorType aSensor);
    147 
    148 /**
    149 * Disable sensor notifications from the backend
    150 *
    151 * This method is only visible from implementation of sensor manager.
    152 * Rest of the system should not try this.
    153 */
    154 void DisableSensorNotifications(hal::SensorType aSensor);
    155 
    156 MOZ_DEFINE_HAL_OBSERVER(Network);
    157 
    158 /**
    159 * Returns the current network information.
    160 */
    161 void GetCurrentNetworkInformation(hal::NetworkInformation* aNetworkInfo);
    162 
    163 /**
    164 * Notify of a change in the network state.
    165 * @param aNetworkInfo The new network information.
    166 */
    167 void NotifyNetworkChange(const hal::NetworkInformation& aNetworkInfo);
    168 
    169 /**
    170 * Enable wake lock notifications from the backend.
    171 *
    172 * This method is only used by WakeLockObserversManager.
    173 */
    174 void EnableWakeLockNotifications();
    175 
    176 /**
    177 * Disable wake lock notifications from the backend.
    178 *
    179 * This method is only used by WakeLockObserversManager.
    180 */
    181 void DisableWakeLockNotifications();
    182 
    183 MOZ_DEFINE_HAL_OBSERVER(WakeLock);
    184 
    185 /**
    186 * Adjust a wake lock's counts for the current process.
    187 *
    188 * @param aTopic        lock topic
    189 * @param aLockAdjust   to increase or decrease active locks
    190 * @param aHiddenAdjust to increase or decrease hidden locks
    191 */
    192 void ModifyWakeLock(const nsAString& aTopic, hal::WakeLockControl aLockAdjust,
    193                    hal::WakeLockControl aHiddenAdjust);
    194 
    195 /**
    196 * Query the wake lock numbers of aTopic.
    197 * @param aTopic        lock topic
    198 * @param aWakeLockInfo wake lock numbers
    199 */
    200 void GetWakeLockInfo(const nsAString& aTopic,
    201                     hal::WakeLockInformation* aWakeLockInfo);
    202 
    203 /**
    204 * Notify of a change in the wake lock state.
    205 * @param aWakeLockInfo The new wake lock information.
    206 */
    207 void NotifyWakeLockChange(const hal::WakeLockInformation& aWakeLockInfo);
    208 
    209 /**
    210 * Lock the screen orientation to the specific orientation.
    211 * @return A promise indicating that the screen orientation has been locked.
    212 */
    213 [[nodiscard]] RefPtr<GenericNonExclusivePromise> LockScreenOrientation(
    214    const hal::ScreenOrientation& aOrientation);
    215 
    216 /**
    217 * Unlock the screen orientation.
    218 */
    219 void UnlockScreenOrientation();
    220 
    221 /**
    222 * Set the priority of the given process.
    223 *
    224 * Exactly what this does will vary between platforms.  On *nix we might give
    225 * background processes higher nice values.  On other platforms, we might
    226 * ignore this call entirely.
    227 */
    228 void SetProcessPriority(int aPid, hal::ProcessPriority aPriority);
    229 
    230 /**
    231 * Creates a PerformanceHintSession.
    232 *
    233 * A PerformanceHintSession represents a workload shared by a group of threads
    234 * that should be completed in a target duration each cycle.
    235 *
    236 * Each cycle, the actual work duration should be reported using
    237 * PerformanceHintSession::ReportActualWorkDuration(). The system can then
    238 * adjust the scheduling accordingly in order to achieve the target.
    239 */
    240 UniquePtr<hal::PerformanceHintSession> CreatePerformanceHintSession(
    241    const nsTArray<PlatformThreadHandle>& aThreads,
    242    mozilla::TimeDuration aTargetWorkDuration);
    243 
    244 /**
    245 * Returns information categorizing the CPUs on the system by performance class.
    246 *
    247 * Returns Nothing if we are unable to calculate the required information.
    248 *
    249 * See the definition of hal::HeterogeneousCpuInfo for more details.
    250 */
    251 const Maybe<hal::HeterogeneousCpuInfo>& GetHeterogeneousCpuInfo();
    252 
    253 /**
    254 * Perform haptic feedback
    255 */
    256 void PerformHapticFeedback(int32_t aType);
    257 
    258 }  // namespace MOZ_HAL_NAMESPACE
    259 }  // namespace mozilla
    260 
    261 #ifdef MOZ_DEFINED_HAL_NAMESPACE
    262 #  undef MOZ_DEFINED_HAL_NAMESPACE
    263 #  undef MOZ_HAL_NAMESPACE
    264 #endif
    265 
    266 #endif  // mozilla_Hal_h