no bug - Import translations from android-l10n r=release a=l10n CLOSED TREE
[gecko.git] / hal / Hal.h
blob705dadff188be8bd84bb1fea1cc07d1d96da7c0c
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/. */
7 #ifndef mozilla_Hal_h
8 #define mozilla_Hal_h
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"
20 #include <cstdint>
23 * Hal.h contains the public Hal API.
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.
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.
32 class nsPIDOMWindowInner;
34 #ifndef MOZ_HAL_NAMESPACE
35 # define MOZ_HAL_NAMESPACE hal
36 # define MOZ_DEFINED_HAL_NAMESPACE 1
37 #endif
39 namespace mozilla {
41 namespace hal {
43 class WindowIdentifier;
45 } // namespace hal
47 namespace MOZ_HAL_NAMESPACE {
49 /**
50 * Initializes the HAL. This must be called before any other HAL function.
52 void Init();
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.
58 void Shutdown();
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.
66 * If |pattern| is empty, any in-progress vibration is canceled.
68 * Only an active window within an active tab may call Vibrate; calls
69 * from inactive windows and windows on inactive tabs do nothing.
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.
75 void Vibrate(const nsTArray<uint32_t>& pattern, nsPIDOMWindowInner* aWindow);
76 void Vibrate(const nsTArray<uint32_t>& pattern, hal::WindowIdentifier&& id);
78 /**
79 * Cancel a vibration started by the content window identified by
80 * WindowIdentifier.
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.
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.
90 void CancelVibrate(nsPIDOMWindowInner* aWindow);
91 void CancelVibrate(hal::WindowIdentifier&& id);
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);
105 MOZ_DEFINE_HAL_OBSERVER(Battery);
108 * Returns the current battery information.
110 void GetCurrentBatteryInformation(hal::BatteryInformation* aBatteryInfo);
113 * Notify of a change in the battery state.
114 * @param aBatteryInfo The new battery information.
116 void NotifyBatteryChange(const hal::BatteryInformation& aBatteryInfo);
119 * Register an observer for the sensor of given type.
121 * The observer will receive data whenever the data generated by the
122 * sensor is avaiable.
124 void RegisterSensorObserver(hal::SensorType aSensor,
125 hal::ISensorObserver* aObserver);
128 * Unregister an observer for the sensor of given type.
130 void UnregisterSensorObserver(hal::SensorType aSensor,
131 hal::ISensorObserver* aObserver);
134 * Post a value generated by a sensor.
136 * This API is internal to hal; clients shouldn't call it directly.
138 void NotifySensorChange(const hal::SensorData& aSensorData);
141 * Enable sensor notifications from the backend
143 * This method is only visible from implementation of sensor manager.
144 * Rest of the system should not try this.
146 void EnableSensorNotifications(hal::SensorType aSensor);
149 * Disable sensor notifications from the backend
151 * This method is only visible from implementation of sensor manager.
152 * Rest of the system should not try this.
154 void DisableSensorNotifications(hal::SensorType aSensor);
156 MOZ_DEFINE_HAL_OBSERVER(Network);
159 * Returns the current network information.
161 void GetCurrentNetworkInformation(hal::NetworkInformation* aNetworkInfo);
164 * Notify of a change in the network state.
165 * @param aNetworkInfo The new network information.
167 void NotifyNetworkChange(const hal::NetworkInformation& aNetworkInfo);
170 * Enable wake lock notifications from the backend.
172 * This method is only used by WakeLockObserversManager.
174 void EnableWakeLockNotifications();
177 * Disable wake lock notifications from the backend.
179 * This method is only used by WakeLockObserversManager.
181 void DisableWakeLockNotifications();
183 MOZ_DEFINE_HAL_OBSERVER(WakeLock);
186 * Adjust a wake lock's counts for the current process.
188 * @param aTopic lock topic
189 * @param aLockAdjust to increase or decrease active locks
190 * @param aHiddenAdjust to increase or decrease hidden locks
192 void ModifyWakeLock(const nsAString& aTopic, hal::WakeLockControl aLockAdjust,
193 hal::WakeLockControl aHiddenAdjust);
196 * Query the wake lock numbers of aTopic.
197 * @param aTopic lock topic
198 * @param aWakeLockInfo wake lock numbers
200 void GetWakeLockInfo(const nsAString& aTopic,
201 hal::WakeLockInformation* aWakeLockInfo);
204 * Notify of a change in the wake lock state.
205 * @param aWakeLockInfo The new wake lock information.
207 void NotifyWakeLockChange(const hal::WakeLockInformation& aWakeLockInfo);
210 * Lock the screen orientation to the specific orientation.
211 * @return A promise indicating that the screen orientation has been locked.
213 [[nodiscard]] RefPtr<GenericNonExclusivePromise> LockScreenOrientation(
214 const hal::ScreenOrientation& aOrientation);
217 * Unlock the screen orientation.
219 void UnlockScreenOrientation();
222 * Set the priority of the given process.
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.
228 void SetProcessPriority(int aPid, hal::ProcessPriority aPriority);
231 * Creates a PerformanceHintSession.
233 * A PerformanceHintSession represents a workload shared by a group of threads
234 * that should be completed in a target duration each cycle.
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.
240 UniquePtr<hal::PerformanceHintSession> CreatePerformanceHintSession(
241 const nsTArray<PlatformThreadHandle>& aThreads,
242 mozilla::TimeDuration aTargetWorkDuration);
245 * Returns information categorizing the CPUs on the system by performance class.
247 * Returns Nothing if we are unable to calculate the required information.
249 * See the definition of hal::HeterogeneousCpuInfo for more details.
251 const Maybe<hal::HeterogeneousCpuInfo>& GetHeterogeneousCpuInfo();
253 } // namespace MOZ_HAL_NAMESPACE
254 } // namespace mozilla
256 #ifdef MOZ_DEFINED_HAL_NAMESPACE
257 # undef MOZ_DEFINED_HAL_NAMESPACE
258 # undef MOZ_HAL_NAMESPACE
259 #endif
261 #endif // mozilla_Hal_h