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 "mozilla/hal_sandbox/PHal.h"
  11 #include "base/basictypes.h"
  12 #include "mozilla/Types.h"
  13 #include "nsTArray.h"
  14 #include "prlog.h"
  15 #include "mozilla/dom/battery/Types.h"
  16 #include "mozilla/dom/network/Types.h"
  17 #include "mozilla/dom/power/Types.h"
  18 #include "mozilla/hal_sandbox/PHal.h"
  19 #include "mozilla/dom/ScreenOrientation.h"
  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 nsIDOMWindow;
  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 template <class T>
  41 class Observer;
  42
  43 namespace hal {
  44
  45 typedef Observer<void_t> AlarmObserver;
  46 typedef Observer<ScreenConfiguration> ScreenConfigurationObserver;
  47
  48 class WindowIdentifier;
  49
  50 extern PRLogModuleInfo *sHalLog;
  51 #define HAL_LOG(msg) PR_LOG(mozilla::hal::sHalLog, PR_LOG_DEBUG, msg)
  52
  53 } // namespace hal
  54
  55 namespace MOZ_HAL_NAMESPACE {
  56
  57 /**
  58  * Turn the default vibrator device on/off per the pattern specified
  59  * by |pattern|.  Each element in the pattern is the number of
  60  * milliseconds to turn the vibrator on or off.  The first element in
  61  * |pattern| is an "on" element, the next is "off", and so on.
  62  *
  63  * If |pattern| is empty, any in-progress vibration is canceled.
  64  *
  65  * Only an active window within an active tab may call Vibrate; calls
  66  * from inactive windows and windows on inactive tabs do nothing.
  67  *
  68  * If you're calling hal::Vibrate from the outside world, pass an
  69  * nsIDOMWindow* in place of the WindowIdentifier parameter.
  70  * The method with WindowIdentifier will be called automatically.
  71  */
  72 void Vibrate(const nsTArray<uint32_t>& pattern,
  73              nsIDOMWindow* aWindow);
  74 void Vibrate(const nsTArray<uint32_t>& pattern,
  75              const 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(nsIDOMWindow* aWindow);
  90 void CancelVibrate(const hal::WindowIdentifier &id);
  91
  92 /**
  93  * Inform the battery backend there is a new battery observer.
  94  * @param aBatteryObserver The observer that should be added.
  95  */
  96 void RegisterBatteryObserver(BatteryObserver* aBatteryObserver);
  97
  98 /**
  99  * Inform the battery backend a battery observer unregistered.
 100  * @param aBatteryObserver The observer that should be removed.
 101  */
 102 void UnregisterBatteryObserver(BatteryObserver* aBatteryObserver);
 103
 104 /**
 105  * Returns the current battery information.
 106  */
 107 void GetCurrentBatteryInformation(hal::BatteryInformation* aBatteryInfo);
 108
 109 /**
 110  * Notify of a change in the battery state.
 111  * @param aBatteryInfo The new battery information.
 112  */
 113 void NotifyBatteryChange(const hal::BatteryInformation& aBatteryInfo);
 114
 115 /**
 116  * Determine whether the device's screen is currently enabled.
 117  */
 118 bool GetScreenEnabled();
 119
 120 /**
 121  * Enable or disable the device's screen.
 122  *
 123  * Note that it may take a few seconds for the screen to turn on or off.
 124  */
 125 void SetScreenEnabled(bool enabled);
 126
 127 /**
 128  * Get the brightness of the device's screen's backlight, on a scale from 0
 129  * (very dim) to 1 (full blast).
 130  *
 131  * If the display is currently disabled, this returns the brightness the
 132  * backlight will have when the display is re-enabled.
 133  */
 134 double GetScreenBrightness();
 135
 136 /**
 137  * Set the brightness of the device's screen's backlight, on a scale from 0
 138  * (very dimm) to 1 (full blast).  Values larger than 1 are treated like 1, and
 139  * values smaller than 0 are treated like 0.
 140  *
 141  * Note that we may reduce the resolution of the given brightness value before
 142  * sending it to the screen.  Therefore if you call SetScreenBrightness(x)
 143  * followed by GetScreenBrightness(), the value returned by
 144  * GetScreenBrightness() may not be exactly x.
 145  */
 146 void SetScreenBrightness(double brightness);
 147
 148 /**
 149  * Determine whether the device is allowed to sleep.
 150  */
 151 bool GetCpuSleepAllowed();
 152
 153 /**
 154  * Set whether the device is allowed to suspend automatically after
 155  * the screen is disabled.
 156  */
 157 void SetCpuSleepAllowed(bool allowed);
 158
 159 /**
 160  * Set the value of a light to a particular color, with a specific flash pattern.
 161  * light specifices which light.  See Hal.idl for the list of constants
 162  * mode specifies user set or based on ambient light sensor
 163  * flash specifies whether or how to flash the light
 164  * flashOnMS and flashOffMS specify the pattern for XXX flash mode
 165  * color specifies the color.  If the light doesn't support color, the given color is
 166  * transformed into a brightness, or just an on/off if that is all the light is capable of.
 167  * returns true if successful and false if failed.
 168  */
 169 bool SetLight(hal::LightType light, const hal::LightConfiguration& aConfig);
 170 /**
 171  * GET the value of a light returning a particular color, with a specific flash pattern.
 172  * returns true if successful and false if failed.
 173  */
 174 bool GetLight(hal::LightType light, hal::LightConfiguration* aConfig);
 175
 176
 177 /**
 178  * Register an observer for the sensor of given type.
 179  *
 180  * The observer will receive data whenever the data generated by the
 181  * sensor is avaiable.
 182  */
 183 void RegisterSensorObserver(hal::SensorType aSensor,
 184                             hal::ISensorObserver *aObserver);
 185
 186 /**
 187  * Unregister an observer for the sensor of given type.
 188  */
 189 void UnregisterSensorObserver(hal::SensorType aSensor,
 190                               hal::ISensorObserver *aObserver);
 191
 192 /**
 193  * Post a value generated by a sensor.
 194  *
 195  * This API is internal to hal; clients shouldn't call it directly.
 196  */
 197 void NotifySensorChange(const hal::SensorData &aSensorData);
 198
 199 /**
 200  * Enable sensor notifications from the backend
 201  *
 202  * This method is only visible from implementation of sensor manager.
 203  * Rest of the system should not try this.
 204  */
 205 void EnableSensorNotifications(hal::SensorType aSensor);
 206
 207 /**
 208  * Disable sensor notifications from the backend
 209  *
 210  * This method is only visible from implementation of sensor manager.
 211  * Rest of the system should not try this.
 212  */
 213 void DisableSensorNotifications(hal::SensorType aSensor);
 214
 215
 216 /**
 217  * Inform the network backend there is a new network observer.
 218  * @param aNetworkObserver The observer that should be added.
 219  */
 220 void RegisterNetworkObserver(NetworkObserver* aNetworkObserver);
 221
 222 /**
 223  * Inform the network backend a network observer unregistered.
 224  * @param aNetworkObserver The observer that should be removed.
 225  */
 226 void UnregisterNetworkObserver(NetworkObserver* aNetworkObserver);
 227
 228 /**
 229  * Returns the current network information.
 230  */
 231 void GetCurrentNetworkInformation(hal::NetworkInformation* aNetworkInfo);
 232
 233 /**
 234  * Notify of a change in the network state.
 235  * @param aNetworkInfo The new network information.
 236  */
 237 void NotifyNetworkChange(const hal::NetworkInformation& aNetworkInfo);
 238
 239 /**
 240  * Adjusting system clock.
 241  * @param aDeltaMilliseconds The difference compared with current system clock.
 242  */
 243 void AdjustSystemClock(int32_t aDeltaMilliseconds);
 244
 245 /**
 246  * Set timezone
 247  * @param aTimezoneSpec The definition can be found in
 248  * http://en.wikipedia.org/wiki/List_of_tz_database_time_zones
 249  */
 250 void SetTimezone(const nsCString& aTimezoneSpec);
 251
 252 /**
 253  * Reboot the device.
 254  */
 255 void Reboot();
 256
 257 /**
 258  * Power off the device.
 259  */
 260 void PowerOff();
 261
 262 /**
 263  * Enable wake lock notifications from the backend.
 264  *
 265  * This method is only used by WakeLockObserversManager.
 266  */
 267 void EnableWakeLockNotifications();
 268
 269 /**
 270  * Disable wake lock notifications from the backend.
 271  *
 272  * This method is only used by WakeLockObserversManager.
 273  */
 274 void DisableWakeLockNotifications();
 275
 276 /**
 277  * Inform the wake lock backend there is a new wake lock observer.
 278  * @param aWakeLockObserver The observer that should be added.
 279  */
 280 void RegisterWakeLockObserver(WakeLockObserver* aObserver);
 281
 282 /**
 283  * Inform the wake lock backend a wake lock observer unregistered.
 284  * @param aWakeLockObserver The observer that should be removed.
 285  */
 286 void UnregisterWakeLockObserver(WakeLockObserver* aObserver);
 287
 288 /**
 289  * Adjust the internal wake lock counts.
 290  * @param aTopic        lock topic
 291  * @param aLockAdjust   to increase or decrease active locks
 292  * @param aHiddenAdjust to increase or decrease hidden locks
 293  */
 294 void ModifyWakeLock(const nsAString &aTopic,
 295                     hal::WakeLockControl aLockAdjust,
 296                     hal::WakeLockControl aHiddenAdjust);
 297
 298 /**
 299  * Query the wake lock numbers of aTopic.
 300  * @param aTopic        lock topic
 301  * @param aWakeLockInfo wake lock numbers
 302  */
 303 void GetWakeLockInfo(const nsAString &aTopic, hal::WakeLockInformation *aWakeLockInfo);
 304
 305 /**
 306  * Notify of a change in the wake lock state.
 307  * @param aWakeLockInfo The new wake lock information.
 308  */
 309 void NotifyWakeLockChange(const hal::WakeLockInformation& aWakeLockInfo);
 310
 311 /**
 312  * Inform the backend there is a new screen configuration observer.
 313  * @param aScreenConfigurationObserver The observer that should be added.
 314  */
 315 void RegisterScreenConfigurationObserver(hal::ScreenConfigurationObserver* aScreenConfigurationObserver);
 316
 317 /**
 318  * Inform the backend a screen configuration observer unregistered.
 319  * @param aScreenConfigurationObserver The observer that should be removed.
 320  */
 321 void UnregisterScreenConfigurationObserver(hal::ScreenConfigurationObserver* aScreenConfigurationObserver);
 322
 323 /**
 324  * Returns the current screen configuration.
 325  */
 326 void GetCurrentScreenConfiguration(hal::ScreenConfiguration* aScreenConfiguration);
 327
 328 /**
 329  * Notify of a change in the screen configuration.
 330  * @param aScreenConfiguration The new screen orientation.
 331  */
 332 void NotifyScreenConfigurationChange(const hal::ScreenConfiguration& aScreenConfiguration);
 333
 334 /**
 335  * Lock the screen orientation to the specific orientation.
 336  * @return Whether the lock has been accepted.
 337  */
 338 bool LockScreenOrientation(const dom::ScreenOrientation& aOrientation);
 339
 340 /**
 341  * Unlock the screen orientation.
 342  */
 343 void UnlockScreenOrientation();
 344
 345 /**
 346  * Register an observer for the switch of given SwitchDevice.
 347  *
 348  * The observer will receive data whenever the data generated by the
 349  * given switch.
 350  */
 351 void RegisterSwitchObserver(hal::SwitchDevice aDevice, hal::SwitchObserver *aSwitchObserver);
 352
 353 /**
 354  * Unregister an observer for the switch of given SwitchDevice.
 355  */
 356 void UnregisterSwitchObserver(hal::SwitchDevice aDevice, hal::SwitchObserver *aSwitchObserver);
 357
 358 /**
 359  * Notify the state of the switch.
 360  *
 361  * This API is internal to hal; clients shouldn't call it directly.
 362  */
 363 void NotifySwitchChange(const hal::SwitchEvent& aEvent);
 364
 365 /**
 366  * Get current switch information.
 367  */
 368 hal::SwitchState GetCurrentSwitchState(hal::SwitchDevice aDevice);
 369
 370 /**
 371  * Register an observer that is notified when a programmed alarm
 372  * expires.
 373  *
 374  * Currently, there can only be 0 or 1 alarm observers.
 375  */
 376 bool RegisterTheOneAlarmObserver(hal::AlarmObserver* aObserver);
 377
 378 /**
 379  * Unregister the alarm observer.  Doing so will implicitly cancel any
 380  * programmed alarm.
 381  */
 382 void UnregisterTheOneAlarmObserver();
 383
 384 /**
 385  * Notify that the programmed alarm has expired.
 386  *
 387  * This API is internal to hal; clients shouldn't call it directly.
 388  */
 389 void NotifyAlarmFired();
 390
 391 /**
 392  * Program the real-time clock to expire at the time |aSeconds|,
 393  * |aNanoseconds|.  These specify a point in real time relative to the
 394  * UNIX epoch.  The alarm will fire at this time point even if the
 395  * real-time clock is changed; that is, this alarm respects changes to
 396  * the real-time clock.  Return true iff the alarm was programmed.
 397  *
 398  * The alarm can be reprogrammed at any time.
 399  *
 400  * This API is currently only allowed to be used from non-sandboxed
 401  * contexts.
 402  */
 403 bool SetAlarm(PRInt32 aSeconds, PRInt32 aNanoseconds);
 404
 405 /**
 406  * Set the priority of the given process.
 407  *
 408  * Exactly what this does will vary between platforms.  On *nix we might give
 409  * background processes higher nice values.  On other platforms, we might
 410  * ignore this call entirely.
 411  */
 412 void SetProcessPriority(int aPid, hal::ProcessPriority aPriority);
 413
 414 } // namespace MOZ_HAL_NAMESPACE
 415 } // namespace mozilla
 416
 417 #ifdef MOZ_DEFINED_HAL_NAMESPACE
 418 # undef MOZ_DEFINED_HAL_NAMESPACE
 419 # undef MOZ_HAL_NAMESPACE
 420 #endif
 421
 422 #endif  // mozilla_Hal_h