hal/Hal.h

   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 "nsTArray.h"
  11 #include "mozilla/hal_sandbox/PHal.h"
  12 #include "mozilla/HalScreenConfiguration.h"
  13 #include "mozilla/HalBatteryInformation.h"
  14 #include "mozilla/HalNetworkInformation.h"
  15 #include "mozilla/HalWakeLockInformation.h"
  16 #include "mozilla/HalTypes.h"
  17 #include "mozilla/MozPromise.h"
  18
  19 #include <cstdint>
  20
  21 /*
  22  * Hal.h contains the public Hal API.
  23  *
  24  * By default, this file defines its functions in the hal namespace, but if
  25  * MOZ_HAL_NAMESPACE is defined, we'll define our functions in that namespace.
  26  *
  27  * This is used by HalImpl.h and HalSandbox.h, which define copies of all the
  28  * functions here in the hal_impl and hal_sandbox namespaces.
  29  */
  30
  31 class nsPIDOMWindowInner;
  32
  33 #ifndef MOZ_HAL_NAMESPACE
  34 #  define MOZ_HAL_NAMESPACE hal
  35 #  define MOZ_DEFINED_HAL_NAMESPACE 1
  36 #endif
  37
  38 namespace mozilla {
  39
  40 namespace hal {
  41
  42 class WindowIdentifier;
  43
  44 }  // namespace hal
  45
  46 namespace MOZ_HAL_NAMESPACE {
  47
  48 /**
  49  * Initializes the HAL. This must be called before any other HAL function.
  50  */
  51 void Init();
  52
  53 /**
  54  * Shuts down the HAL. Besides freeing all the used resources this will check
  55  * that all observers have been properly deregistered and assert if not.
  56  */
  57 void Shutdown();
  58
  59 /**
  60  * Turn the default vibrator device on/off per the pattern specified
  61  * by |pattern|.  Each element in the pattern is the number of
  62  * milliseconds to turn the vibrator on or off.  The first element in
  63  * |pattern| is an "on" element, the next is "off", and so on.
  64  *
  65  * If |pattern| is empty, any in-progress vibration is canceled.
  66  *
  67  * Only an active window within an active tab may call Vibrate; calls
  68  * from inactive windows and windows on inactive tabs do nothing.
  69  *
  70  * If you're calling hal::Vibrate from the outside world, pass an
  71  * nsIDOMWindow* in place of the WindowIdentifier parameter.
  72  * The method with WindowIdentifier will be called automatically.
  73  */
  74 void Vibrate(const nsTArray<uint32_t>& pattern, nsPIDOMWindowInner* aWindow);
  75 void Vibrate(const nsTArray<uint32_t>& pattern, hal::WindowIdentifier&& id);
  76
  77 /**
  78  * Cancel a vibration started by the content window identified by
  79  * WindowIdentifier.
  80  *
  81  * If the window was the last window to start a vibration, the
  82  * cancellation request will go through even if the window is not
  83  * active.
  84  *
  85  * As with hal::Vibrate(), if you're calling hal::CancelVibrate from the outside
  86  * world, pass an nsIDOMWindow*. The method with WindowIdentifier will be called
  87  * automatically.
  88  */
  89 void CancelVibrate(nsPIDOMWindowInner* aWindow);
  90 void CancelVibrate(hal::WindowIdentifier&& id);
  91
  92 #define MOZ_DEFINE_HAL_OBSERVER(name_)                             \
  93   /**                                                              \
  94    * Inform the backend there is a new |name_| observer.           \
  95    * @param aObserver The observer that should be added.           \
  96    */                                                              \
  97   void Register##name_##Observer(hal::name_##Observer* aObserver); \
  98   /**                                                              \
  99    * Inform the backend a |name_| observer unregistered.           \
 100    * @param aObserver The observer that should be removed.         \
 101    */                                                              \
 102   void Unregister##name_##Observer(hal::name_##Observer* aObserver);
 103
 104 MOZ_DEFINE_HAL_OBSERVER(Battery);
 105
 106 /**
 107  * Returns the current battery information.
 108  */
 109 void GetCurrentBatteryInformation(hal::BatteryInformation* aBatteryInfo);
 110
 111 /**
 112  * Notify of a change in the battery state.
 113  * @param aBatteryInfo The new battery information.
 114  */
 115 void NotifyBatteryChange(const hal::BatteryInformation& aBatteryInfo);
 116
 117 /**
 118  * Register an observer for the sensor of given type.
 119  *
 120  * The observer will receive data whenever the data generated by the
 121  * sensor is avaiable.
 122  */
 123 void RegisterSensorObserver(hal::SensorType aSensor,
 124                             hal::ISensorObserver* aObserver);
 125
 126 /**
 127  * Unregister an observer for the sensor of given type.
 128  */
 129 void UnregisterSensorObserver(hal::SensorType aSensor,
 130                               hal::ISensorObserver* aObserver);
 131
 132 /**
 133  * Post a value generated by a sensor.
 134  *
 135  * This API is internal to hal; clients shouldn't call it directly.
 136  */
 137 void NotifySensorChange(const hal::SensorData& aSensorData);
 138
 139 /**
 140  * Enable sensor notifications from the backend
 141  *
 142  * This method is only visible from implementation of sensor manager.
 143  * Rest of the system should not try this.
 144  */
 145 void EnableSensorNotifications(hal::SensorType aSensor);
 146
 147 /**
 148  * Disable sensor notifications from the backend
 149  *
 150  * This method is only visible from implementation of sensor manager.
 151  * Rest of the system should not try this.
 152  */
 153 void DisableSensorNotifications(hal::SensorType aSensor);
 154
 155 MOZ_DEFINE_HAL_OBSERVER(Network);
 156
 157 /**
 158  * Returns the current network information.
 159  */
 160 void GetCurrentNetworkInformation(hal::NetworkInformation* aNetworkInfo);
 161
 162 /**
 163  * Notify of a change in the network state.
 164  * @param aNetworkInfo The new network information.
 165  */
 166 void NotifyNetworkChange(const hal::NetworkInformation& aNetworkInfo);
 167
 168 /**
 169  * Enable wake lock notifications from the backend.
 170  *
 171  * This method is only used by WakeLockObserversManager.
 172  */
 173 void EnableWakeLockNotifications();
 174
 175 /**
 176  * Disable wake lock notifications from the backend.
 177  *
 178  * This method is only used by WakeLockObserversManager.
 179  */
 180 void DisableWakeLockNotifications();
 181
 182 MOZ_DEFINE_HAL_OBSERVER(WakeLock);
 183
 184 /**
 185  * Adjust a wake lock's counts on behalf of a given process.
 186  *
 187  * In most cases, you shouldn't need to pass the aProcessID argument; the
 188  * default of CONTENT_PROCESS_ID_UNKNOWN is probably what you want.
 189  *
 190  * @param aTopic        lock topic
 191  * @param aLockAdjust   to increase or decrease active locks
 192  * @param aHiddenAdjust to increase or decrease hidden locks
 193  * @param aProcessID    indicates which process we're modifying the wake lock
 194  *                      on behalf of.  It is interpreted as
 195  *
 196  *                      CONTENT_PROCESS_ID_UNKNOWN: The current process
 197  *                      CONTENT_PROCESS_ID_MAIN: The root process
 198  *                      X: The process with ContentChild::GetID() == X
 199  */
 200 void ModifyWakeLock(const nsAString& aTopic, hal::WakeLockControl aLockAdjust,
 201                     hal::WakeLockControl aHiddenAdjust,
 202                     uint64_t aProcessID = hal::CONTENT_PROCESS_ID_UNKNOWN);
 203
 204 /**
 205  * Query the wake lock numbers of aTopic.
 206  * @param aTopic        lock topic
 207  * @param aWakeLockInfo wake lock numbers
 208  */
 209 void GetWakeLockInfo(const nsAString& aTopic,
 210                      hal::WakeLockInformation* aWakeLockInfo);
 211
 212 /**
 213  * Notify of a change in the wake lock state.
 214  * @param aWakeLockInfo The new wake lock information.
 215  */
 216 void NotifyWakeLockChange(const hal::WakeLockInformation& aWakeLockInfo);
 217
 218 /**
 219  * Lock the screen orientation to the specific orientation.
 220  * @return A promise indicating that the screen orientation has been locked.
 221  */
 222 [[nodiscard]] RefPtr<GenericNonExclusivePromise> LockScreenOrientation(
 223     const hal::ScreenOrientation& aOrientation);
 224
 225 /**
 226  * Unlock the screen orientation.
 227  */
 228 void UnlockScreenOrientation();
 229
 230 /**
 231  * Set the priority of the given process.
 232  *
 233  * Exactly what this does will vary between platforms.  On *nix we might give
 234  * background processes higher nice values.  On other platforms, we might
 235  * ignore this call entirely.
 236  */
 237 void SetProcessPriority(int aPid, hal::ProcessPriority aPriority);
 238
 239 }  // namespace MOZ_HAL_NAMESPACE
 240 }  // namespace mozilla
 241
 242 #ifdef MOZ_DEFINED_HAL_NAMESPACE
 243 #  undef MOZ_DEFINED_HAL_NAMESPACE
 244 #  undef MOZ_HAL_NAMESPACE
 245 #endif
 246
 247 #endif  // mozilla_Hal_h